Macro

THE SEMWARE(R) EDITOR JUNIOR Version 4 M A C R O

R E F E R E N C E

M A N U A L

MACRO REFERENCE ���������������������������������������������������������������������� To simplify and automate editing tasks and to further customize the editor, you can create macros. A macro is simply a series of commands and/or keystrokes that is assigned to a key. The simplest type of macro to create is a Keyboard Macro. A Keyboard Macro is created by recording a series of keystrokes as they are typed at the keyboard, and assigning that series to a key. For example, if you wish to repeatedly enter a row of asterisks, three Returns, and then a Tab, you could record this series and assign it to a single key, such as <Shift F6>. Then, the next time you wish to enter a row of asterisks, three Returns, and a Tab, you only have to press <Shift F6>. More powerful macros can be created using the editor configuration program (QCONFIG.EXE) and the QMac program (QMAC.EXE). These macros can be permanently tied to the editor (using the configuration program), or can be loaded as needed (using QMac). Using these facilities, you can extend and customize the capabilities of the editor to suit your needs and preferences. Refer to "Creating Macro Programs" in this file for more information. (Note that QMac is included only in the registered version.) KEYBOARD MACROS ������������������������������������������������������������������������ Creating Keyboard Macros ������������������������ Once you have decided to assign a series of commands and keystrokes to a single key, creating a Keyboard Macro is simply a matter of entering this series while the editor "records" the macro. To create a Keyboard Macro, follow these steps: 1. Position the text and cursor to where you wish to begin entering the series of commands and keys. (You may want to practice your series once or twice before actually recording the macro.) 2. Execute the MacroRecord command. An "R" appears on the StatusLine to indicate MacroRecord mode is ON. The following message appears: Assign to what key: (<Enter> for scrap, <Esc> to cancel) 3. Enter the key to which you want to assign the series of commands and keystrokes. This key must be a "configurable" key. If a key is

specified that has a command already assigned to it, the editor prompts you to determine if you want to overlay that key assignment. To assign the macro to a "scrap" or temporary area, simply press <Enter>. The scrap area holds your macro until a new macro is recorded (or you exit the editor). 4. Enter the series of commands and keystrokes to be assigned. that the "R" still appears on the StatusLine.

Note

5. Execute the MacroRecord command again. MacroRecord mode is turned OFF, and the "R" no longer appears on the the StatusLine. The macro is now created and assigned to the key specified in step 3. Using Keyboard Macros ��������������������� To use your Keyboard Macro, position the text and cursor properly and press the key to which you assigned the macro (or use the ExecuteScrap command to retrieve the last macro recorded). If the macro does not behave as you expected, repeat the above steps. Your old macro assignment is replaced with the new one. ��������������������������������������������������������������Ŀ � Tip: � � Be aware of modes, especially Insert mode, when recording � � and using macros. Macros recorded with Insert mode ON and � � then used with Insert mode OFF (and vice-versa) may behave � � very strangely. � ���������������������������������������������������������������� Saving and Reloading Keyboard Macros ������������������������������������ Normally, macros created using this process are lost once the editor is terminated. However, there is an easy method for saving your macros so that they may be reloaded for use in any future editing session. To save macros for future file. (This file is in a editor, and should not be this file is specified by

use, you must write them to a Keyboard Macro special binary format, recognizable by the edited as a normal text file.) The name of the user.

To save macros once they have been created, execute the MacroWrite <Esc><M><W> command. The editor prompts with: ��������������������������������������������������������������Ŀ �Macro file to write: � � � ���������������������������������������������������������������� Enter the name of the file (optionally including drive and/or path) to contain your macros. All Keyboard Macros currently recorded (and/or loaded) during the editing session are saved under the specified filename. (However, macros assigned only to the scrap area, and not to a specific key, cannot be saved.)

