home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / unix / unixtools / util / regex / doc
Text File  |  1992-07-21  |  5KB  |  124 lines
  1. Regular Expression matching functions.
  2.  
  3. Seven functions are supplied.
  4.  
  5. 1. re_create(buffer,len,translate)
  6.  
  7.    Creates a regular expression buffer, re, of type (REGEX *). 
  8.    The user may supply three (optional) parameters. BUFFER and 
  9.    LEN define a user-supplied (fixed) buffer to hold the compiled 
  10.    regular expression. If this is not supplied, the package 
  11.    automatically allocates a buffer of the required size from the 
  12.    heap. TRANSLATE is a 256-character translation table for 
  13.    characters. If it is supplied, the package treats character c 
  14.    in all cases as if it were translate[c].
  15.  
  16. 2. re_free(re)
  17.  
  18.    Frees all storage associated with the regular expression 
  19.    buffer RE.
  20.  
  21. 3. re_compile(patt,re)
  22.  
  23.    Compiles the pattern string PATT into a regular expression 
  24.    buffer RE. Special characters (defined in the header file 
  25.    H.Chars) are as described below. The return value is 0 if the 
  26.    compile succeeds, or a pointer to an error message if it 
  27.    fails.
  28.  
  29. 4. re_anchored_match(re,str,len,start,mem)
  30.  
  31.    Matches string STR against the regular expression buffer RE. 
  32.    The match starts at position START in STR, and must match 
  33.    starting from there. The value returned is the number of 
  34.    characters matched or RE_FAIL if the match fails, or RE_ERROR 
  35.    if an error occurs. The optional argument LEN is the length of 
  36.    STR, and will be calculated if it is omitted (-1). The optional
  37.    argument MEM is a (REGMEM *) which will be filled with details
  38.    of the matched portions of the string. mem[0] holds the whole
  39.    matched string, and mem[1] to mem[9] hold the values matched 
  40.    by the regular expression memories \1 to \9.
  41.  
  42. 5. re_match(re,str,len,mem)
  43.  
  44.    Matches string STR against the regular expression buffer RE. 
  45.    The match may occur at any position in STR, and the value 
  46.    returned is the position of the start of the match (0 to 
  47.    strlen(str)), or RE_FAIL if the match fails, or RE_ERROR if an 
  48.    error occurs. The optional argument LEN is the length of STR,
  49.    and will be calculated if it is omitted (-1). The optional
  50.    argument MEM is a (REGMEM *) which will be filled with details
  51.    of the matched portions of the string. mem[0] holds the whole
  52.    matched string, and mem[1] to mem[9] hold the values matched by
  53.    the regular expression memories \1 to \9. Note that the only way
  54.    of finding the matched string is via mem[0].
  55.  
  56. 6. re_magic(string)
  57.  
  58.    Tests STRING to see if it has any regular expression operators
  59.    in it. Returns 1 if so, 0 otherwise. Note that brackets ('(' and
  60.    ')' ) are not treated as operators, as they are so common in
  61.    normal strings.
  62.  
  63. 7. re_dump(re)
  64.  
  65.    This is a debugging tool, and prints a formatted listing of the
  66.    regular expression in buffer RE.
  67.  
  68. Special characters.
  69.  
  70. The special characters which can be used in a regular expression 
  71. pattern are as follows:
  72.  
  73. Character expressions (ce's)
  74.  
  75.      ^         Start of a line
  76.      $         End of a line
  77.      \`        Start of the string
  78.      \'        End of the string
  79.      \<        Start of a word
  80.      \>        End of a word
  81.      \@        A word boundary
  82.      .         Any character
  83.      \w        A word character
  84.      [...]     A set of characters.
  85.      \c        Where `c' is a special character. Matches c.
  86.      c         Where `c' is any non-special character. Matches itself.
  87.  
  88. Operators
  89.  
  90.      ~         Not. `~ce' matches anything but ce.
  91.      |         Or. `re1 | re2' matches either re1 or re2.
  92.      *         Repeat. `re*' matches re repeated 0 or more times.
  93.      +         Many. `re+' matches re repeated 1 or more times.
  94.      ?         Optional. `re?' matches re or nothing.
  95.      (...)     Bracketing. `(re)' matches the same as re.
  96.  
  97. Memory.
  98.  
  99.      \{        Start memory.
  100.      \}        End memory.
  101.      \n        Match the characters in memory 'n' (n is 1-9).
  102.  
  103.    The operators \{...\} do not affect matching, but the
  104.    characters matched by the expression between the n'th \{ and
  105.    its corresponding \} are saved in memory n, for use in \n 
  106.    matches, and to return in the MEM array.
  107.  
  108. Words.
  109.  
  110.    Word characters are numbers and letters (ie. \w is the same as 
  111.    the expression [a-zA-Z0-9]). A word boundary is the position 
  112.    between a word character and a non-word character (in either 
  113.    order).
  114.  
  115. Character sets.
  116.  
  117.    Within sets, [...], all characters are taken literally, except \, 
  118.    ], and -. The '-' character indicates a range, unless it is the 
  119.    first or last character, when it indicates a literal '-'. The '\' 
  120.    character causes the following character to be taken literally 
  121.    (as in \-, \\, \]). In addition the normal C escape sequences \b, 
  122.    \f, \n, \r, \t, \v are available.
  123.  
  124.