EVOLUTION-MANAGER

Edit File: tre-api.html

<h1>TRE API reference manual</h1>

<h2>The <tt>regcomp()</tt> functions</h2>
<a name="regcomp"></a>

<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
int
regcomp(regex_t *preg,
const char
*regex, int
cflags);
 
int regncomp(regex_t
*preg, const
char *regex,
size_t len,
int cflags);
 
int regwcomp(regex_t
*preg, const
wchar_t *regex, int cflags);
 
int regwncomp(regex_t
*preg, const
wchar_t *regex, size_t
len, int
cflags);
 
void regfree(regex_t
*preg);
 
</code>
</div>

The <tt>regcomp()</tt> function compiles
the regex string pointed to by <tt>regex</tt> to an internal representation and
stores the result in the pattern buffer structure pointed to by
<tt>preg</tt>. The <tt>regncomp()</tt> function is like <tt>regcomp()</tt>, but <tt>regex</tt> is not terminated with the null
byte. Instead, the <tt>len</tt> argument
is used to give the length of the string, and the string may contain
null bytes. The <tt>regwcomp()</tt> and
<tt>regwncomp()</tt> functions work like
<tt>regcomp()</tt> and <tt>regncomp()</tt>, respectively, but take a wide
character (<tt>wchar_t</tt>) string
instead of a byte string.

The <tt>cflags</tt> argument is a the
bitwise inclusive OR of zero or more of the following flags (defined
in the header <tt>&lt;tre/regex.h&gt;</tt>):

<blockquote>
<dl>
<dt><tt>REG_EXTENDED</tt></dt>
<dd>Use POSIX Extended Regular Expression (ERE) compatible syntax when
compiling <tt>regex</tt>. The default
syntax is the POSIX Basic Regular Expression (BRE) syntax, but it is
considered obsolete.</dd>

<dt><tt>REG_ICASE</tt></dt>
<dd>Ignore case. Subsequent searches with the <a
href="#regexec"><tt>regexec</tt></a> family of functions using this
pattern buffer will be case insensitive.</dd>

<dt><tt>REG_NOSUB</tt></dt>
<dd>Do not report submatches. Subsequent searches with the <a
href="#regexec"><tt>regexec</tt></a> family of functions will only
report whether a match was found or not and will not fill the submatch
array.</dd>

<dt><tt>REG_NEWLINE</tt></dt>
<dd>Normally the newline character is treated as an ordinary
character. When this flag is used, the newline character
(<tt>'\n'</tt>, ASCII code 10) is treated specially as follows:
<ol>
<li>The match-any-character operator (dot <tt>"."</tt> outside a
bracket expression) does not match a newline.</li>
<li>A non-matching list (<tt>[^...]</tt>) not containing a newline
does not match a newline.</li>
<li>The match-beginning-of-line operator <tt>^</tt> matches the empty
string immediately after a newline as well as the empty string at the
beginning of the string (but see the <code>REG_NOTBOL</code>
<code>regexec()</code> flag below).
<li>The match-end-of-line operator <tt>$</tt> matches the empty
string immediately before a newline as well as the empty string at the
end of the string (but see the <code>REG_NOTEOL</code>
<code>regexec()</code> flag below).
</ol>
</dd>

<dt><tt>REG_LITERAL</tt></dt>
<dd>Interpret the entire <tt>regex</tt>
argument as a literal string, that is, all characters will be
considered ordinary. This is a nonstandard extension, compatible with
but not specified by POSIX.</dd>

<dt><tt>REG_NOSPEC</tt></dt>
<dd>Same as <tt>REG_LITERAL</tt>. This flag is provided for
compatibility with BSD.</dd>

<dt><tt>REG_RIGHT_ASSOC</tt></dt>
<dd>By default, concatenation is left associative in TRE, as per
the grammar given in the <a
href="http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap09.html">base
specifications on regular expressions</a> of Std 1003.1-2001 (POSIX).
This flag flips associativity of concatenation to right associative.
Associativity can have an effect on how a match is divided into
submatches, but does not change what is matched by the entire regexp.
</dd>

<dt><tt>REG_UNGREEDY</tt></dt>
<dd>By default, repetition operators are greedy in TRE as per Std 1003.1-2001 (POSIX) and
can be forced to be non-greedy by appending a <tt>?</tt> character. This flag reverses this behavior
by making the operators non-greedy by default and greedy when a <tt>?</tt> is specified.</dd>
</dl>
</blockquote>