In a future editing session, when you wish to reuse your previously defined macros, you need only reload the macro file. To do this, execute the MacroRead <Esc><M> command. The editor prompts with: ��������������������������������������������������������������Ŀ �Macro file to read: � � � ���������������������������������������������������������������� Enter the name of the previously saved macro file. Your macros are reloaded. You may then use them in the same manner as before. Example of a Keyboard Macro ��������������������������� To create a Keyboard Macro that inserts a formfeed character (ASCII 12) at column one of the current cursor line, do the following: 1. Position the cursor in the text where you would like to insert the formfeed character. Set Insert mode ON. 2. Execute MacroRecord . 3. Press to assign the macro to this key. 4. Press the following series of keys:

(for the BegLine command) (for the Literal command) (a formfeed character)

5. Enter MacroRecord . the key.

The macro is now created and assigned to

Now, when you press , the cursor moves to column one and a formfeed character is inserted, just as if you had typed it from the keyboard. CREATING MACRO PROGRAMS ������������������������������������������������������������������������ As mentioned in Chapter 2, "Customizing the Editor" (in the file TSEJR.DOC), the editor's configuration program (QCONFIG) allows you to assign multiple commands and/or text to a key (or two-key). With this facility, you can easily write simple programs using the editor's macro language. These macros are included in the Keyboard Definition file (QCONFIG.DAT), and then added to the editor program itself using the configuration program. Each time the editor is loaded, these macros are automatically available. For more information on including macros in the Keyboard Definition file, refer to the "Keyboard Configuration" section of Chapter 2 (in the file TSEJR.DOC). To write a macro program, begin by editing your Keyboard Definition file (QCONFIG.DAT, by default). Locate the key to which you wish to assign your macro program. To the right of that key, specify any combination of text strings and commands, each separated by a space. Text should be

enclosed in single or double quotes. Macros can span multiple lines, as long as 2 simple rules are followed: the key name must begin in column 1, and all succeeding lines must begin in column 2 or greater. Once the macro is written, save your Keyboard Definition file and exit the editor. Then execute the configuration program (QCONFIG). Select the "Keys" option to update the editor program. This assigns your macro program to the specified key. Now when you run the editor, you can execute your own custom macros by pressing the applicable key. Note:

The amount of space that is available for macros included in the Keyboard Definition file is limited to about 2K.

� Example: f1

EditFile

'help.dat'

Return

Press and this macro loads the file "help.dat". Note that the Return command is issued after the text. This is required to terminate the prompt issued by the preceding EditFile command. � Example: @t

GSave Dos 'tpc ' CurrentFilename Return

Press and this macro saves all files that have been changed, and then invokes the TURBO PASCAL compiler using the current file. (Note: There must be a space included within the quotes immediately following "tpc".) � Example: @f1

EditFile 'errors.lst' Return Quit Dos 'tcc ' CurrentFilename ' HorizontalWindow EditFile 'errors.lst' Return

>errors.lst'

Return

Return

Press and this macro runs the TURBO C compiler on the current file, saves the results to a file called "errors.lst", and then loads that file into another window after the compile is finished. In general, any commonly used sequence of commands (or a useful but complicated sequence of commands, for that matter) is a good candidate for a macro. We have received many helpful macro suggestions from users over the years. Here is a short list of some of the more useful (and simple) macros. � A very useful command, GetPrev, copies a character from the line immediately above the cursor line, onto the cursor line. Often it is necessary to copy this character to several succeeding lines in the same column. The GetPrev command, used in a macro, makes this

function easy. Assign this macro to the key (for example) in QCONFIG.DAT as follows: @4

GetPrev

CursorLeft

CursorDown

� The AddLine and DelLine commands do not change the cursor position. Many would prefer that the cursor move to column one when these commands are executed. A solution is to change the QCONFIG.DAT file as follows: Default QCONFIG.DAT file: f2 ^y

AddLine DelLine

Customized QCONFIG.DAT file: f2 ^y

AddLine DelLine

BegLine BegLine

� The CopyBlock and MoveBlock commands leave the copied or moved Block marked. Many would prefer the Block to be unmarked. A solution is to change the QCONFIG.DAT file as follows: Default QCONFIG.DAT file: @c @m

