EMBOSS includes six utilities that are used for debugging and testing ACD files. They are used to run, test and document an ACD file without the need to write the C source code for the program itself:
Reads and processes an ACD file, prompting the user as necessary in exactly the same way as if the application was running. If it encounters an error it will terminate. This allows the behaviour of the command line interface to be tested under different conditions, even if the application itself has not yet been written. It is the most widely used utility and is the basic tool for testing that an ACD file works correctly.
Works the same as acdc but reports the processing of lines in an ACD file. It also prints the results of evaluating any variables and operations in the ACD file (see Section 4.4, “Operations”).
Processes an ACD file and reports any errors or warnings caused by incorrect, deprecated or obsolete syntax. The tests go above and beyond those of acdc and acdtrace. It enforces recommendations for parameter and qualifier naming, and highlights ACD syntax that might cause problems to third party parsing software.
Processes an ACD file and user input while logging the contents of internal data structures. For the time being its use is deprecated and the entrails application (see below) should be used instead.
Generates a correctly formatted ACD file from one which is parsable but which is partly or incorrectly formatted.
Is used to create the table of parameters, allowed values and defaults, used in the application documentation and to provide user help.
The utilities do not have options of their own. They are all invoked in the same way; by specifying the name of the application to be tested along with any command line options after the name of the utility application itself:
UtilityName |
For example, this would test the ACD file of an application called helloworld:
acdc helloworld |
acdc, acdtrace and acdlog will run the command line interface of any EMBOSS program by reading its ACD file and processing the command line and user responses in exactly the same way as if the true program itself were running. The user is prompted for any required values for application parameters and any input files are read. The application proper is not run, it is only the ACD file that is read.
Any command line options can be specified. In the following, seqret is being called to retrieve region 50 - 100 from a sequence (sequence.in) and write the fragment to the output file (sequence.out):
acdc seqret sequence.in sequence.out -sbegin 50 -send 100 |
All EMBOSS applications call the NUCLEUS function embInit (or for EMBASSY applications embInitP) which makes further calls to ACD file processing functions. The utility applications pass any arguments (i.e. the command line for the application being tested) to embInit or embInitP and so run exactly like the native application.
Output files can be specified in any available format however they will be empty (the application code is not called so there will be no output).
The utilities can use all the global qualifiers (see the EMBOSS Users Guide):
-autoTurns off any prompting of the user. It is always useful to test an application with the -auto option because this emulates the condition of the application being called by a script or some other way that doesn't involve interactive user input.
-debugTurns on debugging. This outputs the parameters associated with calls to the AJAX function ajDebug.
-filterReads from stdin and writes to stdout and implies -auto.
-stdoutWrites by default to stdout, but still prompts the user.
-helpWill give usage information for the utility.
-verboseWhen used with -help also gives the associated qualifiers and the global qualifiers.
-warningProgram will generate warning messages if necessary.
-errorProgram will generate error messages if necessary.
-fatalProgram will generate fatal error (termination) messages if necessary.
None of the utilities themselves will generate debugging, warning, error or fatal messages. However, because input files can be read, any debug calls or messages made by the input functions will be reported.
acdc reads and processes an ACD file, prompting the user as necessary in exactly the same way as if the application was running. If it encounters an error it will terminate. This allows the behaviour of the command line interface to be tested under different conditions, even if the application itself has not yet been written. It is the most widely used utility and is the basic tool for testing that an ACD file works correctly.
acdc does not have its own options, but takes a single parameter which is the name of the EMBOSS application that is being tested. It is invoked by specifying the name of the application to be tested along with any command line options after the name of the utility application itself:
acdc |
Any command line options for the application can be specified. The user is prompted for any required values for application parameters and any input files are read. The application proper is not run, it is only the ACD file that is read.
acdc will use any data files specified in the ACD file of the specified program, but will ignore any data files that are only used directly by the program's code. EMBOSS data files are distributed with the applications and stored in the standard EMBOSS data directory (see the EMBOSS Users Guide).
Output files can be specified in any available format however they will be empty (the application code is not called so there will be no output).
Here is a sample session with acdc:
%acdc antigenicFinds antigenic sites in proteins Input protein sequence(s): tsw:act1_fugru Minimum length of antigenic region [6]: Output report [act1_fugru.antigenic]:
acdtrace works the same as acdc but reports the processing of lines in an ACD file. It also prints the results of evaluating any variables and operations in the ACD file (see Section 4.4, “Operations”).
It is invoked as follows:
acdtrace |
acdtrace will run the command line interface of any EMBOSS program by reading its ACD file and processing the command line and user responses in exactly the same way as if the true program itself were running. Any command line options for the application being called can be specified. The user is prompted for any required values for application parameters and any input files are read. The application proper is not run, it is only the ACD file that is read.
Output files can be specified in any available format however they will be empty (the application code is not called so there will be no output).
acdtrace will use any data files specified in the ACD file of the specified program, but will ignore any data files that are only used directly by the program's code. EMBOSS data files are distributed with the applications and stored in the standard EMBOSS data directory (see the EMBOSS Users Guide).
Here is a sample session with acdtrace:
%acdtrace antigenicFinds antigenic sites in proteins Input protein sequence(s): tsw:act1_fugru Minimum length of antigenic region [6]: Output report [act1_fugru.antigenic]:
The output on screen (not shown) can look a little confusing but is by far the best way to see how variables and operations work in your ACD file.
acdvalid processes an ACD file and reports any errors or warnings caused by incorrect, deprecated or obsolete syntax. The tests go above and beyond those of acdc and acdtrace. It highlights ACD syntax that might cause problems to third party parsing software which wrap the EMBOSS applications.
acdvalid validates an ACD file, testing many features which will not prevent an application from running, but which may create problems for any user interfaces, whether on the command line or through use of a wrapper. Most of the messages from acdvalid are warnings and do not prevent a program from running.
It is invoked as follows:
acdvalid |
acdvalid will, like acdtrace, run the command line interface in exactly the same way as if the true program itself were running.
It will use any data files specified in the ACD file of the specified program, but will ignore any data files that are only used directly by the program's code. EMBOSS data files are distributed with the application and stored in the standard EMBOSS data directory (see the EMBOSS Users Guide).
Output files can be specified in any available format however they will be empty (the application code is not called so there will be no output).
Here is a sample session with acdvalid:
%acdvalid antigenic
acdvalid generates both error and warning messages. If the message is an "Error" then the ACD file will not work and requires fixing. If the message is a "Warning" then the ACD file will work, although it is worth trying to fix the problem.
Warning messages are only advisory, but as many warnings as possible are fixed for any application in the main release.
It is worth running acdvalid on all local ACD files with each new version of EMBOSS, because extra validation tests are added with each new release.
These include:
Section and subsection names (Section 4.1.5, “ACD File Sections”) are defined in the EMBOSS system file sections.standard.
Sections are in the correct order of "input", "required", "additional", "advanced" and "output".
Section definitions use a standard information: attribute.
This ensures that interface wrappers will have a consistent description when using sections to group application parameters.
All data definitions are contained in a section or subsection.
Parameters that are restricted to one section are in the correct section.
All input ACD datatypes (Section A.2.2, “Description of Input ACD Datatypes”) must be in the "input" section and all output ACD datatypes (Section A.2.3, “Description of Output ACD Datatypes”) are in the "output" section
Other parameters are valid in the section in which they appear.
For example the "advanced" section cannot include parameters that might be prompted for, which excludes data definitions with a parameter:, standard: or additional: attribute set (parameters, and standard and additional qualifiers). The "additional" section can only have qualifiers whose additional: attribute is set, or toggle objects which control them.
Calculations are not used to set the value of a parameter: attribute.
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).
If a value for the group: attribute in the application definition of the ACD file is used, that it is defined in the file groups.standard.
Calculated values are not typically used for standard:
If an ACD file has calculated values for standard:, a warning message (Calculated standard value for qualifier ) is reported. The use of calculations in this way is supported but is only recommended if absolutely necessary, because it may confuse comprehension of application inputs by, for instance, third party interfaces.QualifierName in section SectionName
Calculated values (see Section 4.5, “Controlling the Prompt”) for the standard: and additional: attributes can use toggle datatype values but not boolean
This allows interface wrappers can use toggle values to split an application into 2 or more simpler definitions.
parameter:, standard: and additional: attribute values are not set explicitly to "N" (the default)
This confuses parsers. You should never explicitly specify Parameter: "N", Standard: "N" or Additional: "N". 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”).
Some datatypes, where defined in an ACD file, are typically the primary input or output of an EMBOSS application and, as such, should be defined as a parameter by using the parameter: attribute. The datatypes include:
Alignment output (align: datatype)
Sequence features for input (features datatype) and output (featout datatype).
File datatypes for input (infile, filelist, directory or dirlist datatypes) and output (outdir).
Application report output (report: datatype).
Sequence inputs (sequence, seqall, seqsetall or seqset datatypes).
The first data definition for any of the datatypes above must be defined as a parameter using the parameter: attribute. It is recommended that subsequent definitions of that datatype (second, third and so on) are also defined as parameters. The exception is if the default: or nullok: attributes are set, in which case no warning or error messages are generated as the application can run with a default or without any value for the definition.
Parameter and qualifier names (data definition flags) match an accepted standard (Section 4.1, “Introduction to ACD File Development”)
For example all sequence input should end in "sequence" so that short forms (e.g. -aseq, -bseq etc) can be used on the command line. A warning message will explain what the standard requires if an error is made.
ACD definitions for alignment output, feature input and output, file inputs and outputs, report output, and sequence inputs and outputs (seqout, seqoutall, seqoutset datatypes) should have standard names (Section 4.1.4, “Parameters and Qualifiers”).
Where the knowntype: attribute is specified, the value matches a standard name defined for the appropriate datatype in the EMBOSS system file knowntypes.standard, or matches an accepted standard format for the datatype.
A few values not in knowntypes.standard are accepted, for example "ApplicationName output" for an outfile: datatype. These are documented with the datatypes (Section A.5, “Datatype-specific Attributes”).
acdvalid reports a warning message for data definitions that require but do not have a value for the knowntype: attribute.
These include any output files (outfile datatype) or directories (outdir), and the string datatypes.
EMBOSS must be able to discern the type of the feature input and output. If no type is specified (using the type: attribute) for a feature or featout definition and there is no sequence input from which to take a default type, then an error will be generated.
EMBOSS must also be able to discern the type of the sequence output. If no type is specified (using the type: attribute) for an output sequence (seqout, seqoutset or seqoutall definition) and there is no sequence input from which to take a default type, then an error will be generated.
Datatypes with standard prompts should not have information: or prompt: attributes (see Section A.4, “Global Attributes”).
To provide standard prompts, a default value for the information: string is defined for most common datatypes. The defaults are in the EMBOSS system file codes.english.
The text given after the help:, information: and prompt: attributes should conform to the following conventions:
The string should start with an uppercase, alphabetic character.
The string should not end with a full-stop.
Any seqset or seqsetall datatype must have the aligned: attribute set.
acdlog processes an ACD file and user input, while logging the contents of internal data structures. For the time being its use is deprecated and the entrails application (Section 4.6, “ACD Utilities”) should be used instead.
It is invoked as follows:
acdlog |
Like acdtrace, acdlog will run the command line interface in exactly the same way as if the true program itself were running.
Output files can be specified in any available format, however they will be empty (the application code is not called so there will be no output).
acdpretty will generate a correctly formatted ACD file from one which is parsable but which is partly or incorrectly formatted.
acdpretty reads an ACD file and rewrites it with clean formatting to the file:
(ProgramName).acdpretty |
which can be used to overwrite the original ACD file. All sections and attributes will be indented. All values will be quoted. Lines will be wrapped at a reasonable width. The output file is intended as a standard format for parsers used by GUIs and other interface wrappers, rather than using the original ACD file directly.
It is invoked as follows:
acdpretty |
Any command line parameters that might normally be specified for the application are essentially ignored as processing stops once the reformatted ACD file is printed. A few of the global qualifiers have the potential to conflict with the function of acdpretty.
acdtable is used to create the table of parameters, allowed values and defaults used in the application documentation and to provide user help.
It is invoked as follows:
acdtable |
Acceptable expected and default values can be generated automatically for most ACD datatypes. In other cases the allowed value is defined with the valid: global attribute, and the default value by the expected: global attribute (see Section A.4, “Global Attributes”).
In addition to the utilities, entrails will report the internals of data structures used to parse the ACD file. It reports:
Details of all known ACD datatypes
Details of all known ACD attributes
Details for all calculated attributes
Internal data structures for sequence access methods
Internal data structures for sequence reading and writing
Internal data structures for feature handling
Internal data structures for alignments
Internal data structures for application reports
Internal data structures for codon usage tables
Report of the database attributes available
Report of the resource attributes available
entrails is not compiled in a standard EMBOSS installation because it is in the "make check" section of the Makefile.am file.
To compile the "check_PROGRAMS" applications, type:
make check |
from the applications directory. If for some reason that fails (the section is after all reserved for applications that are in active development) edit the Makefile.am files accordingly so that entrails.c is treated as a normal application, and compile it as usual. For further information see Section 1.2, “Installation of CVS (Developers) Release”.