After a successful call to <tt>regcomp</tt> it is
possible to use the <tt>preg</tt> pattern buffer for
searching for matches in strings (see below). Once the pattern buffer is no
longer needed, it should be freed with <tt>regfree</tt> to free the memory allocated for it.

The <tt>regex_t</tt> structure has the
following fields that the application can read:

<blockquote>
<dl>
<dt><tt>size_t re_nsub</tt></dt>
<dd>Number of parenthesized subexpressions in <tt>regex</tt>.
</dd>
</dl>
</blockquote>

The <tt>regcomp</tt> function returns
zero if the compilation was successful, or one of the following error
codes if there was an error:

<blockquote>
<dl>
<dt><tt>REG_BADPAT</tt></dt>
<dd>Invalid regexp. TRE returns this only if a multibyte character
set is used in the current locale, and <tt>regex</tt> contained an invalid multibyte
sequence.</dd>
<dt><tt>REG_ECOLLATE</tt></dt>
<dd>Invalid collating element referenced. TRE returns this whenever
equivalence classes or multicharacter collating elements are used in
bracket expressions (they are not supported yet).</dd>
<dt><tt>REG_ECTYPE</tt></dt>
<dd>Unknown character class name in <tt>[[:name:]]</tt>.</dd>
<dt><tt>REG_EESCAPE</tt></dt>
<dd>The last character of <tt>regex</tt>
was a backslash (<tt>\</tt>).</dd>
<dt><tt>REG_ESUBREG</tt></dt>
<dd>Invalid back reference; number in <tt>\digit</tt>
invalid.</dd>
<dt><tt>REG_EBRACK</tt></dt>
<dd><tt>[]</tt> imbalance.</dd>
<dt><tt>REG_EPAREN</tt></dt>
<dd><tt></tt> or <tt>()</tt> imbalance.</dd>
<dt><tt>REG_EBRACE</tt></dt>
<dd><tt>\{\}</tt> or <tt>{}</tt> imbalance.</dd>
<dt><tt>REG_BADBR</tt></dt>
<dd><tt>{}</tt> content invalid: not a number, more than two numbers,
first larger than second, or number too large.
<dt><tt>REG_ERANGE</tt></dt>
<dd>Invalid character range, e.g. ending point is earlier in the
collating order than the starting point.</dd>
<dt><tt>REG_ESPACE</tt></dt>
<dd>Out of memory, or an internal limit exceeded.</dd>
<dt><tt>REG_BADRPT</tt></dt>
<dd>Invalid use of repetition operators: two or more repetition operators have
been chained in an undefined way.</dd>
</dl>
</blockquote>

<h2>The <tt>regexec()</tt> functions</h2>
<a name="regexec"></a>

<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
int regexec(const
regex_t *preg, const char *string,
size_t nmatch,
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regmatch_t pmatch[], int
eflags);
 
int regnexec(const
regex_t *preg, const char *string,
size_t len,
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
size_t nmatch, regmatch_t
pmatch[], int eflags);
 
int regwexec(const
regex_t *preg, const wchar_t *string,
size_t nmatch,
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regmatch_t pmatch[], int
eflags);
 
int regwnexec(const
regex_t *preg, const wchar_t *string,
size_t len,
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
size_t nmatch, regmatch_t
pmatch[], int eflags);
</code>
</div>

The <tt>regexec()</tt> function matches
the null-terminated string against the compiled regexp <tt>preg</tt>, initialized by a previous call to
any one of the <a href="#regcomp"><tt>regcomp</tt></a> functions. The
<tt>regnexec()</tt> function is like
<tt>regexec()</tt>, but <tt>string</tt> is not terminated with a null byte.
Instead, the <tt>len</tt> argument is used
to give the length of the string, and the string may contain null
bytes. The <tt>regwexec()</tt> and
<tt>regwnexec()</tt> functions work like
<tt>regexec()</tt> and <tt>regnexec()</tt>, respectively, but take a wide
character (<tt>wchar_t</tt>) string
instead of a byte string. The <tt>eflags</tt> argument is a bitwise OR of zero or
more of the following flags:

<blockquote>
<dl>
<dt><code>REG_NOTBOL</code></dt>
<dd>

When this flag is used, the match-beginning-of-line operator
<tt>^</tt> does not match the empty string at the beginning of
<tt>string</tt>. If
<code>REG_NEWLINE</code> was used when compiling
<tt>preg</tt> the empty string
immediately after a newline character will still be matched.

</dd>

<dt><code>REG_NOTEOL</code></dt>
<dd>

