CP/M/CPM_CDROM.iso/lambda/soundpot/p/preprss.lbr/BMLP.DZC/BMLP.DOC

Text File | 1993-10-25 | 12.4 KB | 320 lines

BMLP.DOC

       Function

         BMLP  expands macro expressions using program resident and/or
         library file macro definitions.  BMLP  is  written  in  'SSS'
         language and should be a useful learning tool.


       Invocation

         Entering 'BMLP' at the DOS prompt will  envoke  the  compiled
         version  (.EXE)  of BMLP.  The (.BAS) version will have to be
         run using the interpreter by entering 'BASICA  BMLP'  at  the
         DOS  prompt.  BMLP  will  then prompt for the input file name
         and the output file name.  The default  for  the  input  file
         extension  is '.M',  and the default for the output file name
         is the input file name with the extension of '.P'.


       Formats

            Macro expression format:

                 $macro-name param1,param2,param3

         A leading dollar sign ($) is used to identify  a  macro  name
         and,  except for spaces and tabs, must be the first character
         on  the  line.   When  parameters  are  used,  they  must  be
         separated by a comma, tab, or space;  when there are too many
         to put on one line,  a double backslash (\\) may be  used  to
         continue on the next line.


            Macro coding format:

                 MACRO <macro-name>
                 ENDM

         Macros  are  written and maintained with a text editor in one
         or more library  text  files  and/or  program  source  files.
         Macro  names may contain any combination of characters except
         commas,   tabs,   and  spaces,   and   there   is   no   case
         discrimination.  The  keyword  'MACRO'  is used to identify a
         macro name and the beginning of code  for  that  macro  name.
         The  keyword  'ENDM'  identifies  the end of code for a macro
         name.  Within the macro code a number enclosed with  brackets
         ([])  identifies  a  parameter request.  A leading semi-colon
         (;) may be used as a comment character.  Macros may use other
         macros as  well  as  supporting  subroutines  (more  on  this
         later).



       Design


         Writing macros is easy, fun and can be habit forming once you
         get  the  hang  of  it.  To demonstrate let's take the simple
         task of displaying text on the video monitor.  The  following
         list of operations describes this task in detail:


            1. Save the current cursor location.
            2. Turn off and re-position the cursor.
            3. Clear a space the size of the text.
            4. Re-position the cursor.
            5. Display the text.
            6. Restore cursor location and turn it on.


         BASIC code for this example might be:

            100 XR%=CSRLIN:XC%=POS(0)
                :LOCATE,,0:LOCATE ROW,COL
                :PRINT SPACE$(LEN(TEXT$));
                :LOCATE ROW,COL
                :PRINT TEXT$;
                :LOCATE XR%,XC%,1

         A macro expression for the above example:

            $CRT ROW,COL,TEXT$
            /--- -------------\
            Macro Name         Parameter List

         Code for the 'CRT' macro could be written like this:

            MACRO CRT
               XR%=CSRLIN:XC%=POS(0)
               LOCATE,,0:LOCATE [1],[2],0:PRINT SPACE$(LEN([3]));
               LOCATE [1],[2],0:PRINT [3];:LOCATE XR%,XC%,1
            ENDM



         The  parameters  are  numbered in left to right order as they
         appear in the list following the 'CRT' macro, e.g.;


            [1] = ROW     <parameter one>
            [2] = COL     <parameter two>
            [3] = TEXT$   <parameter three>

         Parameters  can  be  passed  using   variables   or   literal
         expressions:

            $CRT 12,10,"Hello World!"



       Nesting Macros

         Because  a  macro  can use other macros (nesting),  the 'CRT'
         macro can also be written using macros for the  required  six
         functions.


            1. Save the current cursor location. ------+
            |  MACRO SVC                               |
            |      [1]=CSRLIN:[2]=POS(0)               |
            |  ENDM                                    |
            +------------------------------------------+

            2. Position the cursor and switch on/off. -+
            |  MACRO XY                                |
            |      LOCATE [1],[2],[3]                  |
            |  ENDM                                    |
            +------------------------------------------+

            3. Clear a space the size of the text. ----+
            |  MACRO CLR                               |
            |      PRINT SPACE$([1]);                  |
            |  ENDM                                    |
            +------------------------------------------+

            4. Re-position the cursor. ----------------+
            |  (Use the XY macro, (2))                 |
            +------------------------------------------+

            5. Display the text. ----------------------+
            |  MACRO SHO                               |
            |      PRINT [1];                          |
            |  ENDM                                    |
            +------------------------------------------+

            6. Restore cursor location, turn it on. ---+
            |  (Again use the XY macro, (2))           |
            +------------------------------------------+


         Now the 'CRT' macro can be written using the four new macros:

            MACRO CRT
                $SVC XR%,XC%
                $XY ,,0
                $XY [1],[2],0
                $CLR LEN([3])
                $XY [1],[2],0
                $SHO [3]
                $XY XR%,XC%,1
            ENDM

         Writing  macros  for  the  lower level functions of the 'CRT'
         macro provides  several  benefits,  one  of  them  being  the
         availability  of  lower  level  macros  to be used in writing
         other higher level macros.


       Conditional Logic

            $IF / $ELSE / $END

         '$IF-$ELSE-$END' are reserved macro keywords that provide the
         ability to control the inclusion or expansion of segments  of
         code  within  a  macro.  The 'CRT' macro can be enhanced with
         added ability to display the text in reverse video.  This  is
         easily  implemented  using a fourth parameter and conditional
         logic to control the inclusion of the "COLOR" statement.


            MACRO CRT
                $SVC XR%,XC%
                $XY ,,0
                $XY [1],[2],0
                $CLR LEN([3])
                $XY [1],[2],0
                $IF [4]     <--+  If fourth parameter ([4]) is provided
                COLOR 0,7      |  then the statement 'COLOR 0,7' will
                $END        <--+  be included. (Reverse)
                $SHO [3]
                $IF [4]     <--+  If fourth parameter ([4]) is provided
                COLOR 7,0      |  then the statement 'COLOR 7,0' will
                $END        <--+  be included. (Reset to Normal)
                $XY XR%,XC%,1
            ENDM


         Example:

            $CRT 12,10,"Hello World!",REV
                                        \..(fourth parameter)
            (Display "Hello World!" at row 12, column 10, in reverse video.)

            $CRT 12,10,"Hello World!"
                                        \..(missing fourth parameter)
            (Display "Hello World!" at row 12, column 10, in normal video.)



       Logical Operators

         The 'equal-to (=)' and the 'not-equal (#)  or  (<>)'  logical
         operators  can  be  used  to  test  literal  parameters for a
         specific value, e.g.;


            $IF [1] = 1
            $IF [6] # NOERROR
            $IF [4] = REV
                    \
                    (Operators must to be separated by spaces or tabs.)

         'CRT' macro with logical operators:

            MACRO CRT
                $SVC XR%,XC%
                $XY ,,0
                $XY [1],[2],0
                $CLR LEN([3])
                $XY [1],[2],0
                $IF [4] = REV  <--+  If fourth parameter ([4]) EQUALS "REV"
                COLOR 0,7         |  then the statement 'COLOR 0,7' will
                $END           <--+  be included. (Reverse)
                $SHO [3]
                $IF [4] # NORM <--+  If fourth parameter ([4]) NOT EQUAL "NORM"
                COLOR 7,0         |  then the statement 'COLOR 7,0' will
                $END           <--+  be included. (Reset to Normal)
                $XY XR%,XC%,1
            ENDM

         Example:

            $CRT 12,10,"Hello World!",REV
                                        \..(fourth parameter)
            (Display "Hello World!" at row 12, column 10, in reverse video.)

            $CRT 12,10,"Hello World!",NORM
                                        \..(fourth parameter)
            (Display "Hello World!" at row 12, column 10, in normal video.)


       Macros and Subroutines

         One of the more powerful features of macro programming is the
         ability to write macros that require supporting  subroutines.
         This  ability  allows  the use of a macro any number of times
         within a program,  with only one inclusion of its  supporting
         subroutine.  Thus, blocks of duplicated code are eliminated.


         An example is the operation of stripping leading and trailing
         space and tab characters from a string of text:


         $STRIP TEXT$

         The code for 'STRIP' macro:------+
         MACRO STRIP                      |
             X$=[1]:Gosub _Stripit:[1]=X$ |
             $$_STRIP                     |
         ENDM                             |
         ---------------------------------+

         The code for '_STRIP' supporting subroutine:----------------+
         MACRO _STRIP                                                |
         proc _Stripit                                               |
             unless LEN(X$)<3                                        |
                 X%=LEN(X$)+1                                        |
                 WHILE(X%>LEN(X$) AND LEN(X$)>2)                     |
                     X%=LEN(X$)                                      |
                     X$=LEFT$(X$,LEN(X$)+(RIGHT$(X$,1)=" "))         |
                     X$=LEFT$(X$,LEN(X$)+(ASC(RIGHT$(X$,1))=9))      |
                     X$=RIGHT$(X$,LEN(X$)+(ASC(X$)=32 OR ASC(X$)=9)) |
                 WEND                                                |
             endu                                                    |
         endp                                                        |
         ENDM                                                        |
         ------------------------------------------------------------+

         The  leading  double  dollar sign ($$) identify '_STRIP' as a
         subroutine which is defined as a procedure (_Stripit) and  it
         will be included into a program source file only one time.  A
         subroutine may include and use other subroutines and macros.



       Developing Libraries

         Macros can be written within a  program  source  file,  where
         they can be easily tested and debugged before being committed
         to  a  library  file.   Library  documentation  is  extremely
         important.  After  writing  a  couple  of  dozen  macros,  it
         becomes  a  little  more  difficult  to remember function and
         parameter requirements for each macro.  The ability to  share
         libraries  among  several  programmers  working  on  the same
         project makes the library documentation essential.


       Using Libraries

            LIBRARY <file-name.ext>

         The keyword 'LIBRARY' is used at the top of a program  source
         file to identify each macro library to use in processing that
         source  file.  Libraries can be nested by specifing libraries
         within libraries.