home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 329_01 / regexp.doc < prev    next >
Text File  |  1988-11-12  |  10KB  |  264 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.           REGEXP (3)                 local                  REGEXP (3)
  68.  
  69.  
  70.      NAME         NAME  
  71.  
  72.           regcomp,  regexec,  regsub,  regerror  -  regular expression
  73.           handler 
  74.  
  75.      SYNOPSIS         SYNOPSIS  
  76.  
  77.           #include <regexp.h>
  78.           
  79.           regexp *regcomp(exp)
  80.           char *exp;
  81.           
  82.           int regexec(prog, string)
  83.           regexp *prog;
  84.           char *string;
  85.           
  86.           regsub(prog, source, dest)
  87.           regexp *prog;
  88.           char *source;
  89.           char *dest;
  90.           
  91.           regerror(msg)
  92.           char *msg;
  93.  
  94.      DESCRIPTION         DESCRIPTION  
  95.  
  96.                                           egrep    1  style                       These   functions   implement   egrep   (1)-style    regular
  97.           expressions and supporting facilities.  
  98.  
  99.           Regcomp                                                                 Regcomp  compiles  a  regular expression into a structure of
  100.                regexp                                                             type regexp , and returns a pointer to it.   The  space  has
  101.                                   malloc   3                                      been  allocated  using  malloc  (3)  and  may be released by
  102.           free               free.  
  103.  
  104.           Regexec                                string                           Regexec  matches  a  NUL-terminated    string  against   the
  105.                                               prog                                compiled regular  expression  in    prog.   It returns 1 for
  106.           success and 0 for  failure,  and  adjusts  the  contents  of
  107.           prog s startp and  endp                                       prog's startp and  endp (see below) accordingly.  
  108.  
  109.                                regexp                                             The  members  of  a  regexp  structure  include at least the
  110.           following (not necessarily in order): 
  111.  
  112.           char *startp[NSUBEXP]; 
  113.           char *endp[NSUBEXP]; 
  114.  
  115.                 NSUBEXP                                                            where NSUBEXP is defined (as 10) in the header file.  Once a 
  116.                       regexec                            regexp                   successful  regexec has been done using the    regexp,  each
  117.           startp endp                                          string              startp/endp pair describes one substring within the  string, 
  118.                        startp                                                     with  the    startp  pointing  to the first character of the
  119.                              endp                                                 substring and the  endp  pointing  to  the  first  character
  120.           following the substring.  The 0th substring is the substring 
  121.                string                                                             of   string  that matched the whole regular expression.  The
  122.           others  are  those  substrings  that  matched  parenthesized
  123.           expressions    within    the    regular   expression,   with
  124.           parenthesized expressions numbered in left-to-right order of 
  125.           their opening parentheses.  
  126.  
  127.           Regsub copies source to dest, making substitutions according 
  128.  
  129.  
  130.                                       -1-
  131.  
  132.  
  133.           REGEXP (3)                 local                  REGEXP (3)
  134.  
  135.  
  136.           to the most recent  regexec  performed  using  prog.    Each
  137.           instance  of  `&'  in    source is replaced by the substring
  138.           indicated by startp[0] and endp[0].  Each instance  of  `n',
  139.           where  n  is a digit, is replaced by the substring indicated
  140.           by startp[n] and endp[n].  
  141.  
  142.           Regerror is called whenever an error is detected in regcomp, 
  143.           regexec, or regsub.  The default regerror writes the  string
  144.           msg,  with  a suitable indicator  of origin, on the standard
  145.                                              Regerror                             error output and invokes exit(2).  Regerror can be  replaced
  146.           by the user if other actions are desirable.  
  147.  
  148.      REGULAR EXPRESSION SYNTAX         REGULAR EXPRESSION SYNTAX  
  149.  
  150.           A  regular expression is zero or more branches, separated by
  151.           `|'.  It matches anything that matches one of the branches.  
  152.  
  153.           A branch is zero or more pieces, concatenated.  It matches a 
  154.           match for the first, followed by a  match  for  the  second,
  155.           etc.  
  156.  
  157.           A  piece  is  an atom possibly followed by `*', `+', or `?'.
  158.           An atom followed by `*' matches a  sequence  of  0  or  more
  159.           matches of  the  atom.    An  atom followed by `+' matches a
  160.           sequence of 1 or more matches of the atom.  An atom followed 
  161.           by `?' matches a match of the atom, or the null string.  
  162.  
  163.           An atom is a regular expression in parentheses  (matching  a
  164.           match  for the regular expression), a range (see below), `.'
  165.           (matching any single  character),  `^'  (matching  the  null
  166.           string  at the beginning of the input string), `$' (matching
  167.           the null string at the end  of  the  input  string),  a  `\'
  168.           followed by a single character (matching that character), or 
  169.           a single character with no other significance (matching that 
  170.           character).  
  171.  
  172.           A range  is  a  sequence of characters enclosed in `[]'.  It
  173.           normally matches any single character from the sequence.  If 
  174.           the  sequence  begins  with  `^',  it  matches  any   single
  175.           character not  from  the  rest  of  the  sequence.    If two
  176.           characters in the sequence are separated  by  `-',  this  is
  177.           shorthand for the full list of ASCII characters between them 
  178.           (e.g. `[0-9]'  matches  any  decimal  digit).   To include a
  179.           literal `]' in the sequence, make  it  the  first  character
  180.           (following a  possible `^').  To include a literal `-', make
  181.           it the first or last character.  
  182.  
  183.      AMBIGUITY         AMBIGUITY  
  184.  
  185.           If a regular expression could match two different  parts  of
  186.           the  input  string,  it  will  match  the  one  which begins
  187.           earliest.  If  both  begin  in  the  same  place  but  match
  188.           different  lengths,  or  match  the same length in different
  189.           ways, life gets messier, as follows.  
  190.  
  191.           In general, the possibilities in  a  list  of  branches  are
  192.           considered  in  left-to-right  order,  the possibilities for
  193.           `*', `+',  and  `?'  are  considered  longest-first,  nested
  194.  
  195.  
  196.                                       -2-
  197.  
  198.  
  199.           REGEXP (3)                 local                  REGEXP (3)
  200.  
  201.  
  202.           constructs   are  considered  from  the  outermost  in,  and
  203.           concatenated constructs are considered leftmost-first.   The
  204.           match  that will be chosen is the one that uses the earliest
  205.           possibility in the first choice that has to  be  made.    If
  206.           there  is more than one choice, the next will be made in the
  207.           same manner (earliest possibility) subject to  the  decision
  208.           on the first choice.  And so forth.  
  209.  
  210.           For  example,  `(ab|a)b*c'  could  match `abc' in one of two
  211.           ways.  The first choice is between `ab' and `a'; since  `ab'
  212.           is  earlier, and does lead to a successful overall match, it
  213.           is chosen.  Since the `b' is already spoken  for,  the  `b*'
  214.           must match its last possibility\(emthe empty string\(emsince 
  215.           it must respect the earlier choice.  
  216.  
  217.           In  the  particular case where no `|'s are present and there
  218.           is only one `*', `+', or `?', the net  effect  is  that  the
  219.           longest possible  match will be chosen.  So `ab*', presented
  220.           with `xabbbby', will match `abbbb'.  Note that if  `ab*'  is
  221.           tried  against  `xabyabbbz',  it  will match `ab' just after
  222.           `x', due to the  begins-earliest  rule.    (In  effect,  the
  223.           decision  on where to start the match is the first choice to
  224.           be made, hence subsequent choices must respect  it  even  if
  225.           this leads them to less-preferred alternatives.) 
  226.  
  227.      SEE         SEE  
  228.  
  229.           egrep(1), expr(1) 
  230.  
  231.      DIAGNOSTICS         DIAGNOSTICS  
  232.  
  233.           Regcomp  returns  NULL  for a failure (regerror permitting),
  234.           where failures are syntax errors,  exceeding  implementation
  235.           limits, or applying `+' or `*' to a possibly-null operand.  
  236.  
  237.      HISTORY         HISTORY  
  238.  
  239.           Both code  and manual page were written at U of T.  They are
  240.           intended to be compatible with the Bell  V8  regexp(3),  but
  241.           are not derived from Bell code.  
  242.  
  243.      BUGS         BUGS  
  244.  
  245.           Empty   branches  and  empty  regular  expressions  are  not
  246.           portable to V8.  
  247.  
  248.           The  restriction  against  applying  `*'   or   `+'   to   a
  249.           possibly-null  operand  is  an  artifact  of  the simplistic
  250.           implementation.  
  251.  
  252.           Does not support egrep's newline-separated branches; neither 
  253.           does the V8 regexp(3), though.  
  254.  
  255.           Due to emphasis on  compactness  and  simplicity,  it's  not
  256.           strikingly fast.  It does give special attention to handling 
  257.           simple cases quickly.  
  258.  
  259.  
  260.  
  261.  
  262.                                       -3-
  263.  
  264.