Macros provide a way to execute a list of WIP commands repetitively. In much the same way, a programmer defines a subroutine which will do a particular task for different programs or different aspects of the same program. Hence, macros provide an easy way to tie together several plotting instructions under one name. Whenever this defined name is called, the commands associated with it are executed. Macros in WIP may be defined, edited, executed, and deleted. In fact, there always exists at least one defined macro: the command buffer .
Most of the commands that the user types are saved in a macro called the command buffer. There are a few commands, however, which do not typically need to be saved (e.g. echo , show , and help ). These commands are generally used diagnostically and not graphically. For the most part, WIP ``knows'' which commands to save and which to not save in the command buffer. If a command is not saved, it may still be stored in the command buffer by explicitly entering it using the insert command (see Section 7.4).
As an example of which commands are typically saved and which commands are not, suppose that during a typical WIP interactive session a user typed the following commands:
The sections that follow will explain how to define macros; pass arguments into the macros; edit, execute, and remove macros. In Chapter 9, more advanced use of macros will be illustrated. Appendix A presents how to have macros automatically defined whenever WIP is started. Finally, Appendix E illustrates several examples of macro definitions and their uses.
Macros are created using the
define
command.
The define command has only one required argument: the macro name.
Macros may have any name as long as it does not conflict with any WIP\
command or any other previously defined macro.
Macro names
are case insensitive (i.e. MyLabel is considered the same macro
name as mylabel).
All valid commands entered after the define command are
inserted into the named macro.
When WIP receives a proper define command, the prompt changes to
DEFINE> to remind the user they are in definition mode,
and this prompt remains until the next
end
command terminates the definition.
Each command entered as part of the definition of a macro
is checked that it is either a valid command or another defined macro
and is then stored for later use.
For this reason, macros may not reference other macros that have not yet
been defined.
Of course, previously defined macros may be used within
another macro definition.
If a macro already exists with the same name as the macro being defined a warning is issued to the user and the previous definition is removed. The warning is issued to indicate to the user that a conflict of names exists and that the user should be careful that the proper macro is going to be used in the plot file.
There are 10 special arguments that may be used within the definition of a macro: $1, $2, ..., $9, and $0. When a macro is executed, any parameters following the macro name are assigned, in order, to the ten variables. Whenever a command in the macro references one of these variables, the command line parameter is substituted in its place. The input arguments to a macro are specified in the same fashion as when providing arguments to a command: tokens separated by white space or commas. And, as usual, arguments may be either numbers or text strings. If a requested argument is not found, the special argument is skipped. As an example of how to define a macro with arguments, consider the following example (remember the # character denotes the beginning of a comment that lasts until the end of the line):
Note also that, in the above example, the number of spaces separating the arguments in the first two calls to the macro does not matter. This is also true of the move command in the macro definition. However, in the label command, the spacing and location of the arguments is important! The macro command
An advanced feature of macro arguments is that of returned values. If used properly, a macro argument may be set in a macro and the new value ``returned'' at the end. In this way, internal counters for the loop command (see section 9.2) can be updated. Several examples of this technique are shown in the section containing sample plot files and figures (Appendix E). It is important to note that the macro argument that is used (and returned) is always a user variable (see Chapter 8) and never a literal value or string.
Notice that comments are used whenever possible in the macro definition, but are not present at the end of any text labeling command. A useful convention to follow is to identify the arguments to a macro in the definition of the macro and identify which user variables , if any, are changed or used by the macro. When working interactively, comments are ignored and are not saved in the command buffer. Working in INSERT mode, as well as when plot files are created external to WIP in an editor, will, however, retain what comments are typed. Hence if you define a macro externally or modify the plot file in an editor, you can place comments and label the inputs to the macro. This will greatly help you at a later time when you return to this macro and try to figure out what it does and what the inputs should be when calling it. Neither comments or identification of arguments are required, but like good programming, they are extremely valuable.
All macros, including the command buffer may be edited. The three commands used to edit a macro and the command buffer are described in the sections that follow. It should be understood that whenever the word macro is used in the discussions that follow, it includes all user defined macros and the command buffer.
Whenever a user edits a macro, the edit command usually requires a line number as an argument. The line number tells the edit command where in the macro to begin to edit. These line numbers are associated with the numbers presented whenever the macro is listed. The list command provides a way to display the contents of a macro.
Without any arguments, list will display the entire contents of the command buffer. Each command will be proceeded by a number representing the order it is executed. As the number of commands in a macro increases, this may make it difficult to ``see'' all the commands on your display.
If only one argument is given to the list command, it is assumed to be the starting command line number. All commands, including the one specified, are displayed until the end of the buffer. So, the command
If a second argument is present, it is the line number at which the listing will stop. This is useful when the user only wants to display the first few lines of a macro. If this second number is greater than the number of commands in the buffer, then the list command will present all commands from the starting line number to the end of the buffer. In this way, the command
Finally, a third argument, if present, will inform the list command which macro to list. If the user wishes to display the entire macro, then the command
Commands are never typed in the way we want them on the first time through a plot. Often, a color change or line style adjustment extends further in the plot file than we first expected. Another command is needed just a few lines prior to the current command. Or perhaps we have, too hastly, finished a definition of a macro and forgot to include an important command. These situations can be quite easily fixed with the insert command. The insert command may have up to two optional arguments (discussed below).
When the insert command is called, it places the user into insert mode.
This is demarked by the prompt changing to INSERT>.
All commands typed at this point are checked that they are valid
commands (if not, they are ignored) and are inserted in the
proper order (without being executed).
Insert mode is terminated by entering the end command.
Without any arguments, insert starts inserting commands at the end of the command buffer. This is the same as interactive mode except that the commands typed are not executed. If one argument is present, it is considered the insert line number and all commands will be inserted before that line in the macro. Hence, if the command buffer has three commands currently in it and the user types
Just as users may wish to insert commands in either the command buffer
or their own macros,
they will want to remove certain commands.
The delete command permits the user to specify lines of commands
or even entire macros to be deleted.
A macro is automatically deleted whenever the number of commands
it contains reaches zero.
Deleting an entire macro is sometimes useful if the user wishes to define
another macro with the same name.
The delete command may have up to three optional arguments. With no arguments present, it removes the last line in the command buffer. The first two arguments are considered as command line numbers. With only one argument, the specified command line in the command buffer is removed. If the line number is greater than the number of commands present in the macro, the last command is removed. If two arguments are present, then the inclusive range of commands are removed from the command buffer. Finally, if all three optional arguments are present, then the lines removed are from the named macro. Hence, the command
Once a macro has been defined, it is executed just like any of the other WIP commands. To execute a macro, just call it by name. The macro name may also be followed by any required or optional arguments as is necessary.
In addition, a macro may be executed without being saved in the command buffer. This is accomplished with the playback command. Without any arguments, playback executes the commands in the command buffer. This is an extremely useful command when the constructed plot begins to become quite complicated. The optional arguments to playback is the name of the macro to be executed and any arguments needed by the macro. Since the playback command is not saved in the command buffer, this permits a user the opportunity to test their macros. However, the real usefulness of the playback command is in repeating the plot file constructed.
Once a user has defined a useful macro, they will undoubtedly wish to save them to a file for use again. This is accomplished with the write command. The write command permits named macros and the command buffer to be written to an ASCII text file. The only required argument to the write command is the name of the output file. With no other arguments, the command buffer is written to the named file. If any other arguments are present after the file name, they are considered to be the macros to be saved and these named macros are written to the specified file. Multiple macros may be written to the same file with only one write command. If the macro name listed is ``all'', then all macros currently defined and the command buffer will be written to the named file.
To retrieve macro definitions, WIP provides three commands . Each command treats the input file differently and are explained in brief detail in the following list.