The Ajax Command Definition (ACD) language was designed for writing ACD files for EMBOSS applications. Every application in EMBOSS or EMBASSY has an ACD file. The ACD syntax allows for very flexible descriptions of an application's parameters and its command line interface. It can specify everything that can appear on the command line or in another interface such as a web page.
ACD files are plain ASCII text files and must have the extension
.acd. Typically they have the same name as the application, but this is not mandatory.
During ACD file parsing, the entire file contents are effectively treated as a single string which is parsed into tokens delimited by space characters. A single space between individual tokens is required: extraneous whitespaces are ignored.
An ACD file contains a single application definition and a data definition for each parameter. The application definition is given first, followed by the data definitions. Data definitions are organised into sections (see Section A.1.6, “ACD File Sections”).
Application and data definitions have the following general form: a single text token followed by a colon
'=') and a white space, followed by a second token. The definition body follows, which is one or more attributes delimited by a mandatory pair of square brackets
[ ], which can span multiple lines. Each attribute is a
pair with the attribute value given between quotes (
The first token is either
application: (for the application definition) or an AJAX datatype (e.g.
sequence) for data definitions. The second token is either the name of the application (e.g.
seqret) or the name of parameter (e.g.
application token and tokens for the datatype and attribute names can be can be abbreviated up to the point where they are not ambiguous. Such abbreviations are not recommended however because they tend to make the ACD file more difficult to read.
Attribute values are normally enclosed in double quotes, although this is only mandatory for values (typically strings) which include whitespace.
The application definition must be the first definition in the file:
The application name is arbitrary but is typically the same as that used for the ACD file name. It is the ACD file name (not
ApplicationName, if different) that's used from within the application C source code to associate it with an ACD file. This allows multiple ACD files (and therefore command line interfaces) to be developed for a single file of application C source code.
For complete description of the available application attributes see Section A.3, “Application Attributes”.
All application parameters must have a data definition. Data definitions follow the application definition and must be placed in an appropriate file section (see Section A.1.6, “ACD File Sections”):
Datatype must be a valid ACD datatype. For a complete descriptions of the available datatypes see Section A.2, “Datatypes”.
is the name of the parameter. It is a string that must conform to certain conventions (Section A.1, “Introduction to ACD Syntax”). This name is used to refer to the data definition from the command line and from within the C source code (see Section 6.3, “Handling ACD Files”).
For a complete description of the available attributes see:
|Global attributes (Section A.4, “Global Attributes”)|
|Datatype-specific attributes (Section A.5, “Datatype-specific Attributes”)|
|Calculated attributes (Section A.6, “Calculated Attributes”)|
The general conventions for parameter and qualifier names are as follows:
Must not contain whitespace characters
Should not normally be single characters
Should be meaningful words and indicate the function of the option so far as possible
They are not case sensitive
The conventions for parameter names that apply for individual datatypes are given in the table below.
Where more than one instance of a datatype is specified in an ACD file, then the character
b etc can be appended to the flag:
bsequence etc. This is indicated in the table by an asterisk in the parameter name, for example
*sequence (see Table A.1, “Parameter and Qualifier Naming Conventions”).
Primary input sequence, generally required
Primary input sequence database, generally required
Primary input sequences, generally required
Primary input sequences, generally required
Primary output sequence, generally required, generally should default to the primary input sequence name, extension defaults to the name of the output sequence format.
Primary output non-sequence results file, generally required. The file extension should be allowed to default to the application name.
Report output file.
Alignment output file.
Primary input non-sequence file
Primary auxiliary input data file, generally optional
File of patterns to search for in sequence
Minimal length of sequence feature to be found
Maximum length of sequence feature to be found
Word size for hash tables etc. Generally minimum value = 2 for protein, 4 for DNA
Window length for calculating dotplots/features/etc.
Amount by which window is shifted in each iteration
Flag for whether consensus sequence should be output
Gap extension penalty
Position of start of input sequence to specify for an operation (e.g. deletion), defaults to start of sequence, minimum value = 1, maximum value = <sequence length>
Position of end of input sequence to specify for an operation (e.g.: deletion), defaults to the
Threshold for various operations
Operation should be done at the start of the sequence
Operation should be done at the end of the sequence
Pattern to search for in sequence
Directory of files
Output directory of files
Directory of files
List of files
For some datatypes, conventions are more strongly enforced: a warning will be generated during ACD processing if a standard name is not used for the following datatypes:
Sequence inputs (any data definition of the type
seqset) and sequence outputs (
Feature inputs (any data definition of the type
feature) and feature outputs (
File inputs and outputs (any data definition of the type
Report output (
Application attributes may be defined for an application definition (Section A.3, “Application Attributes”).
There are three basic types of attributes that may be defined for a data definition:
Additionally, there are various "datatype associated" command line qualifiers (or simply "associated qualifiers") that are inbuilt for certain ACD datatypes may also be defined as attributes in the appropriate data definition. These are listed in the datatype descriptions (Section A.2, “Datatypes”).
Every data definition in the ACD file can be defined via an appropriate attribute to be one of the following:
with the default being:
They differ in terms of how they are prompted for, how they may be specified on the command line and whether help information for them appears.
This behaviour is summarised in the table below (Table A.2, “Behaviour of Command line Parameters and Qualifiers”). "Flag" indicates whether the flag (parameter or qualifier name) must be given on the command line. "Prompt" indicates whether a value will be prompted for if one is not specified on the command line. Additional qualifiers will only be prompted for if
-options is specified. "Help" indicates where the information from the built-in
-help qualifier is shown. For more information, see Section 4.5, “Controlling the Prompt”.
|additional||Yes||Yes (with ||Advanced section|
|advanced (default)||No attribute needed||Yes||No||Advanced section|
Any data definitions in an ACD file must be contained within an appropriate section and given in the correct order. The sections must appear in this order:
Subsections with arbitrary names can also be defined. They can appear in any order but must be nested in a major section.
Sections and subsections have the following general syntax:
SectionName[ information: "
SectionNamesection" type: "page" ] . . (data definitions go here) . section:
NestedSectionName[ information: "
NestedSectionNamesection" type: "page" ] . . (data definitions go here) . endsection:
section: input [ information: "Input section" type: "page" ] . . (input data definitions go here) . section: inputsubsection [ information: "Input sub-section" type: "page" ] . . (input sub-section data definitions go here) . endsection: inputsubsection endsection: input
The section contents is summarised in the table (Table A.3, “ACD File Sections”).
Simple input values and any ACD type that will read input, including
|Required||Parameters and Standard Qualifiers, including any whose |
|Additional||Additional Qualifiers, including any whose |
|Advanced||Any qualifiers (except input and output qualifiers) which have no |
|Output||Any data type that will write output, including any |
Restrictions on the order of sections and what data definitions can appear in what sections are defined in the EMBOSS system file
sections.standard (see Section 4.1, “Introduction to ACD File Development”). The restrictions are enforced during ACD processing and an error will be generated in the following circumstances:
If major sections appear in the wrong order
If subsections appear in the wrong major sections
If a parameter (data definition with a
parameter: "Y" attribute) or a standard qualifier (
standard: "Y" attribute) occurs in the "Advanced" or "Additional" sections
If an additional qualifier (
additional: "Y" attribute) occurs in the "Advanced" or "Required" sections
If an advanced qualifier (no
standard: "Y" or
additional: "Y" attribute) occurs in the "Additional" or "Required" sections