When this flag is used, the match-end-of-line operator
<tt>$</tt> does not match the empty string at the end of
<tt>string</tt>. If
<code>REG_NEWLINE</code> was used when compiling
<tt>preg</tt> the empty string
immediately before a newline character will still be matched.

</dl>

These flags are useful when different portions of a string are passed
to <code>regexec</code> and the beginning or end of the partial string
should not be interpreted as the beginning or end of a line.

</blockquote>

If <code>REG_NOSUB</code> was used when compiling <tt>preg</tt>, <tt>nmatch</tt> is zero, or <tt>pmatch</tt> is <code>NULL</code>, then the
<tt>pmatch</tt> argument is ignored.
Otherwise, the submatches corresponding to the parenthesized
subexpressions are filled in the elements of <tt>pmatch</tt>, which must be dimensioned to have
at least <tt>nmatch</tt> elements.

The <tt>regmatch_t</tt> structure contains
at least the following fields:

<blockquote>
<dl>
<dt><tt>regoff_t rm_so</tt></dt>
<dd>Offset from start of <tt>string</tt> to start of
substring. </dd>
<dt><tt>regoff_t rm_eo</tt></dt>
<dd>Offset from start of <tt>string</tt> to the first
character after the substring. </dd>
</dl>
</blockquote>

The length of a submatch can be computed by subtracting <code>rm_eo</code> and
<code>rm_so</code>. If a parenthesized subexpression did not participate in a
match, the <code>rm_so</code> and <code>rm_eo</code> fields for the
corresponding <code>pmatch</code> element are set to <code>-1</code>. Note
that when a multibyte character set is in effect, the submatch offsets are
given as byte offsets, not character offsets.

The <code>regexec()</code> functions return zero if a match was found,
otherwise they return <code>REG_NOMATCH</code> to indicate no match,
or <code>REG_ESPACE</code> to indicate that enough temporary memory
could not be allocated to complete the matching operation.

<h3>reguexec()</h3>

<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
typedef struct {
 
&nbsp;&nbsp;int (*get_next_char)(tre_char_t *c, unsigned int *pos_add,
void *context);
 
&nbsp;&nbsp;void (*rewind)(size_t pos, void *context);
 
&nbsp;&nbsp;int (*compare)(size_t pos1, size_t pos2, size_t len, void *context);
 
&nbsp;&nbsp;void *context;
 
} tre_str_source;
 
 
int reguexec(const
regex_t *preg, const tre_str_source *string,
size_t nmatch,
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regmatch_t pmatch[], int
eflags);
</code>
</div>

The <tt>reguexec()</tt> function works just
like the other <tt>regexec()</tt> functions, except that the input
string is read from user specified callback functions instead of a
character array. This makes it possible, for example, to match
regexps over arbitrary user specified data structures.

The <tt>tre_str_source</tt> structure
contains the following fields:

<blockquote>
<dl>
<dt><tt>get_next_char</tt></dt>
<dd>This function must retrieve the next available character. If a
character is not available, the space pointed to by
<tt>c</tt> must be set to zero and it must return
a nonzero value. If a character is available, it must be stored
to the space pointed to by
<tt>c</tt>, and the integer pointer to by
<tt>pos_add</tt> must be set to the
number of units advanced in the input (the value must be
<tt>&gt;=1</tt>), and zero must be returned.</dd>

<dt><tt>rewind</tt></dt>
<dd>This function must rewind the input stream to the position
specified by <tt>pos</tt>. Unless the regexp
uses back references, <tt>rewind</tt> is not needed and can be set to
<tt>NULL</tt>.</dd>

<dt><tt>compare</tt></dt>
<dd>This function compares two substrings in the input streams
starting at the positions specified by <tt>pos1</tt> and <tt>pos2</tt> of length <tt>len</tt>. If the substrings are equal,
<tt>compare</tt> must return zero, otherwise a nonzero value must be
returned. Unless the regexp uses back references, <tt>compare</tt> is
not needed and can be set to <tt>NULL</tt>.</dd>

<dt><tt>context</tt></dt>
<dd>This is a context variable, passed as the last argument to
all of the above functions for keeping track of the internal state of
the users code.</dd>

</dl>
</blockquote>

The position in the input stream is measured in <tt>size_t</tt> units. The current position is the
sum of the increments gotten from <tt>pos_add</tt> (plus the position of the last
<tt>rewind</tt>, if any). The starting position is zero. Submatch
positions filled in the <tt>pmatch[]</tt>
array are, of course, given using positions computed in this way.

For an example of how to use <tt>reguexec()</tt>, see the
<tt>tests/test-str-source.c</tt> file in the TRE source code
distribution.

