Reliable prompting of the user for input values is a critical part of any application interface. EMBOSS allows you precise control over how application parameters are prompted for and thereby saves you a great deal of development time. This is achieved by using ACD data attributes:
parameter: "Y" means that the data item is a parameter, i.e. you do not have to use the data label to specify a value for it on the command line. e.g.
standard: "Y" and
additional: "Y" mean that the data item is a qualifier, i.e. you do have to use the data label to specify a value for it on the command line. e.g.
myprog -somevalue 10. If a data definition is not defined to be a parameter, or a standard or additional qualifier then it will default to an advanced qualifier.
Values for parameters and standard qualifiers are always prompted for (with their default value) if not specified on the command line.
Values for additional qualifiers are not prompted for (a default value will be used) unless
-options is given on the command line. A default value for additional qualifiers should always be given in the ACD file.
Values for advanced qualifiers are never prompted for.
Consider the following ACD file, for an application called helloworld, which defines two parameters, namely a string input (
string datatype) and an output file (
application: helloworld [ documentation: "Prints something arguably uninteresting" ] string: message [ parameter: "Y" ] outfile: outfile [ parameter: "Y" ]
Values for parameters must be specified on the command line in the order they appear in the ACD file. So to specify both parameters for helloworld you'd have to type something like:
That would cause Hello World! to be printed to the output file
message.dat. Alternatively it's also perfectly acceptable to use one of:
For parameters you don't have to use the name flag whereas for qualifiers (see below) you do. If you omit the flag for parameters then their values must appear on the command line in the order in which they appear in the ACD file.
However, you might not want to force the user to specify a message, instead relying on a default message (
"Hello World!") defined in the ACD file to be printed if nothing else is given. So by typing:
you want "Hello World!" (the default message) to be printed to the file
The above ACD file will not do that. All the data definitions are parameters (
parameter:) and therefore will be prompted for if they are not given on the command line. Typing the command above would result in
message.dat being taken as the string to be printed, and you'd then be prompted for an output file name. In short, not the desired behaviour. This is where qualifiers come in.
Values for qualifiers (whether "standard", "additional" or "advanced") can appear anywhere on the command line but you must always refer to them by their flag. So if your message is defined as a qualifier, rather than a parameter, the reference to it has to look like this:
To specify a data definition as a qualifier, you use
additional: rather than the
parameter: attribute that's currently specified. Alternatively, if you don't specify any of these attributes it will default to being an
advanced qualifier. For example:
application: helloworld [ documentation: "Prints something arguably uninteresting" ] string: message [ standard: "Y" ] outfile: outfile [ parameter: "Y" ]
As you now have only one parameter, both of the following command lines are valid:
Now if you don't specify the message text on the command line, i.e. you just type:
message.dat will be treated as a parameter, and taken to be the output file name. The program will then prompt you for a string to print out. This is close to what we wanted, but still not quite the desired behaviour. What we wanted was for it to go ahead and run with a default string.
You can associate a default value for most data definitions using the
default: attribute. The ACD can be modified as follows:
application: helloworld [ documentation: "Prints something arguably uninteresting" ] string: message [ standard: "Y" default: "Hello World!" ] outfile: outfile [ parameter: "Y" ]
Now if you typed:
then although you specified a default it's still prompting for a value. Remember that all values for
standard data definitions are always prompted for, regardless of whether a default is specified or not. You need to specify
message as being an "additional" or "advanced" qualifier, which are not normally prompted for.
The ACD file will look like this:
application: helloworld [ documentation: "Prints something arguably uninteresting" ] string: message [ additional: "Y" default: "Hello World!" ] outfile: outfile [ parameter: "Y" ]
This ACD finally does what is needed. Typing:
Hello World! to the file
message.dat i.e. the desired behaviour.
You can of course override the default message by specifying the message on the command line:
This will print a rather morbid message to the output file. You should usually supply a default value for
advanced ACD data definitions as EMBOSS will not prompt you for a value if you don't specify one on the command line. EMBOSS would generate an error if you tried, from within your C source code, to access the value of an unspecified data item. In contrast, values for
parameter data definitions are always prompted for if they're not specified on the command line, therefore a default is useful but not essential.
Note that some datatypes such as
boolean have an inbuilt default value.
It is often either useful or vital to be able to set limits on the maximum and/or minimum values to be associated with an ACD datatype definition. This is done in an intuitive way using the
integer: window [ standard: "Y" default: "10" minimum: "5" maximum: "100" ]
EMBOSS will always provide default prompt text. Consider the following ACD file:
integer: window [ standard: "Y" default: "10" minimum: "5" maximum: "100" ]
The user would be prompted as follows:
-window : Enter a number :
Though adequate this is not entirely friendly. You can set the prompt for a datatype definition by using the
information:attribute. The ACD file would then look like this:
integer: window [ standard: "Y" default: "10" minimum: "5" maximum: "100" information: "Window size" ]
This will give the following as the prompt.
Window size :
which is much more meaningful.
So far you have only described the value of
"Y" after a parameter or qualifier definition. However, negation (specifying, indirectly, a value of
"N") often finds a use in ACD files. Take a simple example:
sequence: sequence [ parameter: "Y" ] integer: n [ standard: "@($(sequence.length) > 100)" ]
standard: attribute i.e. being set to
"Y" if the sequence length is greater than 100 or
N otherwise. Although a value of
"N" should never be specified explicitly after
additional:, calculated values that evaluate to
"N" are in fact supported for the qualifiers (but not parameters). In such cases, the
"N" overrides the default behaviour of the attributes such that prompting for a value will be turned off. This is useful in some situations. In this case, the calculation will switch a prompt on only if the sequence length is greater than 100.
Now let us assume that your application can produce both graphic and textual output. Assume further that you only want textual output if the user hasn't selected graphical output. First you would set up a
toggle ACD datatype definition as follows:
toggle: plot [ standard: "Y" default: "N" information: "Plot a graph" ]
The value of
$(plot) will be
"Y" if the user adds
-plot to the command line. The value is
N if either the user doesn't add anything to the command line or if the user adds
-noplot to the command line.
The output file can now be defined as:
outfile: outfile [ standard: "@(!$(plot))" ]
This becomes equivalent to
standard: "Y" only if
plot is not true. The negation operator (
!) is a calculation so the term must be surrounded by
The only sad thing about this is that it doesn't work as written but not for any reason involving the logic. The reason is because EMBOSS handles file input/output operations in a different manner to other datatypes. If it sees one of the file (e.g.
outfile) or sequence (e.g.
seqout) definitions it will always try and open it.
If the term equates to
standard: "N", and no filename has been specified on the command line or as a default (and you wouldn't normally specify a default name for an output file) then ACD parsing will try and open a file with no name. That would cause an error.
There is a way around this and that is to use the
nullok: attribute. So, a definition of
outfile that works is:
outfile: outfile [ standard: "@(!$(plot))" nullok: "Y" ]
nullok: attribute above means that it's OK to continue (do not generate an error) if no filename is given.
If you run an ACD file (for instance, testing it by using acdc (Section 22.214.171.124, “acdc”) with calculated values for
standard:, you will see a warning message of the type
Calculated standard value for qualifier . The use of calculations in this way is supported but is only recommended if absolutely necessary. This is because it can confuse the comprehension of application inputs by, for instance, third party interfaces.
QualifierName in section
Calculations should not be used to set the value of a
parameter:: an error will be generated during ACD processing if you do. Parameters are taken to be essential inputs to the application. In contrast, calculations can be used to control the prompting for qualifiers (whether standard, additional or advanced).
The ACD syntax provides two datatypes (
Toggle) that have boolean values.
Boolean is a standard boolean datatype whereas a
toggle is a special type of boolean datatype that is used exclusively to control the prompting of other attributes.
In the ACD file below, an application with two parameters and an advanced qualifier (
Boolean datatype is shown.
abool might conceivably be used to set verbose or terse text in the output file, though it would be given a more intuitive name.
application: seqdemo [ documentation: "Demo application" ] sequence: asequence [ parameter: "Y" ] boolean: abool [ default: "Y" ] outfile: outfile [ parameter: "Y" ]
The application could be invoked in either of the following ways:
In the first example the boolean qualifier
abool is set to
True and verbose output (or some other behaviour) would be set. In fact, the value needn't have been set explicitly since the default value is
True. In the second command line
abool is set to
False using the prefix
Care should be taken over the definition of the
help: global attributes for
boolean datatypes. These are used to prompt the user (interactively or via a GUI) and to provide help text. The text provided in each case should reflect the expected default value of the boolean option, which may be the opposite of what the name implies. For example, if set to "Y" by default, then the command line option would typically be "
Flag is the qualifier. If set to "N" by default, then the default action may be the opposite of what the information or help text implies. If the value is calculated then the user may need some extra guidance.