Programmer Guide/Command Reference/ARG

ARG

#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 /Setdefault [ /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.

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

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

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.

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

See the script argument_parsing_example.sts for working examples.