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:

Consider the following ACD file, for an application called helloworld, which defines two parameters, namely a string input (string datatype) and an output file (outfile datatype):

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 message.dat.

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 standard: or 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:

then 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:

will print 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 additional and 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 standard and parameter data definitions are always prompted for if they're not specified on the command line, therefore a default is useful but not essential.

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 minimum and maximum attributes:

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 [10]:

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 [10]:

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)"
]

The 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 parameter:, standard:, or 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"
]

The nullok: attribute above means that it's OK to continue (do not generate an error) if no filename is given.

The ACD syntax provides two datatypes (Boolean and 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 (abool) of 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 no.