Programmer Guide/General Descriptions/Macro Environment: Difference between revisions
No edit summary |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
{{TODO}} <!-- macro variables (with no prefix) --> | |||
The following variables are reserved in the macro environment. | The following variables are reserved in the macro environment. | ||
| Line 10: | Line 11: | ||
When a macro, subroutine or member function is called, the variable <code>#ARGV</code> contains the argument string passed by the calling command. The command <code>READVAR</code> or (for macros only) the extended header format can be used to separate the arguments. | When a macro, subroutine or member function is called, the variable <code>#ARGV</code> contains the argument string passed by the calling command. The command <code>READVAR</code> or (for macros only) the extended header format can be used to separate the arguments. | ||
If a macro passes its environment to another macro (<code>MACROX</code>) or a subroutine (<code>GOSUBX</code>) the variables <code>#ARGV</code>, <code>#ARGC</code> and <code>#MAC</code> in its environment are changed! | If a macro passes its environment to another macro (<code>MACROX</code>) or a subroutine (<code>GOSUBX</code>) the variables <code>#ARGV</code>, <code>#ARGC</code> and <code>#MAC</code> in its environment are changed! | ||
<code>#MAC</code> - the macroname|labelname|classname | |||
The variable <code>#MAC</code> identifies the currently active macro <code>macroname</code>, the subroutine <code>labelname</code> or the member function <code>classname</code>. | The variable <code>#MAC</code> identifies the currently active macro <code>macroname</code>, the subroutine <code>labelname</code> or the member function <code>classname</code>. | ||
<code>#NEW</code> - newitemname | |||
If a <code>NEW</code> command creates a new item successfully, the name of the new item is assigned to the variable <code>#NEW</code>. To save the (e.g. automatically generated) name, it must be assigned to another variable before the next <code>NEW</code> command is executed. | If a <code>NEW</code> command creates a new item successfully, the name of the new item is assigned to the variable <code>#NEW</code>. To save the (e.g. automatically generated) name, it must be assigned to another variable before the next <code>NEW</code> command is executed. | ||
<code>#qarg</code> You may use #qarg in order to pass ARG-style arguments to another function without getting them distorted in any way. This sounds stupid, but consider what happens when calling a user-defined function, e.g. <code>HUGO</code>, with the statement "<code>HUGO $#argv</code>": if the ARG-style arguments you got contain whitespace, the function <code>HUGO</code> will end up with a different argument list than expected (and than the caller has passed to your function). | |||
If, on the other hand, you use the statement "<code>HUGO $#qargv</code>", the callee, <code>HUGO</code>, will get EXACTLY the same argument(s) as the function calling <code>HUGO</code> has been passed. | If, on the other hand, you use the statement "<code>HUGO $#qargv</code>", the callee, <code>HUGO</code>, will get EXACTLY the same argument(s) as the function calling <code>HUGO</code> has been passed. | ||
<code>#qargc</code> contains the number of ARG-style arguments passed to the current. See <code>#qarg</code> for details. | |||
<code>#READ</code> - the number of assigned variables | |||
The variable <code>#READ</code> is set to the number of assigned target-variables by any type of <code>READ</code> command. | The variable <code>#READ</code> is set to the number of assigned target-variables by any type of <code>READ</code> command. | ||
<code>#SHELL</code> - the new shell id | |||
When the command <code>SHELL</code> is used to start a new shell, the id of the started shell is stored in the variable <code>#SHELL</code> of the caller's environment (see also variable <code>SHELL</code>). | When the command <code>SHELL</code> is used to start a new shell, the id of the started shell is stored in the variable <code>#SHELL</code> of the caller's environment (see also variable <code>SHELL</code>). | ||
<code>#THIS</code> - the instance item name | |||
When a member function is called, the variable <code>#THIS</code> is set to the name of the instance item. | When a member function is called, the variable <code>#THIS</code> is set to the name of the instance item. | ||
Latest revision as of 15:35, 14 December 2017
This STx-related article may be outdated.
The following variables are reserved in the macro environment.
#ARGC - the number of arguments
If a macro is defined with the extended header format (see Macros and Classes), the number of arguments passed is assigned to this variable (otherwise the number of arguments can be found in the variable #read after READVAR #argv has been called). Note that #argc only contains the correct number of arguments if they are blank separated.
#ARGV - the argument string
When a macro, subroutine or member function is called, the variable #ARGV contains the argument string passed by the calling command. The command READVAR or (for macros only) the extended header format can be used to separate the arguments.
If a macro passes its environment to another macro (MACROX) or a subroutine (GOSUBX) the variables #ARGV, #ARGC and #MAC in its environment are changed!
#MAC - the macroname|labelname|classname
The variable #MAC identifies the currently active macro macroname, the subroutine labelname or the member function classname.
#NEW - newitemname
If a NEW command creates a new item successfully, the name of the new item is assigned to the variable #NEW. To save the (e.g. automatically generated) name, it must be assigned to another variable before the next NEW command is executed.
#qarg You may use #qarg in order to pass ARG-style arguments to another function without getting them distorted in any way. This sounds stupid, but consider what happens when calling a user-defined function, e.g. HUGO, with the statement "HUGO $#argv": if the ARG-style arguments you got contain whitespace, the function HUGO will end up with a different argument list than expected (and than the caller has passed to your function).
If, on the other hand, you use the statement "HUGO $#qargv", the callee, HUGO, will get EXACTLY the same argument(s) as the function calling HUGO has been passed.
#qargc contains the number of ARG-style arguments passed to the current. See #qarg for details.
#READ - the number of assigned variables
The variable #READ is set to the number of assigned target-variables by any type of READ command.
#SHELL - the new shell id
When the command SHELL is used to start a new shell, the id of the started shell is stored in the variable #SHELL of the caller's environment (see also variable SHELL).
#THIS - the instance item name
When a member function is called, the variable #THIS is set to the name of the instance item.
