Programmer Guide/Command Reference/ARG

ARG

Introduction

This command processes macro arguments. It may be used for retrieving information about arguments supplied to a STx macro (e.g. their number); for retrieving the macro arguments themselves; and for processing macro arguments used as options (e.g. /Option=value or /Switch); and for altering the arguments supplied to a macro.

Usage

#nArgs := ARG

Returns the number of arguments parsed to the current macro.

#argX := ARG iArg

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

#nCopiedArgs := ARG var0 var1 var2 /Variable [ /Index=iarg ] [ /Delete ]

Copies the values of the arguments passed to the macro to the respective variables var0, var1, and so on.

If you supply more variables than there are macro arguments, the surplus variables will not be touched, keeping whatever value they had before executing the ARG command. If this is not what you want, you may use the /Delete argument: With /Delete being supplied, the contents of all surplus variables will be cleared.

If you supply less variables than there are arguments, the surplus arguments will be ignored.

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.

/Delete - delete contents of variables first. If you do not use this option, any surplus variables, i.e. variables without a corresponding macro argument, will be left untouched, meaning that they will keep whatever value they had before executing the ARG command.

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

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

Note

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.

Global options for this command

/Options

decode options (what, exactly, does this do?)

Examples

See the example script argument_parsing_example.sts for working examples.