home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / simtel / sigm / vols000 / vol029 / catalog.051 < prev    next >
Text File  |  1984-04-29  |  14KB  |  453 lines
  1. VOLUME 50    National CP/M Users Group
  2.  
  3. DESCRIPTION: STAGE2 MACRO PROCESSOR
  4.  
  5. By:    Dick Curtiss            
  6.     843 NW 54th
  7.     Seattle, WA 98107
  8.  
  9. <<Congratulations to Dick for a superb User's group contribution: A major
  10.   work, well documented, good examples, a good reference book, etc.>>
  11.  
  12. STAGE2 is a macro programming language, documented
  13. sufficiently on this disk to effectively use it.  Examples
  14. given include a library of extensions for assembler
  15. programming, (ALX) including WHILE, REPEAT, IF, BRANCH (a CASE
  16. statement), etc.  STAGE2 is a general-purpose text-replacement
  17. processor, not limited to programming language applications.
  18. Those interested in transporting it to other machines, or in
  19. studying its background and implementation will want to
  20. purchase:
  21.  
  22.     "Software Tools for Non-Numeric Applications"
  23.  
  24.     by: Wm. M. Waite
  25.  
  26.   from: Prentice Hall, Inc.
  27.     Rt. 59 at Brook Hill Dr.
  28.     P.O. Box 505
  29.     West Nyack, NY 10994
  30.  
  31.    for: $24.95 + 1.00 tax + 1.85 Postage/handling
  32.  
  33. NUMBER    SIZE    NAME        COMMENTS
  34.  
  35.         CATALOG.051    CONTENTS OF CP/M VOL. 51
  36. 51.1    2K    ABSTRACT.051    Overview of volume
  37. 51.2    16K    ALX.S2M        Assembly Language Extension macros
  38. 51.3    3K    ALX-.DOC    Doc on above
  39. 51.4    3K    ALXTEST.ALX    Sample macros to test above, including
  40.         ALXTEST.ALX        errors to be detected.
  41. 51.5    4K    CIO.ALX        Console I/O routines in ALX
  42. 51.6    2K    CRCK.COM    Keith Petersen's program to CRC check files
  43. 51.7    1K    CRCKLIST.CRC    Contains the CRCs for all files on this
  44.                     disk. (except itself)
  45. 51.8    2K    DEMO.S2M    Interactive STAGE2 demo macros.
  46. 51.9    17K    DISKIO2.SRC    (*) disk I/O for STAGE2 processor
  47. 51.10    6K    DISKIO2-.DOC    (*) DOC on above
  48. 51.11    5K    FLD1.DAT    (*) Sample data for FLUB test
  49. 51.12    4K    FLD2.DAT    (*)         "
  50. 51.13    13K    FLT1.FLB    (*) Sample program for FLUB test
  51. 51.14    11K    FLT2.FLB    (*)        "
  52. 51.15    1K    FLUB$.SUB    (*) Submit file for FLT1, FLT2, STG2.
  53. 51.16    4K    FLUB8080.S2M    (*) Macros to turn FLUB into 8080 asm
  54. 51.17    3K    HELP.DOC    First-timer's "to do" list.
  55. 51.18    2K    IMPL.DOC    (*) Notes on implementing STAGE2
  56. 51.19    2K    INTERACT.S2M    Another macro demo.
  57. 51.20    22K    INTRO.DOC    Sufficient info to "read" STAGE2 macros,
  58.                     and with diligence, write them.
  59. 51.22    1K    IOOP$.SUB    (*) submit file for macro pass + asm of above
  60. 51.21    16K    IOOP.SRC    (*) I/O processor 8080 source
  61. 51.23    1K    MEMORY.INP    Another macro demo.
  62. 51.24    2K    ST2T.DAT    (*)
  63. 51.25    12K    STAGE2.COM    The executable macro processor itself.
  64. 51.26    48K    STG2.FLB    (*) Source for STAGE2 in FLUB code
  65. 51.27    5K    STG2MATH.ASM    (*) STAGE2 support routines
  66. 51.28    5K    STG2SUP.ASM    (*)        "
  67. 51.29    8K    TERM.ALX    Sample 8080 terminal program w/ALX macros.
  68. 51.30    3K    TERMSUP.ASM    Subroutines for TERM.ALX
  69. 51.31    2K    USE.DOC        How to execute STAGE2.
  70. 51.32    6K    VDB.ALX        TDL video driver in ALX, a "state machine".
  71. 51.33    5K    VOLUME51.DOC    Dick Curtiss' own excellent documentation.
  72.  
  73. (*)    Files are necessary only to change STAGE2.
  74.  
  75. NOTE:    Included on this volume for the first time, is a file
  76.     of CRC's for each file.  Thus people concerned that a
  77.     copy when wrong somewhere, can check the CRC of the
  78.     file, and compare it to the one stored in CRCKLIST.CRC.
  79.  
  80.     Thanks to Keith Petersen for this excellent program.
  81.  
  82. Abstract for National CP/M Users Group Vol. 51,
  83.     "STAGE2 Macro Processor"
  84.  
  85.  
  86.     Richard Curtiss implemented STAGE2, wrote many of the
  87. sample programs, and did an excellent job of commenting on his
  88. own work.  INTRO.DOC and VOLUME51.DOC, provide not only doc-
  89. umentation, but "insight", which is normally the service an
  90. "abstract" serves.  Because of such good documentation, (and
  91. this disk is full), this abstract will be brief.
  92.     STAGE2 is "cryptic", but quite interesting.  Many of
  93. you will enjor "experimenting with it", and many will make
  94. regular use of it.
  95.     What is a "macro processor"?  A program, which "trans-
  96. forms" or "expands" character strings, into something else.
  97. Traditional uses were in assembler programming, allowing you
  98. to say, for example, " OPEN MYFILE,INPUT,4096", rather than
  99. having to code the necessary assembler instructions.  Richard
  100. Curtiss uses it to expand ANY language he uses on his micro,
  101. to add structured programming:  IF/THEN, WHILE, REPEAT, etc.
  102. The macros generate the proper GOTOs, etc, no matter what the
  103. language
  104.     STAGE2 was written in "FLUB", a machine-independent
  105. simple language.  The FLUB source for STAGE2 is on the disk.
  106. IMPL.DOC goes into the details.  You could transport STAGE2 to
  107. some other processor, quite readily.
  108.     The only thing missing is some documentation on the
  109. "state machine" macros of ALX.  VDB.ALX, a video driver for a
  110. memory-mapped display, uses them.  You are normally in ST1
  111. (state 1) waiting for characters.  If you get an ESC, you go
  112. to ST2, because you are awaiting a control sequence.  Then, if
  113. you receive a "Y", it is cursor addressing, so you set the
  114. next state to ST3 via "SETNEXT ( NSTATE = ST3 )" to get the
  115. row, then when its received, "SETNEXT ( NSTATE = ST4 )", i.e.
  116. state 4 to receive the column.  Then reset to state 1.
  117.     The NSTATE DW is the address of the next state (rou-
  118. tine) you will be in, and "EXECUTE ( NSTATE )" expands to
  119. "branch to what is stored in NSTATE.
  120.  
  121.     Abstract by Ward Christensen
  122.  
  123. STAGE2 IS:
  124.  
  125.     STAGE2 is a versatile macro processor developed by William
  126.     M. Waite.  Operating on a generalized pattern recognition principle,
  127.     it can be used for language translation, textual data filtering,
  128.     limited printer output formatting, batch file editing and other text
  129.     processing applications.
  130.  
  131. FEATURES:
  132.  
  133.     Pattern matching
  134.     Symbol table (storage and retrieval under user control)
  135.     Symbol generator
  136.     Integer arithmetic
  137.     Arithmetic expression evaluator
  138.     Scan controlled iteration (search for specific characters)
  139.     Count controlled iteration
  140.     Conditional and unconditional branching (skips)
  141.     I/O channel control
  142.     Limited output formatting
  143.     Recursion
  144.     Error traceback showing all macro calls
  145.  
  146. STRONG POINTS:
  147.  
  148.     Highly transportable
  149.  
  150.     Some applications are an order of magnitude simpler to implement
  151.     with STAGE2 than with conventional algorithmic languages.
  152.  
  153. WEAK POINTS:
  154.  
  155.     A bit slow
  156.     Uses lots of memory for large applications (language translation)
  157.     Macro code is very cryptic in appearance
  158.  
  159. REFERENCES:
  160.  
  161.     STAGE2 is in the public domain and is documented by the author
  162.     in the book:
  163.         Implementing Software for Non-numeric Applications
  164.         by W. M. Waite
  165.         1973  Prentice Hall
  166.  
  167.     Chapter 9 and appendix A include STAGE2 user information, source
  168.     listings and implementation directions.
  169.  
  170.     STAGE2 is also documented by the author in:
  171.         "Communications of the ACM"
  172.         Volume 13 / Number 7
  173.         July 1970
  174.         Pages 415-421
  175.  
  176. STAGE2 for CP/M:
  177.  
  178.     This 8080 implementation was accomplished by:
  179.         Dick Curtiss
  180.         843 NW 54th
  181.         Seattle, Washington  98107
  182.         (206) 784-8018
  183.                     and is in the public domain.
  184.  
  185. DEVIATIONS FROM THE VERSION DISTRIBUTED BY WAITE:
  186.  
  187.     Variable length lines for input and output (132 char max)
  188.         Input lines
  189.             Carriage return terminates
  190.             Line feeds are ignored
  191.             Nulls are ignored
  192.             Deletes are ignored
  193.  
  194.         Output lines
  195.             Carriage return and line feed on every line
  196.  
  197.     Channel 5 implemented for console input and output
  198.  
  199. IMPLEMENTATION LIMITATIONS:
  200.  
  201.     STAGE2 is modeled on an abstract machine called the FLUB machine.  FLUB
  202.     stands for First Language Under Bootstrap.  The FLUB machine word is
  203.     made up of three fields:
  204.         Pointer field        16 bits in this CP/M implementation
  205.         Value field        8 bits
  206.         Flag field        8 bits (only two used)
  207.  
  208.     Since the value field is sometimes used to hold string length, strings
  209.     are limited to 255 characters maximum.  Under some circumstances the
  210.     value field is considered to be signed so that strings longer than
  211.     127 characters may cause strange results, but NOT a crash.  STAGE2 
  212.     seems to be extremely well protected against crashes.
  213.  
  214.     Since the pointer field is used for arithmetic operations, values are
  215.     limited to the range -32767 to 32767.  -32768 causes trouble.
  216.  
  217.     Each character stored by STAGE2 takes 1 FLUB word or 4 bytes in this
  218.     implementation.
  219.  
  220. CP/M VERSION AVAILABILITY:
  221.     CP/M Users' Group
  222.     1651 Third Avenue   
  223.     New York, NY  10028
  224.  
  225. DISCLAIMER:
  226.  
  227.     )()!&(%$#"#"%!!$(%!##!(!$!!$=(00(!#=!! so there!
  228.     Use it at your own risk.
  229.  
  230. MORE INFORMATION:
  231.  
  232.     HELP.DOC    For the STAGE2 novice - start here
  233.  
  234.     USE.DOC        STAGE2 I/O summary and command line specification
  235.  
  236.     INTRO.DOC    Introduction to the STAGE2 processor
  237.  
  238.     IMPL.DOC    STAGE2 implementation notes
  239.  
  240. EXAMPLE FILES:
  241.  
  242.     ALX.S2M        Assembly Language eXtension translator macros
  243.     ALX-.DOC    Notes on ALX.MAC
  244.  
  245.     ALXTEST.ALX    Test case for the ALX macros
  246.     TERM.ALX    Sample program (incomplete)
  247.     VDB.ALX        TDL video display driver for H19 emulation
  248.     CIO.ALX        CP/M console I/O with PMMI modem in "parallel"
  249.  
  250.     MEMORY.INP    Macros and source for memory demonstration
  251.  
  252.     INTERACT.S2M    Macros to demonstrate interactive use of STAGE2
  253.  
  254.     DEMO.S2M    Macros for interactive exercise of most conversions
  255.             and a few processor functions.  This is to be used
  256.             while reading the INTRO.DOC file.
  257.  
  258. IMPLEMENTATION FILES:
  259.  
  260.     IOOP.SRC    Initialization and input/output package
  261.  
  262.     DISKIO2.SRC    General CP/M disk input/output package
  263.     DISKIO2-.DOC    Documentation for above
  264.  
  265.     IOOP$.SUB    Submit file for creating IOOP.HEX
  266.  
  267.     FLT1.FLB    FLUB translation test program 1
  268.     FLD1.DAT    Test data for FLT1
  269.  
  270.     FLT2.FLB    FLUB translation test program 2
  271.     FLD2.DAT    Test data for FLT2
  272.  
  273.     STG2.FLB    Source program for STAGE2
  274.     ST2T.DAT    Test data for STAGE2
  275.  
  276.     FLUB8080.S2M    STAGE2 macros for translating FLUB into 8080 code
  277.  
  278.     STG2SUP.ASM    Support routines for the FLUB machine
  279.  
  280.     STG2MATH.ASM    16 bit math routines for the FLUB machine
  281.  
  282.     FLUB$.SUB    Submit file for assembling FLT1, FLT2 or STG2
  283.  
  284.         Getting Started for the STAGE2 Novice
  285.                                 3/20/81
  286.  
  287. Step 1.    Print the following files:
  288.         HELP.DOC
  289.         USE.DOC
  290.         INTRO.DOC
  291.         DEMO.S2M
  292.  
  293. Step 2.    Read through INTRO.DOC but do not get bogged down in trying to under-
  294.     stand it.  The idea on this first pass is to become a little familiar
  295.     with what is there.
  296.  
  297. Step 3.    Run STAGE2 using DEMO.S2M for input.
  298.         A>STAGE2 DEMO.S2M        ; make sure printer is on
  299.             or
  300.         A>STAGE2 CON:,CON:=DEMO.S2M    ; if you do not have a printer
  301.  
  302.         STAGE2 error messages go to channel 4 which is defaulted to
  303.         the list device if nothing is specified on the command line.
  304.  
  305. Step 4.    Type the following examples and carefully observe the results.  Go
  306.     through all of the examples once to become familiar with them but do
  307.     not try to understand what is going on.  Then start over and do each
  308.     example while referring to the listings DEMO.S2M and INTRO.DOC in an
  309.     effort to understand the operations being performed.  Don't get dis-
  310.     couraged as it may not make sense at first.  Perseverance is in order.
  311.  
  312.         HELP
  313.         C0 ABC            ; simple copy
  314.         C1 ABC            ; symbol undefined in memory
  315.         F3 ABC=XYZ        ; defines symbol in memory
  316.         C1 ABC            ; symbol now defined -
  317.                     ;   note difference from previous C1 
  318.         F3 ABC=IJK        ; new value for ABC in memory
  319.         C1 ABC
  320.         S            ; next symbol from generator
  321.         S
  322.         S
  323.         C2 ABC            ; similar to C1 except if symbol is not
  324.                     ;   defined it will be given the next
  325.                     ;   value from the symbol generator
  326.         C2 PDQ
  327.         S
  328.         C2 PDQ
  329.         C4 2+3*(4-7/3)        ; expression evaluation
  330.         C4 PDQ-6        ; will use value of PDQ from memory
  331.         C4 XXX+3        ; XXX is undefined so value is 0
  332.         C4 ABC+3        ; causes error message to channel 4
  333. X                    ;   because ABC has non-numeric value
  334.                     ;   in memory
  335.         C5 ABCDEFGHIJK        ; length of string
  336.         C6 MAGIC        ; parameter redefinition
  337.         C7 ONE,TWO;THREE    ; scanner operation
  338.         C8 A
  339.         C8 B            ; internal code for character
  340.         F1            ; output request
  341.         F7 2+3            ; count controlled iteration
  342.         F7 PDQ
  343.         FE            ; error trace back
  344.         F0            ; terminates - WARM BOOT
  345.  
  346.  
  347.         ASSEMBLY LANGUAGE EXTENSION PREPROCESSOR
  348.  
  349. This application of STAGE2 to enhance assembly language programs with a few
  350. control structures is included with this STAGE2 package mainly for example.
  351. No user documentation is provided but it should not be difficult to see how
  352. to use it by trying the examples provided.
  353.  
  354.     Examples:
  355.         STAGE2 ALXTEST.ASM,ALXTEST.LST=ALX.MAC,ALXTEST.ALX
  356.  
  357.         STAGE2 BOUT.ASM,BOUT.LST=ALX.MAC,BOUT.ALX
  358.  
  359.  
  360. IMPLEMENTATION NOTES:
  361.  
  362.     > means push   ^ means pop   C means condition
  363.  
  364.     Stack        Source Statements    Generated Code
  365.  
  366.     >n >K        IF ( C )            JCF    n
  367.  
  368.     ^K ^n            FIN            n:
  369.  
  370.     -----------------------------------------------------------
  371.  
  372.     >n >n+1 >W    WHEN ( C )            JCF    n+1
  373.  
  374.     ^W >E            FIN                JMP    n
  375.  
  376.     ^E ^n+1 >K    ELSE            n+1:
  377.  
  378.     ^K ^n            FIN            n:
  379.  
  380.     -----------------------------------------------------------
  381.  
  382.     >B        BRANCH
  383.  
  384.                 ( V1 )  L1            CPI    V1
  385.                             JZ    L1
  386.  
  387.                 ( V2 | V3 | V4 )  L2    CPI    V2
  388.                             JZ    L2
  389.                             CPI    V3
  390.                             JZ    L2
  391.                             CPI    V4
  392.                             JZ    L2
  393.  
  394.                 ( OTHERWISE )  L3        JMP    L3
  395.  
  396.     ^B            FIN
  397.  
  398.     -----------------------------------------------------------
  399.  
  400.     >n >S        SELECT
  401.  
  402.     >n+1 >I            ( V1 )            CPI    V1
  403.                             JNZ    n+1
  404.  
  405.     ^I ^n+1            FIN            JMP    n
  406.                         n+1:
  407.  
  408.     >n+3 >I            ( V2 | V3 | V4 )        CPI    V2
  409.                             JZ    n+2
  410.                             CPI    V3
  411.                             JZ    n+2
  412.                             CPI    V4
  413.                             JNZ    n+3
  414.                         n+2:
  415.  
  416.     ^I ^n+3            FIN            JMP    n
  417.                         n+3:
  418.  
  419.     >O            ( OTHERWISE )
  420.  
  421.     ^O            FIN
  422.  
  423.     ^S ^n            FIN            n:
  424.  
  425.     -----------------------------------------------------------
  426.  
  427.     >n >n+1 >L    WHILE ( C )        n+1:    JCF    n
  428.  
  429.     ^L ^n+1 ^n        FIN                JMP    n+1
  430.                         n:
  431.  
  432.     -----------------------------------------------------------
  433.  
  434.     >n >R        REPEAT            n:
  435.  
  436.     ^R ^n            UNTIL ( C )            JCF    n
  437.  
  438.     -----------------------------------------------------------
  439.  
  440.     Statement is allowed if top of stack is one of the following:
  441.     I,K,L,O,R,W,*.  Otherwise particular control statements are
  442.     expected.
  443.  
  444.         I,K,L,O,W    statement or FIN
  445.  
  446.         R        statement or UNTIL
  447.  
  448.         E        ELSE only
  449.  
  450.         S        SELECT ITEM or FIN
  451.  
  452.         B        BRANCH ITEM or FIN
  453.