Programmer Guide/Command Reference/MACRO: Difference between revisions
No edit summary |
No edit summary |
||
| (One intermediate revision by the same user not shown) | |||
| Line 2: | Line 2: | ||
MACRO <var>macroname</var> <var>macroarguments</var> | MACRO <var>macroname</var> <var>macroarguments</var> | ||
The <code>MACRO</code> command executes the macro (i.e., the subroutine) specified by <var>macroname</var>, passing | The <code>MACRO</code> command executes the macro (i.e., the subroutine) specified by <var>macroname</var>, passing it the arguments specified by <var>macroarguments</var>. The macro will be started in its own variable environment that is set up as a ''copy'' of the environment of the caller. This means that the subroutine gets a copy of all local variables and is free of modifying them, but that any such modification is local to the subroutine and will get lost after its execution. Hence, your subroutine will never be able to alter (or, damage) the local variables of the caller (for a different behaviour, see below, or directly refer to the {{STX}} statements <code>[[Programmer_Guide/Command_Reference/MACROX|MACROX]]</code>, and <code>[[Programmer_Guide/Command_Reference/SHELL|SHELL]]</code>). | ||
The sourc file containing the macro <var>macroname</var> must be loaded (see the <code>[[User Guide/Workspace/Pre-configured profiles|LOAD]]</code> command). The <var>macroarguments</var> passed to the macro are stored in the variable <code>#ARGV</code> of the called macro. Because of the special command-line processing in {{STX}}, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from <var>macroarguments</var> before it is assigned to <code>#ARGV</code>. For more information on argument passing, and parsing, see [[Programmer_Guide/Concepts/Argument_Passing|Argument Passing]]. For a broader information on macro programming, see [[XXX|Script Programming in {{STX}}]]. | The sourc file containing the macro <var>macroname</var> must be loaded (see the <code>[[User Guide/Workspace/Pre-configured profiles|LOAD]]</code> command). The <var>macroarguments</var> passed to the macro are stored in the variable <code>#ARGV</code> of the called macro. Because of the special command-line processing in {{STX}}, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from <var>macroarguments</var> before it is assigned to <code>#ARGV</code>. For more information on argument passing, and parsing, see [[Programmer_Guide/Concepts/Argument_Passing|Argument Passing]]. For a broader information on macro programming, see [[XXX|Script Programming in {{STX}}]] or [[Programmer_Guide/STx_Guru|Becoming an S_TOOLS-STx Guru (in 240.918 simple steps)]]. | ||
If you want to execute a subroutine in the variable environment of the caller (which is dangerous), you will enjoy the <code>[[Programmer_Guide/Command_Reference/MACROX|MACROX]]</code> command. If, on the other hand, you want to separate the subroutine even more thoroughly from your current environment, you may even have it executed by a separate instance of the {{STX}} shell, i.e. the {{STX}} command interpreter, by using the <code>[[Programmer_Guide/Command_Reference/SHELL|SHELL]]</code> command for executing the subroutine. | If you want to execute a subroutine in the variable environment of the caller (which is dangerous), you will enjoy the <code>[[Programmer_Guide/Command_Reference/MACROX|MACROX]]</code> command. If, on the other hand, you want to separate the subroutine even more thoroughly from your current environment, you may even have it executed by a separate instance of the {{STX}} shell, i.e. the {{STX}} command interpreter, by using the <code>[[Programmer_Guide/Command_Reference/SHELL|SHELL]]</code> command for executing the subroutine. | ||
Latest revision as of 15:58, 25 April 2014
MACRO macroname macroarguments
The MACRO command executes the macro (i.e., the subroutine) specified by macroname, passing it the arguments specified by macroarguments. The macro will be started in its own variable environment that is set up as a copy of the environment of the caller. This means that the subroutine gets a copy of all local variables and is free of modifying them, but that any such modification is local to the subroutine and will get lost after its execution. Hence, your subroutine will never be able to alter (or, damage) the local variables of the caller (for a different behaviour, see below, or directly refer to the STx statements MACROX, and SHELL).
The sourc file containing the macro macroname must be loaded (see the LOAD command). The macroarguments passed to the macro are stored in the variable #ARGV of the called macro. Because of the special command-line processing in STx, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from macroarguments before it is assigned to #ARGV. For more information on argument passing, and parsing, see Argument Passing. For a broader information on macro programming, see Script Programming in STx or Becoming an S_TOOLS-STx Guru (in 240.918 simple steps).
If you want to execute a subroutine in the variable environment of the caller (which is dangerous), you will enjoy the MACROX command. If, on the other hand, you want to separate the subroutine even more thoroughly from your current environment, you may even have it executed by a separate instance of the STx shell, i.e. the STx command interpreter, by using the SHELL command for executing the subroutine.
