The ACD file specifies an input sequence stream (
sequence) and an output sequence stream (
outseq). The ACD file is shown below:
application: seqret [ documentation: "Reads and writes (returns) sequences" groups: "Edit" ] section: input [ information: "Input section" type: "page" ] boolean: feature [ information: "Use feature information" ] seqall: sequence [ parameter: "Y" type: "gapany" features: "$(feature)" ] endsection: input section: advanced [ information: "Advanced section" type: "page" ] boolean: firstonly [ information: "Read one sequence and stop" ] endsection: advanced section: output [ information: "Output section" type: "page" ] seqoutall: outseq [ parameter: "Y" features: "$(feature)" ] endsection: output
Data definitions for
outseq are specified as parameters, which means that a value for them (i.e. a USA) can be given on the command line without the requirement of specifying a flag (the parameter name, i.e.
-outseq) on the command line. The flags, however, may still be given.
So, seqret can be invoked like this:
in which case the parameters must be in the order shown (
OutputSequenceUSA are the USAs of the input and output sequences).
It can also be invoked like this:
in which case the parameters can be given in any order, so this is also acceptable:
The application definition is given at the top of the file:
application: seqret [ documentation: "Reads and writes (returns) sequences" groups: "Edit" ]
The application name (
seqret) is given after the
application: token. A succinct description of the application function (
"Reads and writes (returns) sequences") is given after the
documentation: attribute and will be printed to screen when the program is run. It also appears when the program is run with the
-help qualifier. This text is also searched by the wossname utility, which displays applications after searching for keywords.
groups: attribute has the value of
"Edit", indicating that seqret belongs to the group
"Edit", i.e. applications for sequence editing. All EMBOSS and EMBASSY applications are put into groups of related functionality (Section 18.104.22.168, “Application Group Names File (
Other attributes (see Section 4.3, “Data Definition”) may be given in the application definition.
The ACD file is organised into sections for
Output sections, which are enclosed within text tokens (
endsection: input etc):
section: input [ information: "Input section" type: "page" ] . . . endsection: input
Output sections are used for application inputs and outputs respectively.
Advanced is used for application options which are never prompted for at the command line. In practice there are other types of application parameters and corresponding sections that might appear in the ACD file (see Section 4.1, “Introduction to ACD File Development”).
These sections contain the ACD data definitions which define the application input and output data and other application parameters. Conceptually the data definitions can be thought of as two basic types, either basic input and output files or other types that control the application. For example,
outseq are data definitions for input and output files:
seqall: sequence [ parameter: "Y" type: "gapany" features: "$(feature)" ] . . . seqoutall: outseq [ parameter: "Y" features: "$(feature)" ]
boolean: feature is a control definition which, if set by the user, will cause seqret to read sequence feature information, if available, from the input file.
boolean: firstonly is another control definition which, if set, will cause only a single sequence to be read:
boolean: feature [ information: "Use feature information" ] . . . boolean: firstonly [ information: "Read one sequence and stop" ]
Each ACD definition has attributes which are
pairs. Attributes are of two basic types. Global attributes are available for all datatypes whereas datatype-specific attributes are available for individual or groups of related datatypes.
Consider the definitions for
boolean: feature [ information: "Use feature information" ] seqall: sequence [ parameter: "Y" type: "gapany" features: "$(feature)" ]
information: are global attributes whereas
features: are datatype-specific.
parameter: "Y" defines a data definition to be a parameter as opposed to some kind of qualifier. A value for a parameter can be given on the command line with or without a flag (parameter name) as described above. All parameters are required by the application and a value will be prompted for if one is not given on the command line.
parameter: "Y" is not given for the
boolean definitions which means, in the absence of
standard: "Y" or
additional: "Y" attributes, that they will default to being an advanced qualifier. An advanced qualifier is never prompted for. Had
standard: "Y" or
additional: "Y" been defined, then the data definitions would be standard or additional qualifiers. More information on the behaviour of qualifiers and parameters is available (Section 4.1, “Introduction to ACD File Development”).
information: gives a very succinct description of the data definition. The text is used in Web forms and other GUIs. It is also the text used to prompt the user for a value at the command line. You'll notice
information: is not defined for the sequence inputs and outputs. A default prompt is provided by EMBOSS for these datatypes. All
boolean: datatypes have the default value of
False which means that a default needn't be defined explicitly in the ACD file.
type: attribute is specific to the sequence datatypes.
type: "gapany" indicates that the input sequence can be of any type and may contain gap characters. In practice many different sequence types are supported (Section A.7, “Sequence Types”).
features: attribute is also sequence-specific. The attribute definition looks a little strange:
$ syntax means "retrieve the value of ...", in this case "retrieve the value of the
feature ACD definition", such that the
features: attribute of
outseq is set to that value. In other words, the input sequence will include features if the user turned the
feature advanced qualifier on by giving it on the command line, e.g.
seqret -feature. Whilst it is not strictly necessary to have
features: "$(feature)" (the information is after all specified in
boolean: feature) it makes the application source code a good deal cleaner.
In addition to global and datatype-specific attributes there are two other types of attribute that may appear in an ACD file. Calculated attributes receive a value once the ACD file has been processed and application input files have been read. Finally, there are datatype-specific command line qualifiers which are defined for single or groups of ACD datatypes and may be hard-coded as attributes within an ACD file. See:
|Global atttributes (Section A.4, “Global Attributes”)|
|Datatype-specific attributes (Section A.5, “Datatype-specific Attributes”)|
|Calculated attributes (Section A.6, “Calculated Attributes”)|
|Datatype-specific qualifiers (Section A.5, “Datatype-specific Attributes”)|