PWB macros can prompt for input. This helps you write more general macros. For example, you might keep a history of the changes you make to a file at the top in a format similar to the following:
//** Revision History **
//15-Nov-1991:IAD:Add return value for DoPrint
//31-Oct-1991:IAD:Implement printing primitives
To facilitate entering the revision history in reverse chronological order and to make it easy to keep track of where you were in the source file, you can write a macro to perform the following steps:
1.Set a mark at the cursor for future reference.
2.Insert a revision history header at the beginning of the file if one is not present.
3.Insert the current date.
4.Prompt for initials and insert them just below the header.
5.Prompt for comments and insert them after the initials.
6.Return to the saved position in the file.
Note that while this macro is executing, you can choose the Cancel button in the dialog boxes that prompt for initials and comments. The macro must handle these cases and gracefully back out of the changes to the file.
·To enter this macro in TOOLS.INI:
1.Open TOOLS.INI for editing.
2.Type the following macros and key assignment in the [pwb] section of TOOLS.INI:
LineComment:="// "
RevHead:= "** Revision History **"
RevComment:= \
Arg Arg "Start" Mark \
Begfile Arg RevHead Psearch +>Found \
Linsert LineComment RevHead \
:>Found \
Down Linsert Begline LineComment Curdate " (" \
Arg "Initials" Prompt ->Quit Paste Endline ") " \
Arg "Comment" Prompt ->Quit Paste =>End \
:>Quit Meta Ldelete \
:>End Arg "Start" Mark
RevComment:Ctrl+H
There are at least two spaces before the backslash at the end of each line. The backslashes are line-continuation characters. They allow you to write a macro that is more than one line long. In this case, line continuations format the macro in a readable way. To further assist in readability, you can indent the parts of the macro which define the actual keystrokes, as in the preceding example.
3.Choose Save from the File menu to save your changes.
4.To reinitialize PWB, execute the Initialize function by pressing SHIFT+F8.
PWB discards all of its current settings and rereads the PWB section of TOOLS.INI. The same effect can be achieved by quitting and restarting PWB.
The following discussion analyzes the workings of the definitions you added to TOOLS.INI. It repeats one or two lines from the text you typed and describes how each line works. You may want to refer to the full definition as you follow along.
The first two lines
LineComment:="//"
RevHead:= "** Revision History **"
define two utility macros that are used by the main RevComment macro. They define strings that are used several times in RevComment.
The third line
RevComment:= \
declares the name of the macro. The succeeding lines define the action of the
RevComment macro.
The first line of the definition
Arg Arg "Start" Mark \
sets a mark named “Start” at the cursor so that the macro can restore the cursor position after inserting the comments at the beginning of the file.
The next line
Begfile Arg RevHead Psearch +>Found \
moves to the beginning of the file (Begfile), then searches forward for the revision-history header. If the header is found, PWB branches to the Found label; otherwise, it executes the next line.
Linsert LineComment RevHead \
If the macro is here, the header was not located in the file. The Linsert function creates a new line, and PWB types the revision-history header. The macro continues with the line:
:>Found \
This line defines the Found label. At this point in the macro, the cursor is on the line with the header. The next lines insert the new revision information, starting with the following line:
Down Linsert Begline LineComment Curdate " (" \
PWB moves the cursor down one line (Down), inserts a new line (Linsert), moves to the beginning of the line (Begline), and calls the LineComment macro to designate the line as a comment. PWB then types the current date (Curdate) and an open parenthesis.
The macro prompts for initials:
Arg "Initials" Prompt ->Quit Paste Endline ") " \
The macro uses the Prompt function to get your initials. If you choose the Cancel button, the function returns false, so the macro branches to the label Quit. If you choose the OK button, the text you typed in the dialog box is passed to the Paste function, which inserts the text. The macro moves the cursor to the end of the line (Endline) and types a closing parenthesis.
The code on this line explicitly handles the case when you cancel the prompt (the false condition). The phrase ->Quit causes PWB to skip to the label Quit when Prompt returns false.
If you use the Prompt function and you do not handle the false condition, a null argument (a text string with zero length) is passed to the next function. Therefore, a phrase like Arg "Que?" Prompt Paste pastes either the input or nothing, depending on whether you choose the OK or Cancel button. Passing a null argument to Paste is harmless, but some functions require an argument. In these cases, you can use the -> operator to terminate the macro.
The RevComment macro uses an explicit label so that it can end the macro without an error when you choose the Cancel button. The next line of the macro is almost the same as the previous line in the macro.
Arg "Comment" Prompt ->Quit Paste =>End \
On this line, if the paste is carried out, an unconditional branch is taken to the label End and passes over the Quit branch, which is defined on the next line.
:>Quit Meta Ldelete \
The Quit branch is taken when you cancel a prompt. The macro has to clean up the text already inserted by the macro. The Meta Ldelete function deletes the incomplete line that would have been the revision-history entry. The next line defines the last step of the macro.
:>End Arg "Start" Mark
The End label defines the entry point for the common cleanup code. This line restores the cursor to the initial position when you invoked the macro. Because this line does not end in a line-continuation character (\), it is the end of the RevComment macro.
The last line that you typed is not part of the RevComment macro. It is a separate TOOLS.INI entry.
RevComment:Ctrl+H
This line assigns the CTRL+H key to the RevComment macro.
You can polish this macro by adding Arg "Start" Meta Mark to the end of the macro. This phrase deletes the mark. A better alternative is to use the Savecur and Restcur functions instead of named marks. However, this example uses named marks to illustrate how to use them in a macro.