Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume23/lome/part08

Internet Message Format | 1991-01-08 | 48.1 KB

Path: j.cc.purdue.edu!mentor.cc.purdue.edu!purdue!bu.edu!att!linac!pacific.mps.ohio-state.edu!zaphod.mps.ohio-state.edu!wuarchive!uunet!papaya.bbn.com!rsalz
From: [e-mail] (Rich Salz)
Newsgroups: comp.sources.unix
Subject: v23i058:  Line oriented macro processor, Part08/09
Message-ID: <[e-mail]>
Date: 29 Nov 90 17:44:59 GMT
Organization: BBN Systems and Technologies, Cambridge MA
Lines: 1045
Approved: [e-mail]

Submitted-by: Darren New <[e-mail]>
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 [e-mail] 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 [e-mail].
Use a domain-based address or give alternate paths, or you may lose out.