








                             THE ME TEXT EDITOR
    
           (C) COPYRIGHT 1986   MARC ADLER     ALL RIGHTS RESERVED
    
                           MAGMA SOFTWARE SYSTEMS
                             138-23 HOOVER AVE.
                           JAMAICA, NEW YORK 11435
                               (718) 793 - 5670
    





















































    
    
                              TABLE OF CONTENTS
    
    Installing the Editor...................................Chapter 0
    
    Introduction to the ME Editor...........................Chapter 1
    
    The ME Help Facility....................................Chapter 2
    
    Character-Oriented Commands.............................Chapter 3
    
    Line-Oriented Commands..................................Chapter 4
    
    Block Commands..........................................Chapter 5
    
    Input/Output Commands...................................Chapter 6
    
    Searching and Substituting..............................Chapter 7
    
    Keyboard Macros.........................................Chapter 8
    
    Multi-Window Editing....................................Chapter 9
    
    Miscellaneous Commands..................................Chapter 10
    
    Editor Options..........................................Chapter 11
    
    Introduction to the Macro Language......................Chapter 12
    
    Macro Language - Editor Services........................Chapter 13
    
    Macro Language - Buffer Services........................Chapter 14
    
    Macro Language - Primitives.............................Chapter 15
    
    Remapping the Keyboard..................................Appendix A
    
    The CTags Utility.......................................Appendix B
    
    














                               ME USERS MANUAL






               INSTALLATION INSTRUCTIONS FOR THE ME EDITOR
    
        On  the enclosed disk, you will find the editor, help files, macro
    files, macro compiler, and several other utility  files.  These  files
    are :
    
            INSTALL.BAT - a batch file to perform the installation process
    
            ME.EXE - the editor program
            MACCOMP.EXE - the macro compiler
    
            KEYCHART - a table showing the editor commands
    
            \HELP\MEHELP.xxx - the editor help files
            \MACROS\* - the macro source files
                    *.EXM - the macro executable files
    
            CONFIG.ME - the editor configuration file
    
            MANUAL - the printable documentation for the editor
    
            KEYREMAP.ARC - keyboard remapping utilities
    
        If  you  ordered  the  source  code,  then  there  is another disk
    enclosed which has the source code on it.
    
        The executable file is called ME.EXE. This should be placed in one
    of the directories which is included  in  your  DOS  search  path,  or
    placed in your current directory. To find out what your current search
    path  is,  type "PATH" from the DOS prompt. Refer to the MS/DOS manual
    if you need help on changing your search path.
    
    
                            AUTOMATIC INSTALLATION
    
        There  is  a  batch  file  on  the  distribution  diskette  called
    INSTALL.BAT. Running this batch file will  automatically  install  the
    editor  in the proper subdirectories. This batch file assumes that you
    have a hard disk drive  C:.  If  you  dont,  then  you  can  edit  the
    INSTAL.BAT file. You can also follow the instructions contained in the
    INSTALL.BAT file, and manually install the files.
    
    
                           THE ENVIRONMENT VARIABLE
    
        During an editing session, the editor may have to look for several
    files,  such  as macro files or help files. Normally, the editor first






    Installing the Editor                           Chapter 0   Page 1


                               ME USERS MANUAL






    searches the current directory, then will  search  all  subdirectories
    that are listed in your PATH environment variable. 
    
        To  speed  up  searching,  the editor will look for an environment
    variable called ME. The value of this variable should be the name of a
    subdirectory which the editor should look in first in order to  locate
    certain files. For instance, if I have a subdirectory called \ME which
    contains  all  of  the editor's files, then in my AUTOEXEC.BAT file, I
    might have the statement "set ME=c:\ME".
    
    
                            THE CONFIGURATION FILE
    
        Among the all of the files is one file which is important (but not
    required) for configuring your ME editing session. This file is called
    CONFIG.ME. 
    
        The CONFIG.ME file should be placed in the subdirectory which  you
    have  specified  with  the  ME environment variable. If you don't have
    this variable, you can put the  CONFIG.ME  file  in  any  subdirectory
    along your DOS search path.
    
        Although  you  can alter the values of the parameters in this file
    without reading the manual, it's recommended that you read the  manual
    and have a little bit of practice with ME before modifying them. 




























    Installing the Editor                           Chapter 0   Page 2


                               ME USERS MANUAL






                                 INTRODUCTION
    
        ME  (short for Macro Editor) is a programmer's text editor written
    by a professional programmer for programmers. Although this editor  is
    inexpensive, its power rivals that of much more expensive editors.  We
    strive  to  keep the editor state-of-the-art and bug-free. If you have
    any comments at all about the editor, please feel free to contact us.
    
        This  editor  has  been  written specifically for the IBM Personal
    Computer, and takes advantage of some of its  features,  like  memory-
    mapped  display,  fast  string  operations, etc. The editor is written
    mostly in the C programming  language,  with  some  assembly  language
    routines  to  speed  things  up.  The  version  of  C compiler used is
    Microsoft version 4.0. 
    
        To  run  the editor, you need an IBM PC, XT or AT (or compatible),
    and at least 192K of memory. You should be using DOS 2.0  or  greater.
    The  editor  uses direct screen writes for speed, and assumes that the
    video memory for the color card starts at address B800, and  the  mono
    card  memory starts at B000. If you have an Enhanced Graphics Adapter,
    the editor's <TOGGLE EGA> command can be used  to  switch  the  screen
    into a 43 line display.
    
        All  operations  on  text  work extremely fast. All of the data is
    kept in main memory  for  speed.  With  the  cost  of  memory  rapidly
    decreasing, and with the new generation of CPU's which provide virtual
    memory  capabilities, I have seen no need to include virtual memory in
    the editor. Virtual memory also slows many operations  down,  such  as
    searching  through  the entire file for a word. This is because of the
    disk I/O needed to swap out a section of the file which is  not  being
    used any longer, and to swap another section in. 
    
    
                                   FEATURES
    
    1) Powerful C-like macro language for defining your own commands.
    2) Remapable keyboard.
    3) You  may  have  up  to 12 windows shown simultaneously,  with a
       different file in each window. You can also enlarge any window to
       occupy the whole screen.
    4) Regular expression pattern matching.
    5) Column block operations.
    6) Keyboard macros.
    7) Escape to the DOS operating system.
    8) 10 "pick" buffers.
    
    






    The ME Editor                                   Chapter 1   Page 1


                               ME USERS MANUAL






                              RUNNING THE EDITOR
    
        You can run the editor from either a floopy disk or a  hard  disk.
    If  you  are  using  a  hard  disk,  you may want to create a separate
    subdirectory for all of the editor files, or (most  probably)  install
    the  editor  in  a subdirectory which contains most of your executable
    files. (On my system, I put all the executables in a directory  called
    \bin.)
    
        To run the editor, from the DOS prompt type
    
        me [options] filename [filename ...]
    
    where  "filename"  is the name of the file you want to edit or create.
    With DOS, a filename can have up to 8 characters as the main part, and
    up to 3 characters as the extension. 
    
        On the DOS command line, you can give the name of  more  than  one
    file to edit. For instance, when you invoke the editor, you might like
    to have file "FOO" in the bottom window, and the file "BAR" in the top
    window. From DOS, you would type the command :
    
      me foo bar
    
        There is no wildcard expansion for the command line. Be prudent in
    the  number  of  files you bring up initially, since the editor has no
    virtual memory capabilities.
    
    Pre-loading a Macro
    
        If  you  use the macro facility, there may be times when you would
    like one or more macro files to be  already  loaded  when  the  editor
    starts  up.  To do this, use the "-l" option. ("l" stands for "load".)
    Directly after the "l", you must put the name of the executable  macro
    file (without the ".exm" option).
    
        As an example, let's assume that you have an executable macro file
    called  "efuncs.exm".  To  load it in when the editor starts, type the
    command
    
        me -lefuncs foo.c
    
        The arguments to "-l" may include a full path specification,  like
    "\e\macros\efuncs".  There  also may be more than one "-l" argument on
    the command line, such as
    
        me -lefuncs -l\e\macros\c foo.c






    The ME Editor                                   Chapter 1   Page 2


                               ME USERS MANUAL






    
    
                              EXITING THE EDITOR
    
        To  exit  the  editor,  press  the  <EXIT> command. For historical
    reasons, the <EXIT> command is usually tied to the keystroke <CTRL> D.
    You are asked if you want to save your changes; type 'y' for  yes  and
    'n' for no. Typing any other key will bring you back into the editor.
    
    
    
                               THE STATUS LINE
    
        The 25th line on the IBM PC is reserved for information pertaining
    to   your  current  editing  session.  It  is  also  used  to  display
    information about various commands, and to receive input from the user
    for these commands. This line is referred to as the "status line".
    
        During your editing session, the status line tells you what column
    of the line you are on, the current line number, how many lines  there
    are in the file, whether you are in insert or overstrike mode, and the
    name of the file you are editing. The status line can be distinguished
    from the rest of the display because it is shown in reverse video.
    
        For  some  commands (like the search and substitute commands), the
    status line will contain a prompt. You are then required to enter some
    information on the status line. For most commands,  typing  the  <ESC>
    key will abort the command.
    
        The rightmost part of the status  line  tells  you  if  NUM  LOCK,
    SCROLL LOCK, and CAPS LOCK is on. The status line will show the letter
    'N'  if  NUM  LOCK is on, the letter 'S' if SCROLL LOCK is on, and the
    letter 'C' if CAPS LOCK is on. 
    
    
    
                            CUSTOMIZING THE EDITOR
    
        Probably the most powerful feature of the editor is the ability to
    write macro programs. Many times, you will want to perform a series of
    complex editing operations that may take many keystrokes. These opera-
    tions may have to be repeated many times, or may be subject to certain
    conditions.  If  this  series of operations is something that you need
    more than once, then it may be beneficial to write a macro to do  your
    task. 
    







    The ME Editor                                   Chapter 1   Page 3


                               ME USERS MANUAL






        For instance, a common operation for C programmers is to take some
    text  and  surround it in a comment block. (This was the first macro I
    wrote.) To do this, you would move the cursor to the first line of the
    block, and open up a blank line. Then, you would  type  a  slash,  and
    then  would  fill  the rest of the blank line with asterisks. Then you
    would move the cursor to the beginning of the next  line,  insert  one
    asterisk,  move  the cursor to the end of the line, and insert another
    asterisk. This would have to be done for each line of text inside  the
    block.  Then, you would insert a blank line after the last line of the
    block, and fill the blank line with asterisks, followed by a slash. 
    
         aaaaaaaa                   /***********
         bbbbbbbb       becomes     * aaaaaaaa *
         cccccccc                   * bbbbbbbb *
                                    * cccccccc *
                                    ***********/
    
    Since this operation is something that a C programmer does frequently, 
    then this would be a candidate for a macro.
    
    The editor comes with a programming language  whose  syntax  resembles
    the  C  programming  language. Macro programs are written in this lan-
    guage, then given to the macro  compiler  to  translate  into  an  in-
    termediate language. This intermediate language can be executed quick-
    ly  by  the editor's macro interpreter. When you load a macro into the
    editor, it is the intermediate language version which is loaded in and
    executed. 
    
    When you start the editor,  you can indicate which macro files  should 
    be loaded in with it. At any time throughout your editing session, you 
    can load in any macro and execute it.  






















    The ME Editor                                   Chapter 1   Page 4


                               ME USERS MANUAL






                           THE HELP FACILITY
    
        Among the files that you will find in  the  ME  package  are  help
    files.  Each  help  file  is  called "MEHELP.xx", where xx is a one or
    two-digit number. It is best to store the help files in a subdirectory
    called  "\ME\HELP".  If  this  is  not possible, these files should be
    stored either in your current directory, or in a directory which is in
    your DOS search path. 
    
        When you press the <HELP>  command  (the  ALT  H  key),  ME  first
    looks  in  a subdirectory called "\ME\HELP". If the help files are not
    found, ME searches all of the directories in your DOS search path  for
    a  file  called  "MEHELP.0".  This file contains the text for the main
    help menu, and can be changed by you if you want (see below). When  ME
    finds this file, it will display it on the screen, and then prompt you
    for the help selection. 
    
        To  read  a  help file, type the number next to the help topic you
    want to view. ME will then look for a file called "MEHELP.nn" where nn
    is the number you just typed, and if found,  will  display  the  file.
    After  you view this file, ME will re-display the main help screen and
    prompt you for the next selection. 
    
    CHANGING THE HELP FILES
    
        These  help  files  are  in  ASCII form, and their contents can be
    changed by using any text editor available. If you  decide  to  change
    it,  then  make  sure  that  you  save  your  changes  in  ASCII  form
    (especially if you use a word processor  which  writes  out  files  in
    their own format).
    
        You  can  add  your  own  help  files,  as  long  as  you  name it
    "MEHELP.xx", where xx is a one or two-digit number.  These  new  help
    files  should reside in the same directory as the other help files. If
    you create a new help file, you should add the entry in the help  menu
    found in the file "MEHELP.0".
    
    
                         DISCOVERING KEY ASSIGNMENTS
    
        The  <KEY  TO  FUNC>  function  (key ALT F1) will prompt you for a
    keystroke, and will print out the macro function  which  that  key  is
    associated with, if any. For instance, if after typing <ALT> <F1>, you
    press <F1>, then the editor will tell you that <F1> is associated with
    the  "delline()" function. Type the <ESC> key to return to the editing
    session.







    The ME Help Facility                            Chapter 2   Page 1


                               ME USERS MANUAL






    




















































    The ME Help Facility                            Chapter 2   Page 2


                               ME USERS MANUAL






                         CHARACTER ORIENTED COMMANDS
    
        Normally  the  editor  is in overstrike mode. This means that when
    you type a character,  it  replaces  the  character  over  the  cursor
    position. 
    
        The <INS> key toggles the character insert mode on  and  off.  The
    default  mode  (unless  changed  in  the CONFIG.ME file) is overstrike
    mode. Pressing <INS> will change the mode to insert mode. Any  charac-
    ters typed will push the characters beyond it rightwards. When you are
    in  insert  mode,  the cursor will be block-shaped. On the other hand,
    when you are in overstrike mode, the cursor will be the  the  size  of
    the normal DOS cursor. 
    
        The  editor  considers  all  control  characters  and all extended
    ASCII characters  to  be  potential  commands.  This  means  that  all
    characters  whose ASCII values are between 32 and 126 will be inserted
    into the file as text. To insert the other characters, use the <QUOTE>
    command.
    
        The <QUOTE> command (key <ALT> Q) allows  you  to  insert  control
    characters  into your document. After typing the <QUOTE> key, the fol-
    lowing key you type will have its ASCII value inserted into the  text.
    command below. You may use the  <ALT>  key  in  conjunction  with  the
    numeric keypad to type in an extended character.
    
        Hitting  the  <RETURN> key has the effect of splitting the current
    line in two, starting at the cursor position. If you are at the end of
    the line, then this just has the effect of creating a new line.
    
        Although there can be as many as 32,767 characters  on  one  line,
    please  try  to  limit the number of characters to 256. This should be
    sufficient for most programming languages.
    
    
    
                              ERASING CHARACTERS
    
        The <DEL> key deletes the character under the cursor. If the  cur-
    sor is  at the end of a line, then the next line will be joined to the
    current line. 
    
        The <BACKSPACE> key deletes the character to the left of the  cur-
    sor. If the cursor is at the left margin, the line will be joined with
    the previous line. 
    







    Character Oriented Commands                     Chapter 3   Page 1


                               ME USERS MANUAL






        The <DEL WORD> command (key <SH> <DEL>) deletes the word under the
    cursor. 
    
        The  <DEL  EOL> command (key <SH> KEYPAD 5) deletes all characters
    from the cursor position to the end of the line.
    
    
                                   WORDWRAP
    
        The  editor  gives  you very basic word processing capabilities by
    using the wordwrap toggle in conjunction with altering the right  mar-
    gin.  The  <TOGGLE  WORDWRAP>  command  (the  CTRL  W key) will toggle
    wordwrap mode on and off. If wordwrap mode is on, then  you  will  see
    the letter 'W' on the status line in the "mode" area. 
    
        To  change  the  right margin, use the <RIGHT MARGIN> command (the
    ALT M key). You can type in the  numerical  value  of  the  new  right
    margin.
    
        If wordwrap mode is on, and if you type past the right margin, the
    word will wrap to the next line.
    
                                  8 BIT MODE
    
        All  keystrokes  which  produce a value over 127 are considered by
    the editor to be commands. If you want to  insert  an  extended  ASCII
    code into your document, you usually use the <QUOTE CHAR> command (the
    <ALT>  Q  key).  However, there may be times when you wish to insert a
    sequence of extended ASCII character without having to  type  <ALT>  Q
    before each one.
    
        The  <ALT>  7  key toggles between 7 bit mode and 8 bit mode. When
    you press the <ALT> 7 key to toggle 8 bit mode, the  number  '8'  will
    appear  on  the status line in the mode section. This means that 8 bit
    mode is ON. If you press <ALT> 7 again, the 8 will go away and regular
    7 bit mode will be enabled. 
    
        As long as 8 bit mode is ON, then  you  can  type  extended  ASCII
    sequences  without  having  to  hit  <ALT> Q before each character. To
    enter an extended ASCII code,  you  can  use  the  numeric  keypad  in
    conjunction  with  the ALT key, or you may type any function key which
    produces a character above 127. REMEMBER - all of the editors  command
    will be DISABLED until you toggle back to 7 bit mode.
    
    








    Character Oriented Commands                     Chapter 3   Page 2


                                ME USERS MANUAL






                             LINE-ORIENTED COMMANDS
     
         Since most programming languages  tend  to  be  line  oriented,  a
     programmer's  text  editor  should be able to insert, delete, and move
     lines easily. See the section on block commands to see how to mark and
     move a series of lines.
     
         The  <INSERT LINE> command (key F2) inserts a blank line above the
     cursor. If the auto-indent option is on, then the cursor will move  to
     the  column  corresponding  to  the  first  non-blank character of the
     previous line.
     
         The <APPEND LINE> command (SHIFT F2) will place a blank line below
     the current line. 
     
         The  <DUPLICATE  LINE> command (ALT F9) will duplicate the current
     line and place the copy on the next line. This is equivalent to press-
     ing <COPY>, then <DOWN>, then <PUT>. 
     
         The <DELETE LINE> command (key F1) deletes the line which the cur-
     sor is on. This command can be preceded by  a  count  (ie  -  <ESC>  3
     <DELETE LINE> deletes 3 lines). 
     
         The  <UNDO>  command  (key <ALT> U) allows you to restore the last
     lines or block that was deleted. Buffer 9  is  reserved  as  the  place
     where deleted lines  are  stored.  If  you  press  the  <DELETE  LINE>
     command  5  times,  then  those  5  lines can be restored by using the
     <UNDO> command.
     
























     Line Oriented Commands                          Chapter 4   Page 1


                                ME USERS MANUAL






                      CUTTING, PASTING, AND BLOCK COMMANDS
     
         A "buffer" is a block of memory that holds text. The editor  comes
     equipped  with several pre-defined system buffers used to hold "scrap"
     pieces of text. These buffers are referred to as "pick  buffers".  The
     pick  buffers  are  common to all of the windows in the editor. Hence,
     text that a pick buffer contains can be pasted into any window.
     
         There  are  ten "pick buffers" which you can use to save text when
     you are cutting and pasting text. The buffers are numbered from  0  to
     9,  and  the  default  buffer is number 0. To change the number of the
     current pick buffer, use the <CHG PICK BUFFER> command.  This  command
     is initially assigned to the <CTRL> F7 key.
     
         The  <PICK+CLEAR> command (key F8) clears the current pick buffer,
     and places the current line in the buffer. The line  is  then  deleted
     from  the  file.  This  command  is useful as the first step of moving
     lines from one location to another.
     
         The <PICK+APPEND> command (key <SH> f8) appends the  current  line
     to  the current pick buffer. The current line is then deleted from the
     file. 
     
         The   <COPY>  command  (key  <SH>  F9)  does  the  same  thing  as
     <PICK+CLEAR> except the current line is NOT deleted from the file. 
     
         All  three  of  the above commands may take an optional count (for
     example, <ESCAPE> 3 <PICK+CLEAR> will pick and delete the  next  three
     lines). There are ten pick buffers, numbered 0 through 9. Buffer 9 has
     a  special  use,  in  that  it  stores  lines and blocks that you have
     deleted with either the <DELETE  LINE>  command,  or  a  delete  block
     operation.  The  <UNDO>  command  looks  in  buffer  9 for lines to be
     reinstated. Buffer 0 is the default buffer.
     
     
                                 MARKING BLOCKS
     
         There  are  two  types  of text blocks that you can work with. One
     kind is a contiguous block, starting at one character  and  ending  at
     another. The other kind of block is a rectangular block.
     
         The <MARK> command (key F7) defines a block of text to perform  an
     operation  on.  Move  to  start of the block and press <MARK> - a grey
     rectangle will be shown where you marked the text. Then  move  to  the
     end  of  the  block  and  press <MARK> again. The entire block will be
     highlighted. You are prompted for the  operation  to  perform  on  the
     block.  The  current operations are pick & clear, pick & append, copy,






     Working with Blocks                             Chapter 5   Page 1


                                ME USERS MANUAL






     delete, or write to a file.  If you want to abort the operation, press
     either <ESC> or <CTRL> D. 
     
         The  <RECT  MARK>  command  (key  <SH>  F7)  is  like  the  <MARK>
     operation, except it defines a rectangular block. This is  useful  for
     manipulating  columns. If you pick or delete a rectangular block, then
     you are asked if you want to delete the column or replace  the  column
     with blanks. The default is to delete the column.
     
     
                                  PASTING TEXT
     
         The  <PUT> command (key F9) allows you to take the contents of the
     current pick buffer and place it in your text. (Remember that you  can
     change the current pick buffer with the <CHG  PICK  BUFFER>  command.)
     
         There are three ways that you can put text back into the file. The
     first (and most common) way is to  INSERT  the  lines  from  the  pick
     buffer above the current line. The second  method  is  to  insert  the
     text  at  the  current  cursor  position, pushing the old texst to the
     right. The third method is to overlay the text, wiping  out  any  text
     that  was  there before. The latter two methods are used predominantly
     with COLUMNS of text.
      
         Since most programming languages are line oriented, then the first
     method  of  pasting  the  text  is the one that will be used most fre-
     quently. There is an editor variable which controls whether or not you
     will be prompted for the method you want when you hit the  <PUT>  com-
     mand. This variable, the 'pu' variable in the options menu, is normal-
     ly  off.  If the editor detects that the text that resides in the pick
     buffer was NOT columnar data, and if the 'pu' variable  is  OFF,  then
     the editor will not prompt you for the pasting method. 
     
         If  the 'pu' variable is ON, then you are asked if you want to in-
     sert the text above the cursor, insert the text to the  right  of  the
     cursor, or overlay the text at the cursor position (only if you used a
     <RECT MARK> to extract a column).  These  choices  are  labelled  'i',
     'p',  and  'o'.  The  default is to insert the text above the cursor -
     just hit the <RETURN> key to insert.
     
     
                         OPERATIONS ON GROUPS OF LINES
     
         Since  the structure of computer programs is more oriented towards
     LINES rather than a STREAM of text,  the  editor  provides  operations
     which  you can perform on a disjoint or contiguous set of lines. These
     operations are the same ones as you find withy the  block  operations.
     They are :






     Working with Blocks                             Chapter 5   Page 2


                                ME USERS MANUAL






     
             - Delete a group of lines (F1)
             - Append lines to a pick buffer (SH F8)
             - Place lines in a pick buffer (erasing the pick buffer first)
                (F8)
             - Copy lines into a pick buffer (SH F9)
             - Write marked lines to a file (ALT W)
     
         Normally,  all of the above operations operate on a single line at
     a time (unless preceeded by a count operation). However, if the editor
     detects that there are marked lines, then the operations are performed
     on the marked lines.
     
         There are three keystrokes used to mark lines. They are :
     
             <MARK LINE> (ALT F7) - marks the current line. The  line  will
     be highlighted.
             <MARK  GROUP> (ALT F8) - marks all lines from the current line
     until the previous marked line. For instance, if  you  mark  line  10,
     move the cursor to line 15, and press ALT F8, then lines 11 through 15
     will  be  marked.
             <CLEAR  MARKS>  (CTRL  F8) - this keystroke is usually used to
     erase a block mark that was previously entered. However, if the editor
     sees that lines are marked, then the lines will be unmarked. 
     
         The  <DUPLICATE LINE> command (the ALT F9 key) provides a shortcut
     for copying a group of marked lines to the  current  cursor  position.
     Mark  the  lines  which  you want to make a copy of, and then move the
     cursor to the line where you would like the copied  lines  to  appear.
     Press  <DUPLICATE  LINE>,  and  the  lines will be inserted before the
     line which the cursor is on.
     
         If   you   are   programming  in  the  macro  language,  then  the
     is_linemarked() primitive is used  to  tell  if  the  current  lie  is
     marked.  It  returns  a  zero  if  the  line is not marked, or else it
     returns a non-zero.

















     Working with Blocks                             Chapter 5   Page 3


                               ME USERS MANUAL






                            INPUT/OUTPUT COMMANDS 
    
        The  input  and  ouput  commands  support  full  DOS  path  names,
    including a drive specifier.
    
        The <READ> command (key <SH> F10) reads a  file  and  inserts  the
    contents before the current line. The file should be  an  ASCII  file,
    although it may have embedded control characters.
    
        The  <WRITE> command (key F10) allows you to save the file you are
    editing to another file. You can print the  file  by  specifying  your
    printer  device  as the output file. The name of the printer device is
    usually PRN or LPT1.
    
        The <WRITE BUFFER> command (key <ALT> W) does the  same  thing  as
    <WRITE>  but the lines are taken from the current pick buffer (see the
    help  on  block commands). If the editor detects that there are marked
    lines, then the <WRITE BUFFER> command will write the marked lines out
    to a file.


































    Input/Output Commands                           Chapter 6   Page 1


                                ME USERS MANUAL






                             SEARCHING AND SUBSTITUTING
     
         The editor allows you to search forwards or backwards through  the
     file for a certain pattern. You can specify whether the search is case
     insensitive  or  not.  The  editor  allows  you to use a very powerful
     mechanism called "regular expressions".
     
         The  use  of regular expressions has become very popular since the
     use of UNIX has become widespread. Although most operating systems let
     you specify wildcards, UNIX carries the class of expressions  further.
     For  a  good  discussion  of  regular expressions, please see the book
     "Software Tools" by Kernigan and Ritchie, published by Addison Wesley.
     (UNIX is a trademark of AT&T.)
     
         The process of searching is done much faster if the editor detects
     that  the  pattern you specify does not contain any regular expression
     metacharacters. The editor uses an assembly language  procedure  which
     makes use of the fast 8088 string comparison instructions.
     
         When you type one of the search commands, the editor shows you the
     previous pattern that you typed. If  you  want  to  use  that  pattern
     again, then just press <RETURN>.
     
     
                                   METACHARACTERS
     
     ?       Matches any character
     *       Matches zero or more occurences of the previous pattern.
     +       Matches one or more occurences of the previous pattern.
     [A-Z]   A character class. Matches any character within the class.
     [^A-Z]  Matches any character NOT IN the class.
     \       Takes the next character literally.
     ^       Anchors the match at the beginning of the line.
     $       The match succeeds if at the end of the line.
     a|b     Matches pattern a or pattern b.
     \(a\)   Tags pattern a.
     \n      Refers to the tagged pattern n. N is a number from 1 to 9.
     
     
                                      EXAMPLES
     
     abc             Matches 'abc'.
     ^$              Matches a line with no characters.
     ^abc            Matches a line which starts with 'abc'.
     ^abc$           Matches a line which contains only 'abc'.
     [A-Z][0-9]      Matches a capital letter followed by a digit.
     [^A-Za-z0-9]    Matches a character which is not alphanumeric.






     Searching and Substituting                      Chapter 7   Page 1


                                ME USERS MANUAL






     be?t            Matches 'be', followed by any character, followed by a 't'.
                             (ie - bert, belt, bent).
     ab*c            Matches an 'a', followed by zero or more 'b's, followed by
                             a 'c'.
     ab\*c           Matches 'ab*c'.
     [A-Z][A-Z]*[.?,! ]      Matches a capitalized word.
     if|else         Matches the word 'if' or the word 'else'.
     if|else|for     Matches 'if' or 'else' or 'while'.
     \(abc\)[0-9]\1  Matches 'abc', any digit, then 'abc'.
     \([A-Z]+\)?*\1  Matches a line which case two or more occurences of the
                     same upper-case word.
     
     
         You  are  also allowed to search for a pattern and replace it with
     some text. The substitution commands prompt you for the search pattern
     first, and then the text to be  substituted.  Then,  you  can  specify
     whether  the substitution operation should be done with or without any
     approval.
     
         If you decide to approve each change, then the editor  will  pause
     after  it  has  found a match. You are given the option to perform the
     change ('y'), to ignore the change ('n'), or to quit the  substitution
     operation ('q').
     
         In  the substitution text, you may use the metacharacter '&'. This
     means that you want to use the matched pattern as  part  of  the  sub-
     stitution text.
     
         For  example, let's say that you specified 'abc' as the pattern to
     search for. A substitution  text  of  '&xxx'  would  change  'abc'  to
     'abcxxx'.  Likewise,  a  substitution  text of '12 && 34' would change
     'abc' to '12 abcabc 34'. To use a '&' literally  in  the  substitution
     text, preceed the '&' by a backslash ('\').
     
         In  the substitution text, you may also refer to a tagged pattern.
     For example, let's say that the pattern that you searched for was :
       \(dog\) = \(cat\)
     If you want to replace every occurence of "dog = cat" by "cat =  dog",
     then the substitution pattern that you specify can be :
       \2 = \1
     What  this  says  is that you want the new substitution text to be the
     first matched pattern ("dog") followed by  "  =  ",  followed  by  the
     second matched pattern ("cat").
     
         To show a more powerful example, you can have the search pattern :
       \([a-z]+\)->prev = \([a-z]+\);
     and the substitution pattern :






     Searching and Substituting                      Chapter 7   Page 2


                                ME USERS MANUAL






       \2->next = \1;
     The pattern will match a sequence of lower case letters,  followed  by
     "->next = ",  followed by another sequence of lower case letters, fol-
     lowed by a semi-colon. The first sequence of lower case  letters  that
     is  matched  is  tagged as "\1", and the second sequence of lower case
     letters is tagged as "\2". This would change the line
       currentline->prev = newline;
     to
       newline->next = currentline;
     
         If you need to search for any special control characters, then you
     can  use  the <QUOTE> (ALT Q) command. When you press the <QUOTE> key,
     the next character that you type will be  inserted  literally  in  the
     search string.
     
         Searches are normally sensitive to case (ie - upper and lower case
     letters are different). The <IGNORE CASE> command toggles a flag which
     allows searches to ignore the case of letters. The key associated with
     this command is <ALT> F5.
     

































     Searching and Substituting                      Chapter 7   Page 3


                               ME USERS MANUAL






                               KEYBOARD MACROS
    
        The editor lets you save a sequence of keystrokes  that  you  type
    for  later  use.  This  is referred to as a "keystroke macro". You can
    have only one keystroke macro defined at a time.  (If  popular  demand
    warrants it, we will lift this restriction in future versions.) 
    
        Keystroke macros are useful if you must perform a tedious sequence
    of keystrokes over and over. The sequence is so simple that it may not
    be  worth  it  to write a macro program to do the task. If this is the
    case, invoke the <CAPTURE> command, type the  sequence  of  keystrokes
    once, and then press <CAPTURE> again. Your sequence of keystrokes will
    be saved, and can be replayed by pressing the <REPLAY> key. 
    
    
    <CAPTURE>                              <F4>
    
        This  function  starts  the  definition  of  a keyboard macro. All
    keystrokes that are typed are saved in memory  in  addition  to  being
    sent  to  the  editor.  Pressing  the <CAPTURE> key again will end the
    macro definition. See <REPLAY> to  see  how  to  recall  the  keyboard
    macro. 
    
    <REPLAY>                               <F3>
    
        This function replays a keyboard macro that was previously defined
    by the <CAPTURE> function. This command also takes an optional numeric
    argument, so that <ESC> 5 <REPLAY> will replay the keyboard macro five
    times. 
    
    
    <GENERATE MACRO>                       <SH> <F3>
    
        Occasionally, you may have a keystroke macro that you like so much
    that you will want to write a macro program which does the same thing.
    The <GENERATE MACRO> function prompts you for the name which you would
    like  to call this generated macro. You are also prompted for the file
    name which you would like to APPEND the generated macro to. The editor
    will  then  try  to  generate  a  macro function in the editor's macro
    programming language.
    
        The  generated macro will be APPENDED to the file you specify. The
    reason for this is because you might have a special macro  file  which
    you  like  to  save  these  little  gems  in.  You  should examine the
    generated macro to make sure that the editor generated the right code. 
    







    Keystroke Macros                                Chapter 8   Page 1


                               ME USERS MANUAL






                                WINDOW COMMANDS
    
        A  "window"  is  a view into a buffer of text. Initially, you have
    one full-screen sized window into your file.  There  are  commands  to
    create and delete windows.
    
        Two  windows  can show different parts of the same buffer. This is
    useful if you have a long document, and you want to refer to one  part
    of  the  document  while editing another. Of course, different windows
    can contain different buffers.
    
        The editor allows you to have as many as 12 windows visible on the
    screen.  The  screen  is split horizontally for each of these windows,
    with each window being approximately the same size. 
    
        Many times, you would like to expand a window to take up the whole
    screen. There is a function to enlarge a window so that  it  takes  up
    the  whole screen, and to shrink a window back down and make the other
    windows visible. 
    
        You are allowed to transfer text between windows. The 10 pick buf-
    fers are common to all windows. Any text put into a pick buffer can be
    pasted into any window. 
    
    
    <SPLIT>                                <ALT> 2
    
        This functions adds another window to the screen. You can have  at
    most  12  windows.  Each  window  is  split  horizontally, and has ap-
    proximately the same number of lines. 
    
        You are prompted for the file name to read into  the  new  window.
    Type in the name, or press <RETURN> to have a copy of the current buf-
    fer inserted into the new window. 
    
    <CLOSE WINDOW>                         <ALT> 1 or <CTRL> D
    
        This function closes the current window (the window which the cur-
    sor is in). You are asked if you want to save the contents of the file
    in that window. 
    
    <ENLARGE WINDOW>                       <ALT> +
    
        This  function  allows you to expand the current window occupy the
    entire screen. If there are any other windows, they  will  remain  in-
    visible until the <SHRINK WINDOW> command is pressed. 
    






    Editing Multiple Files with Windows             Chpater 9   Page 1


                               ME USERS MANUAL






    <SHRINK WINDOW>                        <ALT> -
    
        This function makes all windows visible. This is used in  conjunc-
    tion with the <ENLARGE WINDOW> command. 
    
    <NEXT WINDOW>                          <PRTSC>
    
        This function moves the cursor to the next window on  the  screen,
    and makes that window the current window.
    











































    Editing Multiple Files with Windows             Chpater 9   Page 2


                               ME USERS MANUAL






                            MISCELLANEOUS COMMANDS
    
        The <MATCH BRACE> command will find a corresponding curly brace or
    parenthesis.  If  the cursor is on a left curly brace or a left paren-
    thesis, then the editor will search forward for a corresponding  right
    brace  or  right  paren.  If the cursor is on a right brace or a right
    paren, then the editor will search  backwards  for  the  corresponding
    left  brace  or  left paren. If the match is found, then the cursor is
    placed on the matched character. If no match is found, an  error  mes-
    sage will be given. 
    
        You  can set variable length tabs by using the <SET TABS> command.
    This command is invoked by the <ALT> T key. You will first be prompted
    to see if you want to clear the previously set tab stops.  Then,  type
    in the list of tab stops, each number separated by one or more blanks.
    For  instance, an assembly language programmer may want to set tabs at
    "10 16 23 35".
    
        The <REDRAW SCREEN> command (key <ALT> R) clears  the  screen  and
    draws  a new copy of the text on the screen. This is useful if you are
    not sure of what's on the screen, or if  funny  characters  appear  on
    your screen due to noise on communication lines. 
    
        If you have an Enhanced Graphics Adapter, the <TOGGLE EGA> command
    (CTRL E) will toggle you in and out of 43 line mode. 
    
        The <OPERATING SYSTEM> command (key <ALT> X) allows you to execute
    an  operating system command from within the editor. Type the command,
    followed by <RETURN>, and the command will be executed. After the com-
    mand is finished, you will be brought back to your editing screen.  In
    DOS, you can invoke a secondary command processor by typing "command".
    You  will  then  "leave" the word processor, and you can interact with
    DOS. When you want to return to the editing session, type the DOS com-
    mand "exit". 
    
        There  is  another interface to MS-DOS called <DOS CAPTURE>, which
    is invoked by hitting the <CTRL> X key. This  command  functions  like
    <OPERATING SYSTEM> command, except that a complete  log  of  your  DOS
    session  will  be kept. When you exit the command, the captured output
    will be put in another window. If you want to save this file, you must
    use the <WRITE FILE> command to save it to another file. (This is  be-
    cause  the temporary file that the session is saved in will be deleted
    automatically.) 
    
        The  <VERSION>  (key <ALT> V) command displays the current version
    number of the editor.







    Miscellaneous Commands                          Chapter 10  Page 1


                               ME USERS MANUAL






    




















































    Miscellaneous Commands                          Chapter 10  Page 2


                               ME USERS MANUAL






                               EDITOR VARIABLES
    
        There are several variables that are associated with  the  editor.
    These  variables  control some of the behavior of the editor during an
    editing session. By altering these values, you can  further  customize
    your editing session.
    
    
                            THE CONFIGURATION FILE
    
        Included  in the editor package is a file called "CONFIG.ME". This
    file contains a list of the editor variables and their default values.
    The meaning of each editor variable is explained below.
    
        When the editor starts up, it will  try  to  find  the "CONFIG.ME"
    file. The editor will first search your current directory, and if it's
    not  found  there, will search each directory in your DOS search path.
    If the file is still not found, then the editor will use its  built-in
    default values.
    
        There  are directions inside the "CONFIG.ME" file for altering the
    default values.
    
    
                    CHANGING THE VARIABLES FROM THE EDITOR
    
        You can alter any of the  editor  variables  during  your  editing
    session.  To do this, use the <OPTIONS> command. The default keystroke
    for this is <ALT> O.
    
        When you press the <OPTIONS> key, the screen  will  clear,  and  a
    list  of  editor variables will be shown. The name of each variable is
    shown, followed by its two-character code, followed by its  value.  To
    change  the  value of a variable, type the two-character code followed
    by a blank, followed by the value.
    
        As an example, let's say that you want to disable the auto  indent
    feature.  From  the options menu, locate the auto indent variable. You
    see that its two-letter code is "ai". Type "ai n", and  hit  <RETURN>.
    You will see that the auto indent variable has changed.
    
        To get back to the editing session, press either the <ESC> key  or
    the <CTRL> D key. The new values will take effect when you return from
    the  options menu. The changes remain in effect just until the editing
    session is over.
    
    






    Configuring the Editor                          Chapter 11  Page 1


                               ME USERS MANUAL






                             THE EDITOR VARIABLES
    
        Below is a list of the editor variables which are used to  control
    your  editing  session.  After  the  name  of  the  option  is the two
    character code which you use when you want to change an option.
    
    
        Horizontal Scroll (hs)
    
        This variable determines how many columns the screen  will  scroll
    leftwards  or  rightwards  when  horizontal  scrolling  is  performed.
    Horizontal scrolling will be initially performed when the cursor moves
    past the right edge of the current window. The default value  of  this
    variable is 40 columns.
    
        Vertical Scroll (vs)
    
        This parameter controls the number of lines the cursor moves  when
    the  <PGUP>  and <PGDN> key are pressed. When those two keys are pres-
    sed, then the value of the VS parameter will be  SUBTRACTED  from  the
    current  window  size. The result is the number of lines in the buffer
    that the cursor will move upwards or downwards. 
    
        As an example, if you want the cursor to move down only  20  lines
    when  the  <PGDN>  key  is  hit, then the VS parameter should have the
    value 4. In a full screen window, the cursor will move  (24  4)  =  20
    lines.  However, in a split screen window, the cursor will move (11-4)
    = 7 lines. 
    
    
    
    
        Foreground Color (fg)
        Background Color (bg)
    
        These variables determine the color of the characters (foreground)
    and the "spaces" (background). These variables only take effect if you
    have a color card in your PC.  Each  variable  can  take  on  a  Talue
    from  0 to 7. The colors are set according to the standard IBM PC con-
    ventions. Here is a table of the colors and their associated values :
    
      0  Black   (default for background color)
      1  Blue
      2  Green
      3  Cyan
      4  Yellow
      5  Magenta






    Configuring the Editor                          Chapter 11  Page 2


                               ME USERS MANUAL






      6  Brown
      7  White   (default for foreground color)
    
    
        Increment for tab stops (ta)
    
        Controls  the  distance between tab stops. The default value is 8,
    which means that tab stops will be set at columns 9, 17, 25, 33, etc.
    
    
        Filler for tabs  (tb)
    
        When  the <TAB> key is pressed, blank spaces will be inserted into
    the text until the cursor reaches the next tab stop. However,  instead
    of  blanks  being  inserted,  you can choose any character as the fill
    character. This variable takes the ASCII value of the character as its
    value. The default is the space character, which has ASCII value 32.
    
        Automatic Indentation (ai)
    
        When a new line is created (by hitting the  <RETURN>  key  or  the
    <INSERT LINE> key), you can specify whether or not the new line should
    be automatically indented. If this variable has a non-zero value, then
    the new line will be indented underneath the first non-blank character
    of  the  previous  line.  This  feature  is  especially convenient for
    programmers who like to indent their code after certain statements.
    
    
        Automatic backup (ab)
    
        To  help  prevent  losing your work in case of a system crash, the
    editor has an option to do automatic backups. If this  option  is  on,
    then the editor will write out the contents of the current buffer to a
    "filename.BK2"  file  periodically. See the option below to change the
    periodicity. If you finish your editing session successfully, then the
    backup file will be deleted.
    
        Please note that the "BK2" file is different than the ".BAK"  file
    that  the  editor  creates  when you save your work. The "BAK" file is
    just a copy of your old file before the  editing  session.  The  "BK2"
    file  is  a  "snapshot"  of  your  current  session  made  at periodic
    intervals.
    
        Create .BAK file (bk)
    








    Configuring the Editor                          Chapter 11  Page 3


                               ME USERS MANUAL






        If  this  option  is OFF, then the editor will NOT create a backup
    file if you save the current file. The only advantage of turning  this
    option  OFF  is that you won't clutter your disk with .BAK files. But,
    we have come to rely on the .BAK files on numerous ocassions.
    
        Keystrokes for automatic backup (sv)
    
        If the automatic backup feature is  enabled,  then  this  variable
    controls the period between saves, measured in keystrokes. The default
    is  to  do  an  automatic  backup  once every 1000 keystrokes. You can
    decrease this amount for more  reliability,  or  increase  it  if  the
    wait during the automatic backup is annoying.
    
        Sound Bell with Prompts (bl)
    
        If  this  parameter  is  on,  then  the  bell on the PC will sound
    whenever the editor prompts you for a command. The bell may be  annoy-
    ing  to  you,  depending  on  how late you're staying up to debug your
    program. 
    
        Insert Mode (in)
    
        This variable determined whether the editor will be in  insert  or
    overstrike  mode  when  the  editor  starts  up.  Give this variable a
    non-zero value if you want insert mode to be the default.
    
        Cursor can go into "Free Space" (fs)
    
        The  term "Free Space" refers to the area after the last character
    of a line. Some editors refuse to let you move the cursor past the end
    of a line; if you do, then the cursor  usually  jumps  to  either  the
    first  character of the next line, or the column immediately after the
    end of the line. If the Free Space variable is off,  then  the  editor
    will not let the cursor move into free space.
    
        If you type a character in free space, then the area from the last
    character  of  the  line  until the column where the cursor is will be
    filled with blanks.
    
        Prompt user for <PUT> option (pu)
    
        If  this  variable is OFF, and the text that is in the pick buffer
    was not put in there by a columnar block operation,  then  the  editor
    will  not prompt you when you <PUT> the text. (Key F9). Otherwise, the
    editor will ask you if you want to insert the text above  the  current
    line, push the text before the cursor position, or overlay the text.
    






    Configuring the Editor                          Chapter 11  Page 4


                               ME USERS MANUAL






        Wait for acknowledgement of an error (er)
    
        If  this  variable  is  ON,  then the user must hit a key after an
    error message is printed on the status line. If this variable is  OFF,
    then  the  error message will be printed, but the user can go right on
    typing commands.
    
        Strip high bits when reading a file (hb)
    
        Some  word  processors  use  a special encoding where they set the
    high bit ON on some of the characters. If this option is ON, then each
    character that is read in will have its high bit turned OFF. 
    
        Convert blanks to tabs (bt)
    
        In  order to save disk space, you may choose to compress sequences
    of blanks to tabs when the file is saved. The default value is OFF, so
    your output file will contain no tabs. 
    
        Snow on CGA? (ns)
    
        Many  Color  Graphics  Adapters require you to wait for horizontal
    retrace before writing a character to  the  screen.  However,  certain
    CGAs do not require the waiting period. If your CGA does not require a
    wait, turn this option OFF (ie - there is NO snow).
    



























    Configuring the Editor                          Chapter 11  Page 5


                               ME USERS MANUAL






                              THE MACRO LANGUAGE
    
        Even   though  the  editor  is  a  very  powerful  tool  for  text
    manipulation, sometimes you find yourself wishing  for  commands  that
    the editor does not provide. Therefore, the editor provides a facility
    for  you to write your own editing commands. These commands are called
    "macros". 
    
        The  macro  language  that  the  editor  comes  with resembles the
    programming language called "C". Although the macro language is a  far
    cry from the complete C language, the syntax of the statements closely
    resembles that of C.
    
    
                              COMPILING A MACRO
    
        A macro file can contain several macros. The macro  file  must  be
    compiled with the macro compiler  (maccomp.exe).  If  the  compile  is
    successful,  then  the  compiled  macro  will be written out to a file
    with the same "root" name, but with the extension ".EXM". Then the ex-
    ecutable version of the macro (macro.exm) should be  loaded  into  the
    editor when you want to use it.
    
        To load a macro into the editor, you can
    
      1)  use the <ALT> P key and specify the name of the macro. This will
    load but NOT execute the macro. See below for  directions  on  how  to
    execute a macro.
    
      2)  use  the -l option on the command line, and give the name of the
    macro file after the "l". Example - "me -lisrch foo.c".
    
    
                              EXECUTING A MACRO
    
        In order to execute a macro, the macro must  be  loaded  into  the
    editor  by either one of the two methods mentioned above. Once a macro
    is loaded, you can press the <ALT> P key, and give  the  name  of  the
    macro to execute.
    
        Additionally,  you  can  make  any keystroke invoke a macro. To do
    this, use the <ASSIGN KEY> command (the ALT F4 key). You are asked for
    the name of the macro to invoke, and for the keystroke  which  invokes
    it.
    








    Introduction to the Macro Language              Chapter 12  Page 1


                               ME USERS MANUAL






        You  can  bind  a  keystroke  to a macro by using the assign_key()
    function in the macro. You should define the  key  assignment  in  the
    macro's init() procedure (see the end of this chapter).
    
    
                                  DATA TYPES
    
        The  macro  language supports two data types - integer and string.
    An integer is a whole number between -32,767 and +32,767. A string  is
    a sequence of 1 or more characters, ended by the NULL character (ASCII
    value 0).
    
        In the macro language, the word "int" is used to declare variables
    as  type  integer.  The  word  "string"  is  used  to  declare  string
    variables.  If  you  are a C programmer, be careful not to slip up and
    declare string variables as "char *".
    
    
                                  CONSTANTS
    
        An  integer  is  a  sequence  of  digits,  preceded by an optional
    negative sign.
    
        A single character can be referred to by enclosing  it  in  single
    quotes.   Characters  will  be  converted  internally  to  an  integer
    representing the ASCII value of the character. 
    
        You  can  represent   non-printable   characters   and   non-ASCII
    characters  by  enclosing  between  the  single  quotes  a  backslash,
    followed by  up  to  3  digits.  For  instance,  '\07'  represents the
    character CTRL-G (ASCII value 7), and '\233' represents the value 233.
    Notice that the written number is decimal (not octal).
    
        Several   popular   control  characters  can  be  expressed  by  a
    backslash, followed by a letter. Here is a list of those characters.
    
      '\b'  backspace
      '\n'  newline
      '\E'  escape
      '\''  single quote
      '\\'  backslash
    
        A string is a sequence of characters enclosed  in  double  quotes.
    Internally, each string is ended by an invisible NULL character (ASCII
    value  0). You do not have to write the NULL character - its prescence
    is implied by  the  definition  of  a  string.  However,  if  you  are
    examining the string by looking at a character at a time, you can test
    the current character to see if it's 0.






    Introduction to the Macro Language              Chapter 12  Page 2


                               ME USERS MANUAL






    
        Any  character  in the string can be one of the control characters
    mentioned above.
    
    
                                  OPERATORS
    
      Arithmetic operators
    
      +  addition
      -  subtraction or unary minus
      *  multiplication
      /  division
      %  modulo (remainder)
    
        As in most programming languages, multiplication and division take
    precedence over addition and subtraction.
    
       Auto increment and decrement are supported,  as  are  certain  aug-
    mented operators. You can have the constructs 
      
        ++x, x++, --x, x--
        x += y, x -= y, x *= y, x /= y, x %= y
    
      Relational operators
    
      <  less than
      <= less than or equal
      >  greater than
      >= greater than or equal
      == equal
      != not equal
    
        Relational operators have equal precedence. Relational expressions
    evaluate  to 1 if true and to 0 if false. The relational operators can
    be applied to both data types, integer and string. (Note to C program-
    mers - there is no  strcmp()  function  you  can  use  the  relational
    operators to compare strings). 
    
      Logical operators
    
      && and
      || or
      !  not
    








    Introduction to the Macro Language              Chapter 12  Page 3


                               ME USERS MANUAL






        NOT has the highest precedence, followed by AND, and then OR.
    
    
    
                                  CONVERSIONS
    
        While the macro program is executing, the interpreter will attempt
    to  perform  conversions  of  data types to prevent the macro programs
    from bombing.
    
    
                             COMPILER DIRECTIVES
    
        The macro compiler can accept the directives #define and #include.
    The  #define  resembles the #define directive used in the C prepreces-
    sor. The #define directive takes a word and  a  string  it  should  be
    replaced  by.  At  this point, you cannot have macro functions defined
    (ie you cannot have something like "#define sqr(x) ((x)*(x))" yet). 
    
      example of #define
    
    #define CTRL_C    3
    assign_key("center", CTRL_C);
    
        The macro language has an #include directive which allows  you  to
    include files for compilation. The syntax is : 
    
      #include filename
    
    As an example, 
    
      #include srchmark
    
    (Note - filename should NOT be in quotes NOR in angle brackets like in
    C).
    
    
    
                                 STATEMENTS
    
        Each  statement  must be ended by a semi-colon (';').  There is no 
    limit on the number of statements on one line,  or the column in which 
    a statement begins. The macro compiler is insensitive to white space.  
    
    LIST OF STATEMENTS
    







    Introduction to the Macro Language              Chapter 12  Page 4


                               ME USERS MANUAL






    Assignment
    
      variable = value;
    
        This statement is used to put a certain value into the variable on 
    the  left hand side of the '=' sign.  The value can be any expression, 
    which can be comprised of other variables, constants, and operators.  
    
        Examples :
    
      int n;
      string s;
    
      n = 3;
      n = n * 5 + strlen(str);
      s = "This is a message";
    
    
    If statement
    
      if (condition) 
        stmt;
    
      if (condition)
        stmt;
      else
        stmt;
    
        The condition inside the parentheses is evaluated, and tested  for
    a  non-zero value. If the result is non-zero, then the statement after
    the if (the "then" portion) will be executed. If the result was  zero,
    then the "else" portion will be executed.
    
        Each  'stmt'  can be a group of statements. This is often referred
    to as a "block statement". In this macro language, a  block  statement
    must  start  with  a  left curly brace ('{') and must end with a right
    curly brace ('}').
    
        As an example,
        
       if (x == 1)
       {
         y = 2 * y;
         insert(itoa(y));
       }
       else
       {






    Introduction to the Macro Language              Chapter 12  Page 5


                               ME USERS MANUAL






         x = x - 1;
         y = 3;
       }
    
        The curly braces may occur on the same line as the  "if"  and  the
    "else" parts. The style of indenting is up to you.
    
    
    While statement
    
      while (condition)
        stmt;
    
        The statement inside the 'while' will be executed continuously un-
    til the condition is found to be zero. 
    
        Example :
    
      while (!is_eol())
      {
        if (currchar() == 'x')
          delchar();
        else
          right();
      }
    
    
    For statement
    
      for (initial statement;  condition;  increment)
        stmt;
    
        This is equivalent to
    
      initial statement;
      while (condition)
      {
        stmt;
        increment;
      }
    
        The for statement is a more convenient way to do looping than  the 
    while  statement  if  the  loop  involves  counting  from one value to 
    another.  
    
    







    Introduction to the Macro Language              Chapter 12  Page 6


                               ME USERS MANUAL






    Break statement
    
      break;
    
        The break statement is used to exit from the inner most loop. If 
    there is only one loop, then the loop is exited.
    
        Example
    
          while (x < 13)
          {
             ....
             for (i = 1;  i <= len;  i = i + 1)
             {
                ......
                if (x < 0)
                  break;      /* go to the "x = x+1" statement */
                ......
             }
             x = x + 1;
          } 
    
    
    Function calls
    
      function_name ([arg1, arg2, ..., argn]);
    
        You  can  call  any primitive function, any built-in macro, or any
    macro which you define. The calling function can pass arguments to the
    called routine. Each argument in the argument list  is  an  expression
    which  is evaluated, and then whose result is passed down to the call-
    ing routines. Arguments are passed by value, not by reference. 
    
        Examples :
    
        justify_line();
    
        if (is_string_numeric(str))
          ......
    
        n = strlen(str1) + strlen(n2);
    
    
    Return statement
    








    Introduction to the Macro Language              Chapter 12  Page 7


                               ME USERS MANUAL






      return;
      return expression;
    
        A return statement is used to terminate a macro and return to  the 
    calling macro, if any. An optional value may be returned by the macro.  
    The  return  expression  may be of type integer or type string.  Since 
    there is no type associated with a macro,  one  return  statement  may 
    return a string while another may return an integer.  
    
    
                                   COMMENTS
    
        Any  text  that  falls  between  "/*" (comment begin sequence) and
    "*/" (comment end sequence) will be ignored by the macro compiler, and
    will be treated as a comment. A comment may be placed on a line by it-
    self,  or  may  be  placed  after a statement. A comment can also span
    several lines.
    
    
                          THE LAYOUT OF A MACRO FILE
    
        A macro file looks like this :
    
      [optional global variable declarations]
    
      macro1 defintion
    
      [optional globals - seen only by macros 2-n]
    
      macro2 defintion
    
      ................
    
      macro n definition
    
    
                               GLOBAL VARIABLES
    
        Any global variables that you use should be declared at the top of
    the  macro  file.  These variables may be accessed by any macro in the
    macro file. 
    
        You can also declare globals in between two macro definitions  (ie 
    -  after  the  right  curly  brace  which ends a macro).  These global 
    definitions are only seen by the macros which  come  physically  AFTER
    these globals in the file. 
    
    






    Introduction to the Macro Language              Chapter 12  Page 8


                               ME USERS MANUAL






                               LOCAL VARIABLES
    
        Local variables are variables which can only be  used  within  the
    macro  which  they are declared in. These include the parameters which
    are passed to a macro. 
    
        If a variable is used inside a macro, and has not  been  declared,
    then the macro interpreter will declare  it  automatically,  and  will
    try  to  determine  its data type from the context in which it's used.
    The default type is integer. 
    
    
                              DEFINING A MACRO
    
        There can be as multiple macros defined in one  macro  file.  Each
    macro definition has the following form : 
    
      macro-name ([parameters])
        [parameter declarations]
      {
        [local variable declarations]
    
        statements
      }
    
        The first line is a header that contains the name  of  the  macro,
    and  an  optional list of parameters. The macro name must start with a
    letter or an underscore ('_'). The parentheses must follow  the  macro
    name, even if there are no parameters.
    
        If  the  macro  has  parameters,  then  the parameter declarations
    should follow. The  declarations  give  the  type  and  name  of  each
    parameter.  The  parameters  can  either  be  integer  or string. If a
    declaration for a parameter is left out, then the parameter is assumed
    to be of type integer.
    
        After the optional parameter declarations, a left curly brace must
    follow. Any local variables that the macro  uses  should  be  declared
    now.  Then  comes  the list of statement that comprise the body of the
    macro. The right curly brace ends the entire macro.
    
        If  you  are a C programmer, you may be used to declaring the type
    of the function, whether it be  an  integer  function  or  a  function
    returning  a  pointer.  In  this  macro  language,  there  are no type
    declarations associated with macros. The type of value  that  a  macro
    returns (if any) is determined by the RETURN statement.
    






    Introduction to the Macro Language              Chapter 12  Page 9


                               ME USERS MANUAL






        As  a  detailed example of a macro, let's consider writing a macro
    that  determines  if  a  string  contains all digits. The name of this
    macro will be "is_string_numeric". This macro, which should be  called
    by  another  macro,  takes one parameter - the string to examine. This
    macro should return 1 if the string is all numeric, and 0 if not.
    
        A loop is used to traverse the string, one character at a time. To
    extract the character  at  the  ith  position,  we  use  the  built-in
    function  substr().  The first argument to substr() is the name of the
    string to examine, the second argument is  the  starting  position  to
    look  at,  and  the  thrid  argument  is  the  number of characters to
    extract. Substr() returns a string result.
    
        The character is then tested to see if it falls outside the  range
    of  "0"  to  "9".  If  it  does,  then  that  means that a non-numeric
    character was found, and 0 is returned.
    
        If the loop ends, that means that all the characters were numeric.
    The second return statement is executed, and  1  is  returned  to  the
    calling macro.
    
    
    is_string_numeric(str)         /* macro definition */
      string str;                  /* parameters */
    {
      string  c;                   /* local variables */
      int  i, len;
    
      len = strlen(str);         /* get the number of characters in str */
    
      /* The for loop is used to walk through the string, one character at
       * a time. Notice that the  ith  character  of  a  string  occurs  at
       * position i. (Not at position i-1, like in C.) */
    
      for (i = 1;  i <= len;  i = i + 1)
      {
        c = substr(str, i, 1);     /* c is the character at position i */
        if (c < "0" || c > "9")    /* test if c is not numeric */
          return(0);               /* NO!!! */
      }
    
      return(1);    /* A positive return value means that it's numeric */
    }
    
    








    Introduction to the Macro Language              Chapter 12  Page 10


                               ME USERS MANUAL






                               THE INIT() MACRO
    
        When a macro file is loaded into the editor for the first time (by
    the  <LOAD  MACRO>  command  or by the -lmacname option on the command
    line), the editor looks for a macro called init(). If  this  macro  is
    defined  in  the  macro  file, then the editor will execute this macro
    once and only once when the macro file is first loaded.
    
        The kind of things that you might put in the init() macro would be
    key  assignments,  opening  messages,  and  initialization  of  global
    variables.  See  the  assign_key() primitive for information on how to
    make key assignments.









































    Introduction to the Macro Language              Chapter 12  Page 11


                                ME USERS MANUAL






                              THE EDITOR COMMANDS
     
         The  editor  functions  are  available  as a keystroke and/or as a
     function which can be called from a macro program.  In  the  following
     list  of  commands,  the  function name (if there is one) is specified
     first, and the default keystroke (if there is one) is specified  next.
     The keystroke name is enclosed between "<" and ">".
     
         A normal function key is designated as <F1-10>, a shifted function
     key  is  designated at <SH> <F1-10>, a CTRL function key is designated
     as <CTRL> <F1-10>, and an ALT function  key  is  designated  as  <ALT>
     <F1-10>.
     
     
                               NUMERIC ARGUMENTS
     
         Various  commands  can  take  an  optional  numeric argument. This
     number specified the number of  times  to  perform  that  command.  To
     specify  a  numeric  argument,  type the <ESCAPE> key, followed by the
     number, followed directly by the command key. (Do not type a  <RETURN>
     after the last digit of the number!)
     
     
                           CURSOR MOVEMENT COMMANDS
     
     up()                                   <UP ARROW>
     
     This  function  moves  the  cursor  up  one line. If the "GOFREESPACE"
     parameter is zero, and the cursor lands past the end of the new  line,
     then  the  cursor will be moved to just past the last character of the
     line. Up() returns 1 if the move was successful, and 0 if not. 
     
     down()                                 <DOWN ARROW>
     
     This function moves the cursor down one  line.  If  the  "GOFREESPACE"
     parameter  is  zero,  and the cursor is past the end of the line, then
     the cursor will be moved to just past the last character of the  line.
     Down() returns 1 if the move was successful, and 0 if not. 
     
     left()                                 <LEFT ARROW>
     
     This function moves the cursor left one character. If the cursor is at
     the  beginning  of  a line, then the cursor will move to just past the
     last character of the previous line. Left() returns 1  if  successful,
     and 0 if not. 
     







     Macro Functions - Editor Services               Chapter 13  Page 1


                                ME USERS MANUAL






     right()                                <RIGHT ARROW>
     
     This  function moves the cursor right one column. If the "GOFREESPACE"
     parameter is zero, and the cursor is past the end of  the  line,  then
     the  cursor  will  be  moved  to the first character of the next line.
     Right() returns 1 if the move was successful, and 0 if not. 
     
     nextword()                             <CTRL> <RIGHT ARROW>
     
     This  function  moves  the  cursor  to  the  next word in the file. If
     successful, nextword() returns 1, else returns 0.
     
     prevword()                             <CTRL> <LEFT ARROW>
     
     This function moves the cursor to the previous word in  the  file.  If
     successful, prevword() returns 1, else returns 0.
     
     nextpara()                             <CTRL> <PGDN>
     
     This function moves the cursor to the next paragraph in the  file.  If
     successful,  nextpara()  returns  1,  else  returns  0. A paragraph is
     defined as the first line after one or more blank lines. The cursor is
     positioned at the first non-blank character of the new paragraph.
     
     prevpara()                             <CTRL> <PGUP>
     
     This  function moves the cursor to the previous paragraph in the file.
     If successful, prevpara() returns 1, else returns  0.  The  cursor  is
     positioned on the first non-blank character of the new paragraph.
     
     goline(n)                              <ALT> G
       int  n;   # the line number to go to
     
     Goline() allows you to jump to any line in the file. When this command
     is  invoked  from  the  keyboard, you are allowed to enter an absolute
     line number (3, 421), an amount relative to  the  current  line  (-23,
     +4),  or  an amount relative to the last line in the file ($, $-9). If
     you enter the letter 'a' through 'z', then the corresponding  bookmark
     will be jumped to (see bookmark()).
     
     gobof()                                <SH> <PGUP>
     
     This function moves the cursor to the first line of the file.
     
     gobol()                                <HOME>
     







     Macro Functions - Editor Services               Chapter 13  Page 2


                                ME USERS MANUAL






     This function moves the cursor to column 1 on the current line.
     
     goeol()                                <END>
     
     This function moves the cursor to one column beyond the last character
     in the current line.
     
     goeof()                                <SH> <PGDN>
     
     This function moves the cursor to just after the last character of the
     file. 
     
     nextscreen()                           <PGDN>
     
     This  function  scrolls the current window down by the number of lines
     in the window.
     
     prevscreen()                           <PGUP>
     
     This function scrolls the current window up by the number of lines  in
     the window. 
     
     home()                                 <CTRL> <HOME>
     
     This function moves the cursor to the top left corner of  the  current
     window.
     
     bottom()                               <CTRL> <END>
     
     This function moves the cursor to the lower left corner of the current
     window.
     
     
                               DELETION COMMANDS
     
     backspace()                            <BACKSPACE>
     
     This  function deletes the character to the left of the cursor. If the
     cursor is at the beginning of a line, then the current  line  will  be
     joined to the end of the previous line. 
     
     
     delchar()                              <DEL>
     
     This function deletes the character under the cursor. If the cursor is 
     past the last character of the line, then the next line is joined with 
     the current line.
     






     Macro Functions - Editor Services               Chapter 13  Page 3


                                ME USERS MANUAL






     deleol()                               <SH> <NUMERIC 5>
     
     This function deletes all characters from the current cursor  position
     until the end of the current line. 
       
     delline()                              <F1>
     
     This  function deletes the current line. It may be preceeded by a com-
     mand  count.  However,  if  the  editor  sees  that  there  are marked
     lines, then delline() will be performed on the marked lines.
     
     
     delword()                              <SH> <DEL>
     
     This function deletes the next word. If the cursor is in the middle of
     a word, then the whole word is still deleted. 
     
     
                              INSERTION COMMANDS
     
     <INS>
     
     This  keystroke  toggles  the editor between insert mode and overwrite
     mode. When insert mode is enabled, then a character that you type will
     push the remaining characters on the line over  by  one  column.  When
     overwrite  mode  is  on, then the character that you type will replace
     the old character at the cursor position.
     
     On the status line, the mode is indicated by an 'I'  for  insert  mode
     and an 'O' for overwrite mode. Also, the cursor is a full  block  when
     in insert mode, and an underscore when in overwrite mode.
     
     Insert mode is always on when a macro program is being executed.
     
     
     insline()                              <F2>
     
     This function inserts a blank line before the current line.
     
     
                            CUT AND PASTE COMMANDS
     
         The first three commands deal with only the current  line  (unless
     preceeded  by  the  optional numeric argument). However, if the editor
     sees that  there  are  marked  lines,  then  these  commands  will  be
     performed on the marked lines.
     






     Macro Functions - Editor Services               Chapter 13  Page 4


                                ME USERS MANUAL






     cut()                                  <F8>
     
     This functions clears the current pick buffer, then copies the current
     line into it. The current line is then deleted. This function can take
     an optional numeric argument.
     
     cut_append()                           <SH> <F8>
     
     This  function  performs  the same operation as above, except that the
     current pick buffer is NOT cleared first. The  current  line  will  be
     appended onto the end of the pick buffer.
     
     copy()                                 <SH> <F9>
     
     This  function  copies  the current line into the current pick buffer.
     Copy() can take an optional numeric argument. 
     
     paste()                                <F9>
     
     This function inserts the lines contained in the current  pick  buffer
     above the current line. If the inserted lines start at whatever column
     the cursor is currently at.
     This function can take a numeric argument.
     
     
                                BLOCK COMMANDS  
     
     
     mark()                                 <F7>
     
     This function places a mark at the cursor location.  If  this  is  the
     first time the marker was set for this block, nothing happens. If this
     is the second time, the block will be highlighted. 
     
     
     colmark()                              <SH> <F7>
     
     This function places a columnar mark at the cursor location. When this
     mark is set for the second time, then a rectangular region is defined.
     The top left and bottom right corners are defined by the two marks. 
     
     
     markline()                             <ALT> <F7>
     
     This  function  will mark the current line. You can mark any number of
     lines, and the series of lines which are marked  can  be  disjoint  or
     contiguous.  If  the  editor  detects  that lines are marked, then the






     Macro Functions - Editor Services               Chapter 13  Page 5


                                ME USERS MANUAL






     delline(), cut(), cut_append(), copy(), and write_pick() commands work
     on the marked lines instead of the current line.
     
     
     markgroup()                            <ALT> <F8>
     
     This function searches backwards for the last line  that  was  marked,
     and  marks  all lines from the currentline until the last marked line.
     If no marked lines are found, then the current line is marked.
     
     
     clear_mark()                           <CTRL> <F8>
     
     This function clears out any marks, if any exists. This works on  both
     block marks and line marks.
     
     
     set_picknum(n)                         <CTRL> <F7>
       int n;
     
     Changes the current pick buffer to the number  you  choose.  The  pick
     buffers are numbered from 0 to 9, with buffer 0 as the default.
     
     
                         SEARCH & SUBSTITUTE COMMANDS
     
     fsearch(pattern)                       <F5>
       string pattern;
     
     Searches  through  the  buffer  for  the regular expression "pattern".
     The pattern may be any regular expression. If found, then the  current
     line  is set to the line that contains the first match, and the cursor
     is positioned at the match. Search() returns the column number of  the
     match (greater than 0) if it succeeds, and 0 if it doesn't. 
     
     rsearch(pattern)                       <SH> <F5>
       string pattern;
       
     This  function  is  similar to the fsearch() function, except that the
     file is searched backwards starting from the previous line.
     
     fsubst(pattern, subtext, approval)     <F6>
       string pattern, subtext;
       int    approval;
     








     Macro Functions - Editor Services               Chapter 13  Page 6


                                ME USERS MANUAL






     This function  searches  for  the  first  occurence  of  pattern,  and
     substitutes  subtext  in  its  place.  The direction for the search is
     forwards. 'Approval' should be 0 if the substitution should be global,
     or non-zero if you want the user to approve each change.
     Fsubst() returns 1 if successful, and 0 if not.
     
     rsubst(pattern, subtext, approval)     <SH> <F6>
       string pattern, subtext;
       int    approval;
      
     Rsubst() is similar to fsubst(), except the direction for  the  search
     is backwards through the file.
     
     ignore_case(value)                     <ALT> <F5>
       int value;
     
     Allows  you  to  toggle  the  case-ignore  flag.  When  executing this
     function  from  a macro, it will SET the case-ignore flag if the value
     parameter is 1. Otherwise, it will RESET the flag.
     
     
                             INPUT/OUTPUT COMMANDS
     
     readfile(filename)                     <SH> <F10>
       string filename;
     
     This function reads the file "filename" into  the  buffer  BEFORE  the
     current  line. Returns 1 if successful, and 0 if not. The filename may
     be a full path name, including drive designator. 
     
     writefile(filename)                    <F10>
       string filename;
     
     This  function  write  the  current  buffer  out  to  the  file  named
     "filename".  Returns  1 if successful, 0 if not. The filename may be a
     full path name, including drive designator. 
     
     writepick(filename)                    <ALT> W
       string filename;
     
     This  function  write  the  contents of the current pick buffer to the
     named  file.  If there are marked lines, then the marked lines will be
     written to the named file.
     
     








     Macro Functions - Editor Services               Chapter 13  Page 7


                                ME USERS MANUAL






                                WINDOW COMMANDS
     
     The editor allows you to have as many as 6 windows visible on the 
     screen. The screen is split horizontally for each of these windows, 
     with each window being approximately the same size.
     
     Many times, you would like to expand a window to take up the whole 
     screen. There is a function to enlarge a window so that it takes up 
     the whole screen, and to shrink a window back down and make the other 
     windows visible.
     
     You are allowed to transfer text between windows. The 10 pick buffers 
     are common to all windows. Any text put into a pick buffer can be 
     pasted into any window.
     
     
     <SPLIT>                                <ALT> 2
     
     This functions adds another window to the screen. You can have at most six
     windows. Each window is split horizontally, and has approximately the same
     number of lines.
     
     You are prompted for the file name to read into the new window. Type in
     the name, or press <RETURN> to have a copy of the current window inserted
     into the new window.
     
     <CLOSE WINDOW>                         <ALT> 1 or <CTRL> D
     
     This function closes the current window (the window which the cursor is in).
     You are asked if you want to save the contents of the file in that window.
     
     <ENLARGE WINDOW>                       <ALT> +
     
     This function allows you to make the current window occupy the entire screen.
     If there are any other windows, they will remain invisible until the
     <SHRINK WINDOW> command is pressed.
     
     <SHRINK WINDOW>                        <ALT> -
     
     This function makes all windows visible. This is used in conjunction with
     the <ENLARGE WINDOW> command.
     
     <NEXT WINDOW>                          <PRTSC>
     
     This function makes the next window the current window, and moves the
     cursor there.
     
     






     Macro Functions - Editor Services               Chapter 13  Page 8


                                ME USERS MANUAL






                               KEYBOARD MACROS
     
     <CAPTURE>                              <F4>
     
     This   function  starts  the  definition  of  a  keyboard  macro.  All
     keystrokes that are typed are saved in memory, in  addition  to  being
     sent  to  the  editor.  Pressing  the <CAPTURE> key again will end the
     macro definition. See <REPLAY> to  see  how  to  recall  the  keyboard
     macro. 
     
     <REPLAY>                               <F3>
     
     This function replays a keyboard macro that was previously defined by the
     <CAPTURE> function. This command also takes an optional numeric argument,
     so that <ESC> 5 <REPLAY> will replay the keyboard macro five times.
     
     
                                MACRO PROGRAMS
     
         When  typed from the keyboard, <ALT> P will prompt you for a macro
     name. If the macro is not already loaded, then the name  you  type  is
     considered  to be an executable ".exm" file. The editor will load, but
     not execute that macro. On the other hand, if the editor detects  that
     the  macro  is  loaded, then it will execute that macro. In this case,
     <ALT> P may be preceeded by an optional numeric argument.
     
     loadmacro(macrofile)                   <ALT> P
       string macrofile;
     
     This function loads the macro file "macrofile" into the editor. There 
     must be an executable version of  the  macro  called  "macrofile.exm".
     Returns 1 if the loading succeeded, and 0 if not.
     
     domacro(macroname)                     <ALT> P
       string macroname;
     
     This function executes the (previously loaded) macro named "macroname".
     
     
                            MISCELLANEOUS COMMANDS
     
     <QUOTE>                                <ALT> Q
     
     This  allows  you  to  insert a control character into the text at the
     cursor location. A control character is defined as a  character  whose
     ASCII  value  is less than 32 or greater than 126. On the IBM PC, this
     character will usually be represented as a graphic symbol. 
     






     Macro Functions - Editor Services               Chapter 13  Page 9


                                ME USERS MANUAL






     When you press the <QUOTE> key, the prompt on  the  status  line  says
     "QUOTE".  The  character you press next will be inserted at the cursor
     position. You can use the ALT key  in  conjunction  with  the  numeric
     keypad to insert characters above 126. 
     
     <HELP>                                 <ALT> H
     
     This function calls the editor help routine.
     
     <OPTIONS>                              <ALT> O
     
     This  function  brings  up the options menu. The options menu contains
     the names of important editor variables and their values. To change  a
     value,  type  the  two-letter code for the parameter, a space, and the
     value. Typing <CTRL> D or <ESC> will return you to the editor. See the
     section on the editor variables for more information. 
     
     undo()                                 <ALT> U
     
     This function restores the last deleted line or block. Deleted lines and
     blocks are saved in a special system buffer. The undo() function inserts
     this buffer before the current line.
     
     <TEST KEYS>                            <ALT> <F10>
     
     This function prompts you for a keystroke,  and  prints  out  the  key
     value  for  that  keystroke.  The  key  value is the decimal value as-
     sociated with the keystroke. For values less than 127, it's the  ASCII
     code. For values above 127, it's (usually) the scan code plus 128. 
     
     This  can  be used with the assign_key() primitive or the <ASSIGN KEY>
     command to see what value a keystroke is associated with. 
     
     <ASSIGN KEY>                           <ALT> <F4>
     
     This function prompts you for a macro name  (which  has  already  been
     loaded), and asks you what keystroke it should be bound to. To use the
     <ASSIGN  KEY>  function  in  the  macro language, see the assign_key()
     primitive. 
     
     <TAB>                                  <TAB>
     
     This function inserts spaces until a tabstop is reached. The tab  fill
     character  is  initially a space (ASCII 32), but can be changed in the
     options menu. 
     







     Macro Functions - Editor Services               Chapter 13  Page 10


                                ME USERS MANUAL






     os_command(cmd)                        <ALT> X
       string cmd;
     
     This function calls the DOS command interpreter to  perform  one  com-
     mand.  The  string 'cmd' contains the command to execute. 'Cmd' can be
     the string "command" if you want to enter the command interpreter  for
     an  extended  period  of time. To get back to the editor, type the DOS
     command "exit" at the DOS prompt. 
     This function returns the error code sent by the executed command.  An
     error code of 0 usually means successful completion.
     
     refresh()                              <ALT> R
     
     This  function redraws the screen. It's used if the screen happends to
     get messed up by "noise" over transmission lines, or if someone writes
     a message to your tty. 
     
     bookmark(ch)                           <ALT> B
       int ch;
       
     This function sets a "place marker" at the current  line  and  current
     column.  This  marker  is  named with letters 'a' through 'z'. You can
     have as many as 26 different place markers set at one time. 
     





























     Macro Functions - Editor Services               Chapter 13  Page 11


                                ME USERS MANUAL






                         BUFFERS AND THE MACRO LANGUAGE
     
     
         A "buffer" is an area which holds text. Each buffer has a name as-
     sociated with it, which is usually the name of the file where the text
     originated  from.  A buffer may be shown in a window on the screen, or
     may be invisible (ie the editor's "pick  buffers"  are  invisible).  A
     buffer may be shown in one window, or in multiple windows. 
     
        The editor keeps a list of  buffers  which  are  currently  in  ex-
     istence.  This  list can be envisioned as a circular list - the buffer
     that comes after the last buffer  is  the  first  buffer.  The  editor
     operations always deal with the currently active buffer. 
     
         Each buffer contains a unique identifier. The identifier is an in-
     teger  which  starts  at 1. Most of the buffer functions take an iden-
     tifier as an argument. You can always find out  the  identifier  of  a
     buffer by using the find_buffer() function. 
     
        The macro language contains functions which can manipulate buffers.
     These  functions DO NOT have any associated keystrokes - they are only
     available through macros. 
     
     
                                BUFFER FUNCTIONS 
     
     create_buffer(filename)
       string filename; 
     
     DESCRIPTION 
     
         Create_buffer() will create a brand new buffer and  attach  it  to
     the  buffer list. The filename should be the name of the file that the
     buffer is associated with. The editor will search for a file with that
     name, and attempt to read the file into the new buffer. If there is no
     file by that name, then the buffer  will  initially  contain  a  blank
     line. 
     
         It  is  important  to note that the new buffer WILL NOT become the
     current buffer  unless  you  use  the  setcurrbuf()  function  or  the
     show_buffer() function. 
     
     ARGUMENTS 
     
         'Filename' is the name of the file that is associated with the new
     buffer. 
     






     Macro Functions - Buffer Services               Chapter 14  Page 1


                                ME USERS MANUAL






     RETURNS 
     
         If  successful,  the ID of the new buffer will be returned. The ID
     is an integer greater than 0. If not successful, returns 0. 
     
     EXAMPLE 
     
       # The following code tells DOS to do a directory listing and  put
       # the output into a file called "foo". If this was successful, then
       # we will  create  a  new  buffer  and  read  "foo"  into it. If this was
       # successful, we will make the new buffer the current buffer, and
       # show it. 
     
       int id;
       if (os_command("dir > foo") && (id = create_buffer("foo")) > 0)
         show_buffer(id); 
     
     
     currbuf() 
     
     DESCRIPTION 
     
         Currbuf() returns the ID of the current buffer. 
     
     ARGUMENTS 
     
         None. 
     
     RETURNS 
     
         The ID of the current buffer, if one exists. The ID is an  integer
     greater than 0. If no buffer exists, then 0 is returned. 
     
     EXAMPLE 
     
       # See if we already have a buffer associated with the file foo.c. If
       # so, then set the current focus to that buffer. If invisible, the
       # buffer will remain invisible.
     
       int id; 
     
       id = find_buffer("foo.c");
       if (id > 0)
         setcurrbuf(id); 
     
     







     Macro Functions - Buffer Services               Chapter 14  Page 2


                                ME USERS MANUAL






     delete_buffer(id)
       int id; 
     
     DESCRIPTION 
     
         Delete_buffer()  removes  the  buffer  whose identifier is ID. The
     buffer is deleted from the buffer list,  and  any  windows  associated
     with  that  buffer will be deleted. This function does not set the new
     current buffer, nor the new current window.
     
         This function should be used with extreme caution. If  you  delete
     the current buffer, and then try to do editing operations without set-
     ting the new current buffer, chaos may result. 
     
     ARGUMENTS 
     
         The identifier of the buffer to delete. 
     
     RETURNS 
     
         Returns 1 if successful, 0 if not. 
     
     EXAMPLE 
     
       # This code deletes the buffer associated with file "foo.c". 
     
       int currid, id;
     
       currid = currbuf();
       id = find_buffer("foo.c");
       if (id > 0)
         delete_buffer(id);
       if (currid == id)   # watch out!!! We deleted the current buf
         show_buffer(next_buffer(id));   # set the new buffer
     
     
     
     find_buffer(name)
       string name; 
     
     DESCRIPTION 
     
         Find_buffer()  searches for a buffer named "name", and returns the
     identifier associated with that buffer. 
     








     Macro Functions - Buffer Services               Chapter 14  Page 3


                                ME USERS MANUAL






     ARGUMENTS 
     
         The name of the buffer to be located. 
     
     RETURNS 
     
         The ID of the buffer is returned if the buffer was found. If  not,
     0 is returned. 
     
     EXAMPLE 
     
       int id; 
     
       if ((id = find_buffer("foo.c")) > 0) show_buffer(id); 
     
     
     next_buffer(id) 
       int id; 
     
     DESCRIPTION 
     
         Next_buffer()  returns  the  identifier  of the next buffer in the
     buffer list. The buffer list is circular, so the next buffer after the
     last buffer is the first buffer. 
     
     ARGUMENTS 
     
         'Id' is the identifier of the buffer to start at. 
     
     RETURNS 
     
         The identifier of the buffer  AFTER  the  buffer  with  identifier
     'id'. f there are no buffers associated with 'id', returns 0. 
     
     EXAMPLE 
     
       # This searches for the buffer whose identifier is 'id'.
     
       int desired_id;
       int id;
     
       id = currbuf();
       while (id != desired_id)
         id = next_buffer(id);
     
     







     Macro Functions - Buffer Services               Chapter 14  Page 4


                                ME USERS MANUAL






     setcurrbuf(id)
       int id; 
     
     DESCRIPTION 
     
         Setcurrbuf()  makes  the buffer whose identifier is ID the current
     buffer. 
     
     ARGUMENTS 
     
         The identifier of the desired buffer. 
     
     RETURNS 
     
         The ID of the buffer is returned if successful. 0 is  returned  if
     the function failed. 
     
     EXAMPLE 
     
     
     show_buffer(id)
       int id; 
     
     DESCRIPTION 
     
         Show_buffer()  makes  the  buffer with identifier 'id' the current
     buffer. If there is no window  associated  with  the  buffer,  then  a
     window is created.
     
     ARGUMENTS 
     
         The integer identifier of the buffer to be shown.
     
     RETURNS 
     
         The identifier of the buffer if successful, 0 if not.
     
     EXAMPLE 
     
       int id;
     
       if ((id = find_buffer("foo.c")) > 0)
         show_buffer(id);
     









     Macro Functions - Buffer Services               Chapter 14  Page 5


                               ME USERS MANUAL






                             PRIMITIVE FUNCTIONS
    
        The  following  list  of  functions  can  be  used  in  the  macro
    programming  language  of  the editor. For each function, the name and
    optional aruments are given, along with a  brief  description  of  the
    function,  a  description  of  the  arguments and return value, and an
    example.
    
        We realize that you may need to have  a  primitive  which  doesn't
    exist.  If we were to include every primitive which every user wanted,
    then the number of primitives would become unwieldly.  Please  let  us
    know if you think that a certain primitive is absolutely imperative.
    
    
    assign_key(macroname, key)
      string macroname;
      int    key;
    
    DESCRIPTION
    
      Assigns the keystroke specified in "key" to the macro specified
      in "macroname". Whenever that keystroke is pressed, the named
      macro will be executed.
    
    ARGUMENTS
    
      "Macroname" is the name of the macro to be assigned, in quotes.
      "Key" is the value of the key. If you are not sure what the
      value of a key is, use the <TEST KEY> command (ALT F10) in the
      editor.
    
    RETURNS
    
      Returns the second argument if successful, 0 if not.
    
    EXAMPLE
    
      init()
      {
        .....
        assign_key("justify", 10);
        .....
      }
    
      justify()
      {
        .....
      }






    Macro Functions - Primitives                    Chapter 15  Page 1


                               ME USERS MANUAL






      The justify() macro is assigned to CTRL-J key (ASCII value 10).  
    The init() procedure is executed only once,  when the macro  file 
    is  initially loaded into the editor.  From now on,  any time you 
    press the CTRL_J key, the justify() macro will be done.  
    
    
     
     
    atoi(str)
      string str;
    
    DESCRIPTION
    
      Atoi() scans str for an integer and returns the value of the 
    integer. If the first character of the string is not a number (or 
    a valid numerical prefix, like '+' or '-'), then the ASCII value 
    of the first character is returned.
    
    ARGUMENTS
    
      Str is a string which should contain a numerical string 
    starting at the first character.
    
    RETURNS
    
      The integer value extracted from str.
    
    EXAMPLE
    
      string s;
      int    n;
    
      s = "123";
      n = atoi(s);    /* n is 123 */
      s = "ABC";
      n = atoi(s);    /* n is 65, the ASCII value of 'A' */
    
    
    
    
    bell()
    
    DESCRIPTION
    
        Bell()  sounds a tone on the PC. This is useful for alerting users








    Macro Functions - Primitives                    Chapter 15  Page 2


                               ME USERS MANUAL






    to a prompt, error condition, etc.
    
    ARGUMENTS
    
        None.
    
    RETURNS
    
        Nothing
    
    EXAMPLES
    
      if (x < 0)
      {
        bell();
        message("Number must be positive");
      }
    
    
    
    buffer_modified()
    
    DESCRIPTION
    
        Used to tell if the current buffer has been modified since it  was
    used this editing session.
    
    ARGUMENTS
    
        None.
    
    RETURNS
    
        Non-zero if the buffer has been modified, 0 if not.
    
    EXAMPLES
    
      if (buffer_modified())
      {
        bell();
        message("Buffer modified - quit anyway (y/n)");
        if ((c = get_tty_char()) == 'y' || c == 'Y')
          delete_buffer(currbuf());
      }
    
    
    






    Macro Functions - Primitives                    Chapter 15  Page 3


                               ME USERS MANUAL






    
    chr(c)
      int c;
    
    DESCRIPTION
    
        Chr()  takes  the  integer in c and returns a one-character string
    with c as the first character. C should be between  0  and  255.  This
    function  should  be  used  when  you   perform   certain   operations
    between strings, and one of the strings is an integer.
    
    ARGUMENTS
    
        'C' is an integer between 0 and 255.
    
    RETURNS
    
        The one-character string with the ASCII value of 'c' as the  first
    character.
    
    EXAMPLES
    
      int c;
    
      c = 's';
      str = "do";
      str = strcat(str, chr(c));      /* str will be "dos" */
    
      Note  that  if  chr() wasn't used, then str would have been "do115",
    since c is converted to a numeric string. The general rule is that  if
    a  function  expects  a  string  as  an  argument,  and you send it an
    integer, then the integer will be converted to a numeric string.
    
    
    
    
    clear_positions()
    
    DESCRIPTION
    
        Clear_positions() clears the stack of  saved  positions.  See  the
    save_position() and restore_position() functions.
    
    ARGUMENTS
    
        None.
    






    Macro Functions - Primitives                    Chapter 15  Page 4


                               ME USERS MANUAL






    RETURNS
    
        Nothing.
    
    EXAMPLES
    
        See the incremental search macro included with the editor.
    
    
    
    
    command(func)
      int func;
    
    DESCRIPTION
    
        Command()  takes a keystroke whose value is the integer 'func' and
    calls the editor's command  dispatcher  to  execute  the  command.  If
    you  have  a routine which dispatches on user keystrokes, and you need
    to invoke the default processing on the  keys  you  aren't  interested
    in,  this  function  can be used as a default command dispatcher. (See
    example below).
    
    ARGUMENTS
    
        'Func' is the integer keystroke between 0 and 255.
    
    RETURNS
    
        Nothing.
    
    EXAMPLES
    
      if ((c = get_tty_char()) == 145)
         ....
      else if (c == 203)
         ....
      else
        command(c);     /* call the editor to execute the keystroke */
    
    
    
    currchar()
    
    DESCRIPTION
    
      Returns the character under the cursor.






    Macro Functions - Primitives                    Chapter 15  Page 5


                               ME USERS MANUAL






    ARGUMENTS
    
      None.
    
    RETURNS
    
      An integer representing the ASCII value of the character.
    
    EXAMPLE
    
      /* advance cursor forward until a non-blank character is reached */
    
      while (!iseof() && currchar() == ' ')
        right();
    
    
    
    
    currcol()
    
    DESCRIPTION
    
      Returns the value of the column which the cursor is on.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      An integer between 1 and 32767.
    
    EXAMPLE
    
      int col;
    
      col = currcol();
    
    
    
    currline()
    
    DESCRIPTION
    
      Returns the text of the current line (the line where the cursor 
    is).







    Macro Functions - Primitives                    Chapter 15  Page 6


                               ME USERS MANUAL






    
    ARGUMENTS
    
      None.
    
    
    
    
    currlinenum()
    
    DESCRIPTION
    
      Returns the line number of the current line.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      A number between 1 and the last line of the file.
    
    EXAMPLE
    
    /* THIS CODE DELETES ALL LINES FROM THE BEGINNING OF THE FILE  */
    /* UNTIL (BUT NOT INCLUDING) THE CURRENT LINE */
    
    del_from_bof()
    {
      int i, endline;
    
      endline = currlinenum();
      goline(1);
    
      for (i = 1;  i < endline;  i = i + 1)
        delline();      
    }
    
    
    
    
    filename()
    










    Macro Functions - Primitives                    Chapter 15  Page 7


                               ME USERS MANUAL






    DESCRPTION
    
      Returns the filename of the file currently being edited.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      A string result.
    
      
    
    
    get_tty_char()
    
    DESCRIPTION
    
      Waits for the user to press a key, and returns the value of 
    that keystroke.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      The integer value of the keystroke.
    
    EXAMPLE
    
      message("Do you really want to do this?");
      if ((c = get_tty_char()) == 'Y' || c == 'y')
        doit();
    
    
    
    get_tty_str(prompt)
      string prompt;
    
    DESCRIPTION
    
      Displays the prompt on the status line, then waits for the user 
    to enter a string (ended by hitting RETURN). In addition to this
    function being useful for getting information from the user, it is
    also useful for debugging your macros (see below).
    






    Macro Functions - Primitives                    Chapter 15  Page 8


                               ME USERS MANUAL






    ARGUMENTS
    
      The text of the prompt.
    
    RETURNS
    
      The string that the user typed in.
    
    EXAMPLE
    
      int n;
      string foo;
      
      .......
      /* display info, and wait for user to acknowledge  */
      foo = get_tty_str(sprintf("The value of n is %d", n)); 
    
    
    
    
    index(str, pat)
      string str;
      string pat;
    
    DESCRIPTION
    
      Locates the first occurence of the string 'pat' within the string 'str'.
    
    ARGUMENTS
    
      'Str' is the string to search through.
      'Pat' is the string to search for. The length of this string should be
    less than or equal to the length of 'str'.
    
    RETURNS
    
      The position in 'str' where the first occurence of 'pat' is found. This
    position is between 1 and the length of 'str'. If 'pat' is not found, 0 is
    returned.
    
    EXAMPLE
    
      /* The following piece of code changes all occurences of "Mrs." to
         "Miss" on the current line. */
    
      int savecol, i, j;
    






    Macro Functions - Primitives                    Chapter 15  Page 9


                               ME USERS MANUAL






      savecol = currcol();     /* save the current cursor position */
    
      while ((i = index(currline(), "Mrs.")) > 0)
      {
        setcol(i+1);                       /* move to the "r" in "Mrs." */
        insert("iss");                     /* add "iss" to the line */
        for (j = 1;  j <= 3;  j = j + 1)   /* get rid of the "rs." */
          delchar();
      }
    
      setcol(savecol);         /* return to the old cursor position */
    
    
     
    insert(str)
      string str;
    
    DESCRIPTION
    
        Insert()  takes  the  string  'str'  and inserts it at the current
    cursor position. This has the same effect as  if  you  had  typed  the
    characters  in  the string on the keyboard. Characters to the right of
    the inserted string will be pushed over.
    
    ARGUMENTS
    
        Str  is  the string which will be inserted. If you have an integer
    variable between 0 and 255, and you would like to insert it, then  you
    must use the chr() function.
    
    RETURNS
    
        Nothing.
    
    
    
    
    is_bof()
    
    DESCRIPTION
    
      Returns 1 if the cursor is at the first character of the file, 0 if
    not.
    
    ARGUMENTS
    
      None.






    Macro Functions - Primitives                    Chapter 15  Page 10


                               ME USERS MANUAL






    
    RETURNS
    
      See above.
    
    
    
    
    is_bol()
    
    DESCRIPTION
    
      Returns 1 if the cursor is at the beginning of the current line, 0 if not.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      See above.
    
    
    
    
    is_eof()
    
    DESCRIPTION
    
      Returns 1 if the cursor is just past the last character of the file, 0 if 
    not.
    
    ARGUMENTS
    
      None.
    
    RETURNS
      See above.
    
    
    
    
    is_eol()
    
    DESCRIPTION
    
      Returns 1 if the cursor is past the last character of the current line, 0 if 






    Macro Functions - Primitives                    Chapter 15  Page 11


                               ME USERS MANUAL






    not.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    
      See above.
    
    
    
     
    is_linemarked()
    
    DESCRIPTION
    
        Is_linemarked()  is  used to tell if the current line is marked. A
    line can be marked with the <MARK LINE> command (ALT F7), or the <MARK
    GROUP> command (ALT F8).
    
    ARGUMENTS
    
        None.
    
    RETURNS
    
        Returns 1 if the current line is marked, 0 if not.
    
    EXAMPLE
    
      /* This loop changes all marked lines to uppercase characters. Assume
         that the user wrote a routine called uppercase() which changes the
         current line to all uppercase. */
    
      gobof();              /* move to the first line */
      while (currlinenum() <= lastlinenum())
      {
        if (is_linemarked())
          uppercase();      /*  assume this is a user written routine */
        down();
      }
    
    
        As an aside, the above loop would run faster if we kept a variable
    as the line counter, like :
    






    Macro Functions - Primitives                    Chapter 15  Page 12


                               ME USERS MANUAL






      i = 1;
      last = lastlinenum();
      while (i <= last)
        .....
        i = i + 1;
    
    
    
    itoa(n)
      int n;
    
    DESCRIPTION
    
      Converts the integer 'n' to a string.
    
    ARGUMENTS
    
      'N' is the number to convert. The value of 'n' is not changed.
    
    RETURNS
    
      The string which represents the number. This string is dynamically 
    allocated.
    
    EXAMPLE
    
      string linenum;
    
      linenum = itoa(currlinenum());
      message(strcat("We are on line ", linenum));
      
    
    
    
    
    lastlinenum()
    
    DESCRIPTION
    
      Returns the line number of the last line in the current buffer.
    
    ARGUMENTS
    
      None.
    
    RETURNS
    






    Macro Functions - Primitives                    Chapter 15  Page 13


                               ME USERS MANUAL






      An integer.
    
    EXAMPLE
    
      /* The following statement moves the currentline to  the  last  line
      */
    
      goline(lastlinenum());
    
    
    
    
    ltrim(str)
      string str;
    
    DESCRIPTION
    
      Ltrim() trims all leading blanks from the string 'str'.
    
    ARGUMENTS
    
      'Str' is the string to trim.
    
    RETURNS
    
      Nothing.
    
    
    
    
    
    marked_col()
    
    DESCRIPTION
    
      If the mark is set, returns the column which the marker is on. Otherwise,
      returns 0.
      
    ARGUMENTS
    
      None.
      
    RETURNS
     
      See above.
    
    






    Macro Functions - Primitives                    Chapter 15  Page 14


                               ME USERS MANUAL






    
    
    marked_line()
    
    DESCRIPTION
    
      If the mark is set, returns the line number of the line which the marker
      is on. Otherwise, returns 0.
      
    ARGUMENTS
    
      None.
      
    RETURNS
     
      See above.
    
    
    
    
    message(str)
      string str;
      
    DESCRIPTION
    
      Displays the string 'str' on the status line. 
      
    ARGUMENTS
    
      The message to print.
      
    RETURNS
     
      Nothing.
    
    
    
    
    repstr(str, n)
      string str;
      int    n;
      
    DESCRIPTION
    
      Replicates string 'str' 'n' times. String 'str' is NOT altered.
    
    ARGUMENTS






    Macro Functions - Primitives                    Chapter 15  Page 15


                               ME USERS MANUAL






    
      String 'str' contains the string to replicate. 'N' is an integer which is
      the number of times to replicate the string.
    
    RETURNS
    
      Returns the new string.
    
    EXAMPLE
    
      /* This statement inserts a slash, followed by 30 asterisks, */
      /* followed by a slash, into the file. */
      insert(strcat( "/", strcat(repstr("*", 30), "/") ));
    
    
    
    
    restore_position()
    
    DESCRIPTION
    
        Restore_position()  sets  the cursor to the last position that was
    saved on the position stack. This position will be  removed  from  the
    stack. See the save_position() function for more information.
    
    ARGUMENTS
    
        None.
    
    RETURNS
    
        Nothing.
    
    EXAMPLES
    
      save_position();
    
      goline(200);
      insert("foo");
    
      restore_position();
    
        See also the incremental search macro included with the editor.
    
    
    







    Macro Functions - Primitives                    Chapter 15  Page 16


                               ME USERS MANUAL






    rtrim(str)
      string str;
    
    DESCRIPTION
    
      Rtrim() trims all trailing blanks from the string 'str'.
    
    ARGUMENTS
    
      'Str' is the string to trim.
    
    RETURNS
    
      Nothing.
    
    
    
    
    save_position()
    
    DESCRIPTION
    
        Save_position() places the current cursor position on the position
    stack.  The  position  stack  records the current line and the current
    column where the cursor is. To return to a previous position, use  the
    restore_position function.
    
    ARGUMENTS
    
        None.
    
    RETURNS
    
        Nothing.
    
    EXAMPLES
    
      save_position();
    
      goline(200);
      insert("foo");
    
      restore_position();
    
        See also the incremental search macro included with the editor.
    
    
    






    Macro Functions - Primitives                    Chapter 15  Page 17


                               ME USERS MANUAL






    
    setbufnum(n)
      int n;
      
    DESCRIPTION
    
      Changes the current pick buffer number to number 'n'.
    
    ARGUMENTS
    
      The integer 'n' must be between 0 and 9. 0 is the default buffer that
      the editor initially uses for all cut and paste operations.
    
    RETURNS
    
      1 if successful, 0 if not.
    
    
    
    
    setcol(col)
      int col;
      
    DESCRIPTION
    
      Move the cursor to column 'col' on the current line.
    
    ARGUMENTS
    
      'Col' is the integer column to move to.
    
    RETURNS
    
      The column number if successful, 0 if not.
    
    EXAMPLE
    
    /* This function simulates the <GOTO END OF LINE> key. */
    
    go_eol()
    {
      setcol( strlen(currline()) + 1 );
    }
    
    
     
     






    Macro Functions - Primitives                    Chapter 15  Page 18


                               ME USERS MANUAL






    setprompt(n)
      int n;
      
    DESCRIPTION
    
      Enables or disables the prompting that the editor uses for certain commands.
    
    ARGUMENTS
    
      0 if prompts should be turned off, a non-zero if they should be turned on.
    
    RETURNS
    
      Nothing.
    
    EXAMPLE
    
      setprompt(0);
    
    
    
    
    sprintf(format[, args])
      string format;
    
    DESCRIPTION
    
      Formats  a string according to the format string parameter. The for-
    mat string 'format' consists of a combination of characters  to  print
    and  format specifiers. Each format specifier describes a way to print
    out a certain argument. 
    
        The format specifiers currently accepted are
    
      %d  decimal integer
      %s  string
    
    ARGUMENTS
      
      'Format' is the format string. The format string consists of a combination
    of literal characters and format specifiers.
      'Args' is a list of 0 or more arguments. Argument i corresponds to format 
    specifier i in the format string.
    
    RETURNS
    
      The formatted string.






    Macro Functions - Primitives                    Chapter 15  Page 19


                               ME USERS MANUAL






    
    EXAMPLE
    
      string foo;
    
      foo = get_tty_str(sprintf("Col %d  Line %d of %d",
                                           currcol(), currline(), lastline()));
    
    
    
    
    strcat(s1, s2)
      string s1, s2;
      
    DESCRIPTION
    
      Appends string 's2' to the end of string 's1'.
      
    ARGUMENTS
    
      'S1' and 's2' must both be strings. If either are integers, then they
    are converted to strings before the append takes place.
    
    RETURNS
    
      Returns 's1', which contains the appended result.
      
    EXAMPLE
    
      insert(strcat("The current buffer name is ", filename()));
    
    
    
    
    strlen(str)
      string str;
    
    DESCRIPTION
    
      Returns the length of the string in 'str'.
    
    ARGUMENTS
    
      'Str' is the string to examine.
    
    RETURNS
    






    Macro Functions - Primitives                    Chapter 15  Page 20


                               ME USERS MANUAL






      An integer length >= 0.
    
    
    
    
    substr(str, pos, len)
      string str;
      int    pos;
      int    len;
    
    DESCRIPTION
    
      Extracts 'len' characters from the string in 'str' starting at position
    'pos'.
    
    ARGUMENTS
    
      'Str' is the string to examine.
      'Pos' is the position in 'str' to start at. Pos should be a number between 1 
      and the length of the string.
      'Len' is the number of characters to extract.
    
    RETURNS
    
      The string extracted.
     
    EXAMPLE
    
      dotpos = index(filename(), ".");
      if (dotpos > 0)
        root = substr(filename(), 1, dotpos - 1);
      else
        root = filename();
    
    
    
    tabs(str)
      string str;
    
    DESCRIPTION
    
        Tabs() is used to set the tab stops.
    
    ARGUMENTS
    
        Str  is  a  string  which contains a list of tab stops. The string
    consists a numbers separated by one  or  more  blanks.






    Macro Functions - Primitives                    Chapter 15  Page 21


                               ME USERS MANUAL






    
    RETURNS
    
        Nothing.
    
    EXAMPLE
    
      tabs("10 16 25 36");
    
    
    
    ungetc(c)
      int c;
    
    DESCRIPTION
    
        Ungetc()  pushes the character 'c' back onto the input stream. The
    next time that the editor goes to read a character, 'c' will be  read.
    There is no limit as to the number of characters you can push back.
    
    ARGUMENTS
    
        'C'  is the character to push back. It can be the values 0 through
    255.
    
    RETURNS
    
        Nothing.
    
























    Macro Functions - Primitives                    Chapter 15  Page 22


                                ME USERS MANUAL






                             REMAPPING THE KEYBOARD
     
         A  character  that  you  type at the keyboard can take on 256 dif-
     ferent values, from 0 to 255. On the IBM PC, the ASCII characters  are
     numbered  from  0 to 127, and the IBM extended characters are numbered
     from 128 to 255. All of the  function  key  combinations  and  numeric
     keypad combinations fall into the extended character set. 
     
         The  editor  has  an internal table which is used to translate one
     value into another. This internal table is 256 bytes long, with byte 0
     holding the translation value for keystroke value 0,  byte  1  holding
     the  value for keystroke 1, etc. The default values for this table in-
     dicate no translations (ie keystroke number n is translated into value
     n.) 
     
     
                            AN EXAMPLE OF REMAPPING
     
         As an example where translation may be desirable, let's consider a
     very simple remapping of the keyboard. The command that is  associated
     with  the  F1  function key is <DELETE LINE>. Let's say that you would
     like the <HELP> function to be assigned to the F1 key, and the <DELETE
     LINE> function assigned to the <ALT>  D  key.  Currently,  the  <HELP>
     function is assigned to the <ALT> H key. 
     
         To  find  out  what  keystroke  values the F1, <ALT> D and <ALT> H
     keys   produce,   use   the  <TEST  KEYS>  command  from  the  editor.
     This command is done by pressing the ALT F10 key. The <TEST KEYS> com-
     mand prompts you for a keystroke, and then prints the value  that  the
     keystroke produced. 
     
         After invoking the <TEST KEYS> command, we find that the following
     values are produced :
     
       F1     187
       ALT D   60
       ALT H  163
     
         What we would like to do is have the F1 key "generate" the <ALT> H
     keystroke,  and have the <ALT> D key "generate" the F1 value. In other
     words, we would like to fool the editor into thinking that when the F1
     key is pressed, the <ALT> H key was really pressed.
     
         To effect these changes, we would like to put the value  163  into
     byte  187  of the table, and put value 187 into byte 160 of the table.
     How can we do this without  going  altering  the  editor's  executable
     file?






     Remapping the Keyboard                          Appendix A  Page 1


                                ME USERS MANUAL






     
     
                               THE KEYTABLE FILE
     
         The file which holds the keystroke translation  values  is  called
     "KEYTABLE.ME".  When  the editor starts up, it will first look in your
     current subdirectory for the KEYTABLE.ME file. If the  editor  doesn't
     find  it  there, then the editor will search the directories listed in
     your DOS search path. If this file still isn't  found,  then  the  in-
     ternal  table  is  filled  sequentially with the values 0 through 255.
     This means that no remapping will be performed. 
     
         The KEYTABLE.ME file contains one or more  tables  which  are  256
     bytes long, with byte i corresponding to keystroke i. The editor comes
     with  a default KEYTABLE.ME file. It also comes with several utilities
     to create and alter the KEYTABLE.ME file. 
     
         The  first  utility we will talk about is called KEYCOMP.EXE. This
     program  reads  a  keystroke  configuration  file  and   generates   a
     KEYTABLE.ME  file  from  it. A keystroke configuration file contains a
     list of keystrokes and their corresponding values. 
     
         Each line of the keystroke configuration file has the form :
     
       key=func
     
         The  "key"  can  be  a  decimal number, a single character between
     single quotes, ^char (a control character between 0 and 31), F#  where
     '#'  is a number between 1 and 10 (this is a normal function key), AF#
     (ALT function key), SF# (SHIFT function key), CF# (CTRL function key),
     or @char (ALT character key).
     
         "Func" is a number representing the value that the key produces.
     
         Here are some examples :
     
       120=122   (the key with the value 120 produces 122)
       '#'=289   (a pound sign produces 289)
       ^C=14     (CTRL C produces 14)
       F1=160    (F1 produces 160)
       @A=198    (ALT A produces 198)
       SF9=130   (SHIFT f9 produces 130)
     
         Any keystrokes which aren't mentioned in  the  configuration  file
     will just be translated into themselves.
     
         To run the keystroke compiler, type the command






     Remapping the Keyboard                          Appendix A  Page 2


                                ME USERS MANUAL






     
         KEYCOMP filename
     
     where  filename  is  the  name of the keystroke configuration file. If
     everything goes well, the KEYTABLE.ME file will be  created.  You  can
     not  TYPE  out  the  KEYTABLE.ME  file  since it contains binary data.
     However, you can examine it with various disk utilities (such  as  the
     NORTON Utilities). 
     
         The second utility is called KEYCONF.EXE. This program generates a
     default keystroke configuration file.  There  are  256  lines  in  the
     generated file. The file looks like this : 
     
     0=0
     1=1
     255=255
     
         The  output  from  this  program is written to the screen. You can
     redirect the output to a file be giving the command :
         
         KEYCONF > keyfile (or any other name)
     
         Once  this  sample  keystroke configuration file is generated, you
     can alter  it  with  any  text  editor,  and  then  compile  it  using
     KEYCOMP.EXE. 
     
         The third utility is called KEYTEST.EXE. This  program  waits  for
     you  to  type  a  keystroke,  and  then  prints  out the value of that
     keystroke. Hitting the <ESC> key will stop the program.  This  program
     is also simulated by the <TEST KEYS> command of the editor. 
     
     
                                    PREFIXES
     
         Some  people  would like to have the editor emulate their favorite
     word processor, and hence, will make key maps which map  the  function
     keys  of  the  editor  into  the  keystrokes that their word processor
     requires.  Some  word  processors  use  a  two-keystroke  sequence  to
     generate  a  command.  One  of the most well-known examples of this is
     WordStar (WordStar is a trademark of MicroPro Inc.). For instance, the
     keystroke sequence CTRL K D is used to exit WordStar.
     
         You can specify prefixes in the keystroke redefinition file  which
     is compiled by the KEYCOMP.EXE program. A prefix line is of the form :
     
       PREFIX <keystroke>
     






     Remapping the Keyboard                          Appendix A  Page 3


                                ME USERS MANUAL






         The  PREFIX  statement creates a 256 byte table which contains the
     commands generated by the second key of the sequence. As  an  example,
     you  press  CTRL  D  right  now to exit the editor. CTRL D generates a
     keystroke value of 4. If you would like to use the CTRL K D  keystroke
     combination  to  exit  the  editor  instead,  then your keystroke file
     should contain a line like this :
     
       PREFIX ^K
       .....        list of CTRL K commands
       D=4
       ......
     
     
         A prefix command table ends when the compiler  encounters  another
     PREFIX  statement,  or  when  the  compiler  reaches  the  end  of the
     redefinition file. 
     
         All of the prefix definitions should come  after  the  definitions
     for  the main table. For a good example, examine the WSKEYS file which
     comes with the keyboard remapping facility.  This  file  contains  the
     keystroke definitions to configure the keyboard like WordStar.
     
     
                                  SOURCE FILES
     
         Included  in  the editor package are the source files to the above
     mentioned utilities. We request that if you improve  these  utilities,
     that  you  send the source back to us so that we can incorporate it in
     future releases. In exchange, you will receive a free copy of the next
     release of the editor.























     Remapping the Keyboard                          Appendix A  Page 4


                                ME USERS MANUAL






                               THE CTAGS UTILITY
     
         If  you  are  working  on  a  large project, your source code most
     likely  resides  in  several  different  files.  The  CTAGS   utility,
     originated  in  Berkeley UNIX (UNIX is a trademark of AT&T), helps you
     create a little order out of your C files. The CTAGS utility  keeps  a
     record  of  the  name  of each function declared in your source files,
     and which file the function occurs in. By using the CTAGS  utility  in
     conjunction with the <GOTO FUNCTION> command (the CTRL T key), you can
     specify  the  name  of  a function and have the editor move you to the
     point of the function definition. 
     
         As mentioned above, the CTAGS utility creates a file called "TAGS"
     which  resides  in your current directory. The TAGS file has a list of
     all of the functions that you declared in specific source code  files,
     the  full  name of the file in which each function was declared, and a
     pattern to be used by the the editor's <SEARCH> command.
     
         To invoke the CTAGS utility, use this command from the DOS prompt:
     
             CTAGS filename1 [filename2...]
     
         The file name can have wild-card characters in  it.  To  create  a
     TAGS  file  for all of the source files in your current directory, use
     the command
     
             CTAGS *.c
      
         When you use the <GOTO FUNCTION> command (the CTRL T key), you are
     asked  for  the name of the function that you would like to go to. The
     <GOTO FUNCTION> command then reads the TAGS file, and attempts to find
     a line in the TAGS file which contains the name of  the  function  you
     want  to visit. If it's successful, another window will open up on the
     screen, and the cursor will be positioned on that function definition.
     
         In order to keep the TAGS file up-to-date, you may want to  invoke
     the  CTAGS  utility at periodic intervals. If you delete a function or
     move a function from one file to another without  updating  the  CTAGS
     file,  then  the  <GOTO  FUNCTION> command won't be able to locate the
     function.
     












     The CTAGS Utility                               Appendix B  Page 1

