ap_regex.h revision 02ecd1528d77cb0870cc9fb23407d6eb1e688885
842ae4bd224140319ae7feec1872b93dfd491143fielding/* Licensed to the Apache Software Foundation (ASF) under one or more
842ae4bd224140319ae7feec1872b93dfd491143fielding * contributor license agreements. See the NOTICE file distributed with
842ae4bd224140319ae7feec1872b93dfd491143fielding * this work for additional information regarding copyright ownership.
842ae4bd224140319ae7feec1872b93dfd491143fielding * The ASF licenses this file to You under the Apache License, Version 2.0
842ae4bd224140319ae7feec1872b93dfd491143fielding * (the "License"); you may not use this file except in compliance with
842ae4bd224140319ae7feec1872b93dfd491143fielding * the License. You may obtain a copy of the License at
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * Unless required by applicable law or agreed to in writing, software
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * distributed under the License is distributed on an "AS IS" BASIS,
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * See the License for the specific language governing permissions and
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * limitations under the License.
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh/* Derived from PCRE's pcreposix.h.
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh Copyright (c) 1997-2004 University of Cambridge
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding-----------------------------------------------------------------------------
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRedistribution and use in source and binary forms, with or without
1b21d7b3d97def358b2e923655edeb16613a1c31gsteinmodification, are permitted provided that the following conditions are met:
1b21d7b3d97def358b2e923655edeb16613a1c31gstein * Redistributions of source code must retain the above copyright notice,
1b21d7b3d97def358b2e923655edeb16613a1c31gstein this list of conditions and the following disclaimer.
1b21d7b3d97def358b2e923655edeb16613a1c31gstein * Redistributions in binary form must reproduce the above copyright
1b21d7b3d97def358b2e923655edeb16613a1c31gstein notice, this list of conditions and the following disclaimer in the
2d71630471d1c23f0137309e3c3957c633ecbfd6rbb documentation and/or other materials provided with the distribution.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * Neither the name of the University of Cambridge nor the names of its
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding contributors may be used to endorse or promote products derived from
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding this software without specific prior written permission.
51af95bb51b5084e883bad250b2afa2838e9ceebfieldingTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
d4f1d9c1ff112a8ab9bee31f196973761329b236rbbAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
7fae9cc4639013f3c04c085547256c68814aee8ftrawickIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
7fae9cc4639013f3c04c085547256c68814aee8ftrawickARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
7fae9cc4639013f3c04c085547256c68814aee8ftrawickLIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
7fae9cc4639013f3c04c085547256c68814aee8ftrawickCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
7184de27ec1d62a83c41cdeac0953ca9fd661e8csfSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
7184de27ec1d62a83c41cdeac0953ca9fd661e8csfINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
7184de27ec1d62a83c41cdeac0953ca9fd661e8csfCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36ef8f77bffe75d1aa327882be1b5bdbe2ff567asfARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingPOSSIBILITY OF SUCH DAMAGE.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding-----------------------------------------------------------------------------
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @brief Apache Regex defines
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* Allow for C++ users */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingextern "C" {
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* Options for ap_regcomp, ap_regexec, and ap_rxplus versions: */
785be1b6298010956622771c870ab3cd8ca57a2faaron#define AP_REG_ICASE 0x01 /** use a case-insensitive match */
785be1b6298010956622771c870ab3cd8ca57a2faaron#define AP_REG_NEWLINE 0x02 /** don't match newlines against '.' etc */
785be1b6298010956622771c870ab3cd8ca57a2faaron#define AP_REG_NOTBOL 0x04 /** ^ will not match against start-of-string */
785be1b6298010956622771c870ab3cd8ca57a2faaron#define AP_REG_NOTEOL 0x08 /** $ will not match against end-of-string */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding#define AP_REG_MULTI 0x10 /* perl's /g (needs fixing) */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* Error values: */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* The structure representing a compiled regular expression. */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingtypedef struct {
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* The structure in which a captured offset is returned. */
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingtypedef struct {
e08076ca56e6cb68b30846b9e9339061058aae6dpoirier/* The functions */
e08076ca56e6cb68b30846b9e9339061058aae6dpoirier * Compile a regular expression.
e08076ca56e6cb68b30846b9e9339061058aae6dpoirier * @param preg Returned compiled regex
e08076ca56e6cb68b30846b9e9339061058aae6dpoirier * @param regex The regular expression string
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param cflags Bitwise OR of AP_REG_* flags (ICASE and NEWLINE supported,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * other flags are ignored)
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @return Zero on success or non-zero on error
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAP_DECLARE(int) ap_regcomp(ap_regex_t *preg, const char *regex, int cflags);
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * Match a NUL-terminated string against a pre-compiled regex.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param preg The pre-compiled regex
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param string The string to match
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param nmatch Provide information regarding the location of any matches
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param pmatch Provide information regarding the location of any matches
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param eflags Bitwise OR of AP_REG_* flags (NOTBOL and NOTEOL supported,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * other flags are ignored)
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @return 0 for successful match, \p AP_REG_NOMATCH otherwise
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAP_DECLARE(int) ap_regexec(const ap_regex_t *preg, const char *string,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding apr_size_t nmatch, ap_regmatch_t *pmatch, int eflags);
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * Match a string with given length against a pre-compiled regex. The string
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * does not need to be NUL-terminated.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param preg The pre-compiled regex
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param buff The string to match
45acd673a68181802b112e97e84fa3813ddd3ec1stoddard * @param len Length of the string to match
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param nmatch Provide information regarding the location of any matches
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param pmatch Provide information regarding the location of any matches
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param eflags Bitwise OR of AP_REG_* flags (NOTBOL and NOTEOL supported,
e08076ca56e6cb68b30846b9e9339061058aae6dpoirier * other flags are ignored)
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @return 0 for successful match, AP_REG_NOMATCH otherwise
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAP_DECLARE(int) ap_regexec_len(const ap_regex_t *preg, const char *buff,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * Return the error code returned by regcomp or regexec into error messages
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param errcode the error code returned by regexec or regcomp
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param preg The precompiled regex
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm * @param errbuf A buffer to store the error in
e8f95a682820a599fe41b22977010636be5c2717jim * @param errbuf_size The size of the buffer
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAP_DECLARE(apr_size_t) ap_regerror(int errcode, const ap_regex_t *preg,
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick/** Destroy a pre-compiled regex.
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param preg The pre-compiled regex to free.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding/* ap_rxplus: higher-level regexps */
785be1b6298010956622771c870ab3cd8ca57a2faarontypedef struct {
3c290fd0361d6d9d84d97725eaf299456bddd6cfsf const char *subs;
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick const char *match;
e160b861b50a3a8dcc013b8cd3ef849fe777e52fgregames * Compile a pattern into a regexp.
e160b861b50a3a8dcc013b8cd3ef849fe777e52fgregames * supports perl-like formats
e160b861b50a3a8dcc013b8cd3ef849fe777e52fgregames * match-string
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * Intended to support more perl-like stuff as and when round tuits happen
560f6ac786d611b858b2bad932713d9e971f0716trawick * match-string is anything supported by ap_regcomp
560f6ac786d611b858b2bad932713d9e971f0716trawick * replacement-string is a substitution string as supported in ap_pregsub
560f6ac786d611b858b2bad932713d9e971f0716trawick * flags should correspond with perl syntax: treat failure to do so as a bug
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * (documentation TBD)
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param pool Pool to allocate from
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param pattern Pattern to compile
7bf77d70b6830636bc36e6b76a228c301be23ff7brianp * @return Compiled regexp, or NULL in case of compile/syntax error
7bf77d70b6830636bc36e6b76a228c301be23ff7brianpAP_DECLARE(ap_rxplus_t*) ap_rxplus_compile(apr_pool_t *pool, const char *pattern);
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * Apply a regexp operation to a string.
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param pool Pool to allocate from
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param rx The regex match to apply
6b38fca3ec543a0f72efd5683e91a0b30fc752d1trawick * @param pattern The string to apply it to
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * NOTE: This MUST be kept in scope to use regexp memory
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @param newpattern The modified string (ignored if the operation doesn't
7697b1b7376a532163c621e050b70c90dcb15d66covener * modify the string)
7c6f514f2ef9b98f58b8f8a5f534eb78a75f29f2jorton * @return Number of times a match happens. Normally 0 (no match) or 1
de00ec7378227d05be63ecd2053ebbb01b940023jorton * (match found), but may be greater if a transforming pattern
7c6f514f2ef9b98f58b8f8a5f534eb78a75f29f2jorton * is applied with the 'g' flag.
de00ec7378227d05be63ecd2053ebbb01b940023jortonAP_DECLARE(int) ap_rxplus_exec(apr_pool_t *pool, ap_rxplus_t *rx,
8a261a9f7d18d1e862d63f68e93f288d3e1f0d94trawick * Number of matches in the regexp operation's memory
185aa71728867671e105178b4c66fbc22b65ae26sf * This may be 0 if no match is in memory, or up to nmatch from compilation
f3aa436e29aa30e29695a18b7f469dd66b39b7e4jorton * @param rx The regexp
74b39333600dee3260355ad3a06e36ef6c61c8f1dreid * @return Number of matches in memory
97c78987224dcd037076d393aad1867c26b2c8cftrawick#define ap_rxplus_nmatch(rx) (((rx)->match != NULL) ? (rx)->nmatch : 0)
97c78987224dcd037076d393aad1867c26b2c8cftrawick * Get a pointer to a match from regex memory
97c78987224dcd037076d393aad1867c26b2c8cftrawick * NOTE: this relies on the match pattern from the last call to
97c78987224dcd037076d393aad1867c26b2c8cftrawick * ap_rxplus_exec still being valid (i.e. not freed or out-of-scope)
97c78987224dcd037076d393aad1867c26b2c8cftrawick * @param rx The regexp
97c78987224dcd037076d393aad1867c26b2c8cftrawick * @param n The match number to retrieve (must be between 0 and nmatch)
97c78987224dcd037076d393aad1867c26b2c8cftrawick * @param len Returns the length of the match.
97c78987224dcd037076d393aad1867c26b2c8cftrawick * @param match Returns the match pattern
97c78987224dcd037076d393aad1867c26b2c8cftrawickAP_DECLARE(void) ap_rxplus_match(ap_rxplus_t *rx, int n, int *len,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding const char **match);
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * Get a match from regex memory in a string copy
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * NOTE: this relies on the match pattern from the last call to
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * ap_rxplus_exec still being valid (i.e. not freed or out-of-scope)
785be1b6298010956622771c870ab3cd8ca57a2faaron * @param pool Pool to allocate from
785be1b6298010956622771c870ab3cd8ca57a2faaron * @param rx The regexp
785be1b6298010956622771c870ab3cd8ca57a2faaron * @param n The match number to retrieve (must be between 0 and nmatch)
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding * @return The matched string
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAP_DECLARE(char*) ap_rxplus_pmatch(apr_pool_t *pool, ap_rxplus_t *rx, int n);
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding} /* extern "C" */
785be1b6298010956622771c870ab3cd8ca57a2faaron#endif /* AP_REGEX_T */