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.

#argc := arg // get argument count

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

var0, var1

the name of the variable to store the arguments in.

/Variable

mandatory option.

/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.

#nCopiedArgs := ARG arg0 def0 [ arg1 def1 ... ] /Variable /Setdefaultvalues [ /Index=iarg ]

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 aformentioned ARG /Variable.

varX - the name of the variable to store the arguments in. If /Index does not specify otherwise, the value of argument 0 is stored in var0, the value of argument 1 is stored in var1, and so on.

/Variable - mandatory option.

/Setdefaultvalues - mandatory option.

/Index=iarg - if iarg is specified, var0 is set to the value of the argument referenced by iarg, var1 is set to the value of the argument referenced by iarg+1, and so on.

#nChangedArgs := ARG arg0 [ arg1 arg2 ... ] /Replace [ /Variable ] [ /Index=iarg ]

Replace the macro's arguments with the values specified in the ARG command (e.g. arg0 will replace the first argument, arg1 will replace the second argument, and so on).

If /Variable is specified, the arguments to the ARG command will be taken as the names of variables whose contents will replace the respective macro arguments. If, on the other hand, /Variable is omitted, the arguments to ARG themselves will replace the respective macro arguments.

If option /Index=iarg is specified, with iarg being an integer not less than zero, the first macro argument to be replaced will be the (iarg+1)th macro argument, that is the macro argument whose zero-based index is iarg. If "/Index" is omitted, replacement will start with the first macro argument.

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 "THREE".

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. (Both "insert" and "index" start with an "i", you see.)

#rc := ARG /Testoption oname [odefaultvalue]

Tests if option oname is set. It will return the value of option oname, if this option 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 odefaultvalue, if supplied, or the empty string otherwise.

#value := ARG /Getoption oname [odefaultvalue]

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

/Options

This command detects and decodes options in the command string passed to a macro. An ARG command with this option must be executed, before macro options can be tested (see /Testoption) or retrieved (see /Getoption).

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.

See also

macro header, READVAR, SHIFT

Examples

See the example script argument_parsing_example.sts for working examples.