CopyBlock MoveBlock

Customized QCONFIG.DAT file: @c @m

CopyBlock MoveBlock

UnmarkBlock UnmarkBlock

� The DropAnchor command ends or extends a Block if executed after a Block has been initially or entirely marked. Some editors have a similar command, except that it acts as a toggle. That is, if you are already marking a Block, and you execute DropAnchor again, the Block is unmarked and marking begins again at the current cursor position. To implement this behavior, change the QCONFIG.DAT file as follows: Default QCONFIG.DAT file: @a

DropAnchor

Customized QCONFIG.DAT file: @a

UnmarkBlock

DropAnchor

� This macro allows you to edit a sorted list of files in the current directory. Assign this macro to the key (for example) in QCONFIG.DAT as follows: @5

Dos

"dir

*.*

|

sort>filedir.tmp"

Return

Return

EditFile "filedir.tmp" Return DelLine DelLine DelLine DelLine Advanced Macro Programming �������������������������� The following commands and features are intended for advanced macro writers, to make certain macros easier to write. In the examples provided, the key assignments indicated are suggested assignments only; you can assign each macro to the key of your choice. Macro Pause The Pause command allows you to suspend execution of a macro, make entries from the keyboard, and then continue execution of the macro. To use the Pause command, place "Pause" at the appropriate position within a macro in the QCONFIG.DAT file. When you execute a macro containing a Pause command, its execution is suspended when the Pause command is encountered. A "P" appears on the StatusLine. At this point the User can enter text from the keyboard. Press <Enter> to resume execution of the macro; press <Esc> to terminate execution of the suspended macro entirely. Please note that the <Enter> key entered from the keyboard to resume execution of a suspended macro is "eaten" by the Pause command; or, in other words, that <Enter> does not become part of the macro. � For example, suppose you want to create a "find" command that always searches forward, ignores case, and does not prompt for options. In the QCONFIG.DAT file, assign to whatever key you desire ( in this example): f7

Find

Pause

Return

'i'

Return

If you want to get really fancy, you could let be your find-forward, and <Shift F7> be your find-backward: #f7

Find

Pause

Return

'ib'

Return

Using Paste within a Macro It can be handy to use the Paste command in a macro. examples of macros using the Paste command.

Following are some

� With the FillBlock command, you can use the following macro to move a Block, and blank fill the space used by the Block, instead of the text closing in around the Block. The macro assumes a Block is already marked. The Block is Cut to the system scrap buffer. You can then insert the Block where you like by pressing the Paste key . You now have a "copy with wipe" command! f10

GotoBlockBeg

Cut

Paste

FillBlock

' '

Return

UnmarkBlock

� A macro to take the filename at the current cursor position and load that file into the editor (assigned by default to .): ^]

AltWordSet MarkWord DefaultWordSet

Copy

EditFile

Paste

Return

This macro does the following: AltWordSet MarkWord Copy EditFile Paste Return DefaultWordSet

-

sets the proper word set for filenames marks the filename at the current cursor position copies the filename into the scrap buffer initiates the EditFile command inserts the copied filename into the prompt box terminates the EditFile prompt restores the normal word set

� A macro to initiate a Find on the word at the current cursor position (assigned by default to .): @=

MarkWord

Copy

Find

Paste

Return

Return

This macro does the following: MarkWord Copy Find Paste Return Return

-

marks the word at the current cursor position copies the word into the scrap buffer initiates the Find command inserts the copied word into the prompt box terminates the search string prompt box terminates the Find options prompt box

Repeating a Command within a Macro Within macros, in order to repeat the previous command "n" times, the following syntax can be used: command

n

Where "n" is a number between 1 and 32767. The immediately preceding command is executed the number of times indicated. So, for example: CursorDown

1

would move the cursor down one line (and is equivalent to just CursorDown by itself). CursorDown

10

would move the cursor down ten lines. Conditional Logic for Macros Several commands are available for conditional logic within macros: Jump, JTrue, JFalse, MacroQuit, MacroQuitFalse, and MacroQuitTrue.

