The ACD files are files describing parameters and behavior of the command-line programs, using format brought by EMBOSS. The format is flexible enough to be used also for non-EMBOSS applications. This chapter describes the ACD format, especially stressing how to use it for the non-EMBOSS programs.

Let's start by showing a simple ACD file for a HelloWorld application:

appl: HelloWorld [
  documentation: "Classic greeting from the beginning of the UNIX epoch"
  groups: "Classic"
  nonemboss: "Y"
  executable: "echo"
]

string: greeting  [
  additional: "Y"
  parameter: "Y"
  default: "Hello World"
  comment: "defaults"
]

outfile: output  [
  additional: "Y"
  default: "stdout"
]

The original EMBOSS documentation.

This is obviously very detailed source. But for the non-EMBOSS applications you do not need the full richness described here. Many data types are EMBOSS specific (e.g. sequence) - and even though you may use them your application would need to know how to interpret their properties in order to use them fully.

The original AppLab documentation.

This is a very long document describing many details that can be put into ACD files. Unfortunately, it was written for a different file format - so even though the options may be still valid, they are not necessary shown in the correct syntax. Also, many of them were not implemented by Soaplab (such as the repeatable parameters described there in many details).

Because of the drawbacks just mentioned this chapter tries to combine both sources and to show what is relevant for the non-EMBOSS programs. For more formal approach refer to the original EMBOSS documentation.

ACD	Getting started with syntax

Each application has zero or more command-line parameters. In an ACD file, each of them is defined by a single token followed by either a colon ':' (preferred) or an equal sign '=' which in turn is followed by a second token. The definition of the parameter is delimited by a pair of square brackets '[ ]', which can span multiple lines:

token: token [

   definition

]

The first definition in any ACD file must start with token application (usually abbreviated to appl) followed by a token representing the application name, and by attributes describing the whole application (not just an individual parameter):

appl: appname [ 

    application attributes

]

data_type: parameter_name [ 

   parameter attributes

  ]

The ACD syntax also allows to group parameter definitions into several sections (input parameters, output parameters, advanced parameters and perhaps other). The Soaplab at the moment ignores sections - so they are not shown in the examples in this chapter. However, if you look into available ACD files for the EMBOSS programs you will notice them.

Options in Comment and Style

The ACD format uses a rich set of keywords to name its attributes. But sometimes it is not enough. Fortunately, it allows also general keywords comment and style where one can encode whatever Soaplab needs. The (Soaplab-specific) syntax for the values of these attributes is a name followed by a space, followed by a real value. For example:

comment: "result_dataviewer ALDataViewerExt"

If there is no real value (meaning: nothing separated by a space) the resulting Soaplab option is considered to be boolean with the value true, as in this example:

comment: bindata

ACD	Application attributes

documentation

A string describing briefly the function of the program.

groups

This attribute allows to group programs together based on their functionality. Its value contains the name(s) of the group(s). When an application belongs to more then one group, the group names must be separated by either a comma or semi-colon.

supplier

It identifies in a free-text who is supplying this application.

version

A version of this application, a free-text.

executable

A name of the executable representing this application. If missing the application name (defined in the appl line) is used instead. It is not recommended to put here the full path - that would make the ACD file non-portable. The path can be added later and elsewhere.

An example was given above for the hellowold application where the executable was the Unix program echo.

nonemboss !

A boolean parameter that should be always used and should have always value Y. By default, all ACD files are assumed to describe EMBOSS applications. But Soaplab (precisely the generator of the metadata XML files) does slightly different things for EMBOSS and non-EMBOSS programs - so it needs to know what kind of application is being described. This is quite important attribute.

Specific options

comment: "launcher <script-name>"

The launcher is a script that is called by AppLab (a Java application) to call the underlying application. In most cases the default launcher (the script called ALGenLauncher is fine, and there is no need to define this option.

But sometimes there is a need to invoke programs in a special way. An example is a launcher starting applications in a queuing system, such as LSF. If you need it use, for example, the distributed launcher script LSFLauncher, and put its name into this comment/option.

comment: "method <template>"

It defines a template for the whole command-line if the default appearance (tagged parameters with the qualifiers prefixed by minus) is not sufficient. It refers to individual parameters by constructs ${parameter-name}. The details and examples are below.

comment: "help <URL-with-a-help-page>"

A URL pointing to the page explaining the whole application.

ACD	General attributes for all data types

comment: method
template
comment: tagsepar
parameter