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