<h2>The approximate matching functions</h2>
<a name="regaexec"></a>

<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
typedef struct { 
&nbsp;&nbsp;int
cost_ins; 
&nbsp;&nbsp;int
cost_del; 
&nbsp;&nbsp;int
cost_subst; 
&nbsp;&nbsp;int
max_cost; 
&nbsp;&nbsp;int
max_ins; 
&nbsp;&nbsp;int
max_del; 
&nbsp;&nbsp;int
max_subst; 
&nbsp;&nbsp;int
max_err; 
} regaparams_t; 
 
typedef struct { 
&nbsp;&nbsp;size_t
nmatch; 
&nbsp;&nbsp;regmatch_t
*pmatch; 
&nbsp;&nbsp;int
cost; 
&nbsp;&nbsp;int
num_ins; 
&nbsp;&nbsp;int
num_del; 
&nbsp;&nbsp;int
num_subst; 
} regamatch_t; 
 
int regaexec(const
regex_t *preg, const char *string, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regamatch_t
*match,
regaparams_t
params,
int
eflags);
 
int reganexec(const
regex_t *preg, const char *string,
size_t len, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regamatch_t
*match,
regaparams_t
params,
int eflags);
 
int regawexec(const
regex_t *preg, const wchar_t *string, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regamatch_t
*match,
regaparams_t
params,
int
eflags);
 
int
regawnexec(
const
regex_t
*preg,
const
wchar_t
*string,
size_t
len, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
regamatch_t
*match,
regaparams_t
params,
int
eflags);
 
</code>
</div>

The <tt>regaexec()</tt> function searches for
the best match in <tt>string</tt>
against the compiled regexp <tt>preg</tt>, initialized by a previous call to
any one of the <a href="#regcomp"><tt>regcomp</tt></a> functions.

The <tt>reganexec()</tt> function is like
<tt>regaexec()</tt>, but <tt>string</tt> is not terminated by a null byte.
Instead, the <tt>len</tt> argument is used to
tell the length of the string, and the string may contain null
bytes. The <tt>regawexec()</tt> and
<tt>regawnexec()</tt> functions work like
<tt>regaexec()</tt> and <tt>reganexec()</tt>, respectively, but take a wide
character (<tt>wchar_t</tt>) string instead
of a byte string.

The <tt>eflags</tt> argument is like for
the regexec() functions.

The <tt>params</tt> struct controls the
approximate matching parameters:
<blockquote>
<dl>
 <dt><tt>int</tt>
 <tt>cost_ins</tt></dt>
 <dd>The default cost of an inserted character, that is, an extra
 character in <tt>string</tt>.</dd>

<dt><tt>int</tt>
 <tt>cost_del</tt></dt>
 <dd>The default cost of a deleted character, that is, a character
 missing from <tt>string</tt>.</dd>

<dt><tt>int</tt>
 <tt>cost_subst</tt></dt>
 <dd>The default cost of a substituted character.</dd>

<dt><tt>int</tt>
 <tt>max_cost</tt></dt>
 <dd>The maximum allowed cost of a match. If this is set to zero,
 an exact matching is searched for, and results equivalent to
 those returned by the <tt>regexec()</tt> functions are
 returned.</dd>

<dt><tt>int</tt>
 <tt>max_ins</tt></dt>
 <dd>Maximum allowed number of inserted characters.</dd>

<dt><tt>int</tt>
 <tt>max_del</tt></dt>
 <dd>Maximum allowed number of deleted characters.</dd>

<dt><tt>int</tt>
 <tt>max_subst</tt></dt>
 <dd>Maximum allowed number of substituted characters.</dd>

<dt><tt>int</tt>
 <tt>max_err</tt></dt>
 <dd>Maximum allowed number of errors (inserts + deletes +
 substitutes).</dd>
</dl>
</blockquote>

The <tt>match</tt> argument points to a
<tt>regamatch_t</tt> structure. The
<tt>nmatch</tt> and <tt>pmatch</tt> field must be filled by the caller. If
<code>REG_NOSUB</code> was used when compiling the regexp, or
<code>match-&gt;nmatch</code> is zero, or
<code>match-&gt;pmatch</code> is <code>NULL</code>, the
<code>match-&gt;pmatch</code> argument is ignored. Otherwise, the
submatches corresponding to the parenthesized subexpressions are
filled in the elements of <code>match-&gt;pmatch</code>, which must be
dimensioned to have at least <code>match-&gt;nmatch</code> elements.
The <code>match-&gt;cost</code> field is set to the cost of the match
found, and the <code>match-&gt;num_ins</code>,
<code>match-&gt;num_del</code>, and <code>match-&gt;num_subst</code>
fields are set to the number of inserts, deletes, and substitutes in
the match, respectively.

