Revision: 119
http://www.exim.org/viewvc/pcre2?view=rev&revision=119
Author: ph10
Date: 2014-10-20 17:48:14 +0100 (Mon, 20 Oct 2014)
Log Message:
-----------
More documentation
Modified Paths:
--------------
code/trunk/Makefile.am
Added Paths:
-----------
code/trunk/doc/html/pcre2perform.html
code/trunk/doc/html/pcre2posix.html
code/trunk/doc/html/pcre2sample.html
code/trunk/doc/html/pcre2stack.html
code/trunk/doc/html/pcre2syntax.html
code/trunk/doc/pcre2perform.3
code/trunk/doc/pcre2posix.3
code/trunk/doc/pcre2sample.3
code/trunk/doc/pcre2stack.3
code/trunk/doc/pcre2syntax.3
Modified: code/trunk/Makefile.am
===================================================================
--- code/trunk/Makefile.am 2014-10-19 15:30:48 UTC (rev 118)
+++ code/trunk/Makefile.am 2014-10-20 16:48:14 UTC (rev 119)
@@ -36,6 +36,11 @@
doc/html/pcre2matching.html \
doc/html/pcre2partial.html \
doc/html/pcre2pattern.html \
+ doc/html/pcre2perform.html \
+ doc/html/pcre2posix.html \
+ doc/html/pcre2sample.html \
+ doc/html/pcre2stack.html \
+ doc/html/pcre2syntax.html \
doc/html/pcre2test.html \
doc/html/pcre2unicode.html
@@ -66,12 +71,7 @@
# doc/html/pcre2_utf16_to_host_byte_order.html \
# doc/html/pcre2_utf32_to_host_byte_order.html \
# doc/html/pcre2_version.html \
-# doc/html/pcre2perform.html \
-# doc/html/pcre2posix.html \
-# doc/html/pcre2precompile.html \
-# doc/html/pcre2sample.html \
-# doc/html/pcre2stack.html \
-# doc/html/pcre2syntax.html
+# doc/html/pcre2precompile.html
# FIXME
dist_man_MANS = \
@@ -88,6 +88,11 @@
doc/pcre2matching.3 \
doc/pcre2partial.3 \
doc/pcre2pattern.3 \
+ doc/pcre2perform.3 \
+ doc/pcre2posix.3 \
+ doc/pcre2sample.3 \
+ doc/pcre2stack.3 \
+ doc/pcre2syntax.3 \
doc/pcre2test.1 \
doc/pcre2unicode.3
@@ -120,12 +125,7 @@
# doc/pcre2_utf16_to_host_byte_order.3 \
# doc/pcre2_utf32_to_host_byte_order.3 \
# doc/pcre2_version.3 \
-# doc/pcre2perform.3 \
-# doc/pcre2posix.3 \
-# doc/pcre2precompile.3 \
-# doc/pcre2sample.3 \
-# doc/pcre2stack.3 \
-# doc/pcre2syntax.3
+# doc/pcre2precompile.3
# The Libtool libraries to install. We'll add to this later.
Added: code/trunk/doc/html/pcre2perform.html
===================================================================
--- code/trunk/doc/html/pcre2perform.html (rev 0)
+++ code/trunk/doc/html/pcre2perform.html 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,196 @@
+<html>
+<head>
+<title>pcre2perform specification</title>
+</head>
+<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
+<h1>pcre2perform man page</h1>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
+<p>
+This page is part of the PCRE2 HTML documentation. It was generated
+automatically from the original man page. If there is any nonsense in it,
+please consult the man page, in case the conversion went wrong.
+<br>
+<br><b>
+PCRE2 PERFORMANCE
+</b><br>
+<P>
+Two aspects of performance are discussed below: memory usage and processing
+time. The way you express your pattern as a regular expression can affect both
+of them.
+</P>
+<br><b>
+COMPILED PATTERN MEMORY USAGE
+</b><br>
+<P>
+Patterns are compiled by PCRE2 into a reasonably efficient interpretive code,
+so that most simple patterns do not use much memory. However, there is one case
+where the memory usage of a compiled pattern can be unexpectedly large. If a
+parenthesized subpattern has a quantifier with a minimum greater than 1 and/or
+a limited maximum, the whole subpattern is repeated in the compiled code. For
+example, the pattern
+<pre>
+ (abc|def){2,4}
+</pre>
+is compiled as if it were
+<pre>
+ (abc|def)(abc|def)((abc|def)(abc|def)?)?
+</pre>
+(Technical aside: It is done this way so that backtrack points within each of
+the repetitions can be independently maintained.)
+</P>
+<P>
+For regular expressions whose quantifiers use only small numbers, this is not
+usually a problem. However, if the numbers are large, and particularly if such
+repetitions are nested, the memory usage can become an embarrassment. For
+example, the very simple pattern
+<pre>
+ ((ab){1,1000}c){1,3}
+</pre>
+uses 51K bytes when compiled using the 8-bit library. When PCRE2 is compiled
+with its default internal pointer size of two bytes, the size limit on a
+compiled pattern is 64K code units in the 8-bit and 16-bit libraries, and this
+is reached with the above pattern if the outer repetition is increased from 3
+to 4. PCRE2 can be compiled to use larger internal pointers and thus handle
+larger compiled patterns, but it is better to try to rewrite your pattern to
+use less memory if you can.
+</P>
+<P>
+One way of reducing the memory usage for such patterns is to make use of
+PCRE2's
+<a href="pcre2pattern.html#subpatternsassubroutines">"subroutine"</a>
+facility. Re-writing the above pattern as
+<pre>
+ ((ab)(?2){0,999}c)(?1){0,2}
+</pre>
+reduces the memory requirements to 18K, and indeed it remains under 20K even
+with the outer repetition increased to 100. However, this pattern is not
+exactly equivalent, because the "subroutine" calls are treated as
+<a href="pcre2pattern.html#atomicgroup">atomic groups</a>
+into which there can be no backtracking if there is a subsequent matching
+failure. Therefore, PCRE2 cannot do this kind of rewriting automatically.
+Furthermore, there is a noticeable loss of speed when executing the modified
+pattern. Nevertheless, if the atomic grouping is not a problem and the loss of
+speed is acceptable, this kind of rewriting will allow you to process patterns
+that PCRE2 cannot otherwise handle.
+</P>
+<br><b>
+STACK USAGE AT RUN TIME
+</b><br>
+<P>
+When <b>pcre2_match()</b> is used for matching, certain kinds of pattern can
+cause it to use large amounts of the process stack. In some environments the
+default process stack is quite small, and if it runs out the result is often
+SIGSEGV. Rewriting your pattern can often help. The
+<a href="pcre2stack.html"><b>pcre2stack</b></a>
+documentation discusses this issue in detail.
+</P>
+<br><b>
+PROCESSING TIME
+</b><br>
+<P>
+Certain items in regular expression patterns are processed more efficiently
+than others. It is more efficient to use a character class like [aeiou] than a
+set of single-character alternatives such as (a|e|i|o|u). In general, the
+simplest construction that provides the required behaviour is usually the most
+efficient. Jeffrey Friedl's book contains a lot of useful general discussion
+about optimizing regular expressions for efficient performance. This document
+contains a few observations about PCRE2.
+</P>
+<P>
+Using Unicode character properties (the \p, \P, and \X escapes) is slow,
+because PCRE2 has to use a multi-stage table lookup whenever it needs a
+character's property. If you can find an alternative pattern that does not use
+character properties, it will probably be faster.
+</P>
+<P>
+By default, the escape sequences \b, \d, \s, and \w, and the POSIX
+character classes such as [:alpha:] do not use Unicode properties, partly for
+backwards compatibility, and partly for performance reasons. However, you can
+set the PCRE2_UCP option or start the pattern with (*UCP) if you want Unicode
+character properties to be used. This can double the matching time for items
+such as \d, when matched with <b>pcre2_match()</b>; the performance loss is
+less with a DFA matching function, and in both cases there is not much
+difference for \b.
+</P>
+<P>
+When a pattern begins with .* not in parentheses, or in parentheses that are
+not the subject of a backreference, and the PCRE2_DOTALL option is set, the
+pattern is implicitly anchored by PCRE2, since it can match only at the start
+of a subject string. However, if PCRE2_DOTALL is not set, PCRE2 cannot make
+this optimization, because the dot metacharacter does not then match a newline,
+and if the subject string contains newlines, the pattern may match from the
+character immediately following one of them instead of from the very start. For
+example, the pattern
+<pre>
+ .*second
+</pre>
+matches the subject "first\nand second" (where \n stands for a newline
+character), with the match starting at the seventh character. In order to do
+this, PCRE2 has to retry the match starting after every newline in the subject.
+</P>
+<P>
+If you are using such a pattern with subject strings that do not contain
+newlines, the best performance is obtained by setting PCRE2_DOTALL, or starting
+the pattern with ^.* or ^.*? to indicate explicit anchoring. That saves PCRE2
+from having to scan along the subject looking for a newline to restart at.
+</P>
+<P>
+Beware of patterns that contain nested indefinite repeats. These can take a
+long time to run when applied to a string that does not match. Consider the
+pattern fragment
+<pre>
+ ^(a+)*
+</pre>
+This can match "aaaa" in 16 different ways, and this number increases very
+rapidly as the string gets longer. (The * repeat can match 0, 1, 2, 3, or 4
+times, and for each of those cases other than 0 or 4, the + repeats can match
+different numbers of times.) When the remainder of the pattern is such that the
+entire match is going to fail, PCRE2 has in principle to try every possible
+variation, and this can take an extremely long time, even for relatively short
+strings.
+</P>
+<P>
+An optimization catches some of the more simple cases such as
+<pre>
+ (a+)*b
+</pre>
+where a literal character follows. Before embarking on the standard matching
+procedure, PCRE2 checks that there is a "b" later in the subject string, and if
+there is not, it fails the match immediately. However, when there is no
+following literal this optimization cannot be used. You can see the difference
+by comparing the behaviour of
+<pre>
+ (a+)*\d
+</pre>
+with the pattern above. The former gives a failure almost instantly when
+applied to a whole line of "a" characters, whereas the latter takes an
+appreciable time with strings longer than about 20 characters.
+</P>
+<P>
+In many cases, the solution to this kind of performance issue is to use an
+atomic group or a possessive quantifier.
+</P>
+<br><b>
+AUTHOR
+</b><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><b>
+REVISION
+</b><br>
+<P>
+Last updated: 20 October 2014
+<br>
+Copyright © 1997-2014 University of Cambridge.
+<br>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
Added: code/trunk/doc/html/pcre2posix.html
===================================================================
--- code/trunk/doc/html/pcre2posix.html (rev 0)
+++ code/trunk/doc/html/pcre2posix.html 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,292 @@
+<html>
+<head>
+<title>pcre2posix specification</title>
+</head>
+<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
+<h1>pcre2posix man page</h1>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
+<p>
+This page is part of the PCRE2 HTML documentation. It was generated
+automatically from the original man page. If there is any nonsense in it,
+please consult the man page, in case the conversion went wrong.
+<br>
+<ul>
+<li><a name="TOC1" href="#SEC1">SYNOPSIS</a>
+<li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
+<li><a name="TOC3" href="#SEC3">COMPILING A PATTERN</a>
+<li><a name="TOC4" href="#SEC4">MATCHING NEWLINE CHARACTERS</a>
+<li><a name="TOC5" href="#SEC5">MATCHING A PATTERN</a>
+<li><a name="TOC6" href="#SEC6">ERROR MESSAGES</a>
+<li><a name="TOC7" href="#SEC7">MEMORY USAGE</a>
+<li><a name="TOC8" href="#SEC8">AUTHOR</a>
+<li><a name="TOC9" href="#SEC9">REVISION</a>
+</ul>
+<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
+<P>
+<b>#include <pcre2posix.h></b>
+</P>
+<P>
+<b>int regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b>
+<b> int <i>cflags</i>);</b>
+<br>
+<br>
+<b>int regexec(const regex_t *<i>preg</i>, const char *<i>string</i>,</b>
+<b> size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b>
+<br>
+<br>
+<b>size_t regerror(int <i>errcode</i>, const regex_t *<i>preg</i>,</b>
+<b> char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b>
+<br>
+<br>
+<b>void regfree(regex_t *<i>preg</i>);</b>
+</P>
+<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
+<P>
+This set of functions provides a POSIX-style API for the PCRE2 regular
+expression 8-bit library. See the
+<a href="pcre2api.html"><b>pcre2api</b></a>
+documentation for a description of PCRE2's native API, which contains much
+additional functionality. There is no POSIX-style wrapper for PCRE2's 16-bit
+and 32-bit libraries.
+</P>
+<P>
+The functions described here are just wrapper functions that ultimately call
+the PCRE2 native API. Their prototypes are defined in the <b>pcre2posix.h</b>
+header file, and on Unix systems the library itself is called
+<b>libpcre2-posix.a</b>, so can be accessed by adding <b>-lpcre2-posix</b> to the
+command for linking an application that uses them. Because the POSIX functions
+call the native ones, it is also necessary to add <b>-lpcre2-8</b>.
+</P>
+<P>
+Those POSIX option bits that can reasonably be mapped to PCRE2 native options
+have been implemented. In addition, the option REG_EXTENDED is defined with the
+value zero. This has no effect, but since programs that are written to the
+POSIX interface often use it, this makes it easier to slot in PCRE2 as a
+replacement library. Other POSIX options are not even defined.
+</P>
+<P>
+There are also some other options that are not defined by POSIX. These have
+been added at the request of users who want to make use of certain
+PCRE2-specific features via the POSIX calling interface.
+</P>
+<P>
+When PCRE2 is called via these functions, it is only the API that is POSIX-like
+in style. The syntax and semantics of the regular expressions themselves are
+still those of Perl, subject to the setting of various PCRE2 options, as
+described below. "POSIX-like in style" means that the API approximates to the
+POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
+domains it is probably even less compatible.
+</P>
+<P>
+The header for these functions is supplied as <b>pcre2posix.h</b> to avoid any
+potential clash with other POSIX libraries. It can, of course, be renamed or
+aliased as <b>regex.h</b>, which is the "correct" name. It provides two
+structure types, <i>regex_t</i> for compiled internal forms, and
+<i>regmatch_t</i> for returning captured substrings. It also defines some
+constants whose names start with "REG_"; these are used for setting options and
+identifying error codes.
+</P>
+<br><a name="SEC3" href="#TOC1">COMPILING A PATTERN</a><br>
+<P>
+The function <b>regcomp()</b> is called to compile a pattern into an
+internal form. The pattern is a C string terminated by a binary zero, and
+is passed in the argument <i>pattern</i>. The <i>preg</i> argument is a pointer
+to a <b>regex_t</b> structure that is used as a base for storing information
+about the compiled regular expression.
+</P>
+<P>
+The argument <i>cflags</i> is either zero, or contains one or more of the bits
+defined by the following macros:
+<pre>
+ REG_DOTALL
+</pre>
+The PCRE2_DOTALL option is set when the regular expression is passed for
+compilation to the native function. Note that REG_DOTALL is not part of the
+POSIX standard.
+<pre>
+ REG_ICASE
+</pre>
+The PCRE2_CASELESS option is set when the regular expression is passed for
+compilation to the native function.
+<pre>
+ REG_NEWLINE
+</pre>
+The PCRE2_MULTILINE option is set when the regular expression is passed for
+compilation to the native function. Note that this does <i>not</i> mimic the
+defined POSIX behaviour for REG_NEWLINE (see the following section).
+<pre>
+ REG_NOSUB
+</pre>
+The PCRE2_NO_AUTO_CAPTURE option is set when the regular expression is passed
+for compilation to the native function. In addition, when a pattern that is
+compiled with this flag is passed to <b>regexec()</b> for matching, the
+<i>nmatch</i> and <i>pmatch</i> arguments are ignored, and no captured strings
+are returned.
+<pre>
+ REG_UCP
+</pre>
+The PCRE2_UCP option is set when the regular expression is passed for
+compilation to the native function. This causes PCRE2 to use Unicode properties
+when matchine \d, \w, etc., instead of just recognizing ASCII values. Note
+that REG_UCP is not part of the POSIX standard.
+<pre>
+ REG_UNGREEDY
+</pre>
+The PCRE2_UNGREEDY option is set when the regular expression is passed for
+compilation to the native function. Note that REG_UNGREEDY is not part of the
+POSIX standard.
+<pre>
+ REG_UTF
+</pre>
+The PCRE2_UTF option is set when the regular expression is passed for
+compilation to the native function. This causes the pattern itself and all data
+strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF
+is not part of the POSIX standard.
+</P>
+<P>
+In the absence of these flags, no options are passed to the native function.
+This means the the regex is compiled with PCRE2 default semantics. In
+particular, the way it handles newline characters in the subject string is the
+Perl way, not the POSIX way. Note that setting PCRE2_MULTILINE has only
+<i>some</i> of the effects specified for REG_NEWLINE. It does not affect the way
+newlines are matched by the dot metacharacter (they are not) or by a negative
+class such as [^a] (they are).
+</P>
+<P>
+The yield of <b>regcomp()</b> is zero on success, and non-zero otherwise. The
+<i>preg</i> structure is filled in on success, and one member of the structure
+is public: <i>re_nsub</i> contains the number of capturing subpatterns in
+the regular expression. Various error codes are defined in the header file.
+</P>
+<P>
+NOTE: If the yield of <b>regcomp()</b> is non-zero, you must not attempt to
+use the contents of the <i>preg</i> structure. If, for example, you pass it to
+<b>regexec()</b>, the result is undefined and your program is likely to crash.
+</P>
+<br><a name="SEC4" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br>
+<P>
+This area is not simple, because POSIX and Perl take different views of things.
+It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
+never intended to be a POSIX engine. The following table lists the different
+possibilities for matching newline characters in PCRE2:
+<pre>
+ Default Change with
+
+ . matches newline no PCRE2_DOTALL
+ newline matches [^a] yes not changeable
+ $ matches \n at end yes PCRE2_DOLLAR_ENDONLY
+ $ matches \n in middle no PCRE2_MULTILINE
+ ^ matches \n in middle no PCRE2_MULTILINE
+</pre>
+This is the equivalent table for POSIX:
+<pre>
+ Default Change with
+
+ . matches newline yes REG_NEWLINE
+ newline matches [^a] yes REG_NEWLINE
+ $ matches \n at end no REG_NEWLINE
+ $ matches \n in middle no REG_NEWLINE
+ ^ matches \n in middle no REG_NEWLINE
+</pre>
+PCRE2's behaviour is the same as Perl's, except that there is no equivalent for
+PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there is no way to stop
+newline from matching [^a].
+</P>
+<P>
+The default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
+PCRE2_DOLLAR_ENDONLY, but there is no way to make PCRE2 behave exactly as for
+the REG_NEWLINE action.
+</P>
+<br><a name="SEC5" href="#TOC1">MATCHING A PATTERN</a><br>
+<P>
+The function <b>regexec()</b> is called to match a compiled pattern <i>preg</i>
+against a given <i>string</i>, which is by default terminated by a zero byte
+(but see REG_STARTEND below), subject to the options in <i>eflags</i>. These can
+be:
+<pre>
+ REG_NOTBOL
+</pre>
+The PCRE2_NOTBOL option is set when calling the underlying PCRE2 matching
+function.
+<pre>
+ REG_NOTEMPTY
+</pre>
+The PCRE2_NOTEMPTY option is set when calling the underlying PCRE2 matching
+function. Note that REG_NOTEMPTY is not part of the POSIX standard. However,
+setting this option can give more POSIX-like behaviour in some situations.
+<pre>
+ REG_NOTEOL
+</pre>
+The PCRE2_NOTEOL option is set when calling the underlying PCRE2 matching
+function.
+<pre>
+ REG_STARTEND
+</pre>
+The string is considered to start at <i>string</i> + <i>pmatch[0].rm_so</i> and
+to have a terminating NUL located at <i>string</i> + <i>pmatch[0].rm_eo</i>
+(there need not actually be a NUL at that location), regardless of the value of
+<i>nmatch</i>. This is a BSD extension, compatible with but not specified by
+IEEE Standard 1003.2 (POSIX.2), and should be used with caution in software
+intended to be portable to other systems. Note that a non-zero <i>rm_so</i> does
+not imply REG_NOTBOL; REG_STARTEND affects only the location of the string, not
+how it is matched.
+</P>
+<P>
+If the pattern was compiled with the REG_NOSUB flag, no data about any matched
+strings is returned. The <i>nmatch</i> and <i>pmatch</i> arguments of
+<b>regexec()</b> are ignored.
+</P>
+<P>
+If the value of <i>nmatch</i> is zero, or if the value <i>pmatch</i> is NULL,
+no data about any matched strings is returned.
+</P>
+<P>
+Otherwise,the portion of the string that was matched, and also any captured
+substrings, are returned via the <i>pmatch</i> argument, which points to an
+array of <i>nmatch</i> structures of type <i>regmatch_t</i>, containing the
+members <i>rm_so</i> and <i>rm_eo</i>. These contain the byte offset to the first
+character of each substring and the offset to the first character after the end
+of each substring, respectively. The 0th element of the vector relates to the
+entire portion of <i>string</i> that was matched; subsequent elements relate to
+the capturing subpatterns of the regular expression. Unused entries in the
+array have both structure members set to -1.
+</P>
+<P>
+A successful match yields a zero return; various error codes are defined in the
+header file, of which REG_NOMATCH is the "expected" failure code.
+</P>
+<br><a name="SEC6" href="#TOC1">ERROR MESSAGES</a><br>
+<P>
+The <b>regerror()</b> function maps a non-zero errorcode from either
+<b>regcomp()</b> or <b>regexec()</b> to a printable message. If <i>preg</i> is not
+NULL, the error should have arisen from the use of that structure. A message
+terminated by a binary zero is placed in <i>errbuf</i>. The length of the
+message, including the zero, is limited to <i>errbuf_size</i>. The yield of the
+function is the size of buffer needed to hold the whole message.
+</P>
+<br><a name="SEC7" href="#TOC1">MEMORY USAGE</a><br>
+<P>
+Compiling a regular expression causes memory to be allocated and associated
+with the <i>preg</i> structure. The function <b>regfree()</b> frees all such
+memory, after which <i>preg</i> may no longer be used as a compiled expression.
+</P>
+<br><a name="SEC8" href="#TOC1">AUTHOR</a><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><a name="SEC9" href="#TOC1">REVISION</a><br>
+<P>
+Last updated: 20 October 2014
+<br>
+Copyright © 1997-2014 University of Cambridge.
+<br>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
Added: code/trunk/doc/html/pcre2sample.html
===================================================================
--- code/trunk/doc/html/pcre2sample.html (rev 0)
+++ code/trunk/doc/html/pcre2sample.html 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,106 @@
+<html>
+<head>
+<title>pcre2sample specification</title>
+</head>
+<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
+<h1>pcre2sample man page</h1>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
+<p>
+This page is part of the PCRE2 HTML documentation. It was generated
+automatically from the original man page. If there is any nonsense in it,
+please consult the man page, in case the conversion went wrong.
+<br>
+<br><b>
+PCRE2 SAMPLE PROGRAM
+</b><br>
+<P>
+A simple, complete demonstration program to get you started with using PCRE2 is
+supplied in the file <i>pcre2demo.c</i> in the <b>src</b> directory in the PCRE2
+distribution. A listing of this program is given in the
+<a href="pcre2demo.html"><b>pcre2demo</b></a>
+documentation. If you do not have a copy of the PCRE2 distribution, you can
+save this listing to re-create the contents of <i>pcre2demo.c</i>.
+</P>
+<P>
+The demonstration program, which uses the PCRE2 8-bit library, compiles the
+regular expression that is its first argument, and matches it against the
+subject string in its second argument. No PCRE2 options are set, and default
+character tables are used. If matching succeeds, the program outputs the
+portion of the subject that matched, together with the contents of any captured
+substrings.
+</P>
+<P>
+If the -g option is given on the command line, the program then goes on to
+check for further matches of the same regular expression in the same subject
+string. The logic is a little bit tricky because of the possibility of matching
+an empty string. Comments in the code explain what is going on.
+</P>
+<P>
+If PCRE2 is installed in the standard include and library directories for your
+operating system, you should be able to compile the demonstration program using
+this command:
+<pre>
+ gcc -o pcre2demo pcre2demo.c -lpcre2-8
+</pre>
+If PCRE2 is installed elsewhere, you may need to add additional options to the
+command line. For example, on a Unix-like system that has PCRE2 installed in
+<i>/usr/local</i>, you can compile the demonstration program using a command
+like this:
+<pre>
+ gcc -o pcre2demo -I/usr/local/include pcre2demo.c -L/usr/local/lib -lpcre2-8
+
+</PRE>
+</P>
+<P>
+Once you have compiled and linked the demonstration program, you can run simple
+tests like this:
+<pre>
+ ./pcre2demo 'cat|dog' 'the cat sat on the mat'
+ ./pcre2demo -g 'cat|dog' 'the dog sat on the cat'
+</pre>
+Note that there is a much more comprehensive test program, called
+<a href="pcre2test.html"><b>pcre2test</b>,</a>
+which supports many more facilities for testing regular expressions using the
+PCRE2 libraries. The
+<a href="pcre2demo.html"><b>pcre2demo</b></a>
+program is provided as a simple coding example.
+</P>
+<P>
+If you try to run
+<a href="pcre2demo.html"><b>pcre2demo</b></a>
+when PCRE2 is not installed in the standard library directory, you may get an
+error like this on some operating systems (e.g. Solaris):
+<pre>
+ ld.so.1: a.out: fatal: libpcre2.so.0: open failed: No such file or directory
+</pre>
+This is caused by the way shared library support works on those systems. You
+need to add
+<pre>
+ -R/usr/local/lib
+</pre>
+(for example) to the compile command to get round this problem.
+</P>
+<br><b>
+AUTHOR
+</b><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><b>
+REVISION
+</b><br>
+<P>
+Last updated: 20 October 2014
+<br>
+Copyright © 1997-2014 University of Cambridge.
+<br>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
Added: code/trunk/doc/html/pcre2stack.html
===================================================================
--- code/trunk/doc/html/pcre2stack.html (rev 0)
+++ code/trunk/doc/html/pcre2stack.html 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,203 @@
+<html>
+<head>
+<title>pcre2stack specification</title>
+</head>
+<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
+<h1>pcre2stack man page</h1>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
+<p>
+This page is part of the PCRE2 HTML documentation. It was generated
+automatically from the original man page. If there is any nonsense in it,
+please consult the man page, in case the conversion went wrong.
+<br>
+<br><b>
+PCRE2 DISCUSSION OF STACK USAGE
+</b><br>
+<P>
+When you call <b>pcre2_match()</b>, it makes use of an internal function called
+<b>match()</b>. This calls itself recursively at branch points in the pattern,
+in order to remember the state of the match so that it can back up and try a
+different alternative after a failure. As matching proceeds deeper and deeper
+into the tree of possibilities, the recursion depth increases. The
+<b>match()</b> function is also called in other circumstances, for example,
+whenever a parenthesized sub-pattern is entered, and in certain cases of
+repetition.
+</P>
+<P>
+Not all calls of <b>match()</b> increase the recursion depth; for an item such
+as a* it may be called several times at the same level, after matching
+different numbers of a's. Furthermore, in a number of cases where the result of
+the recursive call would immediately be passed back as the result of the
+current call (a "tail recursion"), the function is just restarted instead.
+</P>
+<P>
+The above comments apply when <b>pcre2_match()</b> is run in its normal
+interpretive manner. If the compiled pattern was processed by
+<b>pcre2_jit_compile()</b>, and just-in-time compiling was successful, and the
+options passed to <b>pcre2_match()</b> were not incompatible, the matching
+process uses the JIT-compiled code instead of the <b>match()</b> function. In
+this case, the memory requirements are handled entirely differently. See the
+<a href="pcre2jit.html"><b>pcre2jit</b></a>
+documentation for details.
+</P>
+<P>
+The <b>pcre2_dfa_match()</b> function operates in a different way to
+<b>pcre2_match()</b>, and uses recursion only when there is a regular expression
+recursion or subroutine call in the pattern. This includes the processing of
+assertion and "once-only" subpatterns, which are handled like subroutine calls.
+Normally, these are never very deep, and the limit on the complexity of
+<b>pcre2_dfa_match()</b> is controlled by the amount of workspace it is given.
+However, it is possible to write patterns with runaway infinite recursions;
+such patterns will cause <b>pcre2_dfa_match()</b> to run out of stack. At
+present, there is no protection against this.
+</P>
+<P>
+The comments that follow do NOT apply to <b>pcre2_dfa_match()</b>; they are
+relevant only for <b>pcre2_match()</b> without the JIT optimization.
+</P>
+<br><b>
+Reducing <b>pcre2_match()</b>'s stack usage
+</b><br>
+<P>
+Each time that the internal <b>match()</b> function is called recursively, it
+uses memory from the process stack. For certain kinds of pattern and data, very
+large amounts of stack may be needed, despite the recognition of "tail
+recursion". You can often reduce the amount of recursion, and therefore the
+amount of stack used, by modifying the pattern that is being matched. Consider,
+for example, this pattern:
+<pre>
+ ([^<]|<(?!inet))+
+</pre>
+It matches from wherever it starts until it encounters "<inet" or the end of
+the data, and is the kind of pattern that might be used when processing an XML
+file. Each iteration of the outer parentheses matches either one character that
+is not "<" or a "<" that is not followed by "inet". However, each time a
+parenthesis is processed, a recursion occurs, so this formulation uses a stack
+frame for each matched character. For a long string, a lot of stack is
+required. Consider now this rewritten pattern, which matches exactly the same
+strings:
+<pre>
+ ([^<]++|<(?!inet))+
+</pre>
+This uses very much less stack, because runs of characters that do not contain
+"<" are "swallowed" in one item inside the parentheses. Recursion happens only
+when a "<" character that is not followed by "inet" is encountered (and we
+assume this is relatively rare). A possessive quantifier is used to stop any
+backtracking into the runs of non-"<" characters, but that is not related to
+stack usage.
+</P>
+<P>
+This example shows that one way of avoiding stack problems when matching long
+subject strings is to write repeated parenthesized subpatterns to match more
+than one character whenever possible.
+</P>
+<br><b>
+Compiling PCRE2 to use heap instead of stack for <b>pcre2_match()</b>
+</b><br>
+<P>
+In environments where stack memory is constrained, you might want to compile
+PCRE2 to use heap memory instead of stack for remembering back-up points when
+<b>pcre2_match()</b> is running. This makes it run more slowly, however. Details
+of how to do this are given in the
+<a href="pcre2build.html"><b>pcre2build</b></a>
+documentation. When built in this way, instead of using the stack, PCRE2
+gets memory for remembering backup points from the heap. By default, the memory
+is obtained by calling the system <b>malloc()</b> function, but you can arrange
+to supply your own memory management function. For details, see the section
+entitled
+<a href="pcre2api.html#matchcontext">"The match context"</a>
+in the
+<a href="pcre2api.html"><b>pcre2api</b></a>
+documentation. Since the block sizes are always the same, it may be possible to
+implement customized a memory handler that is more efficient than the standard
+function. The memory blocks obtained for this purpose are retained and re-used
+if possible while <b>pcre2_match()</b> is running. They are all freed just
+before it exits.
+</P>
+<br><b>
+Limiting <b>pcre2_match()</b>'s stack usage
+</b><br>
+<P>
+You can set limits on the number of times the internal <b>match()</b> function
+is called, both in total and recursively. If a limit is exceeded,
+<b>pcre2_match()</b> returns an error code. Setting suitable limits should
+prevent it from running out of stack. The default values of the limits are very
+large, and unlikely ever to operate. They can be changed when PCRE2 is built,
+and they can also be set when <b>pcre2_match()</b> is called. For details of
+these interfaces, see the
+<a href="pcre2build.html"><b>pcre2build</b></a>
+documentation and the section entitled
+<a href="pcre2api.html#matchcontext">"The match context"</a>
+in the
+<a href="pcre2api.html"><b>pcre2api</b></a>
+documentation.
+</P>
+<P>
+As a very rough rule of thumb, you should reckon on about 500 bytes per
+recursion. Thus, if you want to limit your stack usage to 8Mb, you should set
+the limit at 16000 recursions. A 64Mb stack, on the other hand, can support
+around 128000 recursions.
+</P>
+<P>
+The <b>pcre2test</b> test program has a modifier called "find_limits" which, if
+applied to a subject line, causes it to find the smallest limits that allow a a
+pattern to match. This is done by calling <b>pcre2_match()</b> repeatedly with
+different limits.
+</P>
+<br><b>
+Changing stack size in Unix-like systems
+</b><br>
+<P>
+In Unix-like environments, there is not often a problem with the stack unless
+very long strings are involved, though the default limit on stack size varies
+from system to system. Values from 8Mb to 64Mb are common. You can find your
+default limit by running the command:
+<pre>
+ ulimit -s
+</pre>
+Unfortunately, the effect of running out of stack is often SIGSEGV, though
+sometimes a more explicit error message is given. You can normally increase the
+limit on stack size by code such as this:
+<pre>
+ struct rlimit rlim;
+ getrlimit(RLIMIT_STACK, &rlim);
+ rlim.rlim_cur = 100*1024*1024;
+ setrlimit(RLIMIT_STACK, &rlim);
+</pre>
+This reads the current limits (soft and hard) using <b>getrlimit()</b>, then
+attempts to increase the soft limit to 100Mb using <b>setrlimit()</b>. You must
+do this before calling <b>pcre2_match()</b>.
+</P>
+<br><b>
+Changing stack size in Mac OS X
+</b><br>
+<P>
+Using <b>setrlimit()</b>, as described above, should also work on Mac OS X. It
+is also possible to set a stack size when linking a program. There is a
+discussion about stack sizes in Mac OS X at this web site:
+<a href="http://developer.apple.com/qa/qa2005/qa1419.html">http://developer.apple.com/qa/qa2005/qa1419.html.</a>
+</P>
+<br><b>
+AUTHOR
+</b><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><b>
+REVISION
+</b><br>
+<P>
+Last updated: 20 October 2014
+<br>
+Copyright © 1997-2014 University of Cambridge.
+<br>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
Added: code/trunk/doc/html/pcre2syntax.html
===================================================================
--- code/trunk/doc/html/pcre2syntax.html (rev 0)
+++ code/trunk/doc/html/pcre2syntax.html 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,561 @@
+<html>
+<head>
+<title>pcre2syntax specification</title>
+</head>
+<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
+<h1>pcre2syntax man page</h1>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
+<p>
+This page is part of the PCRE2 HTML documentation. It was generated
+automatically from the original man page. If there is any nonsense in it,
+please consult the man page, in case the conversion went wrong.
+<br>
+<ul>
+<li><a name="TOC1" href="#SEC1">PCRE2 REGULAR EXPRESSION SYNTAX SUMMARY</a>
+<li><a name="TOC2" href="#SEC2">QUOTING</a>
+<li><a name="TOC3" href="#SEC3">CHARACTERS</a>
+<li><a name="TOC4" href="#SEC4">CHARACTER TYPES</a>
+<li><a name="TOC5" href="#SEC5">GENERAL CATEGORY PROPERTIES FOR \p and \P</a>
+<li><a name="TOC6" href="#SEC6">PCRE2 SPECIAL CATEGORY PROPERTIES FOR \p and \P</a>
+<li><a name="TOC7" href="#SEC7">SCRIPT NAMES FOR \p AND \P</a>
+<li><a name="TOC8" href="#SEC8">CHARACTER CLASSES</a>
+<li><a name="TOC9" href="#SEC9">QUANTIFIERS</a>
+<li><a name="TOC10" href="#SEC10">ANCHORS AND SIMPLE ASSERTIONS</a>
+<li><a name="TOC11" href="#SEC11">MATCH POINT RESET</a>
+<li><a name="TOC12" href="#SEC12">ALTERNATION</a>
+<li><a name="TOC13" href="#SEC13">CAPTURING</a>
+<li><a name="TOC14" href="#SEC14">ATOMIC GROUPS</a>
+<li><a name="TOC15" href="#SEC15">COMMENT</a>
+<li><a name="TOC16" href="#SEC16">OPTION SETTING</a>
+<li><a name="TOC17" href="#SEC17">NEWLINE CONVENTION</a>
+<li><a name="TOC18" href="#SEC18">WHAT \R MATCHES</a>
+<li><a name="TOC19" href="#SEC19">LOOKAHEAD AND LOOKBEHIND ASSERTIONS</a>
+<li><a name="TOC20" href="#SEC20">BACKREFERENCES</a>
+<li><a name="TOC21" href="#SEC21">SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)</a>
+<li><a name="TOC22" href="#SEC22">CONDITIONAL PATTERNS</a>
+<li><a name="TOC23" href="#SEC23">BACKTRACKING CONTROL</a>
+<li><a name="TOC24" href="#SEC24">CALLOUTS</a>
+<li><a name="TOC25" href="#SEC25">SEE ALSO</a>
+<li><a name="TOC26" href="#SEC26">AUTHOR</a>
+<li><a name="TOC27" href="#SEC27">REVISION</a>
+</ul>
+<br><a name="SEC1" href="#TOC1">PCRE2 REGULAR EXPRESSION SYNTAX SUMMARY</a><br>
+<P>
+The full syntax and semantics of the regular expressions that are supported by
+PCRE2 are described in the
+<a href="pcre2pattern.html"><b>pcre2pattern</b></a>
+documentation. This document contains a quick-reference summary of the syntax.
+</P>
+<br><a name="SEC2" href="#TOC1">QUOTING</a><br>
+<P>
+<pre>
+ \x where x is non-alphanumeric is a literal x
+ \Q...\E treat enclosed characters as literal
+</PRE>
+</P>
+<br><a name="SEC3" href="#TOC1">CHARACTERS</a><br>
+<P>
+<pre>
+ \a alarm, that is, the BEL character (hex 07)
+ \cx "control-x", where x is any ASCII character
+ \e escape (hex 1B)
+ \f form feed (hex 0C)
+ \n newline (hex 0A)
+ \r carriage return (hex 0D)
+ \t tab (hex 09)
+ \0dd character with octal code 0dd
+ \ddd character with octal code ddd, or backreference
+ \o{ddd..} character with octal code ddd..
+ \xhh character with hex code hh
+ \x{hhh..} character with hex code hhh..
+</pre>
+Note that \0dd is always an octal code, and that \8 and \9 are the literal
+characters "8" and "9".
+</P>
+<br><a name="SEC4" href="#TOC1">CHARACTER TYPES</a><br>
+<P>
+<pre>
+ . any character except newline;
+ in dotall mode, any character whatsoever
+ \C one data unit, even in UTF mode (best avoided)
+ \d a decimal digit
+ \D a character that is not a decimal digit
+ \h a horizontal white space character
+ \H a character that is not a horizontal white space character
+ \N a character that is not a newline
+ \p{<i>xx</i>} a character with the <i>xx</i> property
+ \P{<i>xx</i>} a character without the <i>xx</i> property
+ \R a newline sequence
+ \s a white space character
+ \S a character that is not a white space character
+ \v a vertical white space character
+ \V a character that is not a vertical white space character
+ \w a "word" character
+ \W a "non-word" character
+ \X a Unicode extended grapheme cluster
+</pre>
+By default, \d, \s, and \w match only ASCII characters, even in UTF-8 mode
+or in the 16-bit and 32-bit libraries. However, if locale-specific matching is
+happening, \s and \w may also match characters with code points in the range
+128-255. If the PCRE2_UCP option is set, the behaviour of these escape
+sequences is changed to use Unicode properties and they match many more
+characters.
+</P>
+<br><a name="SEC5" href="#TOC1">GENERAL CATEGORY PROPERTIES FOR \p and \P</a><br>
+<P>
+<pre>
+ C Other
+ Cc Control
+ Cf Format
+ Cn Unassigned
+ Co Private use
+ Cs Surrogate
+
+ L Letter
+ Ll Lower case letter
+ Lm Modifier letter
+ Lo Other letter
+ Lt Title case letter
+ Lu Upper case letter
+ L& Ll, Lu, or Lt
+
+ M Mark
+ Mc Spacing mark
+ Me Enclosing mark
+ Mn Non-spacing mark
+
+ N Number
+ Nd Decimal number
+ Nl Letter number
+ No Other number
+
+ P Punctuation
+ Pc Connector punctuation
+ Pd Dash punctuation
+ Pe Close punctuation
+ Pf Final punctuation
+ Pi Initial punctuation
+ Po Other punctuation
+ Ps Open punctuation
+
+ S Symbol
+ Sc Currency symbol
+ Sk Modifier symbol
+ Sm Mathematical symbol
+ So Other symbol
+
+ Z Separator
+ Zl Line separator
+ Zp Paragraph separator
+ Zs Space separator
+</PRE>
+</P>
+<br><a name="SEC6" href="#TOC1">PCRE2 SPECIAL CATEGORY PROPERTIES FOR \p and \P</a><br>
+<P>
+<pre>
+ Xan Alphanumeric: union of properties L and N
+ Xps POSIX space: property Z or tab, NL, VT, FF, CR
+ Xsp Perl space: property Z or tab, NL, VT, FF, CR
+ Xuc Univerally-named character: one that can be
+ represented by a Universal Character Name
+ Xwd Perl word: property Xan or underscore
+</pre>
+Perl and POSIX space are now the same. Perl added VT to its space character set
+at release 5.18.
+</P>
+<br><a name="SEC7" href="#TOC1">SCRIPT NAMES FOR \p AND \P</a><br>
+<P>
+Arabic,
+Armenian,
+Avestan,
+Balinese,
+Bamum,
+Bassa_Vah,
+Batak,
+Bengali,
+Bopomofo,
+Brahmi,
+Braille,
+Buginese,
+Buhid,
+Canadian_Aboriginal,
+Carian,
+Caucasian_Albanian,
+Chakma,
+Cham,
+Cherokee,
+Common,
+Coptic,
+Cuneiform,
+Cypriot,
+Cyrillic,
+Deseret,
+Devanagari,
+Duployan,
+Egyptian_Hieroglyphs,
+Elbasan,
+Ethiopic,
+Georgian,
+Glagolitic,
+Gothic,
+Grantha,
+Greek,
+Gujarati,
+Gurmukhi,
+Han,
+Hangul,
+Hanunoo,
+Hebrew,
+Hiragana,
+Imperial_Aramaic,
+Inherited,
+Inscriptional_Pahlavi,
+Inscriptional_Parthian,
+Javanese,
+Kaithi,
+Kannada,
+Katakana,
+Kayah_Li,
+Kharoshthi,
+Khmer,
+Khojki,
+Khudawadi,
+Lao,
+Latin,
+Lepcha,
+Limbu,
+Linear_A,
+Linear_B,
+Lisu,
+Lycian,
+Lydian,
+Mahajani,
+Malayalam,
+Mandaic,
+Manichaean,
+Meetei_Mayek,
+Mende_Kikakui,
+Meroitic_Cursive,
+Meroitic_Hieroglyphs,
+Miao,
+Modi,
+Mongolian,
+Mro,
+Myanmar,
+Nabataean,
+New_Tai_Lue,
+Nko,
+Ogham,
+Ol_Chiki,
+Old_Italic,
+Old_North_Arabian,
+Old_Permic,
+Old_Persian,
+Old_South_Arabian,
+Old_Turkic,
+Oriya,
+Osmanya,
+Pahawh_Hmong,
+Palmyrene,
+Pau_Cin_Hau,
+Phags_Pa,
+Phoenician,
+Psalter_Pahlavi,
+Rejang,
+Runic,
+Samaritan,
+Saurashtra,
+Sharada,
+Shavian,
+Siddham,
+Sinhala,
+Sora_Sompeng,
+Sundanese,
+Syloti_Nagri,
+Syriac,
+Tagalog,
+Tagbanwa,
+Tai_Le,
+Tai_Tham,
+Tai_Viet,
+Takri,
+Tamil,
+Telugu,
+Thaana,
+Thai,
+Tibetan,
+Tifinagh,
+Tirhuta,
+Ugaritic,
+Vai,
+Warang_Citi,
+Yi.
+</P>
+<br><a name="SEC8" href="#TOC1">CHARACTER CLASSES</a><br>
+<P>
+<pre>
+ [...] positive character class
+ [^...] negative character class
+ [x-y] range (can be used for hex characters)
+ [[:xxx:]] positive POSIX named set
+ [[:^xxx:]] negative POSIX named set
+
+ alnum alphanumeric
+ alpha alphabetic
+ ascii 0-127
+ blank space or tab
+ cntrl control character
+ digit decimal digit
+ graph printing, excluding space
+ lower lower case letter
+ print printing, including space
+ punct printing, excluding alphanumeric
+ space white space
+ upper upper case letter
+ word same as \w
+ xdigit hexadecimal digit
+</pre>
+In PCRE2, POSIX character set names recognize only ASCII characters by default,
+but some of them use Unicode properties if PCRE2_UCP is set. You can use
+\Q...\E inside a character class.
+</P>
+<br><a name="SEC9" href="#TOC1">QUANTIFIERS</a><br>
+<P>
+<pre>
+ ? 0 or 1, greedy
+ ?+ 0 or 1, possessive
+ ?? 0 or 1, lazy
+ * 0 or more, greedy
+ *+ 0 or more, possessive
+ *? 0 or more, lazy
+ + 1 or more, greedy
+ ++ 1 or more, possessive
+ +? 1 or more, lazy
+ {n} exactly n
+ {n,m} at least n, no more than m, greedy
+ {n,m}+ at least n, no more than m, possessive
+ {n,m}? at least n, no more than m, lazy
+ {n,} n or more, greedy
+ {n,}+ n or more, possessive
+ {n,}? n or more, lazy
+</PRE>
+</P>
+<br><a name="SEC10" href="#TOC1">ANCHORS AND SIMPLE ASSERTIONS</a><br>
+<P>
+<pre>
+ \b word boundary
+ \B not a word boundary
+ ^ start of subject
+ also after internal newline in multiline mode
+ \A start of subject
+ $ end of subject
+ also before newline at end of subject
+ also before internal newline in multiline mode
+ \Z end of subject
+ also before newline at end of subject
+ \z end of subject
+ \G first matching position in subject
+</PRE>
+</P>
+<br><a name="SEC11" href="#TOC1">MATCH POINT RESET</a><br>
+<P>
+<pre>
+ \K reset start of match
+</pre>
+\K is honoured in positive assertions, but ignored in negative ones.
+</P>
+<br><a name="SEC12" href="#TOC1">ALTERNATION</a><br>
+<P>
+<pre>
+ expr|expr|expr...
+</PRE>
+</P>
+<br><a name="SEC13" href="#TOC1">CAPTURING</a><br>
+<P>
+<pre>
+ (...) capturing group
+ (?<name>...) named capturing group (Perl)
+ (?'name'...) named capturing group (Perl)
+ (?P<name>...) named capturing group (Python)
+ (?:...) non-capturing group
+ (?|...) non-capturing group; reset group numbers for
+ capturing groups in each alternative
+</PRE>
+</P>
+<br><a name="SEC14" href="#TOC1">ATOMIC GROUPS</a><br>
+<P>
+<pre>
+ (?>...) atomic, non-capturing group
+</PRE>
+</P>
+<br><a name="SEC15" href="#TOC1">COMMENT</a><br>
+<P>
+<pre>
+ (?#....) comment (not nestable)
+</PRE>
+</P>
+<br><a name="SEC16" href="#TOC1">OPTION SETTING</a><br>
+<P>
+<pre>
+ (?i) caseless
+ (?J) allow duplicate names
+ (?m) multiline
+ (?s) single line (dotall)
+ (?U) default ungreedy (lazy)
+ (?x) extended (ignore white space)
+ (?-...) unset option(s)
+</pre>
+The following are recognized only at the very start of a pattern or after one
+of the newline or \R options with similar syntax. More than one of them may
+appear.
+<pre>
+ (*LIMIT_MATCH=d) set the match limit to d (decimal number)
+ (*LIMIT_RECURSION=d) set the recursion limit to d (decimal number)
+ (*NOTEMPTY) set PCRE2_NOTEMPTY when matching
+ (*NOTEMPTY_ATSTART) set PCRE2_NOTEMPTY_ATSTART when matching
+ (*NO_AUTO_POSSESS) no auto-possessification (PCRE2_NO_AUTO_POSSESS)
+ (*NO_START_OPT) no start-match optimization (PCRE2_NO_START_OPTIMIZE)
+ (*UTF) set appropriate UTF mode for the library in use
+ (*UCP) set PCRE2_UCP (use Unicode properties for \d etc)
+</pre>
+Note that LIMIT_MATCH and LIMIT_RECURSION can only reduce the value of the
+limits set by the caller of pcre2_exec(), not increase them.
+</P>
+<br><a name="SEC17" href="#TOC1">NEWLINE CONVENTION</a><br>
+<P>
+These are recognized only at the very start of the pattern or after option
+settings with a similar syntax.
+<pre>
+ (*CR) carriage return only
+ (*LF) linefeed only
+ (*CRLF) carriage return followed by linefeed
+ (*ANYCRLF) all three of the above
+ (*ANY) any Unicode newline sequence
+</PRE>
+</P>
+<br><a name="SEC18" href="#TOC1">WHAT \R MATCHES</a><br>
+<P>
+These are recognized only at the very start of the pattern or after option
+setting with a similar syntax.
+<pre>
+ (*BSR_ANYCRLF) CR, LF, or CRLF
+ (*BSR_UNICODE) any Unicode newline sequence
+</PRE>
+</P>
+<br><a name="SEC19" href="#TOC1">LOOKAHEAD AND LOOKBEHIND ASSERTIONS</a><br>
+<P>
+<pre>
+ (?=...) positive look ahead
+ (?!...) negative look ahead
+ (?<=...) positive look behind
+ (?<!...) negative look behind
+</pre>
+Each top-level branch of a look behind must be of a fixed length.
+</P>
+<br><a name="SEC20" href="#TOC1">BACKREFERENCES</a><br>
+<P>
+<pre>
+ \n reference by number (can be ambiguous)
+ \gn reference by number
+ \g{n} reference by number
+ \g{-n} relative reference by number
+ \k<name> reference by name (Perl)
+ \k'name' reference by name (Perl)
+ \g{name} reference by name (Perl)
+ \k{name} reference by name (.NET)
+ (?P=name) reference by name (Python)
+</PRE>
+</P>
+<br><a name="SEC21" href="#TOC1">SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)</a><br>
+<P>
+<pre>
+ (?R) recurse whole pattern
+ (?n) call subpattern by absolute number
+ (?+n) call subpattern by relative number
+ (?-n) call subpattern by relative number
+ (?&name) call subpattern by name (Perl)
+ (?P>name) call subpattern by name (Python)
+ \g<name> call subpattern by name (Oniguruma)
+ \g'name' call subpattern by name (Oniguruma)
+ \g<n> call subpattern by absolute number (Oniguruma)
+ \g'n' call subpattern by absolute number (Oniguruma)
+ \g<+n> call subpattern by relative number (PCRE2 extension)
+ \g'+n' call subpattern by relative number (PCRE2 extension)
+ \g<-n> call subpattern by relative number (PCRE2 extension)
+ \g'-n' call subpattern by relative number (PCRE2 extension)
+</PRE>
+</P>
+<br><a name="SEC22" href="#TOC1">CONDITIONAL PATTERNS</a><br>
+<P>
+<pre>
+ (?(condition)yes-pattern)
+ (?(condition)yes-pattern|no-pattern)
+
+ (?(n)... absolute reference condition
+ (?(+n)... relative reference condition
+ (?(-n)... relative reference condition
+ (?(<name>)... named reference condition (Perl)
+ (?('name')... named reference condition (Perl)
+ (?(name)... named reference condition (PCRE2)
+ (?(R)... overall recursion condition
+ (?(Rn)... specific group recursion condition
+ (?(R&name)... specific recursion condition
+ (?(DEFINE)... define subpattern for reference
+ (?(assert)... assertion condition
+</PRE>
+</P>
+<br><a name="SEC23" href="#TOC1">BACKTRACKING CONTROL</a><br>
+<P>
+The following act immediately they are reached:
+<pre>
+ (*ACCEPT) force successful match
+ (*FAIL) force backtrack; synonym (*F)
+ (*MARK:NAME) set name to be passed back; synonym (*:NAME)
+</pre>
+The following act only when a subsequent match failure causes a backtrack to
+reach them. They all force a match failure, but they differ in what happens
+afterwards. Those that advance the start-of-match point do so only if the
+pattern is not anchored.
+<pre>
+ (*COMMIT) overall failure, no advance of starting point
+ (*PRUNE) advance to next starting character
+ (*PRUNE:NAME) equivalent to (*MARK:NAME)(*PRUNE)
+ (*SKIP) advance to current matching position
+ (*SKIP:NAME) advance to position corresponding to an earlier
+ (*MARK:NAME); if not found, the (*SKIP) is ignored
+ (*THEN) local failure, backtrack to next alternation
+ (*THEN:NAME) equivalent to (*MARK:NAME)(*THEN)
+</PRE>
+</P>
+<br><a name="SEC24" href="#TOC1">CALLOUTS</a><br>
+<P>
+<pre>
+ (?C) callout
+ (?Cn) callout with data n
+</PRE>
+</P>
+<br><a name="SEC25" href="#TOC1">SEE ALSO</a><br>
+<P>
+<b>pcre2pattern</b>(3), <b>pcre2api</b>(3), <b>pcre2callout</b>(3),
+<b>pcre2matching</b>(3), <b>pcre2</b>(3).
+</P>
+<br><a name="SEC26" href="#TOC1">AUTHOR</a><br>
+<P>
+Philip Hazel
+<br>
+University Computing Service
+<br>
+Cambridge CB2 3QH, England.
+<br>
+</P>
+<br><a name="SEC27" href="#TOC1">REVISION</a><br>
+<P>
+Last updated: 20 October 2014
+<br>
+Copyright © 1997-2014 University of Cambridge.
+<br>
+<p>
+Return to the <a href="index.html">PCRE2 index page</a>.
+</p>
Added: code/trunk/doc/pcre2perform.3
===================================================================
--- code/trunk/doc/pcre2perform.3 (rev 0)
+++ code/trunk/doc/pcre2perform.3 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,178 @@
+.TH PCRE2PERFORM 3 "20 Ocbober 2014" "PCRE2 10.00"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.SH "PCRE2 PERFORMANCE"
+.rs
+.sp
+Two aspects of performance are discussed below: memory usage and processing
+time. The way you express your pattern as a regular expression can affect both
+of them.
+.
+.SH "COMPILED PATTERN MEMORY USAGE"
+.rs
+.sp
+Patterns are compiled by PCRE2 into a reasonably efficient interpretive code,
+so that most simple patterns do not use much memory. However, there is one case
+where the memory usage of a compiled pattern can be unexpectedly large. If a
+parenthesized subpattern has a quantifier with a minimum greater than 1 and/or
+a limited maximum, the whole subpattern is repeated in the compiled code. For
+example, the pattern
+.sp
+ (abc|def){2,4}
+.sp
+is compiled as if it were
+.sp
+ (abc|def)(abc|def)((abc|def)(abc|def)?)?
+.sp
+(Technical aside: It is done this way so that backtrack points within each of
+the repetitions can be independently maintained.)
+.P
+For regular expressions whose quantifiers use only small numbers, this is not
+usually a problem. However, if the numbers are large, and particularly if such
+repetitions are nested, the memory usage can become an embarrassment. For
+example, the very simple pattern
+.sp
+ ((ab){1,1000}c){1,3}
+.sp
+uses 51K bytes when compiled using the 8-bit library. When PCRE2 is compiled
+with its default internal pointer size of two bytes, the size limit on a
+compiled pattern is 64K code units in the 8-bit and 16-bit libraries, and this
+is reached with the above pattern if the outer repetition is increased from 3
+to 4. PCRE2 can be compiled to use larger internal pointers and thus handle
+larger compiled patterns, but it is better to try to rewrite your pattern to
+use less memory if you can.
+.P
+One way of reducing the memory usage for such patterns is to make use of
+PCRE2's
+.\" HTML <a href="pcre2pattern.html#subpatternsassubroutines">
+.\" </a>
+"subroutine"
+.\"
+facility. Re-writing the above pattern as
+.sp
+ ((ab)(?2){0,999}c)(?1){0,2}
+.sp
+reduces the memory requirements to 18K, and indeed it remains under 20K even
+with the outer repetition increased to 100. However, this pattern is not
+exactly equivalent, because the "subroutine" calls are treated as
+.\" HTML <a href="pcre2pattern.html#atomicgroup">
+.\" </a>
+atomic groups
+.\"
+into which there can be no backtracking if there is a subsequent matching
+failure. Therefore, PCRE2 cannot do this kind of rewriting automatically.
+Furthermore, there is a noticeable loss of speed when executing the modified
+pattern. Nevertheless, if the atomic grouping is not a problem and the loss of
+speed is acceptable, this kind of rewriting will allow you to process patterns
+that PCRE2 cannot otherwise handle.
+.
+.
+.SH "STACK USAGE AT RUN TIME"
+.rs
+.sp
+When \fBpcre2_match()\fP is used for matching, certain kinds of pattern can
+cause it to use large amounts of the process stack. In some environments the
+default process stack is quite small, and if it runs out the result is often
+SIGSEGV. Rewriting your pattern can often help. The
+.\" HREF
+\fBpcre2stack\fP
+.\"
+documentation discusses this issue in detail.
+.
+.
+.SH "PROCESSING TIME"
+.rs
+.sp
+Certain items in regular expression patterns are processed more efficiently
+than others. It is more efficient to use a character class like [aeiou] than a
+set of single-character alternatives such as (a|e|i|o|u). In general, the
+simplest construction that provides the required behaviour is usually the most
+efficient. Jeffrey Friedl's book contains a lot of useful general discussion
+about optimizing regular expressions for efficient performance. This document
+contains a few observations about PCRE2.
+.P
+Using Unicode character properties (the \ep, \eP, and \eX escapes) is slow,
+because PCRE2 has to use a multi-stage table lookup whenever it needs a
+character's property. If you can find an alternative pattern that does not use
+character properties, it will probably be faster.
+.P
+By default, the escape sequences \eb, \ed, \es, and \ew, and the POSIX
+character classes such as [:alpha:] do not use Unicode properties, partly for
+backwards compatibility, and partly for performance reasons. However, you can
+set the PCRE2_UCP option or start the pattern with (*UCP) if you want Unicode
+character properties to be used. This can double the matching time for items
+such as \ed, when matched with \fBpcre2_match()\fP; the performance loss is
+less with a DFA matching function, and in both cases there is not much
+difference for \eb.
+.P
+When a pattern begins with .* not in parentheses, or in parentheses that are
+not the subject of a backreference, and the PCRE2_DOTALL option is set, the
+pattern is implicitly anchored by PCRE2, since it can match only at the start
+of a subject string. However, if PCRE2_DOTALL is not set, PCRE2 cannot make
+this optimization, because the dot metacharacter does not then match a newline,
+and if the subject string contains newlines, the pattern may match from the
+character immediately following one of them instead of from the very start. For
+example, the pattern
+.sp
+ .*second
+.sp
+matches the subject "first\enand second" (where \en stands for a newline
+character), with the match starting at the seventh character. In order to do
+this, PCRE2 has to retry the match starting after every newline in the subject.
+.P
+If you are using such a pattern with subject strings that do not contain
+newlines, the best performance is obtained by setting PCRE2_DOTALL, or starting
+the pattern with ^.* or ^.*? to indicate explicit anchoring. That saves PCRE2
+from having to scan along the subject looking for a newline to restart at.
+.P
+Beware of patterns that contain nested indefinite repeats. These can take a
+long time to run when applied to a string that does not match. Consider the
+pattern fragment
+.sp
+ ^(a+)*
+.sp
+This can match "aaaa" in 16 different ways, and this number increases very
+rapidly as the string gets longer. (The * repeat can match 0, 1, 2, 3, or 4
+times, and for each of those cases other than 0 or 4, the + repeats can match
+different numbers of times.) When the remainder of the pattern is such that the
+entire match is going to fail, PCRE2 has in principle to try every possible
+variation, and this can take an extremely long time, even for relatively short
+strings.
+.P
+An optimization catches some of the more simple cases such as
+.sp
+ (a+)*b
+.sp
+where a literal character follows. Before embarking on the standard matching
+procedure, PCRE2 checks that there is a "b" later in the subject string, and if
+there is not, it fails the match immediately. However, when there is no
+following literal this optimization cannot be used. You can see the difference
+by comparing the behaviour of
+.sp
+ (a+)*\ed
+.sp
+with the pattern above. The former gives a failure almost instantly when
+applied to a whole line of "a" characters, whereas the latter takes an
+appreciable time with strings longer than about 20 characters.
+.P
+In many cases, the solution to this kind of performance issue is to use an
+atomic group or a possessive quantifier.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 20 October 2014
+Copyright (c) 1997-2014 University of Cambridge.
+.fi
Added: code/trunk/doc/pcre2posix.3
===================================================================
--- code/trunk/doc/pcre2posix.3 (rev 0)
+++ code/trunk/doc/pcre2posix.3 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,268 @@
+.TH PCRE2POSIX 3 "20 October 2014" "PCRE2 10.00"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.SH "SYNOPSIS"
+.rs
+.sp
+.B #include <pcre2posix.h>
+.PP
+.nf
+.B int regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP,
+.B " int \fIcflags\fP);"
+.sp
+.B int regexec(const regex_t *\fIpreg\fP, const char *\fIstring\fP,
+.B " size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP);"
+.sp
+.B "size_t regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP,"
+.B " char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP);"
+.sp
+.B void regfree(regex_t *\fIpreg\fP);
+.fi
+.
+.SH DESCRIPTION
+.rs
+.sp
+This set of functions provides a POSIX-style API for the PCRE2 regular
+expression 8-bit library. See the
+.\" HREF
+\fBpcre2api\fP
+.\"
+documentation for a description of PCRE2's native API, which contains much
+additional functionality. There is no POSIX-style wrapper for PCRE2's 16-bit
+and 32-bit libraries.
+.P
+The functions described here are just wrapper functions that ultimately call
+the PCRE2 native API. Their prototypes are defined in the \fBpcre2posix.h\fP
+header file, and on Unix systems the library itself is called
+\fBlibpcre2-posix.a\fP, so can be accessed by adding \fB-lpcre2-posix\fP to the
+command for linking an application that uses them. Because the POSIX functions
+call the native ones, it is also necessary to add \fB-lpcre2-8\fP.
+.P
+Those POSIX option bits that can reasonably be mapped to PCRE2 native options
+have been implemented. In addition, the option REG_EXTENDED is defined with the
+value zero. This has no effect, but since programs that are written to the
+POSIX interface often use it, this makes it easier to slot in PCRE2 as a
+replacement library. Other POSIX options are not even defined.
+.P
+There are also some other options that are not defined by POSIX. These have
+been added at the request of users who want to make use of certain
+PCRE2-specific features via the POSIX calling interface.
+.P
+When PCRE2 is called via these functions, it is only the API that is POSIX-like
+in style. The syntax and semantics of the regular expressions themselves are
+still those of Perl, subject to the setting of various PCRE2 options, as
+described below. "POSIX-like in style" means that the API approximates to the
+POSIX definition; it is not fully POSIX-compatible, and in multi-unit encoding
+domains it is probably even less compatible.
+.P
+The header for these functions is supplied as \fBpcre2posix.h\fP to avoid any
+potential clash with other POSIX libraries. It can, of course, be renamed or
+aliased as \fBregex.h\fP, which is the "correct" name. It provides two
+structure types, \fIregex_t\fP for compiled internal forms, and
+\fIregmatch_t\fP for returning captured substrings. It also defines some
+constants whose names start with "REG_"; these are used for setting options and
+identifying error codes.
+.
+.
+.SH "COMPILING A PATTERN"
+.rs
+.sp
+The function \fBregcomp()\fP is called to compile a pattern into an
+internal form. The pattern is a C string terminated by a binary zero, and
+is passed in the argument \fIpattern\fP. The \fIpreg\fP argument is a pointer
+to a \fBregex_t\fP structure that is used as a base for storing information
+about the compiled regular expression.
+.P
+The argument \fIcflags\fP is either zero, or contains one or more of the bits
+defined by the following macros:
+.sp
+ REG_DOTALL
+.sp
+The PCRE2_DOTALL option is set when the regular expression is passed for
+compilation to the native function. Note that REG_DOTALL is not part of the
+POSIX standard.
+.sp
+ REG_ICASE
+.sp
+The PCRE2_CASELESS option is set when the regular expression is passed for
+compilation to the native function.
+.sp
+ REG_NEWLINE
+.sp
+The PCRE2_MULTILINE option is set when the regular expression is passed for
+compilation to the native function. Note that this does \fInot\fP mimic the
+defined POSIX behaviour for REG_NEWLINE (see the following section).
+.sp
+ REG_NOSUB
+.sp
+The PCRE2_NO_AUTO_CAPTURE option is set when the regular expression is passed
+for compilation to the native function. In addition, when a pattern that is
+compiled with this flag is passed to \fBregexec()\fP for matching, the
+\fInmatch\fP and \fIpmatch\fP arguments are ignored, and no captured strings
+are returned.
+.sp
+ REG_UCP
+.sp
+The PCRE2_UCP option is set when the regular expression is passed for
+compilation to the native function. This causes PCRE2 to use Unicode properties
+when matchine \ed, \ew, etc., instead of just recognizing ASCII values. Note
+that REG_UCP is not part of the POSIX standard.
+.sp
+ REG_UNGREEDY
+.sp
+The PCRE2_UNGREEDY option is set when the regular expression is passed for
+compilation to the native function. Note that REG_UNGREEDY is not part of the
+POSIX standard.
+.sp
+ REG_UTF
+.sp
+The PCRE2_UTF option is set when the regular expression is passed for
+compilation to the native function. This causes the pattern itself and all data
+strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF
+is not part of the POSIX standard.
+.P
+In the absence of these flags, no options are passed to the native function.
+This means the the regex is compiled with PCRE2 default semantics. In
+particular, the way it handles newline characters in the subject string is the
+Perl way, not the POSIX way. Note that setting PCRE2_MULTILINE has only
+\fIsome\fP of the effects specified for REG_NEWLINE. It does not affect the way
+newlines are matched by the dot metacharacter (they are not) or by a negative
+class such as [^a] (they are).
+.P
+The yield of \fBregcomp()\fP is zero on success, and non-zero otherwise. The
+\fIpreg\fP structure is filled in on success, and one member of the structure
+is public: \fIre_nsub\fP contains the number of capturing subpatterns in
+the regular expression. Various error codes are defined in the header file.
+.P
+NOTE: If the yield of \fBregcomp()\fP is non-zero, you must not attempt to
+use the contents of the \fIpreg\fP structure. If, for example, you pass it to
+\fBregexec()\fP, the result is undefined and your program is likely to crash.
+.
+.
+.SH "MATCHING NEWLINE CHARACTERS"
+.rs
+.sp
+This area is not simple, because POSIX and Perl take different views of things.
+It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
+never intended to be a POSIX engine. The following table lists the different
+possibilities for matching newline characters in PCRE2:
+.sp
+ Default Change with
+.sp
+ . matches newline no PCRE2_DOTALL
+ newline matches [^a] yes not changeable
+ $ matches \en at end yes PCRE2_DOLLAR_ENDONLY
+ $ matches \en in middle no PCRE2_MULTILINE
+ ^ matches \en in middle no PCRE2_MULTILINE
+.sp
+This is the equivalent table for POSIX:
+.sp
+ Default Change with
+.sp
+ . matches newline yes REG_NEWLINE
+ newline matches [^a] yes REG_NEWLINE
+ $ matches \en at end no REG_NEWLINE
+ $ matches \en in middle no REG_NEWLINE
+ ^ matches \en in middle no REG_NEWLINE
+.sp
+PCRE2's behaviour is the same as Perl's, except that there is no equivalent for
+PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there is no way to stop
+newline from matching [^a].
+.P
+The default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
+PCRE2_DOLLAR_ENDONLY, but there is no way to make PCRE2 behave exactly as for
+the REG_NEWLINE action.
+.
+.
+.SH "MATCHING A PATTERN"
+.rs
+.sp
+The function \fBregexec()\fP is called to match a compiled pattern \fIpreg\fP
+against a given \fIstring\fP, which is by default terminated by a zero byte
+(but see REG_STARTEND below), subject to the options in \fIeflags\fP. These can
+be:
+.sp
+ REG_NOTBOL
+.sp
+The PCRE2_NOTBOL option is set when calling the underlying PCRE2 matching
+function.
+.sp
+ REG_NOTEMPTY
+.sp
+The PCRE2_NOTEMPTY option is set when calling the underlying PCRE2 matching
+function. Note that REG_NOTEMPTY is not part of the POSIX standard. However,
+setting this option can give more POSIX-like behaviour in some situations.
+.sp
+ REG_NOTEOL
+.sp
+The PCRE2_NOTEOL option is set when calling the underlying PCRE2 matching
+function.
+.sp
+ REG_STARTEND
+.sp
+The string is considered to start at \fIstring\fP + \fIpmatch[0].rm_so\fP and
+to have a terminating NUL located at \fIstring\fP + \fIpmatch[0].rm_eo\fP
+(there need not actually be a NUL at that location), regardless of the value of
+\fInmatch\fP. This is a BSD extension, compatible with but not specified by
+IEEE Standard 1003.2 (POSIX.2), and should be used with caution in software
+intended to be portable to other systems. Note that a non-zero \fIrm_so\fP does
+not imply REG_NOTBOL; REG_STARTEND affects only the location of the string, not
+how it is matched.
+.P
+If the pattern was compiled with the REG_NOSUB flag, no data about any matched
+strings is returned. The \fInmatch\fP and \fIpmatch\fP arguments of
+\fBregexec()\fP are ignored.
+.P
+If the value of \fInmatch\fP is zero, or if the value \fIpmatch\fP is NULL,
+no data about any matched strings is returned.
+.P
+Otherwise,the portion of the string that was matched, and also any captured
+substrings, are returned via the \fIpmatch\fP argument, which points to an
+array of \fInmatch\fP structures of type \fIregmatch_t\fP, containing the
+members \fIrm_so\fP and \fIrm_eo\fP. These contain the byte offset to the first
+character of each substring and the offset to the first character after the end
+of each substring, respectively. The 0th element of the vector relates to the
+entire portion of \fIstring\fP that was matched; subsequent elements relate to
+the capturing subpatterns of the regular expression. Unused entries in the
+array have both structure members set to -1.
+.P
+A successful match yields a zero return; various error codes are defined in the
+header file, of which REG_NOMATCH is the "expected" failure code.
+.
+.
+.SH "ERROR MESSAGES"
+.rs
+.sp
+The \fBregerror()\fP function maps a non-zero errorcode from either
+\fBregcomp()\fP or \fBregexec()\fP to a printable message. If \fIpreg\fP is not
+NULL, the error should have arisen from the use of that structure. A message
+terminated by a binary zero is placed in \fIerrbuf\fP. The length of the
+message, including the zero, is limited to \fIerrbuf_size\fP. The yield of the
+function is the size of buffer needed to hold the whole message.
+.
+.
+.SH MEMORY USAGE
+.rs
+.sp
+Compiling a regular expression causes memory to be allocated and associated
+with the \fIpreg\fP structure. The function \fBregfree()\fP frees all such
+memory, after which \fIpreg\fP may no longer be used as a compiled expression.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 20 October 2014
+Copyright (c) 1997-2014 University of Cambridge.
+.fi
Added: code/trunk/doc/pcre2sample.3
===================================================================
--- code/trunk/doc/pcre2sample.3 (rev 0)
+++ code/trunk/doc/pcre2sample.3 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,94 @@
+.TH PCRE2SAMPLE 3 "20 October 2014" "PCRE2 10.00"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.SH "PCRE2 SAMPLE PROGRAM"
+.rs
+.sp
+A simple, complete demonstration program to get you started with using PCRE2 is
+supplied in the file \fIpcre2demo.c\fP in the \fBsrc\fP directory in the PCRE2
+distribution. A listing of this program is given in the
+.\" HREF
+\fBpcre2demo\fP
+.\"
+documentation. If you do not have a copy of the PCRE2 distribution, you can
+save this listing to re-create the contents of \fIpcre2demo.c\fP.
+.P
+The demonstration program, which uses the PCRE2 8-bit library, compiles the
+regular expression that is its first argument, and matches it against the
+subject string in its second argument. No PCRE2 options are set, and default
+character tables are used. If matching succeeds, the program outputs the
+portion of the subject that matched, together with the contents of any captured
+substrings.
+.P
+If the -g option is given on the command line, the program then goes on to
+check for further matches of the same regular expression in the same subject
+string. The logic is a little bit tricky because of the possibility of matching
+an empty string. Comments in the code explain what is going on.
+.P
+If PCRE2 is installed in the standard include and library directories for your
+operating system, you should be able to compile the demonstration program using
+this command:
+.sp
+ gcc -o pcre2demo pcre2demo.c -lpcre2-8
+.sp
+If PCRE2 is installed elsewhere, you may need to add additional options to the
+command line. For example, on a Unix-like system that has PCRE2 installed in
+\fI/usr/local\fP, you can compile the demonstration program using a command
+like this:
+.sp
+.\" JOINSH
+ gcc -o pcre2demo -I/usr/local/include pcre2demo.c \e
+ -L/usr/local/lib -lpcre2-8
+.sp
+.P
+Once you have compiled and linked the demonstration program, you can run simple
+tests like this:
+.sp
+ ./pcre2demo 'cat|dog' 'the cat sat on the mat'
+ ./pcre2demo -g 'cat|dog' 'the dog sat on the cat'
+.sp
+Note that there is a much more comprehensive test program, called
+.\" HREF
+\fBpcre2test\fP,
+.\"
+which supports many more facilities for testing regular expressions using the
+PCRE2 libraries. The
+.\" HREF
+\fBpcre2demo\fP
+.\"
+program is provided as a simple coding example.
+.P
+If you try to run
+.\" HREF
+\fBpcre2demo\fP
+.\"
+when PCRE2 is not installed in the standard library directory, you may get an
+error like this on some operating systems (e.g. Solaris):
+.sp
+ ld.so.1: a.out: fatal: libpcre2.so.0: open failed: No such file or directory
+.sp
+This is caused by the way shared library support works on those systems. You
+need to add
+.sp
+ -R/usr/local/lib
+.sp
+(for example) to the compile command to get round this problem.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 20 October 2014
+Copyright (c) 1997-2014 University of Cambridge.
+.fi
Added: code/trunk/doc/pcre2stack.3
===================================================================
--- code/trunk/doc/pcre2stack.3 (rev 0)
+++ code/trunk/doc/pcre2stack.3 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,199 @@
+.TH PCRE2STACK 3 "20 October 2014" "PCRE2 10.00"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.SH "PCRE2 DISCUSSION OF STACK USAGE"
+.rs
+.sp
+When you call \fBpcre2_match()\fP, it makes use of an internal function called
+\fBmatch()\fP. This calls itself recursively at branch points in the pattern,
+in order to remember the state of the match so that it can back up and try a
+different alternative after a failure. As matching proceeds deeper and deeper
+into the tree of possibilities, the recursion depth increases. The
+\fBmatch()\fP function is also called in other circumstances, for example,
+whenever a parenthesized sub-pattern is entered, and in certain cases of
+repetition.
+.P
+Not all calls of \fBmatch()\fP increase the recursion depth; for an item such
+as a* it may be called several times at the same level, after matching
+different numbers of a's. Furthermore, in a number of cases where the result of
+the recursive call would immediately be passed back as the result of the
+current call (a "tail recursion"), the function is just restarted instead.
+.P
+The above comments apply when \fBpcre2_match()\fP is run in its normal
+interpretive manner. If the compiled pattern was processed by
+\fBpcre2_jit_compile()\fP, and just-in-time compiling was successful, and the
+options passed to \fBpcre2_match()\fP were not incompatible, the matching
+process uses the JIT-compiled code instead of the \fBmatch()\fP function. In
+this case, the memory requirements are handled entirely differently. See the
+.\" HREF
+\fBpcre2jit\fP
+.\"
+documentation for details.
+.P
+The \fBpcre2_dfa_match()\fP function operates in a different way to
+\fBpcre2_match()\fP, and uses recursion only when there is a regular expression
+recursion or subroutine call in the pattern. This includes the processing of
+assertion and "once-only" subpatterns, which are handled like subroutine calls.
+Normally, these are never very deep, and the limit on the complexity of
+\fBpcre2_dfa_match()\fP is controlled by the amount of workspace it is given.
+However, it is possible to write patterns with runaway infinite recursions;
+such patterns will cause \fBpcre2_dfa_match()\fP to run out of stack. At
+present, there is no protection against this.
+.P
+The comments that follow do NOT apply to \fBpcre2_dfa_match()\fP; they are
+relevant only for \fBpcre2_match()\fP without the JIT optimization.
+.
+.
+.SS "Reducing \fBpcre2_match()\fP's stack usage"
+.rs
+.sp
+Each time that the internal \fBmatch()\fP function is called recursively, it
+uses memory from the process stack. For certain kinds of pattern and data, very
+large amounts of stack may be needed, despite the recognition of "tail
+recursion". You can often reduce the amount of recursion, and therefore the
+amount of stack used, by modifying the pattern that is being matched. Consider,
+for example, this pattern:
+.sp
+ ([^<]|<(?!inet))+
+.sp
+It matches from wherever it starts until it encounters "<inet" or the end of
+the data, and is the kind of pattern that might be used when processing an XML
+file. Each iteration of the outer parentheses matches either one character that
+is not "<" or a "<" that is not followed by "inet". However, each time a
+parenthesis is processed, a recursion occurs, so this formulation uses a stack
+frame for each matched character. For a long string, a lot of stack is
+required. Consider now this rewritten pattern, which matches exactly the same
+strings:
+.sp
+ ([^<]++|<(?!inet))+
+.sp
+This uses very much less stack, because runs of characters that do not contain
+"<" are "swallowed" in one item inside the parentheses. Recursion happens only
+when a "<" character that is not followed by "inet" is encountered (and we
+assume this is relatively rare). A possessive quantifier is used to stop any
+backtracking into the runs of non-"<" characters, but that is not related to
+stack usage.
+.P
+This example shows that one way of avoiding stack problems when matching long
+subject strings is to write repeated parenthesized subpatterns to match more
+than one character whenever possible.
+.
+.
+.SS "Compiling PCRE2 to use heap instead of stack for \fBpcre2_match()\fP"
+.rs
+.sp
+In environments where stack memory is constrained, you might want to compile
+PCRE2 to use heap memory instead of stack for remembering back-up points when
+\fBpcre2_match()\fP is running. This makes it run more slowly, however. Details
+of how to do this are given in the
+.\" HREF
+\fBpcre2build\fP
+.\"
+documentation. When built in this way, instead of using the stack, PCRE2
+gets memory for remembering backup points from the heap. By default, the memory
+is obtained by calling the system \fBmalloc()\fP function, but you can arrange
+to supply your own memory management function. For details, see the section
+entitled
+.\" HTML <a href="pcre2api.html#matchcontext">
+.\" </a>
+"The match context"
+.\"
+in the
+.\" HREF
+\fBpcre2api\fP
+.\"
+documentation. Since the block sizes are always the same, it may be possible to
+implement customized a memory handler that is more efficient than the standard
+function. The memory blocks obtained for this purpose are retained and re-used
+if possible while \fBpcre2_match()\fP is running. They are all freed just
+before it exits.
+.
+.
+.SS "Limiting \fBpcre2_match()\fP's stack usage"
+.rs
+.sp
+You can set limits on the number of times the internal \fBmatch()\fP function
+is called, both in total and recursively. If a limit is exceeded,
+\fBpcre2_match()\fP returns an error code. Setting suitable limits should
+prevent it from running out of stack. The default values of the limits are very
+large, and unlikely ever to operate. They can be changed when PCRE2 is built,
+and they can also be set when \fBpcre2_match()\fP is called. For details of
+these interfaces, see the
+.\" HREF
+\fBpcre2build\fP
+.\"
+documentation and the section entitled
+.\" HTML <a href="pcre2api.html#matchcontext">
+.\" </a>
+"The match context"
+.\"
+in the
+.\" HREF
+\fBpcre2api\fP
+.\"
+documentation.
+.P
+As a very rough rule of thumb, you should reckon on about 500 bytes per
+recursion. Thus, if you want to limit your stack usage to 8Mb, you should set
+the limit at 16000 recursions. A 64Mb stack, on the other hand, can support
+around 128000 recursions.
+.P
+The \fBpcre2test\fP test program has a modifier called "find_limits" which, if
+applied to a subject line, causes it to find the smallest limits that allow a a
+pattern to match. This is done by calling \fBpcre2_match()\fP repeatedly with
+different limits.
+.
+.
+.SS "Changing stack size in Unix-like systems"
+.rs
+.sp
+In Unix-like environments, there is not often a problem with the stack unless
+very long strings are involved, though the default limit on stack size varies
+from system to system. Values from 8Mb to 64Mb are common. You can find your
+default limit by running the command:
+.sp
+ ulimit -s
+.sp
+Unfortunately, the effect of running out of stack is often SIGSEGV, though
+sometimes a more explicit error message is given. You can normally increase the
+limit on stack size by code such as this:
+.sp
+ struct rlimit rlim;
+ getrlimit(RLIMIT_STACK, &rlim);
+ rlim.rlim_cur = 100*1024*1024;
+ setrlimit(RLIMIT_STACK, &rlim);
+.sp
+This reads the current limits (soft and hard) using \fBgetrlimit()\fP, then
+attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must
+do this before calling \fBpcre2_match()\fP.
+.
+.
+.SS "Changing stack size in Mac OS X"
+.rs
+.sp
+Using \fBsetrlimit()\fP, as described above, should also work on Mac OS X. It
+is also possible to set a stack size when linking a program. There is a
+discussion about stack sizes in Mac OS X at this web site:
+.\" HTML <a href="http://developer.apple.com/qa/qa2005/qa1419.html">
+.\" </a>
+http://developer.apple.com/qa/qa2005/qa1419.html.
+.\"
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 20 October 2014
+Copyright (c) 1997-2014 University of Cambridge.
+.fi
Added: code/trunk/doc/pcre2syntax.3
===================================================================
--- code/trunk/doc/pcre2syntax.3 (rev 0)
+++ code/trunk/doc/pcre2syntax.3 2014-10-20 16:48:14 UTC (rev 119)
@@ -0,0 +1,540 @@
+.TH PCRE2SYNTAX 3 "20 October 2014" "PCRE2 10.00"
+.SH NAME
+PCRE2 - Perl-compatible regular expressions (revised API)
+.SH "PCRE2 REGULAR EXPRESSION SYNTAX SUMMARY"
+.rs
+.sp
+The full syntax and semantics of the regular expressions that are supported by
+PCRE2 are described in the
+.\" HREF
+\fBpcre2pattern\fP
+.\"
+documentation. This document contains a quick-reference summary of the syntax.
+.
+.
+.SH "QUOTING"
+.rs
+.sp
+ \ex where x is non-alphanumeric is a literal x
+ \eQ...\eE treat enclosed characters as literal
+.
+.
+.SH "CHARACTERS"
+.rs
+.sp
+ \ea alarm, that is, the BEL character (hex 07)
+ \ecx "control-x", where x is any ASCII character
+ \ee escape (hex 1B)
+ \ef form feed (hex 0C)
+ \en newline (hex 0A)
+ \er carriage return (hex 0D)
+ \et tab (hex 09)
+ \e0dd character with octal code 0dd
+ \eddd character with octal code ddd, or backreference
+ \eo{ddd..} character with octal code ddd..
+ \exhh character with hex code hh
+ \ex{hhh..} character with hex code hhh..
+.sp
+Note that \e0dd is always an octal code, and that \e8 and \e9 are the literal
+characters "8" and "9".
+.
+.
+.SH "CHARACTER TYPES"
+.rs
+.sp
+ . any character except newline;
+ in dotall mode, any character whatsoever
+ \eC one data unit, even in UTF mode (best avoided)
+ \ed a decimal digit
+ \eD a character that is not a decimal digit
+ \eh a horizontal white space character
+ \eH a character that is not a horizontal white space character
+ \eN a character that is not a newline
+ \ep{\fIxx\fP} a character with the \fIxx\fP property
+ \eP{\fIxx\fP} a character without the \fIxx\fP property
+ \eR a newline sequence
+ \es a white space character
+ \eS a character that is not a white space character
+ \ev a vertical white space character
+ \eV a character that is not a vertical white space character
+ \ew a "word" character
+ \eW a "non-word" character
+ \eX a Unicode extended grapheme cluster
+.sp
+By default, \ed, \es, and \ew match only ASCII characters, even in UTF-8 mode
+or in the 16-bit and 32-bit libraries. However, if locale-specific matching is
+happening, \es and \ew may also match characters with code points in the range
+128-255. If the PCRE2_UCP option is set, the behaviour of these escape
+sequences is changed to use Unicode properties and they match many more
+characters.
+.
+.
+.SH "GENERAL CATEGORY PROPERTIES FOR \ep and \eP"
+.rs
+.sp
+ C Other
+ Cc Control
+ Cf Format
+ Cn Unassigned
+ Co Private use
+ Cs Surrogate
+.sp
+ L Letter
+ Ll Lower case letter
+ Lm Modifier letter
+ Lo Other letter
+ Lt Title case letter
+ Lu Upper case letter
+ L& Ll, Lu, or Lt
+.sp
+ M Mark
+ Mc Spacing mark
+ Me Enclosing mark
+ Mn Non-spacing mark
+.sp
+ N Number
+ Nd Decimal number
+ Nl Letter number
+ No Other number
+.sp
+ P Punctuation
+ Pc Connector punctuation
+ Pd Dash punctuation
+ Pe Close punctuation
+ Pf Final punctuation
+ Pi Initial punctuation
+ Po Other punctuation
+ Ps Open punctuation
+.sp
+ S Symbol
+ Sc Currency symbol
+ Sk Modifier symbol
+ Sm Mathematical symbol
+ So Other symbol
+.sp
+ Z Separator
+ Zl Line separator
+ Zp Paragraph separator
+ Zs Space separator
+.
+.
+.SH "PCRE2 SPECIAL CATEGORY PROPERTIES FOR \ep and \eP"
+.rs
+.sp
+ Xan Alphanumeric: union of properties L and N
+ Xps POSIX space: property Z or tab, NL, VT, FF, CR
+ Xsp Perl space: property Z or tab, NL, VT, FF, CR
+ Xuc Univerally-named character: one that can be
+ represented by a Universal Character Name
+ Xwd Perl word: property Xan or underscore
+.sp
+Perl and POSIX space are now the same. Perl added VT to its space character set
+at release 5.18.
+.
+.
+.SH "SCRIPT NAMES FOR \ep AND \eP"
+.rs
+.sp
+Arabic,
+Armenian,
+Avestan,
+Balinese,
+Bamum,
+Bassa_Vah,
+Batak,
+Bengali,
+Bopomofo,
+Brahmi,
+Braille,
+Buginese,
+Buhid,
+Canadian_Aboriginal,
+Carian,
+Caucasian_Albanian,
+Chakma,
+Cham,
+Cherokee,
+Common,
+Coptic,
+Cuneiform,
+Cypriot,
+Cyrillic,
+Deseret,
+Devanagari,
+Duployan,
+Egyptian_Hieroglyphs,
+Elbasan,
+Ethiopic,
+Georgian,
+Glagolitic,
+Gothic,
+Grantha,
+Greek,
+Gujarati,
+Gurmukhi,
+Han,
+Hangul,
+Hanunoo,
+Hebrew,
+Hiragana,
+Imperial_Aramaic,
+Inherited,
+Inscriptional_Pahlavi,
+Inscriptional_Parthian,
+Javanese,
+Kaithi,
+Kannada,
+Katakana,
+Kayah_Li,
+Kharoshthi,
+Khmer,
+Khojki,
+Khudawadi,
+Lao,
+Latin,
+Lepcha,
+Limbu,
+Linear_A,
+Linear_B,
+Lisu,
+Lycian,
+Lydian,
+Mahajani,
+Malayalam,
+Mandaic,
+Manichaean,
+Meetei_Mayek,
+Mende_Kikakui,
+Meroitic_Cursive,
+Meroitic_Hieroglyphs,
+Miao,
+Modi,
+Mongolian,
+Mro,
+Myanmar,
+Nabataean,
+New_Tai_Lue,
+Nko,
+Ogham,
+Ol_Chiki,
+Old_Italic,
+Old_North_Arabian,
+Old_Permic,
+Old_Persian,
+Old_South_Arabian,
+Old_Turkic,
+Oriya,
+Osmanya,
+Pahawh_Hmong,
+Palmyrene,
+Pau_Cin_Hau,
+Phags_Pa,
+Phoenician,
+Psalter_Pahlavi,
+Rejang,
+Runic,
+Samaritan,
+Saurashtra,
+Sharada,
+Shavian,
+Siddham,
+Sinhala,
+Sora_Sompeng,
+Sundanese,
+Syloti_Nagri,
+Syriac,
+Tagalog,
+Tagbanwa,
+Tai_Le,
+Tai_Tham,
+Tai_Viet,
+Takri,
+Tamil,
+Telugu,
+Thaana,
+Thai,
+Tibetan,
+Tifinagh,
+Tirhuta,
+Ugaritic,
+Vai,
+Warang_Citi,
+Yi.
+.
+.
+.SH "CHARACTER CLASSES"
+.rs
+.sp
+ [...] positive character class
+ [^...] negative character class
+ [x-y] range (can be used for hex characters)
+ [[:xxx:]] positive POSIX named set
+ [[:^xxx:]] negative POSIX named set
+.sp
+ alnum alphanumeric
+ alpha alphabetic
+ ascii 0-127
+ blank space or tab
+ cntrl control character
+ digit decimal digit
+ graph printing, excluding space
+ lower lower case letter
+ print printing, including space
+ punct printing, excluding alphanumeric
+ space white space
+ upper upper case letter
+ word same as \ew
+ xdigit hexadecimal digit
+.sp
+In PCRE2, POSIX character set names recognize only ASCII characters by default,
+but some of them use Unicode properties if PCRE2_UCP is set. You can use
+\eQ...\eE inside a character class.
+.
+.
+.SH "QUANTIFIERS"
+.rs
+.sp
+ ? 0 or 1, greedy
+ ?+ 0 or 1, possessive
+ ?? 0 or 1, lazy
+ * 0 or more, greedy
+ *+ 0 or more, possessive
+ *? 0 or more, lazy
+ + 1 or more, greedy
+ ++ 1 or more, possessive
+ +? 1 or more, lazy
+ {n} exactly n
+ {n,m} at least n, no more than m, greedy
+ {n,m}+ at least n, no more than m, possessive
+ {n,m}? at least n, no more than m, lazy
+ {n,} n or more, greedy
+ {n,}+ n or more, possessive
+ {n,}? n or more, lazy
+.
+.
+.SH "ANCHORS AND SIMPLE ASSERTIONS"
+.rs
+.sp
+ \eb word boundary
+ \eB not a word boundary
+ ^ start of subject
+ also after internal newline in multiline mode
+ \eA start of subject
+ $ end of subject
+ also before newline at end of subject
+ also before internal newline in multiline mode
+ \eZ end of subject
+ also before newline at end of subject
+ \ez end of subject
+ \eG first matching position in subject
+.
+.
+.SH "MATCH POINT RESET"
+.rs
+.sp
+ \eK reset start of match
+.sp
+\eK is honoured in positive assertions, but ignored in negative ones.
+.
+.
+.SH "ALTERNATION"
+.rs
+.sp
+ expr|expr|expr...
+.
+.
+.SH "CAPTURING"
+.rs
+.sp
+ (...) capturing group
+ (?<name>...) named capturing group (Perl)
+ (?'name'...) named capturing group (Perl)
+ (?P<name>...) named capturing group (Python)
+ (?:...) non-capturing group
+ (?|...) non-capturing group; reset group numbers for
+ capturing groups in each alternative
+.
+.
+.SH "ATOMIC GROUPS"
+.rs
+.sp
+ (?>...) atomic, non-capturing group
+.
+.
+.
+.
+.SH "COMMENT"
+.rs
+.sp
+ (?#....) comment (not nestable)
+.
+.
+.SH "OPTION SETTING"
+.rs
+.sp
+ (?i) caseless
+ (?J) allow duplicate names
+ (?m) multiline
+ (?s) single line (dotall)
+ (?U) default ungreedy (lazy)
+ (?x) extended (ignore white space)
+ (?-...) unset option(s)
+.sp
+The following are recognized only at the very start of a pattern or after one
+of the newline or \eR options with similar syntax. More than one of them may
+appear.
+.sp
+ (*LIMIT_MATCH=d) set the match limit to d (decimal number)
+ (*LIMIT_RECURSION=d) set the recursion limit to d (decimal number)
+ (*NOTEMPTY) set PCRE2_NOTEMPTY when matching
+ (*NOTEMPTY_ATSTART) set PCRE2_NOTEMPTY_ATSTART when matching
+ (*NO_AUTO_POSSESS) no auto-possessification (PCRE2_NO_AUTO_POSSESS)
+ (*NO_START_OPT) no start-match optimization (PCRE2_NO_START_OPTIMIZE)
+ (*UTF) set appropriate UTF mode for the library in use
+ (*UCP) set PCRE2_UCP (use Unicode properties for \ed etc)
+.sp
+Note that LIMIT_MATCH and LIMIT_RECURSION can only reduce the value of the
+limits set by the caller of pcre2_exec(), not increase them.
+.
+.
+.SH "NEWLINE CONVENTION"
+.rs
+.sp
+These are recognized only at the very start of the pattern or after option
+settings with a similar syntax.
+.sp
+ (*CR) carriage return only
+ (*LF) linefeed only
+ (*CRLF) carriage return followed by linefeed
+ (*ANYCRLF) all three of the above
+ (*ANY) any Unicode newline sequence
+.
+.
+.SH "WHAT \eR MATCHES"
+.rs
+.sp
+These are recognized only at the very start of the pattern or after option
+setting with a similar syntax.
+.sp
+ (*BSR_ANYCRLF) CR, LF, or CRLF
+ (*BSR_UNICODE) any Unicode newline sequence
+.
+.
+.SH "LOOKAHEAD AND LOOKBEHIND ASSERTIONS"
+.rs
+.sp
+ (?=...) positive look ahead
+ (?!...) negative look ahead
+ (?<=...) positive look behind
+ (?<!...) negative look behind
+.sp
+Each top-level branch of a look behind must be of a fixed length.
+.
+.
+.SH "BACKREFERENCES"
+.rs
+.sp
+ \en reference by number (can be ambiguous)
+ \egn reference by number
+ \eg{n} reference by number
+ \eg{-n} relative reference by number
+ \ek<name> reference by name (Perl)
+ \ek'name' reference by name (Perl)
+ \eg{name} reference by name (Perl)
+ \ek{name} reference by name (.NET)
+ (?P=name) reference by name (Python)
+.
+.
+.SH "SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)"
+.rs
+.sp
+ (?R) recurse whole pattern
+ (?n) call subpattern by absolute number
+ (?+n) call subpattern by relative number
+ (?-n) call subpattern by relative number
+ (?&name) call subpattern by name (Perl)
+ (?P>name) call subpattern by name (Python)
+ \eg<name> call subpattern by name (Oniguruma)
+ \eg'name' call subpattern by name (Oniguruma)
+ \eg<n> call subpattern by absolute number (Oniguruma)
+ \eg'n' call subpattern by absolute number (Oniguruma)
+ \eg<+n> call subpattern by relative number (PCRE2 extension)
+ \eg'+n' call subpattern by relative number (PCRE2 extension)
+ \eg<-n> call subpattern by relative number (PCRE2 extension)
+ \eg'-n' call subpattern by relative number (PCRE2 extension)
+.
+.
+.SH "CONDITIONAL PATTERNS"
+.rs
+.sp
+ (?(condition)yes-pattern)
+ (?(condition)yes-pattern|no-pattern)
+.sp
+ (?(n)... absolute reference condition
+ (?(+n)... relative reference condition
+ (?(-n)... relative reference condition
+ (?(<name>)... named reference condition (Perl)
+ (?('name')... named reference condition (Perl)
+ (?(name)... named reference condition (PCRE2)
+ (?(R)... overall recursion condition
+ (?(Rn)... specific group recursion condition
+ (?(R&name)... specific recursion condition
+ (?(DEFINE)... define subpattern for reference
+ (?(assert)... assertion condition
+.
+.
+.SH "BACKTRACKING CONTROL"
+.rs
+.sp
+The following act immediately they are reached:
+.sp
+ (*ACCEPT) force successful match
+ (*FAIL) force backtrack; synonym (*F)
+ (*MARK:NAME) set name to be passed back; synonym (*:NAME)
+.sp
+The following act only when a subsequent match failure causes a backtrack to
+reach them. They all force a match failure, but they differ in what happens
+afterwards. Those that advance the start-of-match point do so only if the
+pattern is not anchored.
+.sp
+ (*COMMIT) overall failure, no advance of starting point
+ (*PRUNE) advance to next starting character
+ (*PRUNE:NAME) equivalent to (*MARK:NAME)(*PRUNE)
+ (*SKIP) advance to current matching position
+ (*SKIP:NAME) advance to position corresponding to an earlier
+ (*MARK:NAME); if not found, the (*SKIP) is ignored
+ (*THEN) local failure, backtrack to next alternation
+ (*THEN:NAME) equivalent to (*MARK:NAME)(*THEN)
+.
+.
+.SH "CALLOUTS"
+.rs
+.sp
+ (?C) callout
+ (?Cn) callout with data n
+.
+.
+.SH "SEE ALSO"
+.rs
+.sp
+\fBpcre2pattern\fP(3), \fBpcre2api\fP(3), \fBpcre2callout\fP(3),
+\fBpcre2matching\fP(3), \fBpcre2\fP(3).
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 20 October 2014
+Copyright (c) 1997-2014 University of Cambridge.
+.fi
