Programmer Guide/Command Reference/ARG

This command processes macro arguments. It may be used for ...

• retrieving information about arguments supplied to a STx macro (e.g. their number)
• retrieving the macro arguments themselves
• processing macro arguments used as options (e.g. /Option=value or /Switch)
• altering the arguments supplied to a macro.

Usage

ARG

Returns the number of arguments parsed to the current macro.

ARG iarg

iarg

argument index (≥0)

Returns the value of the argument addressed by the zero-based index iarg.

ARG var0 [var1 ...] /Variable [ /Index=iarg /Delete ]

var0, var1

the name of the variable to store the arguments in.

/Delete

delete contents of variables first (default=do not delete)

/Index=iarg

the index of the first argument to copy (default=0)

Copies the values of the arguments passed to the macro to the respective variables var0, var1, and so on. The command returns the number of copied arguments.

ARG var0 def0 [ var1 def1 ... ] /Variable /Setdefaultvalues [ /Index=iarg ]

var0, var1

the name of the variable to store the arguments in.

def0, def1

the default values to be assigned if an argument is not specified.

Sets the variables specified to the values of the arguments passed to the macro, using the specified default values if the argument is missing, and returns the number of copied arguments. In all other respects, this variant of the ARG command works just like the aforementioned ARG /Variable.

ARG arg0 [ arg1 ... ] /Replace [ /Variable /Index=iarg ]

arg0, arg1

replacement values for argument 0, 1, ..

/Variable

Is specified, the arguments arg0, ... command will be taken as the names of variables whose contents will replace the respective macro arguments. Otherwise, the arguments themselves will replace the respective macro arguments.

/Index=iarg

the index of first argument to replace (default=0)

Replace the macro's arguments with the values or the content of the variables specified in the command (e.g. arg0 will replace the first argument, arg1 will replace the second argument, and so on). The command returns the number of changed arguments

Example

If a macro is called with the three string arguments "one", "two", and "three", after executing ARG /Replace /Index=1 'SPONGE BOB', the macro will behave as if called with the three string arguments "one", "SPONGE BOB", and "trhree".

Note

• Replacing macro arguments will not change the values of any variables the macro arguments have been read into. If you want to change these, too, you need to redo argument parsing.
• As many many arguments will be changed as there are arguments supplied to the ARG command. If the ARG command is supplied less arguments than there are macro arguments, the surplus macro arguments will be left untouched. If the ARG command is supplied more arguments than there are macro arguments, the number of macro arguments will be increased in order to hold all arguments supplied to ARG.

ARG arg0 [ arg1 arg2 ... ] /Nsert [ /Variable ] [ /Index=iarg ]

This command works like the ARG /Replace command with the difference that it does not replace the old argument, but it shifts it (and all further arguments) to the right, thereby causing the supplied argument(s) to be inserted at the respective position.

Remark

This option is called /Nsert because the letter I was already used for the /Index argument.

ARG /Testoption oname [odefault]

Tests if macro option oname is set. It will return the value of the, if it is set to a value, or the constant 1 if the option is set, but no value is assigned. If the option is not set, the function will return odefault, if supplied, or the empty string otherwise.

ARG /Getoption oname [odefault]

retrieve the value of the macro option oname. If there is no such option set, or if no value is assigned to this option, the command will return odefault or, if not supplied, the empty string.

ARG /Options

This command detects and decodes options in the command string passed to a macro. It must be executed, before macro options can be tested (/Testoption) or retrieved (/Getoption). This /Option can also be supplied with any other ARG command.

Note

If no ARG /Options command is executed, macro options remain in the macro argumentstring and are treated like normal parts of the command string. Therefore this option should be applied very early in a macro using options.

See also

macro header, READVAR, SHIFT

Examples

See the example script argument_parsing_example.sts for working examples.