ARG

From STX Wiki
Jump to navigation Jump to search

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 names of the variables to store the arguments in.
/Delete
delete contents of variables first (by default, variables for which no corresponding arguments are supplied, will keep their old content)
/Index=iarg
the index of the first argument to copy (default is 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 names of the variables to store the arguments in.
def0, def1
the default values to be assigned if an argument is omitted.

Stores the macro arguments to the respective variables varn, using the respective default value defn if an argument is missing. The command returns the number of arguments processed. 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
If this option is specified, the arguments arg0, … 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 "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.

Note
  • 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. If the respective option is set to a value, the command will return this value. If the option is set, but no value is assigned, the command will return the constant 1. 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). The option /Options can also be supplied with any other ARG command.

Note
If no ARG /Options command is executed, macro options remain in the macro argument string 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.