rsalz@bbn.com (Rich Salz) (11/30/90)
Submitted-by: Darren New <new@ee.udel.edu>
Posting-number: Volume 23, Issue 58
Archive-name: lome/part08
[ NOTES! The archive-names don't match with the archive-parts listed in
the shar files. Don't panic. :-) --r$ ]
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 9 (of 9)."
# Contents: LOME/LOME.doc
# Wrapped by new@estelle.ee.udel.edu on Tue Aug 14 16:10:04 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'LOME/LOME.doc' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'LOME/LOME.doc'\"
else
echo shar: Extracting \"'LOME/LOME.doc'\" \(46006 characters\)
sed "s/^X//" >'LOME/LOME.doc' <<'END_OF_FILE'
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X This documentation and all accompanying files
X Copyright 1990 Darren New.
X All Rights Reserved.
X See README for distribution conditions.
X
X
X LOME (Line Oriented Macro Expander) is a relatively sophiticated macro
X expander. It is designed to be compiled by Comp1 or interpreted by
X Interp, and as such is very portable. The syntax and semantics are
X described herein.
X
X A second version of LOME, for those with PPL, is available. This
X version is written in C but otherwise behaves like the version in SCM.
X This version is also somewhat more flexible internally, allowing
X expansion of the macro list during execution and so forth.
X
X A LOME program consists of two files. The first file is the macro
X definition file. This file defines the translation between lines in
X the source file(s) and lines in the output file(s). The source file
X contains text which is matched against the macros, with each matching
X line being replaced by the body of the macro with certain parameters
X begin replaced. Each so-expanded line is then matched again against
X the macros until no more matches can be performed, at which point the
X lines are output to the output file. Text in the bodies of the macros
X can redirect input from and output to various files, allowing multiple
X source or output files.
X
X The LOME macro definition file (MDF) consists of a sequence of
X arbitrary non-blank lines serving as comments, a single blank line, a
X parameter line, and then a sequence of macro definitions. Each macro
X definition consists of a header line to be matched against a source
X line, followed by a set of lines known as the macro body. Each macro
X definition (including the final one) is terminated by a line starting
X with two BEOL characters (see below). The overall sequence of macro
X definitions is termated by an end-of-file condition. Each macro header
X line may be preceeded by any number of empty lines (not even
X containing a HEOL). Each macro body contains mixtures of literal text
X and specially-flagged escape sequences. The escape sequences can be
X classified into one of three groups: parameter operations, which
X affect individual parameters matched in the macro header; file
X operations, which manipulate files; and control operations, which do
X things which would be difficult to specify as macro-expansion
X operations.
X
X The parameter line contains characters which serve two purposes. The
X initial portion allows LOME to be independant of the character set of
X the machine it is running on by specifying all characters which LOME
X must treat specially. The final portion contains a series of boolean
X flags, specifying which minor modifications in the operation of LOME
X should be made. The characters on the parameter line, along with the
X recommended setting (Rcmd), are specified below.
X
X
X
X
X
X Page 1 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X Offset Rcmd Meaning
X 0 \ The escape character (ESC), which negates the
X speciality of the following character.
X
X 1 @ The placeholder character (PHC), which indicates where
X in a macro header line a parameter match should be
X attempted.
X
X 2 . The header end-of-line (HEOL), which indicates the end
X of a meaningful source line and which can be followed
X by a comment on the same line.
X
X 3 @ The substitution character (SUBS), which indicates in
X the macro body that this and the following two
X characters are to cause a special action such as
X rewinding a file or substituting the value of a
X parameter for this three-character sequence.
X
X 4 $ Body end-of-line character (BEOL), which indicated the
X end of a meaningful macro body line and which can be
X followed by a comment on the same line.
X
X 5 0 The digit zero (ZERO). Character inputted from or
X outputted to the I/O routines are assumed to map the
X numerals from zero through nine to ten contiguous
X numbers with zero as the lowest-numbered numeral.
X
X 6 A First upper-case letter (UCA). See next entry.
X
X 7 a First lower-case letter (LCA). The I/O routines are
X assumed to map upper- and lower-case letters such that
X the difference between 'A' and any upper-case letter
X is the same as the difference between 'a' and the
X corresponding lower-case letter. In addition, 'A' must
X map to the lowest-numbered upper-case letter and 'a'
X must map to the lowest-numbered lower-case letter.
X
X 8 Z Last upper-case letter (UCZ). See above.
X
X 9 F File operation character (FILEOP). See below.
X
X 10 C Control operation character (CTRLOP). See below.
X
X 11 ` Open quote (OQ). Used in "balanced" parameter
X matching.
X
X 12 ' Close quote (CQ). Used in "balanced" parameter
X matching.
X
X 13 ( Open parenthesis (OP). Used in mathematical evaluation
X and in "balanced" parameter matching.
X
X 14 ) Close parentheses (CP). Used in mathematical
X evaluation and in "balanced" parameter matching.
X
X
X Page 2 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X
X 15 + Plus sign (PLUS). Used in mathematical evaluation.
X
X 16 - Minus sign (MINUS). Used in mathematical evaluation.
X
X 17 * Multiplication sign (MULT). Used in mathematical
X evaluation.
X
X 18 / Division sign (DIV). Used in mathematical evaluation.
X
X 19 ? The "fetch" character (FETCH). Used in mathematical
X evaluation.
X
X 20 ! The "radix" character (RADIX). Used in mathematical
X evaluation.
X
X 21 X Reserved.
X
X 22 X Reserved.
X
X 24 X Reserved.
X
X 25 X Reserved.
X
X 26 Space character (SPACE). Used in stripping lines and
X so on.
X
X 27 0 Case specific flag (FCASE): zero to match macro
X headers and do skip comparisons regardless of case,
X one for case-specific matching and comparing.
X
X 28 1 Blank output line flag (FBLANK): one to allow blank
X (empty) lines in the macro body to be matched and
X outputted, zero to cause blank lines in the macro body
X to be discarded.
X
X 29 0 Leading space flag (FSPACE): zero to ignore leading
X spaces while scanning input lines, one to require
X matching of leading spaces. Does not affect skip
X comparisons.
X
X 30 1 Required match flag (FMATCH): zero to allow inputted
X lines to be output without at least once matching a
X macro header line, one to issue error messages for
X lines read from a file which do not match any macro
X header line, two to issue errors on lines which are
X output becuase they fail to match even after
X rescanning. If two, only file operations may output
X lines.
X
X 31 0 Symbol generator advance flag (FSYMGEN): zero to start
X the symbol generator at zero, one to start the symbol
X generator at 100, two to start the symbol generator at
X 1000 (for consistantly sized numbers).
X
X
X Page 3 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X
X 32 0 Stack underflow flag (FSTACKUNDER): zero if a
X user-maintained stack underflow should cause an ESTK
X error, one if it should not cause an error.
X
X 33 0 Stack size flag (FSTACKSIZE): zero for default initial
X user-maintained stack size.
X
X 34 0 Echo flag (FECHO): one to echo all read lines as
X PLStatus text as they are read, zero for quite operation.
X
X 35 0 Reserved.
X
X 36 0 Reserved.
X
X 37 0 Reserved.
X
X 38 0 Reserved.
X
X
X Each macro header line (MHL) contains a mixture of characters and
X placeholder characters (PCs), possibly terminated by a HEOL character.
X Any character may be immediately preceeded by an escape character to
X cause it to be treated as a regular character. The only characters in
X a MHL which need such treatment are PCs and HEOLs. "Scanning" is the
X processes of attempting to match a input line (IL) against a MHL.
X (Note: an input line is not necessarily read from a file; it may be
X the output of a previous macro expansion.) If a scan is successful,
X each PC in the MHL will correspond to zero or more contiguous
X characters in the IL and the macro whose header was matched is known
X as the matching macro (MM). Each PC will be the shortest "balanced
X string" (BS) of characters which is followed in the IL by the same
X character which follows this parameter's PC in the MHL being scanned.
X A BS is defined with the following BNF. <OQ> is the open quote
X character, <CQ> is the close quote character, <OP> is the open
X parenthesis character, and <CP> is the close parenthesis character.
X <ARB> is any sequence of zero or more characters not containing an
X unescaped <OP>, <CP>, <OQ>, or <CQ> character.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Page 4 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X "a balanced string"
X <BS> ::= <ARB-C> |
X <ARB> <OQ> <ARB-Q> <CQ> <BS> |
X <ARB> <OP> <ARB-P> <CP> <BS>
X
X <ARB-C> ::= <ARB> | <CQ> | <CP>
X
X "an arbitrary string balanced with respect to quotes"
X " but disregarding parentheses"
X <ARB-Q> ::= <ARB> | <OP> | <CP> |
X <ARB-Q> <OQ> <ARB-Q> <CQ> <ARB-Q>
X
X "an arbitrary string balanced with respect to parens"
X " but disregarding quotes"
X <ARB-P> ::= <ARB> | <OQ> | <CQ> |
X <ARB-P> <OP> <ARB-P> <CP> <ARB-P>
X
X The following (including the empty string) are all balanced strings:
X XYZ
X (XYZ)
X `XYZ'
X (don't)
X (won`t)
X `wont)close'
X `can(t-close'
X don\'t
X `dont\'t'
X don't
X WX(Y'Z)AB`C(D'EF
X PDQ(BACH(WAS)HERE)
X LOTS`OF`NESTING'IN'HERE
X ``''
X (())
X )))
X spaces are OK anywhere
X even the beginning and end!
X
X The following are not balanced strings unless they appear at the end
X of a line being scanned:
X don`t
X (won't
X `unmatched)
X )toosoon
X toolate(
X
X
X In summary, the scanner starts with the next character of the input
X string to be matched. If this matches the character in the macro
X header line that follows the placeholder character, it stops. If the
X next input character is an open parenthesis or open quote, it advances
X to the matching close parenthesis or close quote or end-of-line,
X ignoring quotes or parentheses, repectively. Any character advanced
X past during the scan (which does not include the character causing the
X scan to stop nor the end-of-line) are considered part of the matching
X
X
X Page 5 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X parameter. Non-placeholder characters in the macro header line must
X match the next character of the input line exactly (unless the next
X input line character is an escape, in which case the macro header
X character must match the character after the escape). Trailing spaces
X on the input line will match the HEOL in the macro header line; i.e.,
X trailing spaces are ignored in the input line unless escaped. Also,
X trailing spaces in the macro header line will match the BEOL in the
X input line. This allows a macro header line of the form "XXX @" to
X match an input line of the form "XXX" by setting the zero'th parameter
X to an empty string; the space between the "XXX" and the "@" matches
X the BEOL, as does the placeholder character.
X
X Each macro header line may have as few as zero or as many as ten
X unescaped placeholder characters. Once a matching macro (MM) has been
X found for an input line (IL), the substrings corresponding to the PCs
X are numbered zero through nine and referenced in the macro body by
X including the substitution character (SC) in a line of the body. Such
X a reference is known (natually enough) as a substitution, or as an
X operation. Each macro body line of the matching macro (MMBL) is
X expanded and then resubmitted for further scanning. Only when the
X submitted line is found to not match any macro header lines is the
X submitted line written to the output file (unless it causes an error
X because of the required match flag). Certain substitutions can alter
X the scanning, matching, and so on for individual lines; such
X operations are documented under the descriptions of the individual
X operations. As each line is submitted to be rescanned, the current
X parameters as well as the location in the "calling" macro body are
X saved on a stack, and then all of the parameters are cleared to empty.
X This allows new macros to match or modify the parameters without
X disturbing side-effects. There is also a user-managed stack of strings
X which can be moved to and from parameters, allowing global information
X to be passed from line to line. In addition, a "dictionary" of
X variables is globally maintained; certain substitutions use the text
X of a parameter as the name of variable to be set into or retreived
X from this dictionary. There is also a facility for generating symbols;
X one substitution allows a variable to be set to a number never before
X generated by this facility, allowing for unique references for label
X generation and so on.
X
X The result of expanding a macro body line is usually a "constructed
X line". This constructed line is cleared to zero length before the
X start of each macro body line expansion. Some substitutions cause the
X constructed line to be discarded. If no such substitution is
X encountered, then when the macro body line end-of-line is encountered,
X the parameters and current offset into the macro body are saved on the
X "traceback stack" and the constructed line is resubmitted for
X scanning. If a "skip" is in progress, lines in macro bodies are
X skipped; this conditional-expansion facility is descibed completely
X below. Upon encountering an error, the traceback stack is printed out,
X allowing the user to see the macro which caused the error as well as
X all calls that lead up to this line.
X
X Sometimes an error will be detected which cannot be corrected or which
X the parameter line has specified should not be corrected. Each of
X
X
X Page 6 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X these errors results in a four character error message, possibly
X followed by a traceback dump possibly followed by an exit from the
X program. The possible error messages are these:
X
X FULL - Memory is full. Macro definition file too large. Fatal.
X
X IOER - An ILLEGAL was returned from MacroIO. Usually fatal.
X
X UEOF - Unexpected EOF. Trailer left off last macro definition?
X Usually fatal.
X
X FORM - Something is wrong in the format of the input. Parameter
X line wrong size, two consecutive placeholder characters in a macro
X header line, substitution character not followed by proper parameter
X flags, file operation could not parse constructed line to determine
X streams to be affected. Often fatal.
X
X FSTK - User-managed stack overflowed. fatal.
X
X ESTK - User-managed stack underflowed. Issued only if FSTACKUNDER
X is zero, but is fatal if issued.
X
X NYET - Not yet implemented. Fatal.
X
X NONE - Line was not matched but FMATCH said it needed to match. Not
X fatal.
X
X NEST - Traceback stack overflow. Not fatal, but clears stack.
X
X SSTK - Input stream stack overflow (see @F3). Fatal.
X
X VFUL - Variable table full. May also appear as FULL error in some
X implementations. Fatal.
X
X The operations available in an individual macro body line are as
X follows. If a normal character is encountered in the macro body line,
X it is added to the end of the constructed line. If an escape character
X is found, the next character from the body line is added to the end of
X constructed line. An escaped BEOL character is added to the line, but
X an escaped end-of-line is ignored. That is, if an escape character is
X the last character of a macro body line (not followed by a BEOL
X character) then the final escape is ignored; therefore, a macro body
X line must reside on exactly one macro definition file input line. If
X an unescaped BEOL character is encountered, the constructed line is
X resubmitted for output or further expansion. Thus, a line containing
X no escape character and no substitution characters is copied to the
X constructed line as-is and resubmitted. If an unescaped substitution
X character is found, the next two characters are examined to determine
X the operation to be performed. None of these three characters are
X added to the constructed line. If the character after the substitution
X character is the file operation character (usually 'F') then the
X character after the file operation character is a digit specifying one
X of ten possible file operations. If the character after the
X substitution character is the control operation character (usually
X
X
X Page 7 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X 'C') then the character after the file operation character is a digit
X specifying one of ten possible control operations. If the character
X after the substitution character is a digit then the character after
X the first digit is another digit specifying one of ten possible
X parameter operations to be applied to the parameter indicated by the
X first digit. Each of these groups of operations are described below.
X In some operations described below, the phrase "discard constructed
X line" is used. This indicates that the line constructed so far is at
X that point discarded and cleared, never to be rescanned or output.
X Whenever this occurs, the next character of the input line (the third
X after the substitution character) is examined. If found to be a BEOL,
X expansion continues at the next body line without constructing or
X rescanning the blank line that an empty constructed line would
X normally cause. If the character is not found to be a BEOL, it is not
X skipped and will become the first character scanned and interpreted
X after the "discard constructed line" operation ends.
X
X A parameter substitution is specified by including in a macro body
X line the substitution character followed by a digit indicating to
X which parameter (0-9) the operation should be applied followed by a
X digit (0-9) indicating which operation should be applied. If the
X indicated parameter matched an empty string or fewer placeholder
X characters than the indicated parameter were specified in the macro
X header line, then the indicated parameter is "empty". In all cases, it
X is safe to change the text of the parameter with one of the parameter
X substitution operations described below (even if the parameter was not
X matched in the macro header line). When a mathematical (as opposed to
X textual) value is inserted in the line, then a leading minus sign is
X inserted if the number is negative, then the value of the number in
X radix-10 is inserted without leading zeros; a special case is the
X number zero, which is inserted as the single digit zero. The only
X changes to parameters made are the ones explicitly documented. The
X list of operation numbers and their effects follows:
X
X 0 - Insert the text of the parameter into the constructed line without
X modification. An empty parameter or one which has no placeholder
X character causes no change in the constructed line.
X
X 1 - Insert the text of a copy of the parameter, transformed as
X described, into the constructed line. First, remove leading and
X trailing spaces from the text. Then, if the first character of the
X text is the open parenthesis character and the last is the close
X parenthesis character or the first is the open quote character and the
X last is the close quote character, remove the first and last
X characters of the text. Finally, add the text to the constructed line.
X No change is made to the actual text of the parameter during this
X transformation. This is the most convenient mechanism for inserting
X text from a parameter, as it allows the user to quote expressions for
X unambiguous matching. If the transformed parameter is empty (or if the
X pre-transformation parameter is empty or unset) then the constructed
X line is not changed.
X
X 2 - Interpret the text of the parameter as a mathematical expression.
X In each of the addition, subtraction, multiplication, and division
X
X
X Page 8 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X operations, the two tokens immediately to the left of the operator
X character are used. Each must be interpretable as a radix-10 integer
X with a single optional sign. If not, a conversion error (CONV) is
X issued. All tokens and operators must be separated by at least one
X space. operator characters that are not followed by a space (or end of
X parameter) are considered to be part of the token. In all cases (even
X when there are no operator characters), excess spaces are compressed
X to one space. In the case of the `fetch' operator (normally `?'), the
X single token preceeding the fetch operator is treated as the name of a
X variable and is looked up in the variable dictionary. The text of the
X variable is substituted into the line in place of the name of the
X variable, unless the value is not found or is of zero length, in which
X case a conversion error (CONV) is issued. In the case of the radix
X operator (normally `!'), the three tokens before the operator
X represent (from left to right) the number to be converted (with
X optional sign), the radix in which the number is expressed, and the
X radix in which the number should be expressed. These three tokens plus
X the operator are replaced by the number with the same value in the new
X radix. The from-radix and to-radix tokens must each be one character
X long and must each represent the largest single-digit number available
X in that radix. Thus, to convert the number 365 from decimal to hex,
X use `365 9 F !' and to convert the number 0x1A7 from hex to binary use
X `1A7 F 1 !'. Characters after nine run from UCA to UCZ, but upper and
X lower case are treated identically. In all operations except the radix
X conversion, numbers are expected to be in radix-10. If illegal
X characters for the given radix are found, a conversion error (CONV) is
X issued. Outputted numbers are not padded with leading zeros and will
X not have a plus sign if positive. The conversion stops where there are
X no longer any operator characters (+,-,*,/,?,!) in the parameter;
X hence, multiple expressions can be evaluated with one substitution and
X expressions with insufficient operator characters can generate
X multiple words of output.
X
X The range allowable is limited by the implementation underlying the
X LOME interpreter, but can safely be assumed to be at least -9999 to
X +9999. Only integer operations are performed; fractional results from
X divisions are discarded as they are in C. Once the value is evaluated,
X it is inserted into the constructed line as described above. This
X operation does not change the text of any parameters or variables. If
X the text of the parameter cannot be converted to a valid expression
X (undefined variables, division by zero, and so on) then a conversion
X error (CONV) is issued.
X
X
X 3 - Interpret the text of the parameter as the name of a variable to
X be looked up in the dictionary. Insert the value of the so-named
X variable into the constructed line. If the parameter is empty or the
X variable is not set or is empty, insert nothing into the constructed
X line without issuing any error.
X
X 4 - Interpret the text of the parameter as the name of a variable to
X be looked up in the dictionary. If parameter is empty or the variable
X is not set or is empty, insert the decimal equivalent of the value of
X the symbol generator into the constructed line (without leading sign
X
X
X Page 9 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X or zeros) and then increment the symbol generator. If the parameter
X text is not empty but the variable is not set or is empty, set the
X value of the variable to be the just-inserted text. If the parameter
X text is not empty and the value of the so-named variable is not empty,
X insert the value of the variable without referencing or modifying the
X symbol generator. In this way, symbols (variables) can be given unique
X numbers which henceforth do not change. The text of the parameter does
X not change, although the text of the value of the variable might.
X
X 5 - Substitute the decimal equivalent of the I/O mapping code (see
X MacroIO.doc) of the first character of the parameter into the
X constructed line. If the parameter is empty, substitute the single
X digit zero, which is the code for end-of-line. This mapping may change
X from machine to machine and from implementation to implementation.
X
X 6 - Substitute the decimal equivalent of the number of characters in
X the parameter. That is, insert the length of the text of the
X parameter.
X
X 7 - Assign the current constructed line to the parameter. The previous
X text of the parameter is lost. Discard the constructed line, possibly
X skipping the following end-of-line. This change lasts until the
X current macro expansion is complete.
X
X 8 - Interpret the text of the parameter as the name of a variable in
X the dictionary. Assign to the value of the variable the text of the
X current constructed line. If the variable has never before been set,
X create the variable. If the variable already has a value, discard the
X old value. If the test of the parameter is empty or unset, ignore the
X setting of the variable. An any case, discard the constructed line,
X possibly skipping the following EOL. This change lasts until
X overridden or until execution terminates.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X Possibility: a Word-Wrap substitution. Parameters give the left
X margin, the right margin, and one of ragged-right, ragged-left,
X centered, or justified. The contents of the parameter is then put into
X the constructed line as specified, with any that did not fit going
X back into the parameter (possibly for the next line).
X
X
X A control substitution is specified by including in a macro body line
X the substitution character followed by a control operation character
X (usually 'C') followed by a digit (0-9) indicating which operation
X should be applied. The only changes to parameters made are the ones
X explicitly documented. In ALL control substitutions, the constructed
X line is discarded and any immediately following BEOL is skipped. In
X many cases, the constructed line is referenced before it is discarded.
X In some cases, the values of parameters are referenced or changed.
X References to parameters are indicated by the notation P0 for
X parameter zero, P1 for parameter one, and P2 for parameter two. When a
X skip command ($C1, $C2, $C3, or $C4) is encountered whose condition is
X satisfied, the skip counter is set to the value of P0 interpreted as a
X signed decimal number (zero if it cannot be so interpreted). If the
X
X
X Page 10 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X skip counter is zero, the remainder of the macro body line (after the
X skip operation) is skipped; if the skip operation is the last on the
X line, this has no effect. If the skip counter is negative, that many
X entire macro bodies are skipped. That is, minus one will skip to the
X end of the macro which contains the skip command, minus two will skip
X to the end of the macro which called the macro containing the skip
X command and so on. A skip of -999 can be used to skip to the next line
X of input, because negative skips only ever affect macros already in
X the process of being expanded. After a skip is complete (positive or
X negative), the skip counter is cleared. The list of control operation
X numbers and their effects follows:
X
X 0 - Stop. If the constructed line is empty, stop normally. If the
X constructed line is not empty, output it as an error message and then
X exit with a debugging dump. The error message may go to the current
X output stream or it may go to wherever the debugging dump goes; this
X is implementation dependant.
X
X 1 - Skip P0 lines if the value of P1 (interpreted as a signed decimal
X number) is less than the value of P2 (interpreted as a signed decimal
X number). If either P0 or P1 cannot be interpreted as a number, it is
X assumed to be the value zero.
X
X 2 - Skip P0 lines if the text of P1 is equal to the text of P2.
X
X 3 - Skip P0 lines if the text of P1 is not equal to the text of P2.
X
X 4 - Skip P0 lines if the text of P1 is an initial portion of the text
X of P2.
X
X 5 - Push the constructed line onto the user-managed string stack.
X Issue a FSTK (full stack) error and exit if too many entries are
X pushed.
X
X 6 - Pop the user-managed string stack into the parameter whose number
X (0-9) is the first character of the constructed line, which must be a
X digit. If the constructed line is empty, discard the top entry of the
X user-managed string stack without storing into any parameter. If the
X stack is empty, either issue an ESTK (empty stack) error and exit or
X leave the parameter unchanged, depending on the stack underflow flag.
X
X 7 - Decimal loop. P0 and P1 provide signed decimal values. If either
X cannot be interpreted as a signed decimal value, it is assumed to be
X zero. The constructed line is pseudo-replicated (P1-P0+1) times with
X the numbers from P1 through P2 represented in decimal and surrounded
X by parentheses appended. If P0 is greater than P1 then no
X pseudo-replication is performed. The pseudo-replication is
X distingushed from true replication in two ways. A skip within a macro
X matched by the constructed line that causes a skip out of the macro
X matched by the constructed line will terminate the skip immediately.
X For example, if P0 is one and P1 is five, then five lines are
X pseudo-replicated. If during the expansion of the macro matching the
X second constructed line a skip that leaves the macro with the skip
X counter set at one occurs, no further expansion will occur. Also, the
X
X
X Page 11 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X value of P0 is changed by this control function to match either the
X last line expanded before a skip aborted the pseudo-replication (as
X described above) or to one larger than P1 if the pseudo-replication
X was not aborted by a skip. Both of these effects are artifacts of the
X way in which this control function is implemented. After constructing
X a line, the P0 parameter is modified to the value it will have at the
X next pseudo-replication and then the start of the current macro body
X line is pushed onto the traceback stack. When the constructed macro
X line is finished its expansion, the macro body line causing the
X decimal loop is rescanned, causing the next expansion. Once P0 exceeds
X P1, the constructed line is discarded without rescanning. Hence, a
X skip out of the constructed macro causes the decimal loop line to be
X skipped and the execution of the decimal loop corrupts the value of P0
X in order to keep track of where in the expansion the loop is. Note
X that since the start of the current macro body line is pushed onto the
X traceback stack, other operations (before the $C7 operation but on the
X same line) can be performed during each iteration, as the entire line
X will be rescanned. Anything on the line after the loop command is
X executed at the end of the loop unless the loop is skipped out of.
X
X 8 - String loop. This is similar to the decimal loop except in the
X interpretation of P0 and P1 and the constructed line that gets
X rescanned. If P1 is empty, then the constructed line is rescanned once
X for each character in P0. Each rescanned line consists of the
X constructed line followed by the next character off the front of P0.
X The loop stops when P0 is empty. The constructed line is not rescanned
X at all when P0 is empty, whether it is empty at the start or empty due
X to prior expansions. If P1 is not empty then P1 is interpreted as a
X series of "break characters". In this case, P0 is broken into a series
X of balanced strings, each being the shortest initial balanced string
X of P0 which is immediately followed by any of the characters in P1 or
X by the end of P0. The constructed line is pseudo-replicated once for
X each such string in P0. The rescanned line consists of the constructed
X line followed by the character from P1 which immediately followed the
X balanced string case enclosed parenthesis (possibly escaped to prevent
X imbalance), followed by initial balanced substring of P0 that was
X terminated by the character from P1 or the end of P0. On the last
X replication, the first parameter (the single character from P1) is
X missing, resulting in empty parentheses. For example, if the
X constructed line is "EVAL" and P0 is "AB+(B*CD)*E+-FG" and P1 is
X "+-*/" then five lines will be generated: "EVAL(+)AB",
X "EVAL(*)(B*CD)", "EVAL(+)E", "EVAL(-)", and "EVAL()FG". The macro
X header which would match all of these is "EVAL(@)@". If the
X constructed line is "XX" and P0 is "AB(CD`" and P1 is "()`'" then the
X result will be two lines: "XX(\()AB", and "XX(`)CD"; "XX()" will not
X appear because P0 was empty at the start of that iteration. Regardless
X of the initial value of P1, P0 will become empty after this command
X terminates unless terminated by an embedded skip. Anything on the line
X after the loop command is executed after the loop unless the loop is
X skipped out of.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X Possibility: A state control. Two ways of doing this are possible:
X Method one would have this control substitution take the constructed
X
X
X Page 12 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X line and pseudo-prepend it to each inputted line just before it is
X matched against macro headers. This allows certain macros to match
X some times and not others. It has the disadvantage that each macro can
X only belong to one state. Method two would have this control
X substitution take a single state and have each macro header tagged
X with the set of states in which it may be matched. Both of these
X should require changes only to FindMatch() and LoadMacros().
X
X
X A file substitution is specified by including in a macro body line the
X substitution character followed by a file operation character (usually
X 'F') followed by a digit (0-9) indicating which operation should be
X applied. The only changes to parameters made are the ones explicitly
X documented. In ALL file substitutions, the constructed line is
X discarded and any immediately following BEOL is skipped. In many
X cases, the constructed line is referenced before it is discarded. In
X some cases, the values of parameters are referenced or changed.
X References to parameters are indicated by the notation P0 for
X parameter zero, P1 for parameter one, and P2 for parameter two. All
X I/O performed by LOME is performed via calls on the MacroIO package.
X This package allows reference to up to nine different text-based
X streams, numbered one through nine, each (probably) associated with a
X named file on the host system. Stream zero is defined to always return
X end-of-file on read and to discard output on write. The association
X between the stream number and the name of the file is established at
X the time LOME is started and cannot (at this time) be changed by the
X LOME program. Streams which have no explicit name associated can be
X used temporarily but are deleted when the program completes. Each of
X these streams can be rewound. Normally, once writing to a stream has
X begun, a rewind of that stream must be performed before it can be
X read, and vica versa. LOME defines a "current input stream" and a
X "current output stream," which may be changed via file substitution
X operations. If an illegal operation is attempted, one of two events
X will occur. If an unexpected end-of-file condition is encountered (for
X example, while reading a macro body) then a UEOF error will be
X reported and operation will stop. If some other occurs or an illegal
X operation is reported during processing, an IOER (input/output error)
X will be reported. Stream numbers are indicated by giving either a
X digit (0-9) or an upper-case 'A' (UCA on parameter line) meaning the
X current input stream or an upper-case 'Z' (UCZ on the parameter line)
X meaning the current output stream. In all cases these parameters are
X allowed and passed to MacroIO; however, in many cases the calls may
X fail (for example, if output is attempted to current input stream).
X
X The list of file operation numbers and their effects follows:
X
X 0 - Rewind the stream indicated by the first character of the
X constructed line, which may be a digit or UCA or UCZ. If the
X constructed line is more that one character long, use the rest of the
X constructed line as a new name for the file after it is rewound; in
X this case, any scratch data on the file is deleted and this file will
X remain after the execution.
X
X 1 - Copy from the stream (S) indicated by the first character of the
X
X
X Page 13 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X constructed line, which must be a digit or UCA or UCZ, to the stream
X (T) indicated by the second character of the constructed line, which
X must also be a digit or UCA or UCZ, until a line starting with the
X constructed line excluding the first two characters (R) is encountered
X or until end-of-file is detected on stream S. If R is empty (i.e., the
X constructed line is two characters long), append the entire stream S
X to the stream T. If R is not empty then the line that matches R is
X discarded and is not appended to T. Lines of a file can be skipped
X (read without parsing) by copying them to stream 0. If R is not empty
X and R is not found to start a line in the remainder of stream S, a
X UEOF error is issued and processing continues. Exausting a stream
X never causes the input stream stack (see 3, below) to be popped.
X
X 2 - Direct future output to the stream indicated by the first
X character of the constructed line, which must be a digit or UCA or
X UCZ.
X
X 3 - Read future input from the stream indicated by the first character
X of the constructed line, which must be a digit or UCA or UCZ. If the
X constructed line contains more than one character then when
X end-of-file is detected on this stream, revert to the previous input
X stream.
X
X 4 - Output the constructed line except for the first character to the
X stream indicated by the first character of the constructed line, which
X must be a digit or UCA or UCZ. This outputs empty output lines for
X empty constructed lines even if the blank output line flag (FBLANK) is
X zero. This is one method of outputting lines without errors when the
X required match flag (FMATCH) is two.
X
X 5 - Use the constructed line as a format pattern. Use the parameters
X as the values to substituted into the format pattern. Output without
X rescanning the formatted results to the stream indicated by the first
X character of the constructed line, which must be a digit or UCA or
X UCZ. This outputs empty output lines for empty constructed lines even
X if the blank output line flag (FBLANK) is zero. This is one method of
X outputting lines without errors when the required match flag (FMATCH)
X is two. The constructed line contains characters which are output
X exactly and strings of identical digits (fields) which are replaced
X with the leftmost portion of the parameter indicated by the digit and
X space-filled on the right. If a field (X) is separated from a field of
X the same digits (Y) by either other digits or non-digit characters,
X then the second field (Y) will start over at the beginning of the same
X parameter that the first field (X) used. For example, if the
X constructed line is "Zb000000b11111b000bHELP22ME" (where "b" is a
X space character) and P0 is "ZERO" and P1 is "23" and P2 is "" then the
X outputted line will be "bZERObbb23bbbbZERbHELPbbME".
X
X 6 - Output a debugging dump to the stream indicated by the first
X character of the constructed line, which must be a digit or UCA or
X UCZ, with a heading containing the constructed line excluding the
X first character.
X
X 7 - Output the constructed line except for the first character to the
X
X
X Page 14 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X user as a status message. The first character must be a digit
X indicating the priority of this message with lower digits indicating
X more important messages. This may not cause any output under some
X implementations, as it is explicitly designed to bypass the MacroIO
X package.
X
X 8 - Read one line from the stream indicated by the first character of
X the constructed line, which must be a digit or UCA or UCZ. Assign the
X text of that line, without parsing or rescanning in any way, to the
X parameter indicated by the second character of the constructed line,
X which must be a digit. If an error occurs while reading the file, the
X parameter remains unchanged if the file was specified by a digit or
X UCZ. If an error occurs while reading the stream indicated by UCA, the
X input stream stack (as created by $F3) is popped and the read is
X retried; only at EOF of the initial stream is the parameter left
X unchanged. If the second character of the constructed line is not a
X digit then the line is read and discarded.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X Possibility: Binary output. Output to a stream is performed at a given
X offset and the number is output with a given size. For example, a
X two-byte integer whose value is 1000 is output to offset 93 in the
X file xyzzy.bin. This needs more thought and will probably be quite
X slow.
X
X SUMMARY OF SUBSTITUTION OPERATIONS:
X
X PARAMETER SUBSTITUTION OPERATIONS:
X
X 0 - Insert parameter without change.
X
X 1 - Insert the parameter, stripping spaces and outermost parens.
X
X 2 - Insert value interpreted as mathematical expression.
X
X 3 - Insert value of variable named by parameter.
X
X 4 - Insert var, or insert new generated number and set variable.
X
X 5 - Insert I/O code of first character of parameter.
X
X 6 - Insert length of parameter.
X
X 7 - Assign the current constructed line to the parameter.
X
X 8 - Assign constructed line to variable named by parameter.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X
X
X
X
X
X
X
X
X Page 15 Printed Tue Aug 14, 1990
X
X
X LOME.Doc Line Oriented Macro Expander Darren New
X
X
X CONTROL OPERATIONS:
X
X 0 - Stop. Error if constructed line contains characters.
X
X 1 - Skip P0 if P1 less than P2 (numeric interpretation)
X
X 2 - Skip P0 if "P1" equal "P2"
X
X 3 - Skip P0 if "P1" not equal "P2"
X
X 4 - Skip P0 if "P1" starts "P2"
X
X 5 - Push the constructed line onto the user-managed string stack.
X
X 6 - Pop the user-managed string stack into the parameter named by C0.
X
X 7 - Decimal loop. P0 is start and P1 is end.
X
X 8 - String loop. P0 gets scanned and P1 provides break characters.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X
X FILE OPERATIONS:
X
X 0 - Rewind the stream indicated by C0. Rename if line size > 1.
X
X 1 - Copy C0 to C1 looking for constructed line.
X
X 2 - Future output to C0.
X
X 3 - Future input from C0. Revert on EOF if line size > 1.
X
X 4 - Output rest of line to C0 without rescanning.
X
X 5 - Formatted output line to C0.
X
X 6 - Debug dump to C0.
X
X 7 - Status message to C0, priority is C1.
X
X 8 - Read from C0, assign to parameter named by C1.
X
X 9 - RESERVED FOR FUTURE EXPANSION.
X
X
X
X
X
X
X
X
X
X
X
X
X
X Page 16 Printed Tue Aug 14, 1990
X
END_OF_FILE
if test 46006 -ne `wc -c <'LOME/LOME.doc'`; then
echo shar: \"'LOME/LOME.doc'\" unpacked with wrong size!
fi
# end of 'LOME/LOME.doc'
fi
echo shar: End of archive 9 \(of 9\).
cp /dev/null ark9isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 9 archives.
rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
--- Darren New --- Grad Student --- CIS --- Univ. of Delaware ---
exit 0 # Just in case...
--
Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.
Use a domain-based address or give alternate paths, or you may lose out.