INCLAN: syntax

Synopsis

syntax format

Description

Analyzes the command line parameters of the current macro. This statement can only be called within a macro. Command line parameters that match with one of the format specifications are removed from the list of command line parameters and assigned to a new local variable.

The possible format items are:

name=[=]type[=default]

Declares a named parameter with the given name, type and, optionally, default value. If the default value is absent, the parameter is required, and an error will occur if the parameter is not specified in the macro call. A local variable with the given name is created, and either the value specified by the user, or, in its absence, the default value is assigned to it. The value must be compatible with the given type (see below). In a macro call, a named parameter can either be specified anywhere in the parameter list in the form “name = value” or as a positional parameter of the form “value” at the same position in the parameter list as the corresponding format in the syntax statement. Only parameters that appear before “*” or “**” (see below) can be specified as positional parameters without giving their name. A name may contain an asterisk “*” to indicate how much it can be abbreviated. By default, all unambiguous abbreviations are allowed. If a name starts with an asterisk, then the corresponding parameter is a positional parameter that cannot be given in the form “name = value”. The optional second “=” sign after the name indicates that a parameter that matches name but does not contain an “=” sign is not recognized, otherwise (with only one “=” sign after name), an error occurs in this situation.

name

Declares a literal option with the name. A local variable with the given name is created. If the option name is present in the macro call this variable is set to 1 (i.e. the logical value “true”), otherwise it is set to 0 (“false”).

name₁|name₂ . . .

Declares a set of mutually exclusive literal options with the names name₁, name₂, etc. Local variables with the given names are created. If one of the option names is present in the macro call, the corresponding variable is set to 1 (i.e. the logical value “true”). The other variables are set to 0.

**

Allows for additional parameters that do not match with one of the formats.

*

Has the same meaning as “**” except that additional parameters must not contain an “=” sign.

Formats must not contain blanks.
A type can be one of the following:

*

Any character string.

@i

Integer expression.

@r

Real expression.

[l<[=]]@i[<[=]u]

Integer expression with the given lower and/or upper bounds.

[l<[=]]@r[<[=]u]

Real expression in with the given lower and/or upper bounds.

@ii

Integer range. The lower and upper bounds are available as name(1) and name(2), respectively. A range is given in the form l..u or l-u, where l and u denote the upper and the lower bound of the range. Either the lower bound or the upper bound can be omitted (“..u” or “l..”).

@rr

Real range, defined in the way as an integer range.

name₁|name₂. . .

List of mutually exclusive literals.

@f.extension

Filename that will be extended with the given extension, if necessary (extension can also be $name to denote the value of the preceding parameter name).

Examples

command read_file
  syntax format=asc|bin file=@f.$format weight=@r=1.0	
  ...
end

# The command read_file has three parameters.
# The first parameter (format) is required and
# can either be asc or bin, the second parameter
# (file) is also required and is a filename that
# will be given the extension .asc or .bin,
# depending on the chosen format, and the third
# parameter (weight) is an optional real number
# with default value 1.0.

read_file asc test

# Positional parameters and default value for
# weight. Equivalent to setting format=asc,
# file=test.asc and weight=1.0.

read_file file=test format=asc weight=2.0

# Named parameters in any order.