AidaDoc Wiki

Brought to you by: bdesgraupes

AidaHelp_7 Log in to Edit

Syntax of the aida command

This section contains information about the usage of the aida shell
command. In order to write an Aida file, all you need is a simple text
editor. When your file is ready, you will certainly want to convert it to some
target format: this is where the aida command comes in. It can be viewed
as a compiler which is able to read and interpret your Aida file and call
the appropriate drivers to perform the conversion. The aida command
can also be used to get information about the system or to display help about
the Aida syntax.

Syntax

The general syntax of the aida command is

    aida <subcommand> [options]

Depending on the subcommand several options and additional arguments may
have to be specified. They are documented in the following subsections.

All the subcommands and options can be abbreviated as long as they remain
unambiguous. For instance

    aida info version

can also be written as

    aida inf vers

or even the minimalist

    aida i ve

Global options

The global options are settings which apply to the aida command
itself, no matter which subcommand is invoked. They mostly concern
debugging and will be of interest only for developers.

Here are the currently supported global options:
the -d option sets the level of verbosity of the command. Its
value is a number between 0 (silent) and 3 (pedantic). the -q option sets verbosity to 0.
the -tl option enables tracing of the lexer's activity.
the -tp option enables tracing of the parser's activity.
the -x option tells aida not to delete the temporary files it
writes during processing. These files are written in a temporary location
(see the command aida info temp)
and are normally deleted when they are not used anymore. With the -x
option you can keep them for inspection. the -- option marks the end of the options.

There are also two standalone options:
the -h option prints a usage string. It is a shortcut for aida help.
the -v option returns the current version number of the
command. It is a shortcut for aida info version.

Subcommands

The currently available subcommands are convert, help, info, split.

The convert subcommand

The syntax of the convert subcommand is:

    aida convert [options] [file]

The available options are:
_-from_: the input encoding.
-output: the name of the output file. See details below.
_-prefix_: a file containing Tcl code to evaluate before starting the conversion
process. -target: the name of the target format.
_-to*_: the output encoding.

The last argument of the command line is the name of the Aida input file to
convert. If it is not specified, Aida reads from the standard input (stdin).

Available targets can be obtained with the command aida info targets.

Available encodings can be obtained with the command aida info encodings.

If the -output option is omitted, the result of the aida
convert command is written to the standard output (stdout). If this
option is explicitely set to an empty string, Aida builds the name of the
output file from the name of the input file by removing the extension and
replacing it by an appropriate extension depending on the target.
For instance, the following command:

    aida convert -targ latex -output "" foobar.aida

will write the output in a file named foobar.tex.
On the contrary, the following command:

    aida convert -targ latex foobar.aida

would write the output directly to the terminal window or the standard
output of the shell where the command is executed.

The help subcommand

The help subcommand is used to get help about the syntax of the
subcommands or about the markup language itself. Its syntax is:

    aida help [subcommand|keyword]

This means that it can be used without any additional argument, or followed
by the name of a subcommand, or by a keyword.

The currently supported keywords are:
_header_: this prints information about the parameters of the header section of an Aida file.
syntax: this prints information about the usage of tags in an Aida input file.

Here are a few examples (try them!):

    aida help
    aida help convert
    aida help help
    aida help header
    aida help syntax

The info subcommand

The syntax of the info subcommand:

    aida info arg

The arg argument can be:
_attributes_: print the values of all the target specific tag attributes.
configuration: print the configuration files (config.tcl, default.tcl) known to Aida in
the user and in the local domains. The returned list may be empty
depending on the installation's settings.
_encodings_: print the list of all the encodings available for the -from and -to options.
from: print the default input encoding. This is the default value for the option
-from. It can be set in configuration files.
_library_: print the path to the Aida Tcl library on the system.
path: print the list of directories visited by Aida when looking for a target
implementation.
_targets_: print the list of available targets.
temp: print the location of the directory where aida writes temporary files.
_to_: print the default output encoding. This is the default value for the option
-to. It can be set in configuration files.
variables: print the values of all the variables (global or target specific) known to
aida's Tcl interpreter.
_version*_: print the version number of the command.

In the case of the attributes, encodings, variables
keywords, the -q option can be useful in order to get a less
verbose output, or an output in a format easier to parse in a script.

Here are a few examples (try them!):

    aida info library
    aida info version
    aida info encodings
    aida info from
    aida info variables
    aida info -q variables

The split subcommand

The syntax of the split subcommand is:

    aida split [options] [file]

The available options are:
_-from_: the input encoding.
-level: the level at which splitting occurs. See details below.
_-output_: a format string to build the name of the output files. See details below.
-prefix: a file containing Tcl code to evaluate before starting the conversion
process.
_-target_: the name of the target format.
-to: the output encoding.

The last argument of the command line is the name of the Aida file to
convert. If it is not specified, aida reads from the standard input (stdin).

Available targets can be obtained with the command aida info targets.

Available encodings can be obtained with the command aida info encodings.

The -level option is a number indicating the section level
at which the splitting must be performed. For instance, if the value is 1,
the Aida file is split each time a new section declared with the tag
((s1 is met. If the value is 2, the Aida file is split each time a
new section declared with one of the tags ((s1 or ((s2 is
met, etc. One can thus specify values from 1 to 6. The default value is 1.

One can also specify a value 0 for the -level option: in that case, splitting occurs when an
((input tag is met rather than a section tag. This is the
difference between the ((input and the ((include tags:
the ((include tag is not considered as a splitting point.

The ((split)) tag can also be used to force a split
anywhere in an Aida file (no matter what the -level option is set
to).

The -output option lets you specify a format string used by Aida to
build the names of the split files. Its syntax is inspired by the formats
used
with the C function printf. When the aida split command is
executed, the output files are numbered sequentially: the numbers are
represented, in the format string, by symbols like %d. For instance,
one can specify the -output option like this:

    -output "foobar_%d"

This would cause the split files to be named "foobar_1", "foobar_2", etc.

The format obeys the same rules as with the printf function.
For instance, if the -output option is declared like this:

    -output "%02d_foobar"

the split files will be named "01_foobar", "02_foobar", etc.

One can also use a %x or a %o specifier for hexadecimal or
octal numbering respectively.

If the -output option is not specified, Aida uses a default format
string built by removing the extension of the input file, appending the
format specifier _%d and the appropriate extension depending on the
target.

Wiki: AidaHelp_1
Wiki: AidaHelp_6
Wiki: AidaHelp_8