Revision: 878
http://vcs.pcre.org/viewvc?view=rev&revision=878
Author: ph10
Date: 2012-01-15 15:44:47 +0000 (Sun, 15 Jan 2012)
Log Message:
-----------
Fix HTML documentation and rebuild.
Modified Paths:
--------------
code/trunk/doc/html/pcre_jit_stack_alloc.html
code/trunk/doc/html/pcre_utf16_to_host_byte_order.html
code/trunk/doc/html/pcrebuild.html
code/trunk/doc/html/pcretest.html
code/trunk/doc/html/pcreunicode.html
code/trunk/doc/pcre.txt
code/trunk/doc/pcretest.txt
code/trunk/doc/pcreunicode.3
Modified: code/trunk/doc/html/pcre_jit_stack_alloc.html
===================================================================
--- code/trunk/doc/html/pcre_jit_stack_alloc.html 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/html/pcre_jit_stack_alloc.html 2012-01-15 15:44:47 UTC (rev 878)
@@ -23,7 +23,8 @@
<b>int <i>maxsize</i>);</b>
</P>
<P>
-<b>pcre16_jit_stack *pcre16_jit_stack_alloc(int <i>startsize</i>, int <i>maxsize</i>);</b>
+<b>pcre16_jit_stack *pcre16_jit_stack_alloc(int <i>startsize</i>, </b>
+<b>int <i>maxsize</i>);</b>
</P>
<br><b>
DESCRIPTION
Modified: code/trunk/doc/html/pcre_utf16_to_host_byte_order.html
===================================================================
--- code/trunk/doc/html/pcre_utf16_to_host_byte_order.html 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/html/pcre_utf16_to_host_byte_order.html 2012-01-15 15:44:47 UTC (rev 878)
@@ -20,7 +20,7 @@
</P>
<P>
<b>int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *<i>output</i>,</b>
-<b>PCRE_SPTR16 <i>input</i>, int <i>length</i>, int *<i>byte_order</i>, </b>
+<b>PCRE_SPTR16 <i>input</i>, int <i>length</i>, int *<i>host_byte_order</i>, </b>
<b>int <i>keep_boms</i>);</b>
</P>
<br><b>
@@ -31,20 +31,20 @@
string to the correct order for the current host, taking account of any byte
order marks (BOMs) within the string. Its arguments are:
<pre>
- <i>output</i> pointer to output buffer, may be the same as <i>input</i>
- <i>input</i> pointer to input buffer
- <i>length</i> number of 16-bit units in the input, or negative for
- a zero-terminated string
- <i>byte_order</i> a NULL value or a value of 0 pointed to means start
- in host byte order
- <i>keep_boms</i> if non-zero, BOMs are copied to the output string
+ <i>output</i> pointer to output buffer, may be the same as <i>input</i>
+ <i>input</i> pointer to input buffer
+ <i>length</i> number of 16-bit units in the input, or negative for
+ a zero-terminated string
+ <i>host_byte_order</i> a NULL value or a non-zero value pointed to means
+ start in host byte order
+ <i>keep_boms</i> if non-zero, BOMs are copied to the output string
</pre>
The result of the function is the number of 16-bit units placed into the output
buffer, including the zero terminator if the string was zero-terminated.
</P>
<P>
-If <i>byte_order</i> is not NULL, it is set to indicate the byte order that is
-current at the end of the string.
+If <i>host_byte_order</i> is not NULL, it is set to indicate the byte order that
+is current at the end of the string.
</P>
<P>
There is a complete description of the PCRE native API in the
Modified: code/trunk/doc/html/pcrebuild.html
===================================================================
--- code/trunk/doc/html/pcrebuild.html 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/html/pcrebuild.html 2012-01-15 15:44:47 UTC (rev 878)
@@ -110,11 +110,14 @@
<pre>
--enable-utf
</pre>
-to the <b>configure</b> command. This setting applies to both libraries, adding
+to the <b>configure</b> command. This setting applies to both libraries, adding
support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit
-library. It is not possible to build one library with UTF support and the other
-without in the same configuration. (For backwards compatibility, --enable-utf8
-is a synonym of --enable-utf.)
+library. There are no separate options for enabling UTF-8 and UTF-16
+independently because that would allow ridiculous settings such as requesting
+UTF-16 support while building only the 8-bit library. It is not possible to
+build one library with UTF support and the other without in the same
+configuration. (For backwards compatibility, --enable-utf8 is a synonym of
+--enable-utf.)
</P>
<P>
Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As
Modified: code/trunk/doc/html/pcretest.html
===================================================================
--- code/trunk/doc/html/pcretest.html 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/html/pcretest.html 2012-01-15 15:44:47 UTC (rev 878)
@@ -543,12 +543,12 @@
digits inside the braces; invalid values provoke error messages.
</P>
<P>
-Note that \xhh specifies one byte in UTF-8 mode; this makes it possible to
-construct invalid UTF-8 sequences for testing purposes. On the other hand,
-\x{hh} is interpreted as a UTF-8 character in UTF-8 mode, generating more than
-one byte if the value is greater than 127. When testing the 8-bit library not
-in UTF-8 mode, \x{hh} generates one byte for values less than 256, and causes
-an error for greater values.
+Note that \xhh specifies one byte rather than one character in UTF-8 mode;
+this makes it possible to construct invalid UTF-8 sequences for testing
+purposes. On the other hand, \x{hh} is interpreted as a UTF-8 character in
+UTF-8 mode, generating more than one byte if the value is greater than 127.
+When testing the 8-bit library not in UTF-8 mode, \x{hh} generates one byte
+for values less than 256, and causes an error for greater values.
</P>
<P>
In UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it
@@ -923,7 +923,7 @@
</P>
<br><a name="SEC16" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 13 January 2012
+Last updated: 14 January 2012
<br>
Copyright © 1997-2012 University of Cambridge.
<br>
Modified: code/trunk/doc/html/pcreunicode.html
===================================================================
--- code/trunk/doc/html/pcreunicode.html 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/html/pcreunicode.html 2012-01-15 15:44:47 UTC (rev 878)
@@ -38,7 +38,7 @@
<P>
In order process UTF-16 strings, you must build PCRE's 16-bit library with UTF
support, and, in addition, you must call
-<a href="pcre16_compile.html"><b>pcre16_compile()</b></a>
+<a href="pcre_compile.html"><b>pcre16_compile()</b></a>
with the PCRE_UTF16 option flag, or the pattern must start with the sequence
(*UTF16). When either of these is the case, both the pattern and any subject
strings that are matched against it are treated as UTF-16 strings instead of
Modified: code/trunk/doc/pcre.txt
===================================================================
--- code/trunk/doc/pcre.txt 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/pcre.txt 2012-01-15 15:44:47 UTC (rev 878)
@@ -554,37 +554,40 @@
to the configure command. This setting applies to both libraries,
adding support for UTF-8 to the 8-bit library and support for UTF-16 to
- the 16-bit library. It is not possible to build one library with UTF
- support and the other without in the same configuration. (For backwards
- compatibility, --enable-utf8 is a synonym of --enable-utf.)
+ the 16-bit library. There are no separate options for enabling UTF-8
+ and UTF-16 independently because that would allow ridiculous settings
+ such as requesting UTF-16 support while building only the 8-bit
+ library. It is not possible to build one library with UTF support and
+ the other without in the same configuration. (For backwards compatibil-
+ ity, --enable-utf8 is a synonym of --enable-utf.)
- Of itself, this setting does not make PCRE treat strings as UTF-8 or
- UTF-16. As well as compiling PCRE with this option, you also have have
+ Of itself, this setting does not make PCRE treat strings as UTF-8 or
+ UTF-16. As well as compiling PCRE with this option, you also have have
to set the PCRE_UTF8 or PCRE_UTF16 option when you call one of the pat-
tern compiling functions.
- If you set --enable-utf when compiling in an EBCDIC environment, PCRE
+ If you set --enable-utf when compiling in an EBCDIC environment, PCRE
expects its input to be either ASCII or UTF-8 (depending on the runtime
- option). It is not possible to support both EBCDIC and UTF-8 codes in
+ option). It is not possible to support both EBCDIC and UTF-8 codes in
the same version of the library. Consequently, --enable-utf and
--enable-ebcdic are mutually exclusive.
UNICODE CHARACTER PROPERTY SUPPORT
- UTF support allows the libraries to process character codepoints up to
- 0x10ffff in the strings that they handle. On its own, however, it does
+ UTF support allows the libraries to process character codepoints up to
+ 0x10ffff in the strings that they handle. On its own, however, it does
not provide any facilities for accessing the properties of such charac-
ters. If you want to be able to use the pattern escapes \P, \p, and \X,
which refer to Unicode character properties, you must add
--enable-unicode-properties
- to the configure command. This implies UTF support, even if you have
+ to the configure command. This implies UTF support, even if you have
not explicitly requested it.
- Including Unicode property support adds around 30K of tables to the
- PCRE library. Only the general category properties such as Lu and Nd
+ Including Unicode property support adds around 30K of tables to the
+ PCRE library. Only the general category properties such as Lu and Nd
are supported. Details are given in the pcrepattern documentation.
@@ -594,9 +597,9 @@
--enable-jit
- This support is available only for certain hardware architectures. If
- this option is set for an unsupported architecture, a compile time
- error occurs. See the pcrejit documentation for a discussion of JIT
+ This support is available only for certain hardware architectures. If
+ this option is set for an unsupported architecture, a compile time
+ error occurs. See the pcrejit documentation for a discussion of JIT
usage. When JIT support is enabled, pcregrep automatically makes use of
it, unless you add
@@ -607,14 +610,14 @@
CODE VALUE OF NEWLINE
- By default, PCRE interprets the linefeed (LF) character as indicating
- the end of a line. This is the normal newline character on Unix-like
- systems. You can compile PCRE to use carriage return (CR) instead, by
+ By default, PCRE interprets the linefeed (LF) character as indicating
+ the end of a line. This is the normal newline character on Unix-like
+ systems. You can compile PCRE to use carriage return (CR) instead, by
adding
--enable-newline-is-cr
- to the configure command. There is also a --enable-newline-is-lf
+ to the configure command. There is also a --enable-newline-is-lf
option, which explicitly specifies linefeed as the newline character.
Alternatively, you can specify that line endings are to be indicated by
@@ -626,40 +629,40 @@
--enable-newline-is-anycrlf
- which causes PCRE to recognize any of the three sequences CR, LF, or
+ which causes PCRE to recognize any of the three sequences CR, LF, or
CRLF as indicating a line ending. Finally, a fifth option, specified by
--enable-newline-is-any
causes PCRE to recognize any Unicode newline sequence.
- Whatever line ending convention is selected when PCRE is built can be
- overridden when the library functions are called. At build time it is
+ Whatever line ending convention is selected when PCRE is built can be
+ overridden when the library functions are called. At build time it is
conventional to use the standard for your operating system.
WHAT \R MATCHES
- By default, the sequence \R in a pattern matches any Unicode newline
- sequence, whatever has been selected as the line ending sequence. If
+ By default, the sequence \R in a pattern matches any Unicode newline
+ sequence, whatever has been selected as the line ending sequence. If
you specify
--enable-bsr-anycrlf
- the default is changed so that \R matches only CR, LF, or CRLF. What-
- ever is selected when PCRE is built can be overridden when the library
+ the default is changed so that \R matches only CR, LF, or CRLF. What-
+ ever is selected when PCRE is built can be overridden when the library
functions are called.
POSIX MALLOC USAGE
- When the 8-bit library is called through the POSIX interface (see the
- pcreposix documentation), additional working storage is required for
- holding the pointers to capturing substrings, because PCRE requires
+ When the 8-bit library is called through the POSIX interface (see the
+ pcreposix documentation), additional working storage is required for
+ holding the pointers to capturing substrings, because PCRE requires
three integers per substring, whereas the POSIX interface provides only
- two. If the number of expected substrings is small, the wrapper func-
- tion uses space on the stack, because this is faster than using mal-
- loc() for each call. The default threshold above which the stack is no
+ two. If the number of expected substrings is small, the wrapper func-
+ tion uses space on the stack, because this is faster than using mal-
+ loc() for each call. The default threshold above which the stack is no
longer used is 10; it can be changed by adding a setting such as
--with-posix-malloc-threshold=20
@@ -669,19 +672,19 @@
HANDLING VERY LARGE PATTERNS
- Within a compiled pattern, offset values are used to point from one
- part to another (for example, from an opening parenthesis to an alter-
- nation metacharacter). By default, two-byte values are used for these
- offsets, leading to a maximum size for a compiled pattern of around
- 64K. This is sufficient to handle all but the most gigantic patterns.
- Nevertheless, some people do want to process truly enormous patterns,
- so it is possible to compile PCRE to use three-byte or four-byte off-
+ Within a compiled pattern, offset values are used to point from one
+ part to another (for example, from an opening parenthesis to an alter-
+ nation metacharacter). By default, two-byte values are used for these
+ offsets, leading to a maximum size for a compiled pattern of around
+ 64K. This is sufficient to handle all but the most gigantic patterns.
+ Nevertheless, some people do want to process truly enormous patterns,
+ so it is possible to compile PCRE to use three-byte or four-byte off-
sets by adding a setting such as
--with-link-size=3
- to the configure command. The value given must be 2, 3, or 4. For the
- 16-bit library, a value of 3 is rounded up to 4. Using longer offsets
+ to the configure command. The value given must be 2, 3, or 4. For the
+ 16-bit library, a value of 3 is rounded up to 4. Using longer offsets
slows down the operation of PCRE because it has to load additional data
when handling them.
@@ -689,92 +692,92 @@
AVOIDING EXCESSIVE STACK USAGE
When matching with the pcre_exec() function, PCRE implements backtrack-
- ing by making recursive calls to an internal function called match().
- In environments where the size of the stack is limited, this can se-
- verely limit PCRE's operation. (The Unix environment does not usually
+ ing by making recursive calls to an internal function called match().
+ In environments where the size of the stack is limited, this can se-
+ verely limit PCRE's operation. (The Unix environment does not usually
suffer from this problem, but it may sometimes be necessary to increase
- the maximum stack size. There is a discussion in the pcrestack docu-
- mentation.) An alternative approach to recursion that uses memory from
- the heap to remember data, instead of using recursive function calls,
- has been implemented to work round the problem of limited stack size.
+ the maximum stack size. There is a discussion in the pcrestack docu-
+ mentation.) An alternative approach to recursion that uses memory from
+ the heap to remember data, instead of using recursive function calls,
+ has been implemented to work round the problem of limited stack size.
If you want to build a version of PCRE that works this way, add
--disable-stack-for-recursion
- to the configure command. With this configuration, PCRE will use the
- pcre_stack_malloc and pcre_stack_free variables to call memory manage-
- ment functions. By default these point to malloc() and free(), but you
+ to the configure command. With this configuration, PCRE will use the
+ pcre_stack_malloc and pcre_stack_free variables to call memory manage-
+ ment functions. By default these point to malloc() and free(), but you
can replace the pointers so that your own functions are used instead.
- Separate functions are provided rather than using pcre_malloc and
- pcre_free because the usage is very predictable: the block sizes
- requested are always the same, and the blocks are always freed in
- reverse order. A calling program might be able to implement optimized
- functions that perform better than malloc() and free(). PCRE runs
+ Separate functions are provided rather than using pcre_malloc and
+ pcre_free because the usage is very predictable: the block sizes
+ requested are always the same, and the blocks are always freed in
+ reverse order. A calling program might be able to implement optimized
+ functions that perform better than malloc() and free(). PCRE runs
noticeably more slowly when built in this way. This option affects only
the pcre_exec() function; it is not relevant for pcre_dfa_exec().
LIMITING PCRE RESOURCE USAGE
- Internally, PCRE has a function called match(), which it calls repeat-
- edly (sometimes recursively) when matching a pattern with the
- pcre_exec() function. By controlling the maximum number of times this
- function may be called during a single matching operation, a limit can
- be placed on the resources used by a single call to pcre_exec(). The
- limit can be changed at run time, as described in the pcreapi documen-
- tation. The default is 10 million, but this can be changed by adding a
+ Internally, PCRE has a function called match(), which it calls repeat-
+ edly (sometimes recursively) when matching a pattern with the
+ pcre_exec() function. By controlling the maximum number of times this
+ function may be called during a single matching operation, a limit can
+ be placed on the resources used by a single call to pcre_exec(). The
+ limit can be changed at run time, as described in the pcreapi documen-
+ tation. The default is 10 million, but this can be changed by adding a
setting such as
--with-match-limit=500000
- to the configure command. This setting has no effect on the
+ to the configure command. This setting has no effect on the
pcre_dfa_exec() matching function.
- In some environments it is desirable to limit the depth of recursive
+ In some environments it is desirable to limit the depth of recursive
calls of match() more strictly than the total number of calls, in order
- to restrict the maximum amount of stack (or heap, if --disable-stack-
+ to restrict the maximum amount of stack (or heap, if --disable-stack-
for-recursion is specified) that is used. A second limit controls this;
- it defaults to the value that is set for --with-match-limit, which
- imposes no additional constraints. However, you can set a lower limit
+ it defaults to the value that is set for --with-match-limit, which
+ imposes no additional constraints. However, you can set a lower limit
by adding, for example,
--with-match-limit-recursion=10000
- to the configure command. This value can also be overridden at run
+ to the configure command. This value can also be overridden at run
time.
CREATING CHARACTER TABLES AT BUILD TIME
- PCRE uses fixed tables for processing characters whose code values are
- less than 256. By default, PCRE is built with a set of tables that are
- distributed in the file pcre_chartables.c.dist. These tables are for
+ PCRE uses fixed tables for processing characters whose code values are
+ less than 256. By default, PCRE is built with a set of tables that are
+ distributed in the file pcre_chartables.c.dist. These tables are for
ASCII codes only. If you add
--enable-rebuild-chartables
- to the configure command, the distributed tables are no longer used.
- Instead, a program called dftables is compiled and run. This outputs
+ to the configure command, the distributed tables are no longer used.
+ Instead, a program called dftables is compiled and run. This outputs
the source for new set of tables, created in the default locale of your
C runtime system. (This method of replacing the tables does not work if
- you are cross compiling, because dftables is run on the local host. If
- you need to create alternative tables when cross compiling, you will
+ you are cross compiling, because dftables is run on the local host. If
+ you need to create alternative tables when cross compiling, you will
have to do so "by hand".)
USING EBCDIC CODE
- PCRE assumes by default that it will run in an environment where the
- character code is ASCII (or Unicode, which is a superset of ASCII).
- This is the case for most computer operating systems. PCRE can, how-
+ PCRE assumes by default that it will run in an environment where the
+ character code is ASCII (or Unicode, which is a superset of ASCII).
+ This is the case for most computer operating systems. PCRE can, how-
ever, be compiled to run in an EBCDIC environment by adding
--enable-ebcdic
to the configure command. This setting implies --enable-rebuild-charta-
- bles. You should only use it if you know that you are in an EBCDIC
- environment (for example, an IBM mainframe operating system). The
+ bles. You should only use it if you know that you are in an EBCDIC
+ environment (for example, an IBM mainframe operating system). The
--enable-ebcdic option is incompatible with --enable-utf.
@@ -788,18 +791,18 @@
--enable-pcregrep-libbz2
to the configure command. These options naturally require that the rel-
- evant libraries are installed on your system. Configuration will fail
+ evant libraries are installed on your system. Configuration will fail
if they are not.
PCREGREP BUFFER SIZE
- pcregrep uses an internal buffer to hold a "window" on the file it is
+ pcregrep uses an internal buffer to hold a "window" on the file it is
scanning, in order to be able to output "before" and "after" lines when
- it finds a match. The size of the buffer is controlled by a parameter
+ it finds a match. The size of the buffer is controlled by a parameter
whose default value is 20K. The buffer itself is three times this size,
but because of the way it is used for holding "before" lines, the long-
- est line that is guaranteed to be processable is the parameter size.
+ est line that is guaranteed to be processable is the parameter size.
You can change the default parameter value by adding, for example,
--with-pcregrep-bufsize=50K
@@ -814,24 +817,24 @@
--enable-pcretest-libreadline
- to the configure command, pcretest is linked with the libreadline
- library, and when its input is from a terminal, it reads it using the
+ to the configure command, pcretest is linked with the libreadline
+ library, and when its input is from a terminal, it reads it using the
readline() function. This provides line-editing and history facilities.
Note that libreadline is GPL-licensed, so if you distribute a binary of
pcretest linked in this way, there may be licensing issues.
- Setting this option causes the -lreadline option to be added to the
- pcretest build. In many operating environments with a sytem-installed
+ Setting this option causes the -lreadline option to be added to the
+ pcretest build. In many operating environments with a sytem-installed
libreadline this is sufficient. However, in some environments (e.g. if
- an unmodified distribution version of readline is in use), some extra
- configuration may be necessary. The INSTALL file for libreadline says
+ an unmodified distribution version of readline is in use), some extra
+ configuration may be necessary. The INSTALL file for libreadline says
this:
"Readline uses the termcap functions, but does not link with the
termcap or curses library itself, allowing applications which link
with readline the to choose an appropriate library."
- If your environment has not been set up so that an appropriate library
+ If your environment has not been set up so that an appropriate library
is automatically included, you may need to add something like
LIBS="-ncurses"
Modified: code/trunk/doc/pcretest.txt
===================================================================
--- code/trunk/doc/pcretest.txt 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/pcretest.txt 2012-01-15 15:44:47 UTC (rev 878)
@@ -500,90 +500,91 @@
decimal digits inside the braces; invalid values provoke error mes-
sages.
- Note that \xhh specifies one byte in UTF-8 mode; this makes it possible
- to construct invalid UTF-8 sequences for testing purposes. On the other
- hand, \x{hh} is interpreted as a UTF-8 character in UTF-8 mode, gener-
- ating more than one byte if the value is greater than 127. When testing
- the 8-bit library not in UTF-8 mode, \x{hh} generates one byte for val-
- ues less than 256, and causes an error for greater values.
+ Note that \xhh specifies one byte rather than one character in UTF-8
+ mode; this makes it possible to construct invalid UTF-8 sequences for
+ testing purposes. On the other hand, \x{hh} is interpreted as a UTF-8
+ character in UTF-8 mode, generating more than one byte if the value is
+ greater than 127. When testing the 8-bit library not in UTF-8 mode,
+ \x{hh} generates one byte for values less than 256, and causes an error
+ for greater values.
In UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it
possible to construct invalid UTF-16 sequences for testing purposes.
- The escapes that specify line ending sequences are literal strings,
+ The escapes that specify line ending sequences are literal strings,
exactly as shown. No more than one newline setting should be present in
any data line.
- A backslash followed by anything else just escapes the anything else.
- If the very last character is a backslash, it is ignored. This gives a
- way of passing an empty line as data, since a real empty line termi-
+ A backslash followed by anything else just escapes the anything else.
+ If the very last character is a backslash, it is ignored. This gives a
+ way of passing an empty line as data, since a real empty line termi-
nates the data input.
- The \J escape provides a way of setting the maximum stack size that is
- used by the just-in-time optimization code. It is ignored if JIT opti-
- mization is not being used. Providing a stack that is larger than the
+ The \J escape provides a way of setting the maximum stack size that is
+ used by the just-in-time optimization code. It is ignored if JIT opti-
+ mization is not being used. Providing a stack that is larger than the
default 32K is necessary only for very complicated patterns.
- If \M is present, pcretest calls pcre[16]_exec() several times, with
+ If \M is present, pcretest calls pcre[16]_exec() several times, with
different values in the match_limit and match_limit_recursion fields of
- the pcre[16]_extra data structure, until it finds the minimum numbers
- for each parameter that allow pcre[16]_exec() to complete without
- error. Because this is testing a specific feature of the normal inter-
+ the pcre[16]_extra data structure, until it finds the minimum numbers
+ for each parameter that allow pcre[16]_exec() to complete without
+ error. Because this is testing a specific feature of the normal inter-
pretive pcre[16]_exec() execution, the use of any JIT optimization that
might have been set up by the /S+ qualifier of -s+ option is disabled.
- The match_limit number is a measure of the amount of backtracking that
- takes place, and checking it out can be instructive. For most simple
- matches, the number is quite small, but for patterns with very large
- numbers of matching possibilities, it can become large very quickly
- with increasing length of subject string. The match_limit_recursion
- number is a measure of how much stack (or, if PCRE is compiled with
- NO_RECURSE, how much heap) memory is needed to complete the match
+ The match_limit number is a measure of the amount of backtracking that
+ takes place, and checking it out can be instructive. For most simple
+ matches, the number is quite small, but for patterns with very large
+ numbers of matching possibilities, it can become large very quickly
+ with increasing length of subject string. The match_limit_recursion
+ number is a measure of how much stack (or, if PCRE is compiled with
+ NO_RECURSE, how much heap) memory is needed to complete the match
attempt.
- When \O is used, the value specified may be higher or lower than the
+ When \O is used, the value specified may be higher or lower than the
size set by the -O command line option (or defaulted to 45); \O applies
only to the call of pcre[16]_exec() for the line in which it appears.
- If the /P modifier was present on the pattern, causing the POSIX wrap-
- per API to be used, the only option-setting sequences that have any
- effect are \B, \N, and \Z, causing REG_NOTBOL, REG_NOTEMPTY, and
+ If the /P modifier was present on the pattern, causing the POSIX wrap-
+ per API to be used, the only option-setting sequences that have any
+ effect are \B, \N, and \Z, causing REG_NOTBOL, REG_NOTEMPTY, and
REG_NOTEOL, respectively, to be passed to regexec().
THE ALTERNATIVE MATCHING FUNCTION
- By default, pcretest uses the standard PCRE matching function,
+ By default, pcretest uses the standard PCRE matching function,
pcre[16]_exec() to match each data line. PCRE also supports an alterna-
- tive matching function, pcre[16]_dfa_test(), which operates in a dif-
- ferent way, and has some restrictions. The differences between the two
+ tive matching function, pcre[16]_dfa_test(), which operates in a dif-
+ ferent way, and has some restrictions. The differences between the two
functions are described in the pcrematching documentation.
- If a data line contains the \D escape sequence, or if the command line
- contains the -dfa option, the alternative matching function is used.
+ If a data line contains the \D escape sequence, or if the command line
+ contains the -dfa option, the alternative matching function is used.
This function finds all possible matches at a given point. If, however,
- the \F escape sequence is present in the data line, it stops after the
+ the \F escape sequence is present in the data line, it stops after the
first match is found. This is always the shortest possible match.
DEFAULT OUTPUT FROM PCRETEST
- This section describes the output when the normal matching function,
+ This section describes the output when the normal matching function,
pcre[16]_exec(), is being used.
When a match succeeds, pcretest outputs the list of captured substrings
- that pcre[16]_exec() returns, starting with number 0 for the string
- that matched the whole pattern. Otherwise, it outputs "No match" when
- the return is PCRE_ERROR_NOMATCH, and "Partial match:" followed by the
- partially matching substring when pcre[16]_exec() returns
- PCRE_ERROR_PARTIAL. (Note that this is the entire substring that was
- inspected during the partial match; it may include characters before
- the actual match start if a lookbehind assertion, \K, \b, or \B was
- involved.) For any other return, pcretest outputs the PCRE negative
- error number and a short descriptive phrase. If the error is a failed
- UTF string check, the offset of the start of the failing character and
- the reason code are also output, provided that the size of the output
- vector is at least two. Here is an example of an interactive pcretest
+ that pcre[16]_exec() returns, starting with number 0 for the string
+ that matched the whole pattern. Otherwise, it outputs "No match" when
+ the return is PCRE_ERROR_NOMATCH, and "Partial match:" followed by the
+ partially matching substring when pcre[16]_exec() returns
+ PCRE_ERROR_PARTIAL. (Note that this is the entire substring that was
+ inspected during the partial match; it may include characters before
+ the actual match start if a lookbehind assertion, \K, \b, or \B was
+ involved.) For any other return, pcretest outputs the PCRE negative
+ error number and a short descriptive phrase. If the error is a failed
+ UTF string check, the offset of the start of the failing character and
+ the reason code are also output, provided that the size of the output
+ vector is at least two. Here is an example of an interactive pcretest
run.
$ pcretest
@@ -597,10 +598,10 @@
No match
Unset capturing substrings that are not followed by one that is set are
- not returned by pcre[16]_exec(), and are not shown by pcretest. In the
- following example, there are two capturing substrings, but when the
- first data line is matched, the second, unset substring is not shown.
- An "internal" unset substring is shown as "<unset>", as for the second
+ not returned by pcre[16]_exec(), and are not shown by pcretest. In the
+ following example, there are two capturing substrings, but when the
+ first data line is matched, the second, unset substring is not shown.
+ An "internal" unset substring is shown as "<unset>", as for the second
data line.
re> /(a)|(b)/
@@ -612,11 +613,11 @@
1: <unset>
2: b
- If the strings contain any non-printing characters, they are output as
- \xhh escapes if the value is less than 256 and UTF mode is not set.
+ If the strings contain any non-printing characters, they are output as
+ \xhh escapes if the value is less than 256 and UTF mode is not set.
Otherwise they are output as \x{hh...} escapes. See below for the defi-
- nition of non-printing characters. If the pattern has the /+ modifier,
- the output for substring 0 is followed by the the rest of the subject
+ nition of non-printing characters. If the pattern has the /+ modifier,
+ the output for substring 0 is followed by the the rest of the subject
string, identified by "0+" like this:
re> /cat/+
@@ -624,7 +625,7 @@
0: cat
0+ aract
- If the pattern has the /g or /G modifier, the results of successive
+ If the pattern has the /g or /G modifier, the results of successive
matching attempts are output in sequence, like this:
re> /\Bi(\w\w)/g
@@ -636,32 +637,32 @@
0: ipp
1: pp
- "No match" is output only if the first match attempt fails. Here is an
- example of a failure message (the offset 4 that is specified by \>4 is
+ "No match" is output only if the first match attempt fails. Here is an
+ example of a failure message (the offset 4 that is specified by \>4 is
past the end of the subject string):
re> /xyz/
data> xyz\>4
Error -24 (bad offset value)
- If any of the sequences \C, \G, or \L are present in a data line that
- is successfully matched, the substrings extracted by the convenience
+ If any of the sequences \C, \G, or \L are present in a data line that
+ is successfully matched, the substrings extracted by the convenience
functions are output with C, G, or L after the string number instead of
a colon. This is in addition to the normal full list. The string length
- (that is, the return from the extraction function) is given in paren-
+ (that is, the return from the extraction function) is given in paren-
theses after each string for \C and \G.
Note that whereas patterns can be continued over several lines (a plain
">" prompt is used for continuations), data lines may not. However new-
- lines can be included in data by means of the \n escape (or \r, \r\n,
+ lines can be included in data by means of the \n escape (or \r, \r\n,
etc., depending on the newline sequence setting).
OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION
- When the alternative matching function, pcre[16]_dfa_exec(), is used
- (by means of the \D escape sequence or the -dfa command line option),
- the output consists of a list of all the matches that start at the
+ When the alternative matching function, pcre[16]_dfa_exec(), is used
+ (by means of the \D escape sequence or the -dfa command line option),
+ the output consists of a list of all the matches that start at the
first point in the subject where there is at least one match. For exam-
ple:
@@ -671,11 +672,11 @@
1: tang
2: tan
- (Using the normal matching function on this data finds only "tang".)
- The longest matching string is always given first (and numbered zero).
+ (Using the normal matching function on this data finds only "tang".)
+ The longest matching string is always given first (and numbered zero).
After a PCRE_ERROR_PARTIAL return, the output is "Partial match:", fol-
- lowed by the partially matching substring. (Note that this is the
- entire substring that was inspected during the partial match; it may
+ lowed by the partially matching substring. (Note that this is the
+ entire substring that was inspected during the partial match; it may
include characters before the actual match start if a lookbehind asser-
tion, \K, \b, or \B was involved.)
@@ -691,16 +692,16 @@
1: tan
0: tan
- Since the matching function does not support substring capture, the
- escape sequences that are concerned with captured substrings are not
+ Since the matching function does not support substring capture, the
+ escape sequences that are concerned with captured substrings are not
relevant.
RESTARTING AFTER A PARTIAL MATCH
When the alternative matching function has given the PCRE_ERROR_PARTIAL
- return, indicating that the subject partially matched the pattern, you
- can restart the match with additional subject data by means of the \R
+ return, indicating that the subject partially matched the pattern, you
+ can restart the match with additional subject data by means of the \R
escape sequence. For example:
re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
@@ -709,30 +710,30 @@
data> n05\R\D
0: n05
- For further information about partial matching, see the pcrepartial
+ For further information about partial matching, see the pcrepartial
documentation.
CALLOUTS
- If the pattern contains any callout requests, pcretest's callout func-
- tion is called during matching. This works with both matching func-
+ If the pattern contains any callout requests, pcretest's callout func-
+ tion is called during matching. This works with both matching func-
tions. By default, the called function displays the callout number, the
- start and current positions in the text at the callout time, and the
+ start and current positions in the text at the callout time, and the
next pattern item to be tested. For example:
--->pqrabcdef
0 ^ ^ \d
- This output indicates that callout number 0 occurred for a match
- attempt starting at the fourth character of the subject string, when
+ This output indicates that callout number 0 occurred for a match
+ attempt starting at the fourth character of the subject string, when
the pointer was at the seventh character of the data, and when the next
- pattern item was \d. Just one circumflex is output if the start and
+ pattern item was \d. Just one circumflex is output if the start and
current positions are the same.
Callouts numbered 255 are assumed to be automatic callouts, inserted as
- a result of the /C pattern modifier. In this case, instead of showing
- the callout number, the offset in the pattern, preceded by a plus, is
+ a result of the /C pattern modifier. In this case, instead of showing
+ the callout number, the offset in the pattern, preceded by a plus, is
output. For example:
re> /\d?[A-E]\*/C
@@ -745,7 +746,7 @@
0: E*
If a pattern contains (*MARK) items, an additional line is output when-
- ever a change of latest mark is passed to the callout function. For
+ ever a change of latest mark is passed to the callout function. For
example:
re> /a(*MARK:X)bc/C
@@ -759,59 +760,59 @@
+12 ^ ^
0: abc
- The mark changes between matching "a" and "b", but stays the same for
- the rest of the match, so nothing more is output. If, as a result of
- backtracking, the mark reverts to being unset, the text "<unset>" is
+ The mark changes between matching "a" and "b", but stays the same for
+ the rest of the match, so nothing more is output. If, as a result of
+ backtracking, the mark reverts to being unset, the text "<unset>" is
output.
- The callout function in pcretest returns zero (carry on matching) by
- default, but you can use a \C item in a data line (as described above)
+ The callout function in pcretest returns zero (carry on matching) by
+ default, but you can use a \C item in a data line (as described above)
to change this and other parameters of the callout.
- Inserting callouts can be helpful when using pcretest to check compli-
- cated regular expressions. For further information about callouts, see
+ Inserting callouts can be helpful when using pcretest to check compli-
+ cated regular expressions. For further information about callouts, see
the pcrecallout documentation.
NON-PRINTING CHARACTERS
- When pcretest is outputting text in the compiled version of a pattern,
- bytes other than 32-126 are always treated as non-printing characters
+ When pcretest is outputting text in the compiled version of a pattern,
+ bytes other than 32-126 are always treated as non-printing characters
are are therefore shown as hex escapes.
- When pcretest is outputting text that is a matched part of a subject
- string, it behaves in the same way, unless a different locale has been
- set for the pattern (using the /L modifier). In this case, the
+ When pcretest is outputting text that is a matched part of a subject
+ string, it behaves in the same way, unless a different locale has been
+ set for the pattern (using the /L modifier). In this case, the
isprint() function to distinguish printing and non-printing characters.
SAVING AND RELOADING COMPILED PATTERNS
- The facilities described in this section are not available when the
- POSIX interface to PCRE is being used, that is, when the /P pattern
+ The facilities described in this section are not available when the
+ POSIX interface to PCRE is being used, that is, when the /P pattern
modifier is specified.
When the POSIX interface is not in use, you can cause pcretest to write
- a compiled pattern to a file, by following the modifiers with > and a
+ a compiled pattern to a file, by following the modifiers with > and a
file name. For example:
/pattern/im >/some/file
- See the pcreprecompile documentation for a discussion about saving and
- re-using compiled patterns. Note that if the pattern was successfully
+ See the pcreprecompile documentation for a discussion about saving and
+ re-using compiled patterns. Note that if the pattern was successfully
studied with JIT optimization, the JIT data cannot be saved.
- The data that is written is binary. The first eight bytes are the
- length of the compiled pattern data followed by the length of the
- optional study data, each written as four bytes in big-endian order
- (most significant byte first). If there is no study data (either the
+ The data that is written is binary. The first eight bytes are the
+ length of the compiled pattern data followed by the length of the
+ optional study data, each written as four bytes in big-endian order
+ (most significant byte first). If there is no study data (either the
pattern was not studied, or studying did not return any data), the sec-
- ond length is zero. The lengths are followed by an exact copy of the
- compiled pattern. If there is additional study data, this (excluding
- any JIT data) follows immediately after the compiled pattern. After
+ ond length is zero. The lengths are followed by an exact copy of the
+ compiled pattern. If there is additional study data, this (excluding
+ any JIT data) follows immediately after the compiled pattern. After
writing the file, pcretest expects to read a new pattern.
- A saved pattern can be reloaded into pcretest by specifying < and a
+ A saved pattern can be reloaded into pcretest by specifying < and a
file name instead of a pattern. The name of the file must not contain a
< character, as otherwise pcretest will interpret the line as a pattern
delimited by < characters. For example:
@@ -820,42 +821,42 @@
Compiled pattern loaded from /some/file
No study data
- If the pattern was previously studied with the JIT optimization, the
- JIT information cannot be saved and restored, and so is lost. When the
- pattern has been loaded, pcretest proceeds to read data lines in the
+ If the pattern was previously studied with the JIT optimization, the
+ JIT information cannot be saved and restored, and so is lost. When the
+ pattern has been loaded, pcretest proceeds to read data lines in the
usual way.
- You can copy a file written by pcretest to a different host and reload
- it there, even if the new host has opposite endianness to the one on
- which the pattern was compiled. For example, you can compile on an i86
- machine and run on a SPARC machine. When a pattern is reloaded on a
+ You can copy a file written by pcretest to a different host and reload
+ it there, even if the new host has opposite endianness to the one on
+ which the pattern was compiled. For example, you can compile on an i86
+ machine and run on a SPARC machine. When a pattern is reloaded on a
host with different endianness, the confirmation message is changed to:
Compiled pattern (byte-inverted) loaded from /some/file
The test suite contains some saved pre-compiled patterns with different
- endianness. These are reloaded using "<!" instead of just "<". This
+ endianness. These are reloaded using "<!" instead of just "<". This
suppresses the "(byte-inverted)" text so that the output is the same on
- all hosts. It also forces debugging output once the pattern has been
+ all hosts. It also forces debugging output once the pattern has been
reloaded.
- File names for saving and reloading can be absolute or relative, but
- note that the shell facility of expanding a file name that starts with
+ File names for saving and reloading can be absolute or relative, but
+ note that the shell facility of expanding a file name that starts with
a tilde (~) is not available.
- The ability to save and reload files in pcretest is intended for test-
- ing and experimentation. It is not intended for production use because
- only a single pattern can be written to a file. Furthermore, there is
- no facility for supplying custom character tables for use with a
- reloaded pattern. If the original pattern was compiled with custom
- tables, an attempt to match a subject string using a reloaded pattern
- is likely to cause pcretest to crash. Finally, if you attempt to load
+ The ability to save and reload files in pcretest is intended for test-
+ ing and experimentation. It is not intended for production use because
+ only a single pattern can be written to a file. Furthermore, there is
+ no facility for supplying custom character tables for use with a
+ reloaded pattern. If the original pattern was compiled with custom
+ tables, an attempt to match a subject string using a reloaded pattern
+ is likely to cause pcretest to crash. Finally, if you attempt to load
a file that is not in the correct format, the result is undefined.
SEE ALSO
- pcre(3), pcre16(3), pcreapi(3), pcrecallout(3), pcrejit, pcrematch-
+ pcre(3), pcre16(3), pcreapi(3), pcrecallout(3), pcrejit, pcrematch-
ing(3), pcrepartial(d), pcrepattern(3), pcreprecompile(3).
@@ -868,5 +869,5 @@
REVISION
- Last updated: 13 January 2012
+ Last updated: 14 January 2012
Copyright (c) 1997-2012 University of Cambridge.
Modified: code/trunk/doc/pcreunicode.3
===================================================================
--- code/trunk/doc/pcreunicode.3 2012-01-15 12:20:28 UTC (rev 877)
+++ code/trunk/doc/pcreunicode.3 2012-01-15 15:44:47 UTC (rev 878)
@@ -28,7 +28,8 @@
.sp
In order process UTF-16 strings, you must build PCRE's 16-bit library with UTF
support, and, in addition, you must call
-.\" HREF
+.\" HTML <a href="pcre_compile.html">
+.\" </a>
\fBpcre16_compile()\fP
.\"
with the PCRE_UTF16 option flag, or the pattern must start with the sequence
