WORDPERFECT MACRO TUTORIAL

14. Flow Control

14.1 Flow of a macro

The order in which commands in a macro are executed is sometimes called the "flow" of the macro. Usually when a macro is played, the macro commands are executed in order, from the beginning of the macro to the end. But there are occasions when you will want to change the flow of the macro, for example by skipping certain commands when some condition exists. Of you may wish to have two "branches" of flow in the macros, depending on a decision. You might also want to end the macro prematurely (before all the commands are executed).

14.2 The Label() command

When you change the normal flow of the macro, you need some way to identify the point to which the flow should be diverted (i.e., the next command that should be executed). This identification is effected with the Label() command. Label() serves as a sort of signpost, since its purpose is simply to mark a location in the macro. That location, the "name" on that signpost, is the parameter for both the Label() command and the commands that make use of the label (by causing the macro flow to move to that location).

The form of the Label() command is:

Label(name)

where "name" is any identifier you want to use as the name for the location.

A Label() command can be inserted anywhere in the macro. It does nothing but mark a location. You can have as many labels as you need in a macro, but of course each label must have a separate name. You should follow the same rules in naming labels as for naming variables. To readily identify labels, the "@" character is sometimes added to the end of label names.

14.3 The Go() command

There are several PerfectScript command that control the flow of a macro. Later in this tutorial we will discuss controlling program flow in response to not-found and error conditions by performing error trapping and handling. Here we will discuss the simplest flow-control command: Go(). This command causes the macro to "jump" to a specific point in the macro (i.e., to "go" there), skipping over any intervening commands, and continue execution from that point.

The form of the GO() command is

Go(name)

When this command is executed, the macro immediately jumps to the point in the macro program labeled with that name, and continues execution from that point.

You should use go GO() commands sparingly; they make it difficult to follow the flow of the macro during editing or debugging. This command is PerfectScript's equivalent of the "goto" statement in other languages, whose use is considered a bad programming practice. If you find yourself using the Go() command frequently, you should familiarize yourself with the Call() command, which enables a technique known as structured programming. Structured programming is beyond the scope of this tutorial.

14.4 The Quit command

Rather than "diverting" the flow of macro execution, there are occasions when you want to "shut it off," i.e., terminate the macro before the end. You can do so by inserting the Quit command where you want the macro to end. Of course normally a macro just ends when all its commands have been executed. But you may wish to terminate a macro earlier if a certain condition exists. To do so you could use the Quit command in one branch of an If() command.

You will often need to use the Quit() command if you jump to a different location in the macro. Remember that a Label() simply marks a location in the macro. This means that the commands after the label are part of the macro, and will be executed as part of the normal flow of the macro, even if you don't jump to the label. If you want to avoid this, insert a Quit command before the label. Then those commands will be executed only if you jump to the label with a Go() command.