Every EMBOSS and EMBASSY program has an ACD (AJAX Command Definition) file which describes the application, its options (parameters) and command line interface. The ACD file controls the behaviour of the application at the command line, particularly, all the user input operations. It includes:
An application definition describing the application itself, for instance its name, documentation text and functional grouping.
A data definition for every application option. These describe the program parameters, i.e. the data the program can accept or requires to run. This includes input and output files and all other parameters.
Attributes defining exactly what options are permitted or required under different conditions, how option values may be specified on the command line and how the user is prompted for values.
A datatype for each application option and attributes describing the permissible type or value in detail, for example default values and whether data has to be within limits. These are used for user input validation to ensure the application parameters are set correctly.
Dependencies between application options, such as when a value is only required if another is specified, or the permitted type of value depends on the value or the presence of another. If for example the input sequence for an alignment program is DNA it should not accept a protein comparison matrix.
When an application is run, the ACD file is read and the command line processed automatically by an ACD file parser and command line processor that is internal to EMBOSS. Together these ensure that the required information is available at start-up. All of the required option values are prompted for as necessary before the application starts. Input values that are incorrect or out of range are reprompted for automatically. The input values are read and held in memory, files are opened as required and so forth, so that all the required data are available when the application proper runs. An EMBOSS application cannot ask the user for more information after several hours of processing!
ACD files are written in the AJAX Command Definition (ACD) language which was designed specifically for EMBOSS. The ACD syntax allows for very flexible descriptions of an application's options and its command line interface. It specifies everything that can appear on the command line or in another interface such as a web page. Metadata specifically for Web, GUI, and other types of interface are provided. For example, whether graphical elements such as radio buttons are appropriate for setting option values. These metadata and the syntax in general make it easy for interface developers to create friendly and intuitive interfaces. Many different interfaces are available (see the EMBOSS Users Guide).
The description of an application's options and interface frequently involves calculations, conditional statements and the use of variables and menus. The ACD syntax supports all these operations and also lets you probe the properties of input datatypes such as sequences. ACD files support various biological datatypes and many different file formats, saving the application developer huge effort. For instance, biological sequences can be read from many different formats and using a variety of different access methods. Usage of these features is transparent to an application and they do not have to be specified in the ACD file.
ACD (Appendix A, ACD Syntax Reference) is a forgiving language that does not restrict the available syntax or layout any more than is strictly necessary. You don't need to know the full syntax to start writing ACD files; all the major features you'll need are summarised below.
Various utility applications (Section 4.6, “ACD Utilities”) are provided for validating, debugging and processing ACD files. These can be used to validate and cleanly reformat an ACD file once it has been written.
ACD files are plain ASCII text files. They must have the extension .acd and typically have the same name as the application:
|
ApplicationName is the name that's passed to the function embInit which invokes ACD file parsing from the application C source code (see Section 4.2, “Application Definition”).
During ACD file parsing, the entire file content is effectively treated as a single string which is parsed into tokens delimited by space characters. Only a single space between individual tokens is required, extra whitespace is ignored. All the tokens are treated as strings until they are finally resolved to their appropriate datatype. There is only one pass through when parsing, so any element (for example a datatype definition) must be declared before it can be referred to. This is relevant when handling dependencies in ACD files (see Section 6.3, “Handling ACD Files”).
An ACD file contains a definition of the application and all its options. An ACD file must contain a single application definition and then a data definition for each option. A definition contains one or more attributes, each of which is an AttributeName: AttributeValue
The general format for the application definition is:
application:ApplicationName[ApplicationAttribute1Name: "ApplicationAttribute1Value"ApplicationAttribute2Name: "ApplicationAttribute2Value" ]
The general format for a data definition is:
Datatype:OptionName[Attribute1Name: "Attribute1Value"Attribute2Name: "Attribute2Value" ]
See elsewhere for guidelines in programming application (Section 4.2, “Application Definition”) and data definitions (Section 4.3, “Data Definition”), including datatypes, attributes and option (parameter) naming conventions.
Attribute values are normally enclosed in double quotes, although this is only mandatory for values (typically strings) which include whitespace. For example, here is a valid attribute definition:
string: "A String Value"
Here is an invalid one:
string: A String Value
The application: token and tokens representing datatypes can be abbreviated so long as they remain unambiguous. For example
appl: |
is sometimes given instead of
application: |
Similarly the sequence datatypes:
sequence:, seqset: and seqall: |
could in principle be abbreviated to:
sequ, seqs and seqa. |
Attributes can also be abbreviated. For example, the attribute to set a default value for a data definition:
default: |
can be abbreviated to
def: or even d: |
Such abbreviations are not recommended, however, because they tend to make the ACD file more difficult to read. Typically you will use the ACD utilities (Section 4.6, “ACD Utilities”) to cleanly reformat an ACD file once it has been written.
Each application option, i.e. every data definition in the ACD file, can be defined via the appropriate ACD attribute to be one of the following:
Parameter
Standard Qualifier
Additional Qualifier
with the default being:
Advanced Qualifier
The attributes to use are as follows:
parameter: "Y" standard: "Y" additional: "Y"
parameter: "Y" means that the data definition is a parameter. standard: "Y" and additional: "Y" mean that the data definition is a standard qualifier or an additional qualifier. If none of parameter: "Y", standard: "Y" or additional: "Y" are specified then the data definition defaults to being an advanced qualifier.
Only one of parameter: "Y", standard: "Y" or additional: "Y" should ever be given in a data definition. If more than one is used an error message will be generated during ACD processing.
You should never explicitly specify Parameter: "N", standard: "N" or additional: "N". An error will be generated during ACD processing if you do. The "Y" in the previous definitions is given for consistency because every ACD attribute, being a label:value pair, has to have a value. In practice, calculated values of "N" are in fact supported and can be used, in exceptional circumstances, to override the default behaviour of these attributes (see Section 4.5, “Controlling the Prompt”).
In earlier versions of EMBOSS, required: and optional: were used but this led to confusion because, depending on the details of the ACD definitions, some required: data definitions were not actually required by the application, and some optional: definitions were in fact mandatory.
To clear things up, standard: now replaces required: and additional: replaces optional:.
Parameters are commonly used for input and output files and other primary input and output data, whereas the different types of qualifier are used for other application options. The difference between parameters and qualifiers is that you don't have to use a flag to specify a value for a parameter on the command line. Values are specified like this:
|
In contrast, you do have to use a flag (the option name) to specify a value for a qualifier. Values for standard, additional and advanced qualifiers are specified like this:
|
The flag (option name) can also be given before parameter values but it is not required. If flags for parameters are not used it is, however, necessary to give the values in the same order as the corresponding data definitions appear in the ACD file.
This gives a simplified view of how to assign a value to an application parameter. There are more possibilities not described here, particularly for handling multiple options of the same type. For more information see the EMBOSS Users Guide.
Values for parameters and standard qualifiers are always prompted for if not specified on the command line. If a default value is specified in the ACD file, the user may accept this by pressing <Return>.
Values for additional qualifiers are not prompted for (the default value will be used instead) unless -options is given on the command line, which will turn prompting on for these qualifiers. A default value should always be given in the ACD file for additional qualifiers by specifying the default: attribute.
An advanced qualifier is never prompted for, even if -options is used, therefore a default value should be given in the ACD file.
Help information for parameters and qualifiers appears, in the form of sections of the documentation output, when a program is run with the -help inbuilt qualifier. Help information for parameters and standard qualifiers appears in the "Required" section of the help display. Information for additional and advanced qualifiers appears in the "Advanced" section.
The following ACD file defines an application with a sequence parameter (sequence) and standard qualifier (thresh) to set a scoring threshold:
application: seqdemo
[
documentation: "Demo application"
]
sequence: asequence
[
parameter: "Y"
]
float: thresh
[
standard: "Y"
default: "2.5"
minimum: "0.0"
maximum: "100.0"
information: "Score threshold"
]The asequence parameter can be set without the qualifier name (flag), but one is needed for thresh. The application could be invoked as follows:
seqdemo |
seqdemo |
In the first case, thresh is set directly. In the second case, it is not set and the user would be prompted for a value.
If, in contrast, thresh was defined as an additional qualifier:
float: thresh [ additional: "Y" default: "2.5" minimum: "0.0" maximum: "100.0" information: "Score threshold" ]
the user would only be prompted for a value if -options was set:
seqdemo |
The following ACD definition would define an advanced qualifier (abool):
boolean: abool [ default: "Yes" ]
The user would never be prompted for a value for abool, so if it was not set on the command line, the application would proceed with the default value ("Yes"). abool could be set on or off as follows:
acddemo -asequence (turn abool on) |
acddemo -asequence (turn abool off) |
EMBOSS processes ACD definitions in the order in which they appear in an ACD file. This order is insufficient, however, to allow interface developers to build clean groupings of options for user interfaces. To help interface developers, all ACD data definitions are grouped into five major sections, which must appear in the following order:
Input
Required
Additional
Advanced
Output
A section appears like this:
section: input [ information: "Input section" type: "page" ] # # Input data definitions go here # endsection: input
All data definitions in an ACD file must be contained within an appropriate section and the sections must be given in the order indicated. An error will be generated during ACD processing otherwise (see Section A.1.6, “ACD File Sections”). The order is also tested by the acdvalid tool which will generate an error if the sections are in the wrong order.
Each major section may include nested within it one or more subsections, which may contain further nested subsections as required although this is seldom necessary. Subsections, in contrast to major sections, have arbitrary names and can be given in any order.
For a detailed description of these sections and what goes in them, see Section A.1.6, “ACD File Sections”.
Input datatypes and other data definitions related to input. See Section A.2.2, “Description of Input ACD Datatypes”.
Options which always require a value from the user but which are not in the input or output section. This includes all data definitions that are defined as parameters using the attribute:
parameter: "Y" |
and all those defined as standard qualifiers:
standard: "Y" |
Additional qualifiers which are occasionally set by the user and are defined by the attribute:
additional: "Y" |
Advanced qualifiers for which a value may be set but is never prompted for. They are defined by the absence of the attributes:
parameter: "Y" |
standard: "Y" |
additional: "Y" |
Output datatypes and other parameters related to output. See Section A.2.3, “Description of Output ACD Datatypes”.
The search input string of the wossname application is contained within an input section. The output section contains all the parameters and qualifiers related to output and also contains a subsection called htmlsection:
section: input
[
information: "Input section"
type: "page"
]
string: search
[
parameter: "Y"
default: ""
information: "Text to search for, or blank to list all
programs"
help: "Enter a word or words here and a case-independent search
for it will be made in the one-line documentation, group names and
keywords of all of the EMBOSS programs. If no keyword is
specified, all programs will be listed."
knowntype: "emboss keyword"
]
endsection: input
.
.
.
section: output
[
information: "Output section"
type: "page"
]
outfile: outfile
[
additional: "Y"
default: "stdout"
knowntype: "wossname output"
]
section: htmlsection
[
information: "Html section"
type: "frame"
]
toggle: html
[
additional: "Y"
default: "N"
information: "Format the output for HTML"
help: "If you are sending the output to a file, this will format
it for displaying as a table in a WWW document."
outputmodifier: "Y"
]
endsection: htmlsection
boolean: groups
[
additional: "Y"
default: "N"
information: "Output only the group names"
help: "If you use this option, then only the group names will
output to the file"
outputmodifier: "Y"
]
boolean: alphabetic
[
additional: "Y"
default: "N"
information: "Output an alphabetic list of programs"
help: "If you use this option, then you will get a single list of
the program names and descriptions instead of the programs being
listed in their functional groups."
outputmodifier: "Y"
]
endsection: outputAll sections and subsections are defined in the file:
sections.standard |
which is stored in the EMBOSS application ACD file directory, e.g.:
.../emboss/emboss/emboss/acd |
An excerpt of this file is shown below:
# # ACD sections # # top level (page) sections # ========================= additional page Additional section advanced page Advanced section input page Input section output page Output section required page Required section # # # sub level (frame) sections # ========================== afeaturesection input First feature options bfeaturesection input Second feature options consensussection additional Consensus section datasection output Data output section fastalignsection additional Fast align options
The file defines the permissible order of the top level (page) sections ("Input", "Required", "Additional" etc.) The file also defines the permissible subsections (given under # sub level (frame) sections), which have been defined and used for individual applications as required. The first token is the subsection name. The second token is the top-level section to which the subsection belongs: a subsection cannot appear in any other section other than that listed. The remaining text on the line is a description of the section.