home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource5 / 329_01 / regexp.doc < prev    next >
Encoding:
Text File  |  1988-11-13  |  9.5 KB  |  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.  
  68.           REGEXP (3)                 local                  REGEXP (3)
  69.  
  70.  
  71.  
  72.      NAME    
  73.      NAME  
  74.  
  75.  
  76.           regcomp,  regexec,  regsub,  regerror  -  regular expression
  77.           handler 
  78.  
  79.  
  80.      SYNOPSIS    
  81.      SYNOPSIS  
  82.  
  83.  
  84.           #include <regexp.h>
  85.           
  86.           regexp *regcomp(exp)
  87.           char *exp;
  88.           
  89.           int regexec(prog, string)
  90.           regexp *prog;
  91.           char *string;
  92.           
  93.           regsub(prog, source, dest)
  94.           regexp *prog;
  95.           char *source;
  96.           char *dest;
  97.           
  98.           regerror(msg)
  99.           char *msg;
  100.  
  101.  
  102.      DESCRIPTION    
  103.      DESCRIPTION  
  104.  
  105.  
  106.                                           egrep    1  style             
  107.           These   functions   implement   egrep   (1)-style    regular
  108.           expressions and supporting facilities.  
  109.  
  110.  
  111.           Regcomp                                                       
  112.           Regcomp  compiles  a  regular expression into a structure of
  113.                regexp                                                   
  114.           type regexp , and returns a pointer to it.   The  space  has
  115.                                   malloc   3                            
  116.           been  allocated  using  malloc  (3)  and  may be released by
  117.           free     
  118.           free.  
  119.  
  120.  
  121.           Regexec                                string                 
  122.           Regexec  matches  a  NUL-terminated    string  against   the
  123.                                               prog                      
  124.           compiled regular  expression  in    prog.   It returns 1 for
  125.           success and 0 for  failure,  and  adjusts  the  contents  of
  126.           prog s startp and  endp                             
  127.           prog's startp and  endp (see below) accordingly.  
  128.  
  129.  
  130.                                regexp                                   
  131.           The  members  of  a  regexp  structure  include at least the
  132.           following (not necessarily in order): 
  133.  
  134.  
  135.           char *startp[NSUBEXP]; 
  136.           char *endp[NSUBEXP]; 
  137.  
  138.  
  139.                 NSUBEXP                                                  
  140.           where NSUBEXP is defined (as 10) in the header file.  Once a 
  141.                       regexec                            regexp         
  142.           successful  regexec has been done using the    regexp,  each
  143.           startp endp                                          string    
  144.           startp/endp pair describes one substring within the  string, 
  145.                        startp                                           
  146.           with  the    startp  pointing  to the first character of the
  147.                              endp                                       
  148.           substring and the  endp  pointing  to  the  first  character
  149.           following the substring.  The 0th substring is the substring 
  150.                string                                                   
  151.           of   string  that matched the whole regular expression.  The
  152.           others  are  those  substrings  that  matched  parenthesized
  153.           expressions    within    the    regular   expression,   with
  154.           parenthesized expressions numbered in left-to-right order of 
  155.           their opening parentheses.  
  156.  
  157.  
  158.           Regsub copies source to dest, making substitutions according 
  159.  
  160.  
  161.  
  162.                                       -1-
  163.  
  164.  
  165.  
  166.           REGEXP (3)                 local                  REGEXP (3)
  167.  
  168.  
  169.  
  170.           to the most recent  regexec  performed  using  prog.    Each
  171.           instance  of  `&'  in    source is replaced by the substring
  172.           indicated by startp[0] and endp[0].  Each instance  of  `n',
  173.           where  n  is a digit, is replaced by the substring indicated
  174.           by startp[n] and endp[n].  
  175.  
  176.  
  177.           Regerror is called whenever an error is detected in regcomp, 
  178.           regexec, or regsub.  The default regerror writes the  string
  179.           msg,  with  a suitable indicator  of origin, on the standard
  180.                                              Regerror                   
  181.           error output and invokes exit(2).  Regerror can be  replaced
  182.           by the user if other actions are desirable.  
  183.  
  184.  
  185.      REGULAR EXPRESSION SYNTAX    
  186.      REGULAR EXPRESSION SYNTAX  
  187.  
  188.  
  189.           A  regular expression is zero or more branches, separated by
  190.           `|'.  It matches anything that matches one of the branches.  
  191.  
  192.  
  193.           A branch is zero or more pieces, concatenated.  It matches a 
  194.           match for the first, followed by a  match  for  the  second,
  195.           etc.  
  196.  
  197.  
  198.           A  piece  is  an atom possibly followed by `*', `+', or `?'.
  199.           An atom followed by `*' matches a  sequence  of  0  or  more
  200.           matches of  the  atom.    An  atom followed by `+' matches a
  201.           sequence of 1 or more matches of the atom.  An atom followed 
  202.           by `?' matches a match of the atom, or the null string.  
  203.  
  204.  
  205.           An atom is a regular expression in parentheses  (matching  a
  206.           match  for the regular expression), a range (see below), `.'
  207.           (matching any single  character),  `^'  (matching  the  null
  208.           string  at the beginning of the input string), `$' (matching
  209.           the null string at the end  of  the  input  string),  a  `\'
  210.           followed by a single character (matching that character), or 
  211.           a single character with no other significance (matching that 
  212.           character).  
  213.  
  214.  
  215.           A range  is  a  sequence of characters enclosed in `[]'.  It
  216.           normally matches any single character from the sequence.  If 
  217.           the  sequence  begins  with  `^',  it  matches  any   single
  218.           character not  from  the  rest  of  the  sequence.    If two
  219.           characters in the sequence are separated  by  `-',  this  is
  220.           shorthand for the full list of ASCII characters between them 
  221.           (e.g. `[0-9]'  matches  any  decimal  digit).   To include a
  222.           literal `]' in the sequence, make  it  the  first  character
  223.           (following a  possible `^').  To include a literal `-', make
  224.           it the first or last character.  
  225.  
  226.  
  227.      AMBIGUITY    
  228.      AMBIGUITY  
  229.  
  230.  
  231.           If a regular expression could match two different  parts  of
  232.           the  input  string,  it  will  match  the  one  which begins
  233.           earliest.  If  both  begin  in  the  same  place  but  match
  234.           different  lengths,  or  match  the same length in different
  235.           ways, life gets messier, as follows.  
  236.  
  237.  
  238.           In general, the possibilities in  a  list  of  branches  are
  239.           considered  in  left-to-right  order,  the possibilities for
  240.           `*', `+',  and  `?'  are  considered  longest-first,  nested
  241.  
  242.  
  243.  
  244.                                       -2-
  245.  
  246.  
  247.  
  248.           REGEXP (3)                 local                  REGEXP (3)
  249.  
  250.  
  251.  
  252.           constructs   are  considered  from  the  outermost  in,  and
  253.           concatenated constructs are considered leftmost-first.   The
  254.           match  that will be chosen is the one that uses the earliest
  255.           possibility in the first choice that has to  be  made.    If
  256.           there  is more than one choice, the next will be made in the
  257.           same manner (earliest possibility) subject to  the  decision
  258.           on the first choice.  And so forth.  
  259.  
  260.  
  261.           For  example,  `(ab|a)b*c'  could  match `abc' in one of two
  262.           ways.  The first choice is between `ab' and `a'; since  `ab'
  263.           is  earlier, and does lead to a successful overall match, it
  264.           is chosen.  Since the `b' is already spoken  for,  the  `b*'
  265.           must match its last possibility\(emthe empty string\(emsince 
  266.           it must respect the earlier choice.  
  267.  
  268.  
  269.           In  the  particular case where no `|'s are present and there
  270.           is only one `*', `+', or `?', the net  effect  is  that  the
  271.           longest possible  match will be chosen.  So `ab*', presented
  272.           with `xabbbby', will match `abbbb'.  Note that if  `ab*'  is
  273.           tried  against  `xabyabbbz',  it  will match `ab' just after
  274.           `x', due to the  begins-earliest  rule.    (In  effect,  the
  275.           decision  on where to start the match is the first choice to
  276.           be made, hence subsequent choices must respect  it  even  if
  277.           this leads them to less-preferred alternatives.) 
  278.  
  279.  
  280.      SEE    
  281.      SEE  
  282.  
  283.  
  284.           egrep(1), expr(1) 
  285.  
  286.  
  287.      DIAGNOSTICS    
  288.      DIAGNOSTICS  
  289.  
  290.  
  291.           Regcomp  returns  NULL  for a failure (regerror permitting),
  292.           where failures are syntax errors,  exceeding  implementation
  293.           limits, or applying `+' or `*' to a possibly-null operand.  
  294.  
  295.  
  296.      HISTORY    
  297.      HISTORY  
  298.  
  299.  
  300.           Both code  and manual page were written at U of T.  They are
  301.           intended to be compatible with the Bell  V8  regexp(3),  but
  302.           are not derived from Bell code.  
  303.  
  304.  
  305.      BUGS    
  306.      BUGS  
  307.  
  308.  
  309.           Empty   branches  and  empty  regular  expressions  are  not
  310.           portable to V8.  
  311.  
  312.  
  313.           The  restriction  against  applying  `*'   or   `+'   to   a
  314.           possibly-null  operand  is  an  artifact  of  the simplistic
  315.           implementation.  
  316.  
  317.  
  318.           Does not support egrep's newline-separated branches; neither 
  319.           does the V8 regexp(3), though.  
  320.  
  321.  
  322.           Due to emphasis on  compactness  and  simplicity,  it's  not
  323.           strikingly fast.  It does give special attention to handling 
  324.           simple cases quickly.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.                                       -3-
  331.  
  332.  
  333.