pre.h

   1 /* Regular expression functions which allocate in the pool.
   2  * By Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: pre.h,v 1.1 2002/10/05 16:42:04 rich Exp $
  19  */
  20
  21 #ifndef PRE_H
  22 #define PRE_H
  23
  24 #include <pcre.h>
  25
  26 #include <pool.h>
  27 #include <vector.h>
  28
  29 /* Function: precomp - Compile, match, substitute regular expressions.
  30  * Function: prematch
  31  * Function: presubst
  32  *
  33  * These functions are wrappers around the Perl Compatible
  34  * Regular Expressions (PCRE) library (see
  35  * @code{http://www.pcre.org/}).
  36  *
  37  * @code{precomp} compiles the regular expression @code{pattern}
  38  * returning a pointer to the opaque @code{pcre} structure. The
  39  * structure is allocated in @code{pool}. The @code{options} argument
  40  * is a list of PCRE options, passed directly to the
  41  * @code{pcre_compile} function (see @ref{pcre(3)}). You
  42  * should normally set @code{options} to 0.
  43  *
  44  * @code{prematch} matches the string @code{str} with the
  45  * compiled regular expression @code{pattern}.
  46  *
  47  * If there is no match, this returns @code{NULL}. If the string
  48  * matches, then this function returns a @code{vector} of @code{char *},
  49  * allocated in @code{pool}.  The first element of this vector is
  50  * the portion of the original string which matched the whole
  51  * pattern. The second and subsequent elements of this vector are
  52  * captured substrings. It is possible in rare circumstances for some
  53  * of these captured substrings to be @code{NULL} (see the
  54  * @ref{pcre(3)} manual page for an example).
  55  *
  56  * The @code{options} argument is passed directly to
  57  * @code{pcre_exec}. You should normally set @code{options} to 0.
  58  *
  59  * @code{presubst} substitutes @code{sub} for @code{pattern}
  60  * wherever @code{pattern} occurs in @code{str}. It is equivalent
  61  * to the @code{str =~ s/pat/sub/} function in Perl.
  62  *
  63  * Placeholders @code{$1}, @code{$2}, etc. in @code{sub} are
  64  * substituted for the matching substrings of @code{pattern}.
  65  * Placeholder substitution can be disabled completely by
  66  * including the @code{PRESUBST_NO_PLACEHOLDERS} flag in @code{options}.
  67  *
  68  * If the @code{PRESUBST_GLOBAL} flag is given, then all
  69  * matches are substituted. Otherwise only the first match
  70  * is substituted.
  71  *
  72  * The @code{options} argument is passed to @code{pcre_exec}
  73  * (after removing the @code{PRESUBST_*} flags).
  74  *
  75  * The return value from @code{presubst} is the string with
  76  * replacements.
  77  *
  78  * See also: @ref{pcre(3)}.
  79  */
  80 pcre *precomp (pool pool, const char *pattern, int options);
  81 vector prematch (pool pool, const char *str, const pcre *pattern, int options);
  82 const char *presubst (pool pool, const char *str, const pcre *pattern, const char *sub, int options);
  83
  84 #define PRESUBST_NO_PLACEHOLDERS 0x10000000
  85 #define PRESUBST_GLOBAL          0x20000000
  86
  87 #endif /* PRE_H */