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}}}}
-==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. <code>/Option=value</code> or <code>/Switch</code>)
+*altering the arguments supplied to a macro.
+==Usage==
+ ARG
+Returns the number of arguments parsed to the current macro.
-;<code>#nArgs := ARG</code>: Returns the number of arguments parsed to the current macro.
+ ARG <var>iarg</var>
-; <code>#argX := ARG <var>iArg</var></code>: Returns the value of the argument addressed by the zero-based index <var>iArg</var>.
+:;<var>iarg</var>:argument index (&ge;0)
-;<code>#nCopiedArgs := ARG <var>var0</var> <var>var1</var> <var>var2</var> /Variable [ /Index=iarg ] [ /Delete ]</code>: Copies the values of the arguments passed to the macro to the respective variables <code>var0</code>, <code>var1</code>, and so on.
+Returns the value of the argument addressed by the zero-based index <var>iarg</var>.
-:If you supply more variables than there are macro arguments, the surplus variables will <em>not</em> be touched, keeping whatever value they had before executing the <code>ARG</code> command. If this is not what you want, you may use the <code>/Delete</code> argument: With <code>/Delete</code> 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.
-:<code><var>varX</var></code> - the name of the variable to store the arguments in. If <code>/Index</code> does not specify otherwise, the value of argument 0 is stored in <var>var0</var>, the value of argument 1 is stored in <var>var1</var>, and so on.
-:<code>/Variable</code> - mandatory option.
-:<code>/Delete</code> - 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 <code>ARG</code> command.
-:<code>/Index=<var>iarg</var></code> - if iarg is specified, <code><var>var0</var></code> is set to the value of the argument referenced by <code><var>iarg</var></code>, <code><var>var1</var></code> is set to the value of the argument referenced by </code><var>iarg+1</var></code>, and so on.
-;<code>#nCopiedArgs := ARG <var>arg0</var> <var>def0</var> [ <var>arg1</var> <var>def1</var> ... ] /Variable /Setdefaultvalues [ /Index=<var>iarg</var> ]</code>: 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 aformentioned <code>ARG /Variable</code>.
-:<code><var>varX</var></code> - the name of the variable to store the arguments in. If <code>/Index</code> does not specify otherwise, the value of argument 0 is stored in <var>var0</var>, the value of argument 1 is stored in <var>var1</var>, and so on.
-:<code>/Variable</code> - mandatory option.
-:<code>/Setdefaultvalues</code> - mandatory option.
-:<code>/Index=<var>iarg</var></code> - if iarg is specified, <code><var>var0</var></code> is set to the value of the argument referenced by <code><var>iarg</var></code>, <code><var>var1</var></code> is set to the value of the argument referenced by </code><var>iarg+1</var></code>, and so on.
-;<code>#nChangedArgs := ARG <var>arg0</var> [ <var>arg1</var> <var>arg2</var> ... ] /Replace [ /Variable ] [ /Index=<var>iarg</var> ]</code>: Replace the macro's arguments with the values specified in the <code>ARG</code> command (e.g. <var>arg0</var> will replace the first argument, <var>arg1</var> will replace the second argument, and so on).
-:If <code>/Variable</code> is specified, the arguments to the <code>ARG</code> command will be taken as the names of variables whose <em>contents</em> will replace the respective macro arguments. If, on the other hand, <code>/Variable</code> is omitted, the arguments to <code>ARG</code> themselves will replace the respective macro arguments.
-:If option <code>/Index=<var>iarg</var></code> is specified, with <var>iarg</var> being an integer not less than zero, the first macro argument to be replaced will be the (<var>iarg</var>+1)th macro argument, that is the macro argument whose zero-based index is <var>iarg</var>. 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 <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.
-:;Note: 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> <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.
-:;Remark: This option is called <code>/Nsert</code> because the letter "i" was already used for the <code>/Index</code> argument. (Both "insert" and "index" start with an "i", you see.)
-;<code>#rc := ARG /Testoption oname [odefaultvalue]</code>: tests if option <code>oname</code> is set. It will return the value of option <code>oname</code>, if this option 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 <code>odefaultvalue</code>, if supplied, or the empty string otherwise.
-;<code>#value := ARG /Getoption oname [odefaultvalue]</code>: retrieve the value of the option <code>oname</code>. If there is no such option set, or if no value is assigned to this option, the command will return <code>odefaultvalue</code> or, if not supplied, the empty string.
-=== Global options for this command ===
+ ARG <var>var<sub>0</sub></var> [<var>var<sub>1</sub></var> &hellip;] /Variable [ /Index=<var>iarg</var> /Delete ]
+;<var>var<sub>0</sub></var>, <var>var<sub>1</sub></var>, &hellip;: the names of the variables to store the arguments in.
+;<code>/Delete</code>: delete contents of variables first (by default, variables for which no corresponding arguments are supplied, will keep their old content)
+;<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>var<sub>0</sub></code>, <code>var<sub>1</sub></code>, and so on. The command returns the number of copied arguments.
-;<code>/Options</code>: decode options (''what, exactly, does this do?'')
+ 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>.
-=== Examples ===
+ ARG <var>arg<sub>0</sub></var> [ <var>arg<sub>1</sub></var> &hellip; ] /Replace [ /Variable /Index=<var>iarg</var> ]
+;<var>arg<sub>0</sub>, arg<sub>1</sub></var>:replacement values for argument 0, 1, &hellip;
+;<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.
+;/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>.
+ 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> ]
+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.
+;Note:
+*This option is called <code>/Nsert</code> because the letter '''I''' was already used for the <code>/Index</code> argument.
+ 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.
+ ARG /Getoption <var>oname</var> [<var>odefault</var>]
+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
+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.
+==See also==
+[[Programmer_Guide/Source_code#Definition of Macros|macro header]], [[../READ|READVAR]], [[../SHIFT|SHIFT]]
+==Examples==
 See the example script <code>argument_parsing_example.sts</code> for working examples.
 <!-- C.G. 11.3.2011 -->
+<!-- A.N. 27.4.2011 -->

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