/[pcre]/code/trunk/doc/pcretest.1

Diff of /code/trunk/doc/pcretest.1

Parent Directory | Revision Log | View Patch Patch

-revision 77 by nigel,
Sat Feb 24 21:40:45 2007 UTC
+revision 598 by ph10,
Sat May  7 15:37:31 2011 UTC
 Line 4 
 pcretest - a program for testing Perl-co
  .SH SYNOPSIS
  .rs
  .sp
- .B pcretest "[-C] [-d] [-dfa] [-i] [-m] [-o osize] [-p] [-t] [source]"
+ .B pcretest "[options] [source] [destination]"
- .ti +5n
+ .sp
- .B "[destination]"
- .P
  \fBpcretest\fP was written as a test program for the PCRE regular expression
  library itself, but it can also be used for experimenting with regular
  expressions. This document describes the features of the test program; for
-Line 26 
 documentation.
+Line 24 
 documentation.
  .SH OPTIONS
  .rs
  .TP 10
+ \fB-b\fP
+ Behave as if each regex has the \fB/B\fP (show bytecode) modifier; the internal
+ form is output after compilation.
+ .TP 10
  \fB-C\fP
  Output the version number of the PCRE library, and all available information
  about the optional features that are included, and then exit.
  .TP 10
  \fB-d\fP
  Behave as if each regex has the \fB/D\fP (debug) modifier; the internal
- form is output after compilation.
+ form and information about the compiled pattern is output after compilation;
+ \fB-d\fP is equivalent to \fB-b -i\fP.
  .TP 10
  \fB-dfa\fP
  Behave as if each data line contains the \eD escape sequence; this causes the
  alternative matching function, \fBpcre_dfa_exec()\fP, to be used instead of the
  standard \fBpcre_exec()\fP function (more detail is given below).
  .TP 10
+ \fB-help\fP
+ Output a brief summary these options and then exit.
+ .TP 10
  \fB-i\fP
  Behave as if each regex has the \fB/I\fP modifier; information about the
  compiled pattern is given after compilation.
  .TP 10
+ \fB-M\fP
+ Behave as if each data line contains the \eM escape sequence; this causes
+ PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by
+ calling \fBpcre_exec()\fP repeatedly with different limits.
+ .TP 10
  \fB-m\fP
  Output the size of each compiled pattern after it has been compiled. This is
  equivalent to adding \fB/M\fP to each regular expression. For compatibility
-Line 50 
 with earlier versions of pcretest, \fB-s
+Line 61 
 with earlier versions of pcretest, \fB-s
  .TP 10
  \fB-o\fP \fIosize\fP
  Set the number of elements in the output vector that is used when calling
- \fBpcre_exec()\fP to be \fIosize\fP. The default value is 45, which is enough
+ \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP to be \fIosize\fP. The default value
- for 14 capturing subexpressions. The vector size can be changed for individual
+ is 45, which is enough for 14 capturing subexpressions for \fBpcre_exec()\fP or
- matching calls by including \eO in the data line (see below).
+different matches for \fBpcre_dfa_exec()\fP. The vector size can be
+ changed for individual matching calls by including \eO in the data line (see
+ below).
  .TP 10
  \fB-p\fP
  Behave as if each regex has the \fB/P\fP modifier; the POSIX wrapper API is
  used to call PCRE. None of the other options has any effect when \fB-p\fP is
  set.
  .TP 10
+ \fB-q\fP
+ Do not output the version number of \fBpcretest\fP at the start of execution.
+ .TP 10
+ \fB-S\fP \fIsize\fP
+ On Unix-like systems, set the size of the runtime stack to \fIsize\fP
+ megabytes.
+ .TP 10
  \fB-t\fP
  Run each compile, study, and match many times with a timer, and output
  resulting time per compile or match (in milliseconds). Do not set \fB-m\fP with
  \fB-t\fP, because you will then get the size output a zillion times, and the
- timing will be distorted.
+ timing will be distorted. You can control the number of iterations that are
+ used for timing by following \fB-t\fP with a number (as a separate item on the
+ command line). For example, "-t 1000" would iterate 1000 times. The default is
+ to iterate 500000 times.
+ .TP 10
+ \fB-tm\fP
+ This is like \fB-t\fP except that it times only the matching phase, not the
+ compile or study phases.
  .
  .
  .SH DESCRIPTION
