home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 192_01 / sgrep.doc < prev    next >
Text File  |  1979-12-31  |  9KB  |  212 lines
  1.  
  2.     SGREP is a modification of the public domain
  3. version of the Unix utility GREP, PC Sig #149 or CUG 152.
  4. The following additions were made:
  5.  
  6.     1) string substitution capability,
  7.     2) multiple pattern search,
  8.     3) distinction between upper and lower case,
  9.     4) scanning options to extend capability and speed-up processing.
  10.  
  11. All Grep options are retained except multiple files.
  12.  
  13.     The command line for Sgrep is similar to that
  14. for Grep but with the pattern replaced by the name of the
  15. pattern file. For output to the screen the command line is
  16.  
  17.     sgrep [-y] pattern_file input_file
  18.  
  19. and for output to disk,
  20.  
  21.     sgrep [-y] pattern_file input_file > output_file
  22.  
  23. The y-option removes the distinction between upper and lower case
  24. when matching patterns.
  25.  
  26.     Also included is a peprocessor using Sgrep which translates
  27. from a Basic - Fortran like language into C. Several programs are
  28. included in this "BC" language, which may also contain C statements.
  29. The pattern file, pf.bc, for this preprocessor language illustrates
  30. the use of Sgrep.
  31.  
  32.     This disk contains the following files:
  33.  
  34.     summary.doc
  35.     sgrep.doc
  36.     sgrep.c        pattern matching and substitution utility
  37.     sgrep.exe
  38.     pf.bc        BC to C translator
  39.     progs.bc    programs in BC
  40.     progs.c        programs translated into C by Sgrep
  41.     bc.h        small header file
  42.     bc.bat        batch file to translate and compile
  43.  
  44.     Information on the construction of patterns is contained
  45. in the help file which is displayed on typing "sgrep ?". The contents
  46. of the help file is:
  47.  
  48.                  *     *     *     *
  49.  
  50. Sgrep searches a file for a given pattern and substitutes a pattern.
  51. If no substitution is required, the command sgrep -myn corresponds
  52. to grep -n and will match only. Output is to the screen and may be
  53. re-directed using ">" at the DOS level. Execute by
  54.   sgrep [flags] pattern-file input-file
  55.  
  56. Flags are single characters preceeded by '-':
  57.    -c      Only a count of matching lines is printed.
  58.    -m      Match patterns only. No substitutions.
  59.    -n      Each line is preceeded by its line number.
  60.    -v      Only print non-matching lines.
  61.    -y      Upper and lower case match.
  62.  
  63. Each match pattern is on a separate line followed by its substitute
  64. pattern, if any, also on a separate line.
  65.  MATCH PATTERNS
  66. The regular_expression defines the pattern to search for.  Upper and
  67. lower-case are regarded as different unless -y option is used.
  68. x      An ordinary character (not mentioned below) matches that character.
  69. '\'    The backslash quotes any character.  "\$" matches a dollar-sign.
  70. '$'    Matches beginning or end of line.
  71. '.'    A period matches any character except "new-line".
  72. ':a'   A colon matches a class of characters described by the following
  73. ':d'     character.  ":a" matches any alphabetic, ":d" matches digits,
  74. ':n'     ":n" matches alphanumerics, ": " matches spaces, tabs, and
  75. ': '     other control characters except new-line.
  76. '*'    An expression followed by an asterisk matches zero or more
  77.        occurrances of that expression: "fo*" matches "f", "fo"
  78.        "foo", etc.
  79. '+'    An expression followed by a plus sign matches one or more
  80.        occurrances of that expression: "fo+" matches "fo", etc.
  81. '-'    An expression followed by a minus sign optionally matches
  82.        the expression.
  83. '[]'   A string enclosed in square brackets matches any character in
  84.        that string, but no others.  If the first character in the
  85.        string is a circumflex, the expression matches any character
  86.        except "new-line" and the characters in the string.  For
  87.        example, "[xyz]" matches "xx" and "zyx", while "[^xyz]"
  88.        matches "abc" but not "axb".  A range of characters may be
  89.        specified by two characters separated by "-".  Note that,
  90.        [a-z] matches alphabetics, while [z-a] never matches.
  91. The concatenation of regular expressions is a regular expression.
  92.  Scanning options:
  93. The default scanning option is match all occurences of the pattern.
  94. '@'    at the beginning of the pattern, is equivalent to
  95.        "$: *", meaning match first non-whitespace pattern.
  96. '@e'   at the end of a pattern means that if a match is
  97.        found (and a substitution made), end all pattern search
  98.        on current line.
  99. '@r'   at the end of a pattern means that after a match
  100.        (and substitution), rescan line until no match occurs.
  101.  SUBSTITUTE PATTERNS 
  102. The only control character for substitute patterns is "?".
  103. Any other character represents itself. Only the characters ? and
  104.  \ itself need to be quoted.
  105. '?n'   where n is a non-zero digit, indicates the position where
  106.        the nth wildcard string is to be placed.
  107. A wildcard string is any string which is not completely fixed,
  108. both as to the characters and number of characters in the string.
  109.  
  110.                  *     *     *     *
  111.  
  112.     The options n, c and v are carried over from Grep and can be
  113. used only with the m (match only) option. The added y option applies
  114. to both match only and substitution.
  115.  
  116.     A substituiton file consists of 2N records, where N is the
  117. number of substitutions. The file contains N pattern pairs, each
  118. pair consisting of a match pattern followed by its substitute pattern.
  119. A match only file contains N records.
  120.  
  121.     The control characters for constructing match patterns, listed
  122.  above, are the same as those for Grep with a few changes and addtions:
  123.  
  124.     1) The beginning of line symbol "^", which also represents the
  125. complement or NCLASS operator, has been replaced by "$, now used
  126. for both beginning and end of line. When "$" is the first character in
  127. the pattern, it is a beginning of line, otherwise, it is an end of line.
  128.     2) The expressions ".", "[^x]" and ": " do not match newline (linefeed).
  129.     3) The scan options described above have been added. The @ and @e
  130. options speed-up processing. The @r option allows certain repetitve
  131. operations. For example, the standard array index designation
  132.   A[I,J,K] is changed to the C form A[I][J][K] by the pattern pair
  133.  
  134.     \[:n+,@r
  135.     [?1][
  136.  
  137. This will handle arrays of any number of dimensions. The @r scan option
  138. is also used to insert the & before each item in a list of input variables.
  139.  
  140.  
  141.     The file pf.bc is the pattern file for the BC to C translator
  142. and illustrates the use of Sgrep. The file progs.bc contains programs
  143. in the BC language with C translations in progs.c. Translation
  144. from the BC language into C is line for line to simplify
  145. error detection. While some of the substitutions could be accomplished
  146. with #define macros placed in the bc.h file, the target language would
  147. not then be standard C.
  148.  
  149.     The BC language has the following properties:
  150.  
  151.     1) Each program must begin with the line GLOBAL even if there
  152. are no global declarations.
  153.  
  154.     2) Generally, each condition or statement occupies a separate
  155. line but multiple declaration and assignment statements are possible,
  156.  
  157.     REAL A; INTEGER N
  158.     I=1; J=2; K=3
  159.  
  160.     3) No semicolons are required at the end of lines.
  161.  
  162.     4) Only lines whose first non-whitespace character is a capital
  163. letter will be processed. Other lines are copied without change. This
  164. allows C statements to be included anywhere provided the first character
  165. in the line is not a capital letter.
  166.  
  167.     5) Comments are usually on a separate line but a comment may
  168. follow a statement terminated by a semicolon,
  169.  
  170.         A = B + C;  /* Comment* /
  171.  
  172.     6) All conditions and loops must have a terminal statement,
  173.  
  174.         IF ...
  175.         ENDIF
  176.         WHILE ...
  177.         ENDWH
  178.         FOR I ...
  179.         NEXT I
  180.         etc.
  181.  
  182. The FOR statement is terminated with NEXT rather than END to increase
  183. readability.
  184.  
  185.     7) The & is inserted before variables in an input statement but
  186. a string variable must be preceded by *,
  187.  
  188.         INPUT #1, "%d %s", A, *S
  189.  
  190.     8) The file unit #n becomes file pointer fpn when used in C functions.
  191.     9) The switch ... case construction, although fairly common, has
  192. been omitted because IF ... ELSE IF ... ELSE ... ENDIF is more general
  193. and because the constructions switch, structure, typedef, #include, etc.
  194. can be included in C.
  195.  
  196.  
  197.  
  198.     This program, SGREP, is a modification of the public domain
  199. version of the Unix utility GREP, PC Sig #149 or CUG 152. The following
  200. additions were made:
  201.  
  202.     1) string substitution capability
  203.     2) multiple pattern search
  204.     3) distinction between upper and lower case
  205.     4) scanning options to extend capability and speed-up processing.
  206.  
  207.     Also included is a peprocessor using Sgrep which translates
  208. from a Basic - Fortran like language into C. Several programs are
  209. included in this "BC" language, which may also contain C statements.
  210.  
  211.                     James J. McKeon
  212.