OS/2 Shareware BBS: 5 Edit/05-Edit.zip/tse2jr4.zip/MACRO.DOC

Text File | 1997-02-21 | 26KB | 693 lines

                      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
TSEJR2.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 TSEJR2.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
TSEJR2.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.

■ 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.

■ 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