Placement of one of these commands in a macro following another command allows for branching or looping during macro execution. All commands set an internal result code of TRUE upon successful execution, or FALSE if execution is unsuccessful or no action occurs. These result codes can be used to determine different courses of action during execution of a macro, based on the outcome of a particular command. The Jump command makes an unconditional jump, regardless of the outcome of the preceding command. The JTrue command makes a jump only when a result code of TRUE is returned; JFalse makes a jump only for a result code of FALSE. The MacroQuit command unconditionally terminates a macro. The MacroQuitTrue command terminates a macro only when a result code of TRUE is returned; MacroQuitFalse terminate a macro only if a result code of FALSE is returned. Labels can be defined for branching, in the format "label:". maximum label length is 32 characters.

The

For example, here is a macro to delete the text from the cursor position to the beginning of the line (assigned to the f10 key): f10

begin: CursorLeft MacroQuitFalse DelCh Jump begin: Special-Purpose Macro Commands

The editor includes a number of commands that are intended specifically for use in macros. One group of special macro commands is the Set commands. This group of commands force the indicated mode or setting. If the setting was already in that condition, they set the internal result code to FALSE; otherwise, they set it to TRUE. In many cases, macros can behave differently based on the currently set editor modes. The following Set commands give you some control in establishing the proper environment so that your macro always works as intended. (Refer to the "Modes" section of Chapter 1, in the file TSEJR.DOC, for more information about modes in the editor.) Each of these Set commands set the indicated mode or feature ON. To set the indicated mode or feature OFF, first turn the mode or feature ON by issuing the Set command, and then turn it OFF by issuing the corresponding Toggle command. For example, to set Insert mode OFF, use the following code: SetInsMode

ToggleInsert

Or, to set file backups OFF, use the following code: SetBakups

ToggleBakups

� SetAutoIndentMode Sets ON AutoIndent mode. � SetBakups Sets ON file Backup mode. � SetBoxDraw Sets ON Box Drawing mode. � SetCenterFinds Sets ON Find centering (to center found text, located by the Find, FindReplace, or IncrementalSearch commands, vertically on the screen). � SetCUAMarking Sets ON CUA-Style Block Marking mode. � SetEnterMatching Sets ON EnterMatching mode. � SetInsMode Sets ON Insert mode. � SetPrintAddFF Sets ON the option to automatically send a formfeed character to the printer at the end of each print operation. � SetPromptForEAs Sets ON the option to have the editor prompt for a .TYPE EA when saving a file that does not already have Extended Attributes assigned. (This command is available in the OS/2 version ONLY.) � SetSortCaseInsensitive Sets ON the option to have the editor perform case-insensitive (rather than case-sensitive) sorts. � SetSortDescending Sets ON the option to have the editor perform sorting operations in descending (rather than ascending) order. � SetSwap Sets ON the option to swap to EMS or Disk when the Shell and DOS commands are executed. (This command is NOT available in the memory-resident or OS/2 versions.) � SetSyncScroll Sets ON Synchronized Scrolling mode. � SetTabsExpand Sets ON Physical Tab Expansion mode. � SetTabsOut Sets ON Tabs Out mode.

� SetWordWrapMode Sets ON WordWrap mode. The Find command sounds a tone when the search string cannot be found. This may be undesirable in a long-running macro, that may possibly execute hundreds of find operations that fail. The following commands allow you to selectively turn the sound ON and OFF. � SetSoundOn Sets Sound ON. � SetSoundOff Sets Sound OFF. Most macros execute dozens of commands, possibly hundreds of times. This can cause the screen to flash rapidly as the macro runs. Not only is this somewhat disconcerting to watch, it actually slows down the speed of some macros. The following commands allow you to temporarily suspend or resume screen updating, while a macro is running. � SetScreenOn Turns Screen Updating ON. � SetScreenOff Turns Screen Updating OFF. You must turn screen updating back ON before your macro prompts for input, or if there is output from the macro that you want displayed on the screen. Note:

The editor AUTOMATICALLY turns Screen Updating back ON when the macro is finished executing. Thus, it is not necessary to issue the SetScreenOn command at the end of the macro.

Many times, it would be nice for a macro to force a few settings, do its assigned task, and then restore the original settings. The following commands allow you to do just that. Note that each time SaveSettings is executed, the previous settings saved with SaveSettings are overwritten. � SaveSettings Saves the current settings of: Insert, AutoIndent, WordWrap, Sound, and Screen Updating. � RestoreSettings Restores the saved settings for the settings indicated in SaveSettings. The following commands set the editor's result code to TRUE or FALSE based on the condition being tested. These commands make certain types of macro tests easy and reliable. � isBegLine Returns TRUE if the cursor is at column 1; otherwise, FALSE is returned.

� isCurrChar Returns TRUE if the character at the cursor position in the file is the same as that specified by the character immediately following the isCurrChar command. � isCursorInBlock Returns TRUE if the cursor is inside a marked Block; otherwise, FALSE is returned. � isEndLine Returns TRUE if the cursor is past the last non-white character on the current line; otherwise, FALSE is returned (including when the cursor is on an empty line). � isEmptyLine Returns TRUE if the current line is empty or contains only white space; otherwise, FALSE is returned. � isFirstLine Returns TRUE if the cursor is on the first line of the currently edited file; otherwise, FALSE is returned. � isLastLine Returns TRUE if the cursor is on the last line of the currently edited file; otherwise, FALSE is returned. � isWord Returns TRUE if the character at the cursor position in the file is in the current word set. See the AltWordSet command for more information on word sets. In order to tie a few of these concepts together, we present a simple macro to delete all the blank lines in a marked Block. The cursor should be at the beginning of the Block when the macro is invoked. #f9

SetScreenOff begin: isCursorInBlock isEmptyLine isLastLine DelLine next: CursorDown MacroQuit last: DelLine

MacroQuitFalse JFalse next: JTrue last: Jump begin: JTrue begin:

* * * * * * * * *

turn off screen for speed exit if not in Block skip if not empty line handle last line delete empty lines try next line delete the last line that's all, folks!

The Main Macro The editor has a provision for a special-purpose macro that is automatically executed at editor startup. In a Keyboard Definition file, assigning a macro to the key "main" causes that macro to be executed whenever the editor is initially invoked. � Example: main

MacroRead

"c:\macros\mymacs.qm"

Return

This causes a macro file named "mymacs.qm" to be loaded into the editor, every time the editor is started. (Note that the "key" the macro is assigned to is "main".) STARTUP MACROS ���������������������������������������������������������������������� The editor offers a feature that allows you to load and/or execute macros from the DOS command line. To load a macro from the DOS command line, type "-l" (this is a dash character and the letter "l") immediately followed by a macro filename when you execute the editor. For example, from the DOS prompt type: q



-l<macro filename>

To execute a macro from the DOS command line, type "-e" immediately followed by a macro filename when you execute the editor. The editor then automatically executes the first macro in the macro file after the file to be edited has been loaded. For example, from the DOS prompt type: q



-e<macro filename>

Following are additional notes about the use of Startup macros. � The macro file to be loaded and/or executed must be created using either the MacroWrite <Esc><M><W> command or QMac. � A macro file to be executed (-e) is limited to a maximum size of 500 bytes. � A "/" character can be used instead of the "-" character, as "/l" and "/e". � You MUST supply a filename to be edited on the DOS command line to use this feature. � When using the execute ("-e") option, only the first macro in the macro file is executed. This macro is executed only after the file to be edited has been loaded. � You can load one macro and execute another macro at the same time. For example, from the DOS prompt: q



-e<macro filename>

-l<macro filename>

Following is an example of using Startup macros. Suppose you have created two macro files, called first.mac and second.mac. Now you want to load a file for editing called work.tmp, and at the same time, load the macro file called first.mac and execute the macro file called second.mac. From the DOS command line, enter: q

work.tmp

-lfirst.mac

-esecond.mac