-Line 75 
 that file and writes to stdout. Otherwis
+Line 102 
 that file and writes to stdout. Otherwis
  stdout, and prompts for each line of input, using "re>" to prompt for regular
  expressions, and "data>" to prompt for data lines.
  .P
+ When \fBpcretest\fP is built, a configuration option can specify that it should
+ be linked with the \fBlibreadline\fP library. When this is done, if the input
+ is from a terminal, it is read using the \fBreadline()\fP function. This
+ provides line-editing and history facilities. The output from the \fB-help\fP
+ option states whether or not \fBreadline()\fP will be used.
+ .P
  The program handles any number of sets of input on a single input file. Each
  set starts with a regular expression, and continues with any number of data
  lines to be matched against the pattern.
  .P
  Each data line is matched separately and independently. If you want to do
- multiple-line matches, you have to use the \en escape sequence in a single line
+ multi-line matches, you have to use the \en escape sequence (or \er or \er\en,
- of input to encode the newline characters. The maximum length of data line is
+ etc., depending on the newline setting) in a single line of input to encode the
-,000 characters.
+ newline sequences. There is no limit on the length of data lines; the input
+ buffer is automatically extended if it is too small.
  .P
  An empty line signals the end of the data lines, at which point a new regular
  expression is read. The regular expressions are given enclosed in any
- non-alphanumeric delimiters other than backslash, for example
+ non-alphanumeric delimiters other than backslash, for example:
  .sp
    /(a|bc)x+yz/
  .sp
-Line 131 
 effect as they do in Perl. For example:
+Line 165 
 effect as they do in Perl. For example:
  .sp
    /caseless/i
  .sp
- The following table shows additional modifiers for setting PCRE options that do
+ The following table shows additional modifiers for setting PCRE compile-time
- not correspond to anything in Perl:
+ options that do not correspond to anything in Perl:
  .sp
-   \fB/A\fP    PCRE_ANCHORED
+   \fB/8\fP              PCRE_UTF8
-   \fB/C\fP    PCRE_AUTO_CALLOUT
+   \fB/?\fP              PCRE_NO_UTF8_CHECK
-   \fB/E\fP    PCRE_DOLLAR_ENDONLY
+   \fB/A\fP              PCRE_ANCHORED
-   \fB/f\fP    PCRE_FIRSTLINE
+   \fB/C\fP              PCRE_AUTO_CALLOUT
-   \fB/N\fP    PCRE_NO_AUTO_CAPTURE
+   \fB/E\fP              PCRE_DOLLAR_ENDONLY
-   \fB/U\fP    PCRE_UNGREEDY
+   \fB/f\fP              PCRE_FIRSTLINE
-   \fB/X\fP    PCRE_EXTRA
+   \fB/J\fP              PCRE_DUPNAMES
+   \fB/N\fP              PCRE_NO_AUTO_CAPTURE
+   \fB/U\fP              PCRE_UNGREEDY
+   \fB/W\fP              PCRE_UCP
+   \fB/X\fP              PCRE_EXTRA
+   \fB/Y\fP              PCRE_NO_START_OPTIMIZE
+   \fB/<JS>\fP           PCRE_JAVASCRIPT_COMPAT
+   \fB/<cr>\fP           PCRE_NEWLINE_CR
+   \fB/<lf>\fP           PCRE_NEWLINE_LF
+   \fB/<crlf>\fP         PCRE_NEWLINE_CRLF
+   \fB/<anycrlf>\fP      PCRE_NEWLINE_ANYCRLF
+   \fB/<any>\fP          PCRE_NEWLINE_ANY
+   \fB/<bsr_anycrlf>\fP  PCRE_BSR_ANYCRLF
+   \fB/<bsr_unicode>\fP  PCRE_BSR_UNICODE
+ .sp
+ The modifiers that are enclosed in angle brackets are literal strings as shown,
+ including the angle brackets, but the letters can be in either case. This
+ example sets multiline matching with CRLF as the line ending sequence:
+ .sp
+   /^abc/m<crlf>
+ .sp
+ As well as turning on the PCRE_UTF8 option, the \fB/8\fP modifier also causes
+ any non-printing characters in output strings to be printed using the
+ \ex{hh...} notation if they are valid UTF-8 sequences. Full details of the PCRE
+ options are given in the
+ .\" HREF
+ \fBpcreapi\fP
+ .\"
+ documentation.
+ .
+ .
+ .SS "Finding all matches in a string"
+ .rs
  .sp
  Searching for all possible matches within each subject string can be requested
  by the \fB/g\fP or \fB/G\fP modifier. After finding a match, PCRE is called
-Line 152 
 substring. This makes a difference to th
+Line 218 
 substring. This makes a difference to th
  begins with a lookbehind assertion (including \eb or \eB).
  .P
  If any call to \fBpcre_exec()\fP in a \fB/g\fP or \fB/G\fP sequence matches an
- empty string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED
+ empty string, the next call is done with the PCRE_NOTEMPTY_ATSTART and
- flags set in order to search for another, non-empty, match at the same point.
+ PCRE_ANCHORED flags set in order to search for another, non-empty, match at the
- If this second match fails, the start offset is advanced by one, and the normal
+ same point. If this second match fails, the start offset is advanced, and the
- match is retried. This imitates the way Perl handles such cases when using the
+ normal match is retried. This imitates the way Perl handles such cases when
- \fB/g\fP modifier or the \fBsplit()\fP function.
+ using the \fB/g\fP modifier or the \fBsplit()\fP function. Normally, the start
- .P
+ offset is advanced by one character, but if the newline convention recognizes
+ CRLF as a newline, and the current character is CR followed by LF, an advance
+ of two is used.
+ .
+ .
+ .SS "Other modifiers"
+ .rs
+ .sp
  There are yet more modifiers for controlling the way \fBpcretest\fP
  operates.
  .P
-Line 166 
 matched the entire pattern, pcretest sho
+Line 239 
 matched the entire pattern, pcretest sho
  the subject string. This is useful for tests where the subject contains
  multiple copies of the same substring.
  .P
- The \fB/L\fP modifier must be followed directly by the name of a locale, for
+ The \fB/B\fP modifier is a debugging feature. It requests that \fBpcretest\fP
- example,
+ output a representation of the compiled byte code after compilation. Normally
- .sp
+ this information contains length and offset values; however, if \fB/Z\fP is
-   /pattern/Lfr_FR
+ also present, this data is replaced by spaces. This is a special feature for
- .sp
+ use in the automatic test scripts; it ensures that the same output is generated
- For this reason, it must be the last modifier. The given locale is set,
+ for different internal link sizes.
- \fBpcre_maketables()\fP is called to build a set of character tables for the
- locale, and this is then passed to \fBpcre_compile()\fP when compiling the
- regular expression. Without an \fB/L\fP modifier, NULL is passed as the tables
- pointer; that is, \fB/L\fP applies only to the expression on which it appears.
  .P
- The \fB/I\fP modifier requests that \fBpcretest\fP output information about the
+ The \fB/D\fP modifier is a PCRE debugging feature, and is equivalent to
- compiled pattern (whether it is anchored, has a fixed first character, and
+ \fB/BI\fP, that is, both the \fB/B\fP and the \fB/I\fP modifiers.
- so on). It does this by calling \fBpcre_fullinfo()\fP after compiling a
- pattern. If the pattern is studied, the results of that are also output.
- .P
- The \fB/D\fP modifier is a PCRE debugging feature, which also assumes \fB/I\fP.
- It causes the internal form of compiled regular expressions to be output after
- compilation. If the pattern was studied, the information returned is also
- output.
  .P
  The \fB/F\fP modifier causes \fBpcretest\fP to flip the byte order of the
  fields in the compiled pattern that contain 2-byte and 4-byte numbers. This
-Line 195 
 available when the POSIX interface to PC
+Line 257 
 available when the POSIX interface to PC
  \fB/P\fP pattern modifier is specified. See also the section about saving and
  reloading compiled patterns below.
  .P
- The \fB/S\fP modifier causes \fBpcre_study()\fP to be called after the
+ The \fB/I\fP modifier requests that \fBpcretest\fP output information about the
- expression has been compiled, and the results used when the expression is
+ compiled pattern (whether it is anchored, has a fixed first character, and
- matched.
+ so on). It does this by calling \fBpcre_fullinfo()\fP after compiling a
+ pattern. If the pattern is studied, the results of that are also output.
+ .P
+ The \fB/K\fP modifier requests \fBpcretest\fP to show names from backtracking
+ control verbs that are returned from calls to \fBpcre_exec()\fP. It causes
+ \fBpcretest\fP to create a \fBpcre_extra\fP block if one has not already been
+ created by a call to \fBpcre_study()\fP, and to set the PCRE_EXTRA_MARK flag
+ and the \fBmark\fP field within it, every time that \fBpcre_exec()\fP is
+ called. If the variable that the \fBmark\fP field points to is non-NULL for a
+ match, non-match, or partial match, \fBpcretest\fP prints the string to which
+ it points. For a match, this is shown on a line by itself, tagged with "MK:".
+ For a non-match it is added to the message.
+ .P
+ The \fB/L\fP modifier must be followed directly by the name of a locale, for
+ example,
+ .sp
+   /pattern/Lfr_FR
+ .sp
+ For this reason, it must be the last modifier. The given locale is set,
+ \fBpcre_maketables()\fP is called to build a set of character tables for the
+ locale, and this is then passed to \fBpcre_compile()\fP when compiling the
+ regular expression. Without an \fB/L\fP (or \fB/T\fP) modifier, NULL is passed
+ as the tables pointer; that is, \fB/L\fP applies only to the expression on
+ which it appears.
  .P
  The \fB/M\fP modifier causes the size of memory block used to hold the compiled
  pattern to be output.
  .P
+ The \fB/S\fP modifier causes \fBpcre_study()\fP to be called after the
+ expression has been compiled, and the results used when the expression is
+ matched.
+ .P
+ The \fB/T\fP modifier must be followed by a single digit. It causes a specific
+ set of built-in character tables to be passed to \fBpcre_compile()\fP. It is
+ used in the standard PCRE tests to check behaviour with different character
+ tables. The digit specifies the tables as follows:
+ .sp
+  the default ASCII tables, as distributed in
+         pcre_chartables.c.dist
+  a set of tables defining ISO 8859 characters
+ .sp
+ In table 1, some characters whose codes are greater than 128 are identified as
+ letters, digits, spaces, etc.
+ .
+ .
+ .SS "Using the POSIX wrapper API"
+ .rs
+ .sp
  The \fB/P\fP modifier causes \fBpcretest\fP to call PCRE via the POSIX wrapper
- API rather than its native API. When this is done, all other modifiers except
+ API rather than its native API. When \fB/P\fP is set, the following modifiers
- \fB/i\fP, \fB/m\fP, and \fB/+\fP are ignored. REG_ICASE is set if \fB/i\fP is
+ set options for the \fBregcomp()\fP function:
- present, and REG_NEWLINE is set if \fB/m\fP is present. The wrapper functions
+ .sp
- force PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set.
+   /i    REG_ICASE
- .P
+   /m    REG_NEWLINE
- The \fB/8\fP modifier causes \fBpcretest\fP to call PCRE with the PCRE_UTF8
+   /N    REG_NOSUB
- option set. This turns on support for UTF-8 character handling in PCRE,
+   /s    REG_DOTALL     )
- provided that it was compiled with this support enabled. This modifier also
+   /U    REG_UNGREEDY   ) These options are not part of
- causes any non-printing characters in output strings to be printed using the
+   /W    REG_UCP        )   the POSIX standard
- \ex{hh...} notation if they are valid UTF-8 sequences.
+   /8    REG_UTF8       )
- .P
+ .sp
- If the \fB/?\fP modifier is used with \fB/8\fP, it causes \fBpcretest\fP to
+ The \fB/+\fP modifier works as described above. All other modifiers are
- call \fBpcre_compile()\fP with the PCRE_NO_UTF8_CHECK option, to suppress the
+ ignored.
- checking of the string for UTF-8 validity.
  .
  .
  .SH "DATA LINES"
-Line 229 
 complicated features of PCRE. If you are
+Line 333 
 complicated features of PCRE. If you are
  expressions, you probably don't need any of these. The following escapes are
  recognized:
  .sp
-   \ea         alarm (= BEL)
+   \ea         alarm (BEL, \ex07)
-   \eb         backspace
+   \eb         backspace (\ex08)
-   \ee         escape
+   \ee         escape (\ex27)
-   \ef         formfeed
+   \ef         formfeed (\ex0c)
-   \en         newline
+   \en         newline (\ex0a)
-   \er         carriage return
+ .\" JOIN
-   \et         tab
+   \eqdd       set the PCRE_MATCH_LIMIT limit to dd
-   \ev         vertical tab
+                (any number of digits)
+   \er         carriage return (\ex0d)
+   \et         tab (\ex09)
+   \ev         vertical tab (\ex0b)
    \ennn       octal character (up to 3 octal digits)
-   \exhh       hexadecimal character (up to 2 hex digits)
+                always a byte unless > 255 in UTF-8 mode
+   \exhh       hexadecimal byte (up to 2 hex digits)
  .\" JOIN
    \ex{hh...}  hexadecimal character, any number of digits
                 in UTF-8 mode
+ .\" JOIN
    \eA         pass the PCRE_ANCHORED option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
    \eB         pass the PCRE_NOTBOL option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
  .\" JOIN
    \eCdd       call pcre_copy_substring() for substring dd
                 after a successful match (number less than 32)
-Line 276 
 recognized:
+Line 388 
 recognized:
  .\" JOIN
    \eL         call pcre_get_substringlist() after a
                 successful match
-   \eM         discover the minimum MATCH_LIMIT setting
+ .\" JOIN
+   \eM         discover the minimum MATCH_LIMIT and
+                MATCH_LIMIT_RECURSION settings
+ .\" JOIN
    \eN         pass the PCRE_NOTEMPTY option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP; if used twice, pass the
+                PCRE_NOTEMPTY_ATSTART option
  .\" JOIN
    \eOdd       set the size of the output vector passed to
                 \fBpcre_exec()\fP to dd (any number of digits)
  .\" JOIN
-   \eP         pass the PCRE_PARTIAL option to \fBpcre_exec()\fP
+   \eP         pass the PCRE_PARTIAL_SOFT option to \fBpcre_exec()\fP
-                or \fBpcre_dfa_exec()\fP
+                or \fBpcre_dfa_exec()\fP; if used twice, pass the
+                PCRE_PARTIAL_HARD option
+ .\" JOIN
+   \eQdd       set the PCRE_MATCH_LIMIT_RECURSION limit to dd
+                (any number of digits)
    \eR         pass the PCRE_DFA_RESTART option to \fBpcre_dfa_exec()\fP
    \eS         output details of memory get/free calls during matching
+ .\" JOIN
+   \eY         pass the PCRE_NO_START_OPTIMIZE option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
    \eZ         pass the PCRE_NOTEOL option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
  .\" JOIN
    \e?         pass the PCRE_NO_UTF8_CHECK option to
-                \fBpcre_exec()\fP
+                \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP
-   \e>dd       start the match at offset dd (any number of digits);
+ .\" JOIN
-                this sets the \fIstartoffset\fP argument for \fBpcre_exec()\fP
+   \e>dd       start the match at offset dd (optional "-"; then
- .sp
+                any number of digits); this sets the \fIstartoffset\fP
- A backslash followed by anything else just escapes the anything else. If the
+                argument for \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP
- very last character is a backslash, it is ignored. This gives a way of passing
+ .\" JOIN
- an empty line as data, since a real empty line terminates the data input.
+   \e<cr>      pass the PCRE_NEWLINE_CR option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
+   \e<lf>      pass the PCRE_NEWLINE_LF option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
+   \e<crlf>    pass the PCRE_NEWLINE_CRLF option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
+   \e<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .\" JOIN
+   \e<any>     pass the PCRE_NEWLINE_ANY option to \fBpcre_exec()\fP
+                or \fBpcre_dfa_exec()\fP
+ .sp
+ Note that \exhh always specifies one byte, even in UTF-8 mode; this makes it
+ possible to construct invalid UTF-8 sequences for testing purposes. On the
+ other hand, \ex{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 not in
+ UTF-8 mode, it generates one byte for values less than 256, and causes an error
+ for greater values.
+ .P
+ 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.
+ .P
+ 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 terminates the data
+ input.
  .P
  If \eM is present, \fBpcretest\fP calls \fBpcre_exec()\fP several times, with
- different values in the \fImatch_limit\fP field of the \fBpcre_extra\fP data
+ different values in the \fImatch_limit\fP and \fImatch_limit_recursion\fP
- structure, until it finds the minimum number that is needed for
+ fields of the \fBpcre_extra\fP data structure, until it finds the minimum
- \fBpcre_exec()\fP to complete. This number is a measure of the amount of
+ numbers for each parameter that allow \fBpcre_exec()\fP to complete. The
- recursion and backtracking that takes place, and checking it out can be
+ \fImatch_limit\fP number is a measure of the amount of backtracking that takes
- instructive. For most simple matches, the number is quite small, but for
+ place, and checking it out can be instructive. For most simple matches, the
- patterns with very large numbers of matching possibilities, it can become large
+ number is quite small, but for patterns with very large numbers of matching
- very quickly with increasing length of subject string.
+ possibilities, it can become large very quickly with increasing length of
+ subject string. The \fImatch_limit_recursion\fP 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.
  .P
  When \eO is used, the value specified may be higher or lower than the size set
  by the \fB-O\fP command line option (or defaulted to 45); \eO applies only to
  the call of \fBpcre_exec()\fP for the line in which it appears.
  .P
  If the \fB/P\fP modifier was present on the pattern, causing the POSIX wrapper
- API to be used, only \eB and \eZ have any effect, causing REG_NOTBOL and
+ API to be used, the only option-setting sequences that have any effect are \eB,
- REG_NOTEOL to be passed to \fBregexec()\fP respectively.
+ \eN, and \eZ, causing REG_NOTBOL, REG_NOTEMPTY, and REG_NOTEOL, respectively,
+ to be passed to \fBregexec()\fP.
  .P
  The use of \ex{hh...} to represent UTF-8 characters is not dependent on the use
  of the \fB/8\fP modifier on the pattern. It is recognized always. There may be
  any number of hexadecimal digits inside the braces. The result is from one to
- six bytes, encoded according to the UTF-8 rules.
+ six bytes, encoded according to the original UTF-8 rules of RFC 2279. This
+ allows for values in the range 0 to 0x7FFFFFFF. Note that not all of those are
+ valid Unicode code points, or indeed valid UTF-8 characters according to the
+ later rules in RFC 3629.
  .
  .
  .SH "THE ALTERNATIVE MATCHING FUNCTION"
-Line 346 
 found. This is always the shortest possi
+Line 507 
 found. This is always the shortest possi
  This section describes the output when the normal matching function,
  \fBpcre_exec()\fP, is being used.
  .P
- When a match succeeds, pcretest outputs the list of captured substrings that
+ When a match succeeds, \fBpcretest\fP outputs the list of captured substrings
- \fBpcre_exec()\fP returns, starting with number 0 for the string that matched
+ that \fBpcre_exec()\fP returns, starting with number 0 for the string that
- the whole pattern. Otherwise, it outputs "No match" or "Partial match"
+ matched the whole pattern. Otherwise, it outputs "No match" when the return is
- when \fBpcre_exec()\fP returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PARTIAL,
+ PCRE_ERROR_NOMATCH, and "Partial match:" followed by the partially matching
- respectively, and otherwise the PCRE negative error number. Here is an example
+ substring when \fBpcre_exec()\fP returns PCRE_ERROR_PARTIAL. (Note that this is
- of an interactive \fBpcretest\fP run.
+ the entire substring that was inspected during the partial match; it may
+ include characters before the actual match start if a lookbehind assertion,
+ \eK, \eb, or \eB was involved.) For any other return, \fBpcretest\fP outputs
+ the PCRE negative error number and a short descriptive phrase. If the error is
+ a failed UTF-8 string check, the byte 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
+ \fBpcretest\fP run.
  .sp
    $ pcretest
-   PCRE version 5.00 07-Sep-2004
+   PCRE version 8.13 2011-04-30
  .sp
      re> /^abc(\ed+)/
    data> abc123
-Line 363 
 of an interactive \fBpcretest\fP run.
+Line 531 
 of an interactive \fBpcretest\fP run.
    data> xyz
    No match
  .sp
+ Unset capturing substrings that are not followed by one that is set are not
+ returned by \fBpcre_exec()\fP, and are not shown by \fBpcretest\fP. 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.
+ .sp
+     re> /(a)|(b)/
+   data> a
+: a
+: a
+   data> b
+: b
+: <unset>
+: b
+ .sp
  If the strings contain any non-printing characters, they are output as \e0x
  escapes, or as \ex{...} escapes if the \fB/8\fP modifier was present on the
- pattern. If the pattern has the \fB/+\fP modifier, the output for substring 0
+ pattern. See below for the definition of non-printing characters. If the
- is followed by the the rest of the subject string, identified by "0+" like
+ pattern has the \fB/+\fP modifier, the output for substring 0 is followed by
- this:
+ the the rest of the subject string, identified by "0+" like this:
  .sp
      re> /cat/+
    data> cataract
-Line 386 
 matching attempts are output in sequence
+Line 569 
 matching attempts are output in sequence
 : ipp
 : pp
  .sp
- "No match" is output only if the first match attempt fails.
+ "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 \e>4 is past the end of
+ the subject string):
+ .sp
+     re> /xyz/
+   data> xyz\>4
+   Error -24 (bad offset value)
  .P
  If any of the sequences \fB\eC\fP, \fB\eG\fP, or \fB\eL\fP are present in a
  data line that is successfully matched, the substrings extracted by the
-Line 395 
 instead of a colon. This is in addition
+Line 584 
 instead of a colon. This is in addition
  length (that is, the return from the extraction function) is given in
  parentheses after each string for \fB\eC\fP and \fB\eG\fP.
  .P
- Note that while patterns can be continued over several lines (a plain ">"
+ Note that whereas patterns can be continued over several lines (a plain ">"
  prompt is used for continuations), data lines may not. However newlines can be
- included in data by means of the \en escape.
+ included in data by means of the \en escape (or \er, \er\en, etc., depending on
+ the newline sequence setting).
+ .
  .
  .
  .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"
-Line 415 
 the subject where there is at least one
+Line 606 
 the subject where there is at least one
 : tan
  .sp
  (Using the normal matching function on this data finds only "tang".) The
- longest matching string is always given first (and numbered zero).
+ longest matching string is always given first (and numbered zero). After a
+ PCRE_ERROR_PARTIAL return, the output is "Partial match:", followed 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 assertion, \eK, \eb, or \eB was involved.)
  .P
- If \fB/g\P is present on the pattern, the search for further matches resumes
+ If \fB/g\fP is present on the pattern, the search for further matches resumes
  at the end of the longest match. For example:
  .sp
      re> /(tang|tangerine|tan)/g
-Line 441 
 indicating that the subject partially ma
+Line 636 
 indicating that the subject partially ma
  match with additional subject data by means of the \eR escape sequence. For
  example:
  .sp
-     re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+     re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/
    data> 23ja\eP\eD
    Partial match: 23ja
    data> n05\eR\eD
-Line 498 
 the
+Line 693 
 the
  documentation.
  .
  .
+ .
+ .SH "NON-PRINTING CHARACTERS"
+ .rs
+ .sp
+ When \fBpcretest\fP 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.
+ .P
+ When \fBpcretest\fP 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 \fB/L\fP modifier). In this case, the \fBisprint()\fP
+ function to distinguish printing and non-printing characters.
+ .
+ .
+ .
  .SH "SAVING AND RELOADING COMPILED PATTERNS"
  .rs
  .sp
-Line 558 
 Finally, if you attempt to load a file t
+Line 768 
 Finally, if you attempt to load a file t
  result is undefined.
  .
  .
+ .SH "SEE ALSO"
+ .rs
+ .sp
+ \fBpcre\fP(3), \fBpcreapi\fP(3), \fBpcrecallout\fP(3), \fBpcrematching\fP(3),
+ \fBpcrepartial\fP(d), \fBpcrepattern\fP(3), \fBpcreprecompile\fP(3).
+ .
+ .
  .SH AUTHOR
  .rs
  .sp
+ .nf
  Philip Hazel
- .br
+ University Computing Service
- University Computing Service,
+ Cambridge CB2 3QH, England.
- .br
+ .fi
- Cambridge CB2 3QG, England.
+ .
- .P
+ .
- .in 0
+ .SH REVISION
- Last updated: 28 February 2005
+ .rs
- .br
+ .sp
- Copyright (c) 1997-2005 University of Cambridge.
+ .nf
+ Last updated: 06 May 2011
+ Copyright (c) 1997-2011 University of Cambridge.
+ .fi

 Legend:



Removed from v.77
 


changed lines


 
Added in v.598
 Legend:



Removed from v.77
 


changed lines


 
Added in v.598
-Removed from v.77
+Added in v.598

	ViewVC Help
Powered by ViewVC 1.1.5