Programmer Guide/Command Reference/ARG: Difference between revisions

Latest revision as of 09:20, 28 June 2017

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 var₀ [var₁ …] /Variable [ /Index=iarg /Delete ]

var₀, var₁, …: 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 var₀, var₁, and so on. The command returns the number of copied arguments.

ARG var₀ def₀ [ var₁ def₁ … ] /Variable /Setdefaultvalues [ /Index=iarg ]

var₀, var₁, …: the names of the variables to store the arguments in.
def₀, def₁: the default values to be assigned if an argument is omitted.

Stores the macro arguments to the respective variables var_n, using the respective default value def_n 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 arg₀ [ arg₁ … ] /Replace [ /Variable /Index=iarg ]

arg₀, arg₁: replacement values for argument 0, 1, …
/Variable: If this option is specified, the arguments arg₀, … 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 arg₀ [ arg₁ arg₂ … ] /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.

Examples

See the example script argument_parsing_example.sts for working examples.

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:{{SUBPAGENAME}}}}
-This command processes macro arguments. It may be used for ...
+This command processes macro arguments. It may be used for:
-:*retrieving information about arguments supplied to a {{STX}} macro (e.g. their number)
+* retrieving information about arguments supplied to a {{STX}} macro (e.g. their number)
-:*retrieving the macro arguments themselves
+* retrieving the macro arguments themselves
-:*processing macro arguments used as options (e.g. <code>/Option=value</code> or <code>/Switch</code>)
+* processing macro arguments used as options (e.g. <code>/Option=value</code> or <code>/Switch</code>)
-:*altering the arguments supplied to a macro.
+*altering the arguments supplied to a macro.
 ==Usage==
-;<code>ARG</code>: Returns the number of arguments parsed to the current macro.
+ ARG
+Returns the number of arguments parsed to the current macro.
-;<code>ARG <var>iarg</var></code>:
+ ARG <var>iarg</var>
 :;<var>iarg</var>:argument index (&ge;0)
