home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / libs / regexlib.lzh / REGEXPLIB / REGEXP.DOC < prev    next >
Encoding:
Text File  |  1991-08-15  |  8.0 KB  |  216 lines
  1.                 Documentation for regexp.library
  2.                            version 1.0
  3.                           January 1991
  4.                          Stephen Moehle
  5.                            BIX: stephe
  6.                     USENET: sjm@well.sf.ca.us
  7.  
  8.  
  9.  
  10.                            COPYRIGHT 
  11.  
  12.      Copyright (c) Stephen Moehle 1991
  13.  
  14.      I retain my full copyright on this library.  It may be
  15. used for any purpose and is freely distributable.
  16.  
  17.  
  18.  
  19.                             OVERVIEW
  20.  
  21.      regexp.library provides UN*X style regular expression
  22. pattern matching for both general programs and ARexx programs.
  23. The regular expression code comes from bawk, a public domain awk
  24. clone.  The regular expressions available are largely but not
  25. exactly compatible with those found in UN*X programs such as
  26. grep, ex, awk, etc.  The following is a description of the
  27. regular expressions:
  28.  
  29.         x   An ordinary character (not mentioned below)
  30.             matches that character.
  31.         '\' The backslash quotes any character.
  32.             "\$" matches a dollar-sign.
  33.         '^' A circumflex at the beginning of an expression
  34.             matches the beginning of a line.
  35.         '$' A dollar-sign at the end of an expression
  36.             matches the end of a line.
  37.         '.' A period matches any single character except
  38.             newline.
  39.         ':x'    A colon matches a class of characters described
  40.             by the character following it:
  41.         ':a'    ":a" matches any alphabetic;
  42.         ':d'    ":d" matches digits;
  43.         ':n'    ":n" matches alphanumerics;
  44.         ': '    ": " matches spaces, tabs, and other control
  45.             characters, such as newline.
  46.         '*' An expression followed by an asterisk matches
  47.             zero or more occurrences of that expression:
  48.             "fo*" matches "f", "fo", "foo", "fooo", etc.
  49.         '+' An expression followed by a plus sign matches
  50.             one or more occurrences of that expression:
  51.             "fo+" matches "fo", "foo", "fooo", etc.
  52.         '-' An expression followed by a minus sign
  53.             optionally matches the expression.
  54.         '[]'    A string enclosed in square brackets matches
  55.             any single character in that string, but no
  56.             others.  If the first character in the string
  57.             is a circumflex, the expression matches any
  58.             character except newline and the characters in
  59.             the string.  For example, "[xyz]" matches "xx"
  60.             and "zyx", while "[^xyz]" matches "abc" but not
  61.             "axb".  A range of characters may be specified
  62.             by two characters separated by "-".  Note that,
  63.             [a-z] matches alphabetics, while [z-a] never
  64.             matches.
  65.  
  66.  
  67.  
  68.                               AREXX
  69.  
  70.      The ARexx part of the library consists of 5 functions
  71. available from any ARexx program.  Before this library can be
  72. used, however, it must be added to ARexx's list of function
  73. libraries which can be done by either using the ADDLIB function
  74. from within ARexx or using the external rxlib program.  This
  75. library has an offset of -30.  One caveat to keep in mind when
  76. using these functions is that regular expressions should be no
  77. longer than 200 bytes.  Otherwise some internal buffers might be
  78. blown, leading to a sure guru.  The functions available are:
  79.  
  80. REINDEX()
  81.  
  82.      Usage: REINDEX(string, pattern, [{'F' | 'L'}])
  83.      Searches <string> for the first or last occurrence of
  84.      the regular expression <pattern>.  First or last is
  85.      determined by whether the third argument is 'F' or 'L'. 
  86.      First is the default.  The returned value is the index
  87.      of the matched pattern, 0 if the pattern was not found,
  88.      or -1 if pattern was an illegal regular expression.
  89.      Examples:
  90.  
  91.           say reindex("abcdefg", "d.*g")          ==> 4
  92.           say reindex("abcdefg", "e.*c")          ==> 0
  93.           say reindex("abcdefg", "a[b")           ==> -1
  94.  
  95. REDELSTR()
  96.  
  97.      Usage: REDELSTR(string, pattern, [{'F' | 'L'}])
  98.      Deletes the first or last substring of <string> that
  99.      matches the regular expression <pattern>.  First or
  100.      last is determined by whether the third argument is 'F'
  101.      or 'L'.  First is the default.  If no matching
  102.      substring was found or <pattern> contains an illegal
  103.      regular expression, <string> is returned unchanged.
  104.      Examples:
  105.  
  106.           say redelstr("abcdefg", "b[cd]+e")      ==> afg
  107.           say redelstr("abcdefg", "bz+c")         ==> abcdefg
  108.  
  109. RESUBSTR()
  110.  
  111.      Usage: RESUBSTR(string, pattern, [{'F' | 'L'}])
  112.      Returns the first or last substring of <string> that
  113.      matches the regular expression pattern.  First or last
  114.      is determined by whether the third argument is 'F' or
  115.      'L'.  First is the default.  If no matching substring
  116.      was found or <pattern> contains an illegal regular
  117.      expression, an empty string is returned.
  118.      Examples:
  119.  
  120.           say resubstr("abcdefg", "b[cd]*e")      ==> bcde
  121.           say resubstr("abcdefg", "a[b")          ==>
  122.  
  123. RECOMPILE()
  124.  
  125.      Usage: RECOMPILE(pattern)
  126.      Compiles the regular expression <pattern> into the form
  127.      needed by the REMATCH function.  Returns the compiled
  128.      string or an empty string if <pattern> contained an
  129.      illegal regular expression.
  130.      Example:
  131.  
  132.           patbuf = recompile("ab.*f")
  133.  
  134. REMATCH()
  135.  
  136.      Usage: REMATCH(string, patbuf)
  137.      Searches <string> for the compiled regular expression
  138.      <patbuf>.  Returns 0 is a match was found, -1 if not,
  139.      and -2 if <patbuf> is an empty string or invalid.  If
  140.      multiple searches are to be made using the same regular
  141.      expression, this function could be potentially much
  142.      faster than REINDEX since REINDEX has to do the
  143.      equivalent of RECOMPILE each time it is called.
  144.      Example:
  145.  
  146.           patbuf = recompile("c.*f")
  147.           say rematch("abcdefg", patbuf)          ==> 0
  148.  
  149.  
  150.  
  151.  
  152.                            C LANGUAGE
  153.  
  154.      The regular expression routines are easily called from
  155. Lattice or SAS/C.  All that is needed is to OpenLibrary
  156. regexp.library and assign the result to RegExpBase.  The header
  157. file regexp.h contains the prototypes and the pragmas for
  158. performing inline calls for the two provided functions and also
  159. an extern declaration for RegExpBase.  I have made RegExpBase a
  160. void *, but you can easily make it a struct Library *.  I have
  161. included the fd file so that interfaces for other compilers and
  162. languages can be created.  The functions provided are:
  163.  
  164. NAME
  165.      RegExpCompile
  166.  
  167. SYNOPSIS
  168.      #include "regexp.h"
  169.  
  170.      success = RegExpCompile(pattern, patbuf)
  171.  
  172.      int success;        success or error code
  173.      char *pattern;      regular expression to be compiled
  174.      char *patbuf;       buffer in which compiled expression is
  175.                          to be place
  176.  
  177. DESCRIPTION
  178.      Compiles the regular expression <pattern> and places the
  179.      result in <patbuf>.  It is the programmer's responsibility
  180.      to ensure that <patbuf> is large enough to hold the compiled
  181.      expression.  No checking is done for overflow of the buffer.
  182.  
  183. RETURNS
  184.      Returns 0 if successful or a negative error code.  See the
  185.      enum errs in regexp.h for valid error codes.
  186.  
  187.  
  188. NAME
  189.      RegExpMatch
  190.  
  191. SYNOPSIS
  192.      #include "regexp.h"
  193.  
  194.      success = RegExpMatch(text, patbuf, index, length, flags)
  195.  
  196.      int success;
  197.      char *text;         text to search
  198.      char *patbuf;       a compiled regular expression
  199.      int  *index;        set to offset in <text> of match
  200.      int  *length;       set to length of match in <text>
  201.      int  flags;         FIRST_MATCH or LAST_MATCH
  202.  
  203. DESCRIPTION
  204.      Searches <text> for a match of the compiled regular
  205.      expression <patbuf>.  RegExpCompile() must be used to create
  206.      <patbuf>.  If a match is found, <index> is set to the 0
  207.      based offset into <text> of the beginning of the match, and
  208.      <length> is set to the length of the span of matching
  209.      characters.  The parameter <flags> controls whether the
  210.      first of last match in <text> is taken.  The values
  211.      FIRST_MATCH and LAST_MATCH are defined in regexp.h.
  212.  
  213. RETURNS
  214.      Returns 0 if successful, -1 if no match found, and -2 if
  215.      <patbuf> contains an invalid compiled regular expression.
  216.