The <tt>regaexec()</tt> functions return zero if a match with cost
smaller than <code>params-&gt;max_cost</code> was found, otherwise
they return <code>REG_NOMATCH</code> to indicate no match, or
<code>REG_ESPACE</code> to indicate that enough temporary memory could
not be allocated to complete the matching operation.

<h2>Miscellaneous</h2>

<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
int tre_have_backrefs(const
regex_t *preg);
 
int tre_have_approx(const
regex_t *preg);
 
</code>
</div>

The <tt>tre_have_backrefs()</tt> and
<tt>tre_have_approx()</tt> functions return
1 if the compiled pattern has back references or uses approximate
matching, respectively, and 0 if not.

<h2>Checking build time options</h2>

<a name="tre_config"></a>
<div class="code">
<code>
#include &lt;tre/regex.h&gt;
 
 
char *tre_version(void);
 
int tre_config(int query, void *result);
 
</code>
</div>

The <tt>tre_config()</tt> function can be
used to retrieve information of which optional features have been
compiled into the TRE library and information of other parameters that
may change between releases.

The <tt>query</tt> argument is an integer
telling what information is requested for. The <tt>result</tt> argument is a pointer to a variable
where the information is returned. The return value of a call to
<tt>tre_config()</tt> is zero if <tt>query</tt> was recognized, REG_NOMATCH otherwise.

The following values are recognized for <tt>query</tt>:

<blockquote>
<dl>
<dt><tt>TRE_CONFIG_APPROX</tt></dt>
<dd>The result is an integer that is set to one if approximate
matching support is available, zero if not.</dd>
<dt><tt>TRE_CONFIG_WCHAR</tt></dt>
<dd>The result is an integer that is set to one if wide character
support is available, zero if not.</dd>
<dt><tt>TRE_CONFIG_MULTIBYTE</tt></dt>
<dd>The result is an integer that is set to one if multibyte character
set support is available, zero if not.</dd>
<dt><tt>TRE_CONFIG_SYSTEM_ABI</tt></dt>
<dd>The result is an integer that is set to one if TRE has been
compiled to be compatible with the system regex ABI, zero if not.</dd>
<dt><tt>TRE_CONFIG_VERSION</tt></dt>
<dd>The result is a pointer to a static character string that gives
the version of the TRE library.</dd>
</dl>
</blockquote>

The <tt>tre_version()</tt> function returns
a short human readable character string which shows the software name,
version, and license.

<h2>Preprocessor definitions</h2>

The header <tt>&lt;tre/regex.h&gt;</tt> defines certain
C preprocessor symbols.

<h3>Version information</h3>

The following definitions may be useful for checking whether a new
enough version is being used. Note that it is recommended to use the
<tt>pkg-config</tt> tool for version and other checks in Autoconf
scripts.

<blockquote>
<dl>
<dt><tt>TRE_VERSION</tt></dt>
<dd>The version string. </dd>

<dt><tt>TRE_VERSION_1</tt></dt>
<dd>The major version number (first part of version string).</dd>

<dt><tt>TRE_VERSION_2</tt></dt>
<dd>The minor version number (second part of version string).</dd>

<dt><tt>TRE_VERSION_3</tt></dt>
<dd>The micro version number (third part of version string).</dd>

</dl>
</blockquote>

<h3>Features</h3>

The following definitions may be useful for checking whether all
necessary features are enabled. Use these only if compile time
checking suffices (linking statically with TRE). When linking
dynamically <a href="#tre_config"><tt>tre_config()</tt></a> should be used
instead.

<blockquote>
<dl>
<dt><tt>TRE_APPROX</tt></dt>
<dd>This is defined if approximate matching support is enabled. The
prototypes for approximate matching functions are defined only if
<tt>TRE_APPROX</tt> is defined.</dd>

<dt><tt>TRE_WCHAR</tt></dt>
<dd>This is defined if wide character support is enabled. The
prototypes for wide character matching functions are defined only if
<tt>TRE_WCHAR</tt> is defined.</dd>

<dt><tt>TRE_MULTIBYTE</tt></dt>
<dd>This is defined if multibyte character set support is enabled.
If this is not set any locale settings are ignored, and the default
locale is used when parsing regexps and matching strings.</dd>

</dl>
</blockquote>