-:Returns the value of the argument addressed by the zero-based index <var>iarg</var>.
+Returns the value of the argument addressed by the zero-based index <var>iarg</var>.
-;<code>ARG <var>var0</var> [<var>var1</var> ...] /Variable [ /Index=<var>iarg</var> /Delete ]</code>:
+ ARG <var>var<sub>0</sub></var> [<var>var<sub>1</sub></var> &hellip;] /Variable [ /Index=<var>iarg</var> /Delete ]
-:;<var>var0, var1</var>: the name of the variable to store the arguments in.
+;<var>var<sub>0</sub></var>, <var>var<sub>1</sub></var>, &hellip;: the names of the variables to store the arguments in.
-:;/Delete: delete contents of variables first (default=do ''not'' delete)
+;<code>/Delete</code>: delete contents of variables first (by default, variables for which no corresponding arguments are supplied, will keep their old content)
-:;/Index=<var>iarg</var>: the index of the first argument to copy (default=0)
+;<code>/Index=<var>iarg</var></code>: 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 <code>var0</code>, <code>var1</code>, and so on. The command returns the number of copied arguments.
+Copies the values of the arguments passed to the macro to the respective variables <code>var<sub>0</sub></code>, <code>var<sub>1</sub></code>, and so on. The command returns the number of copied arguments.
+ ARG <var>var<sub>0</sub></var> <var>def<sub>0</sub></var> [ <var>var<sub>1</sub></var> <var>def<sub>1</sub></var> &hellip; ] /Variable /Setdefaultvalues [ /Index=<var>iarg</var> ]
+;<var>var<sub>0</sub></var>, <var>var<sub>1</sub></var>, &hellip;: the names of the variables to store the arguments in.
+;<var>def<sub>0</sub></var>, <var>def<sub>1</sub></var>: the default values to be assigned if an argument is omitted.
+Stores the macro arguments to the respective variables <var>var<sub>n</sub></var>, using the respective default value <var>def<sub>n</sub></var> if an argument is missing. The command returns the number of arguments processed. In all other respects, this variant of the <code>ARG</code> command works just like the aforementioned <code>ARG /Variable</code>.
-;<code>ARG <var>var0</var> <var>def0</var> [ <var>var1</var> <var>def1</var> ... ] /Variable /Setdefaultvalues [ /Index=<var>iarg</var> ]</code>:
+ ARG <var>arg<sub>0</sub></var> [ <var>arg<sub>1</sub></var> &hellip; ] /Replace [ /Variable /Index=<var>iarg</var> ]
-:;<var>var0, var1</var>: the name of the variable to store the arguments in.
+;<var>arg<sub>0</sub>, arg<sub>1</sub></var>:replacement values for argument 0, 1, &hellip;
-:;<var>def0, def1</var>: the default values to be assigned if an argument is not specified.
+;<code>/Variable</code>: If this option is specified, the arguments <var>arg<sub>0</sub></var>, &hellip; will be taken as the names of variables whose <em>contents</em> will replace the respective macro arguments. Otherwise, the arguments themselves will replace the respective macro arguments.
-: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 <code>ARG</code> command works just like the aforementioned <code>ARG /Variable</code>.
+;/Index=<var>iarg</var>: 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. <var>arg0</var> will replace the first argument, <var>arg1</var> 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 <code>ARG /Replace /Index=1 'SPONGE BOB'</code>, the macro will behave as if called with the three string arguments "one", "SPONGE BOB", and "three".
+;Note:
+*Replacing macro arguments will <em>not</em> 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 <code>ARG</code> command. If the <code>ARG</code> command is supplied <em>less</em> arguments than there are macro arguments, the surplus macro arguments will be left <em>untouched</em>. If the <code>ARG</code> command is supplied <em>more</em> arguments than there are macro arguments, the number of macro arguments will be increased in order to hold <em>all</em> arguments supplied to <code>ARG</code>.
-;<code>ARG <var>arg0</var> [ <var>arg1</var> ... ] /Replace [ /Variable /Index=<var>iarg</var> ]</code>:
+ ARG <var>arg<sub>0</sub></var> [ <var>arg<sub>1</sub></var> <var>arg<sub>2</sub></var> &hellip; ] /Nsert [ /Variable ] [ /Index=<var>iarg</var> ]
-:;<var>arg0, arg1</var>:replacement values for argument 0, 1, ..
+This command works like the <code>ARG /Replace</code> 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 <em>inserted</em> at the respective position.
-:;/Variable: Is specified, the arguments <var>arg0, ... </var> command will be taken as the names of variables whose <em>contents</em> will replace the respective macro arguments. Otherwise, the arguments themselves will replace the respective macro arguments.
+;Note:
-:;/Index=<var>iarg</var>: the index of first argument to replace (default=0)
+*This option is called <code>/Nsert</code> because the letter '''I''' was already used for the <code>/Index</code> argument.
-:Replace the macro's arguments with the values or the content of the variables specified in the command (e.g. <var>arg0</var> will replace the first argument, <var>arg1</var> 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 <code>ARG /Replace /Index=1 'SPONGE BOB'</code>, the macro will behave as if called with the three string arguments "one", "SPONGE BOB", and "trhree".
-:;Note:
-:*Replacing macro arguments will <em>not</em> 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 <code>ARG</code> command. If the <code>ARG</code> command is supplied <em>less</em> arguments than there are macro arguments, the surplus macro arguments will be left <em>untouched</em>. If the <code>ARG</code> command is supplied <em>more</em> arguments than there are macro arguments, the number of macro arguments will be increased in order to hold <em>all</em> arguments supplied to <code>ARG</code>.
+ ARG /Testoption <var>oname</var> [<var>odefault</var>]
+Tests if macro option <var>oname</var> 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 <code>1</code>. If the option is ''not'' set, the function will return <var>odefault</var>, if supplied, or the empty string otherwise.
-;<code>ARG <var>arg0</var> [ <var>arg1</var> <var>arg2</var> ... ] /Nsert [ /Variable ] [ /Index=<var>iarg</var> ]</code>: This command works like the <code>ARG /Replace</code> 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 <em>inserted</em> at the respective position.
+ ARG /Getoption <var>oname</var> [<var>odefault</var>]
-:;Remark: This option is called <code>/Nsert</code> because the letter '''I''' was already used for the <code>/Index</code> argument.
+retrieve the value of the macro option <var>oname</var>. If there is no such option set, or if no value is assigned to this option, the command will return <var>odefault</var> or, if not supplied, the empty string.
+ ARG /Options
-;<code>ARG /Testoption <var>oname</var> [<var>odefault</var>]</code>: Tests if macro option <var>oname</var> is set. It will return the value of the, if it is set to a value, or the constant <code>1</code> if the option is set, but no value is assigned. If the option is '''not''' set, the function will return <var>odefault</var>, if supplied, or the empty string otherwise.
+This command detects and decodes options in the command string passed to a macro. It must be executed before macro options can be tested (<code>/Testoption</code>) or retrieved (<code>/Getoption</code>). The option <code>/Options</code> can also be supplied with any other <code>ARG</code> command.
+;Note: If no <code>ARG /Options</code> 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.
-;<code>ARG /Getoption <var>oname</var> [<var>odefault</var>]</code>: retrieve the value of the macro option <var>oname</var>. If there is no such option set, or if no value is assigned to this option, the command will return <var>odefault</var> or, if not supplied, the empty string.
-;<code>ARG /Options</code>: 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 <code>ARG</code> command.
-:;Note:
-:If no <code>ARG /Options</code> 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==

Programmer Guide/Command Reference/ARG: Difference between revisions

Latest revision as of 09:20, 28 June 2017

Usage

See also

Examples

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools