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 <Ctrl M> 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. Note

that the "R" still appears on the StatusLine.

5. Execute the MacroRecord <Ctrl M> 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
<Ctrl Enter> 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 use, you must write them to a Keyboard Macro
file. (This file is in a special binary format, recognizable by the
editor, and should not be edited as a normal text file.) The name of
this file is specified by 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><R> 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 <Ctrl M>.

3. Press <Alt F1> to assign the macro to this key.

4. Press the following series of keys:

<Home> (for the BegLine command)

<Ctrl P> (for the Literal command)
<Ctrl L> (a formfeed character)

5. Enter MacroRecord <Ctrl M>. The macro is now created and assigned to
the <Alt F1> key.

Now, when you press <Alt F1>, 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 <F1> 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 <Alt T> 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 ' >errors.lst' Return Return
HorizontalWindow
EditFile 'errors.lst' Return

Press <Alt F1> 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 <Alt 4> 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 AddLine
^y DelLine

Customized QCONFIG.DAT file:

f2 AddLine BegLine
^y DelLine 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 CopyBlock
@m MoveBlock

Customized QCONFIG.DAT file:

@c CopyBlock UnmarkBlock
@m MoveBlock 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 <Alt 5> 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 (<F7> in this
example):

f7 Find Pause Return 'i' Return

If you want to get really fancy, you could let <F7> 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. Following are some
examples of macros using the Paste command.

� 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 <Grey *>.
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 <Ctrl ]>.):

^] AltWordSet MarkWord Copy EditFile Paste Return

DefaultWordSet

This macro does the following:

AltWordSet - sets the proper word set for filenames

MarkWord - marks the filename at the current cursor position
Copy - copies the filename into the scrap buffer
EditFile - initiates the EditFile command
Paste - inserts the copied filename into the prompt box
Return - terminates the EditFile prompt
DefaultWordSet - restores the normal word set

� A macro to initiate a Find on the word at the current cursor position

(assigned by default to <Alt =>.):

@= MarkWord Copy Find Paste Return Return

This macro does the following:

MarkWord - marks the word at the current cursor position

Copy - copies the word into the scrap buffer
Find - initiates the Find command
Paste - inserts the copied word into the prompt box
Return - terminates the search string prompt box
Return - 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:". The

maximum label length is 32 characters.

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 * turn off screen for speed

begin: isCursorInBlock MacroQuitFalse * exit if not in Block
isEmptyLine JFalse next: * skip if not empty line
isLastLine JTrue last: * handle last line
DelLine Jump begin: * delete empty lines
next: CursorDown JTrue begin: * try next line
MacroQuit *
last: DelLine * 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 <filename to edit> -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 <filename to edit> -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 <filename to edit> -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