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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1033 by ph10, Mon Sep 10 11:02:48 2012 UTC revision 1055 by chpe, Tue Oct 16 15:53:30 2012 UTC
# Line 18  options, see the Line 18  options, see the
18  .\" HREF  .\" HREF
19  \fBpcreapi\fP  \fBpcreapi\fP
20  .\"  .\"
21  and  ,
22  .\" HREF  .\" HREF
23  \fBpcre16\fP  \fBpcre16\fP
24    and
25    .\" HREF
26    \fBpcre32\fP
27  .\"  .\"
28  documentation.  documentation.
29  .P  .P
# Line 37  PCRE, and are unlikely to be of use othe Line 40  PCRE, and are unlikely to be of use othe
40  but without much justification.  but without much justification.
41  .  .
42  .  .
43  .SH "PCRE's 8-BIT and 16-BIT LIBRARIES"  .SH "PCRE's 8-BIT, 16-BIT AND 32-BIT LIBRARIES"
44  .rs  .rs
45  .sp  .sp
46  From release 8.30, two separate PCRE libraries can be built. The original one  From release 8.30, two separate PCRE libraries can be built. The original one
47  supports 8-bit character strings, whereas the newer 16-bit library supports  supports 8-bit character strings, whereas the newer 16-bit library supports
48  character strings encoded in 16-bit units. The \fBpcretest\fP program can be  character strings encoded in 16-bit units. From release 8.FIXME, a third
49  used to test both libraries. However, it is itself still an 8-bit program,  library can be built, supporting character strings encoded in 32-bit units.
50  reading 8-bit input and writing 8-bit output. When testing the 16-bit library,  The \fBpcretest\fP program can be
51  the patterns and data strings are converted to 16-bit format before being  used to test all three libraries. However, it is itself still an 8-bit program,
52  passed to the PCRE library functions. Results are converted to 8-bit for  reading 8-bit input and writing 8-bit output. When testing the 16-bit or 32-bit
53  output.  library, the patterns and data strings are converted to 16- or 32-bit format
54    before being passed to the PCRE library functions. Results are converted to
55    8-bit for output.
56  .P  .P
57  References to functions and structures of the form \fBpcre[16]_xx\fP below  References to functions and structures of the form \fBpcre[16|32]_xx\fP below
58  mean "\fBpcre_xx\fP when using the 8-bit library or \fBpcre16_xx\fP when using  mean "\fBpcre_xx\fP when using the 8-bit library or \fBpcre16_xx\fP when using
59  the 16-bit library".  the 16-bit library".
60  .  .
# Line 58  the 16-bit library". Line 63  the 16-bit library".
63  .rs  .rs
64  .TP 10  .TP 10
65  \fB-16\fP  \fB-16\fP
66  If both the 8-bit and the 16-bit libraries have been built, this option causes  If both the 8-bit or the 32-bit, and the 16-bit libraries have been built, this
67  the 16-bit library to be used. If only the 16-bit library has been built, this  option causes the 16-bit library to be used. If only the 16-bit library has been
68  is the default (so has no effect). If only the 8-bit library has been built,  built, this is the default (so has no effect). If only the 8-bit or the 32-bit
69  this option causes an error.  library has been built, this option causes an error.
70    .TP 10
71    \fB-32\fP
72    If both the 8-bit or the 16-bit, and the 32-bit libraries have been built, this
73    option causes the 32-bit library to be used. If only the 32-bit library has been
74    built, this is the default (so has no effect). If only the 8-bit or the 16-bit
75    library has been built, this option causes an error.
76  .TP 10  .TP 10
77  \fB-b\fP  \fB-b\fP
78  Behave as if each pattern has the \fB/B\fP (show byte code) modifier; the  Behave as if each pattern has the \fB/B\fP (show byte code) modifier; the
# Line 89  The following options output 1 for true Line 100  The following options output 1 for true
100    ebcdic     compiled for an EBCDIC environment    ebcdic     compiled for an EBCDIC environment
101    jit        just-in-time support is available    jit        just-in-time support is available
102    pcre16     the 16-bit library was built    pcre16     the 16-bit library was built
103      pcre32     the 32-bit library was built
104    pcre8      the 8-bit library was built    pcre8      the 8-bit library was built
105    ucp        Unicode property support is available    ucp        Unicode property support is available
106    utf        UTF-8 and/or UTF-16 support is available    utf        UTF-8 and/or UTF-16 and/or UTF-32 support is available
107  .TP 10  .TP 10
108  \fB-d\fP  \fB-d\fP
109  Behave as if each pattern has the \fB/D\fP (debug) modifier; the internal  Behave as if each pattern has the \fB/D\fP (debug) modifier; the internal
# Line 100  form and information about the compiled Line 112  form and information about the compiled
112  .TP 10  .TP 10
113  \fB-dfa\fP  \fB-dfa\fP
114  Behave as if each data line contains the \eD escape sequence; this causes the  Behave as if each data line contains the \eD escape sequence; this causes the
115  alternative matching function, \fBpcre[16]_dfa_exec()\fP, to be used instead of  alternative matching function, \fBpcre[16|32]_dfa_exec()\fP, to be used instead
116  the standard \fBpcre[16]_exec()\fP function (more detail is given below).  of the standard \fBpcre[16|32]_exec()\fP function (more detail is given below).
117  .TP 10  .TP 10
118  \fB-help\fP  \fB-help\fP
119  Output a brief summary these options and then exit.  Output a brief summary these options and then exit.
# Line 113  compiled pattern is given after compilat Line 125  compiled pattern is given after compilat
125  \fB-M\fP  \fB-M\fP
126  Behave as if each data line contains the \eM escape sequence; this causes  Behave as if each data line contains the \eM escape sequence; this causes
127  PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by  PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by
128  calling \fBpcre[16]_exec()\fP repeatedly with different limits.  calling \fBpcre[16|32]_exec()\fP repeatedly with different limits.
129  .TP 10  .TP 10
130  \fB-m\fP  \fB-m\fP
131  Output the size of each compiled pattern after it has been compiled. This is  Output the size of each compiled pattern after it has been compiled. This is
# Line 122  bytes for both libraries. Line 134  bytes for both libraries.
134  .TP 10  .TP 10
135  \fB-o\fP \fIosize\fP  \fB-o\fP \fIosize\fP
136  Set the number of elements in the output vector that is used when calling  Set the number of elements in the output vector that is used when calling
137  \fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP to be \fIosize\fP. The  \fBpcre[16|32]_exec()\fP or \fBpcre[16|32]_dfa_exec()\fP to be \fIosize\fP. The
138  default value is 45, which is enough for 14 capturing subexpressions for  default value is 45, which is enough for 14 capturing subexpressions for
139  \fBpcre[16]_exec()\fP or 22 different matches for \fBpcre[16]_dfa_exec()\fP.  \fBpcre[16|32]_exec()\fP or 22 different matches for
140    \fBpcre[16|32]_dfa_exec()\fP.
141  The vector size can be changed for individual matching calls by including \eO  The vector size can be changed for individual matching calls by including \eO
142  in the data line (see below).  in the data line (see below).
143  .TP 10  .TP 10
# Line 143  megabytes. Line 156  megabytes.
156  \fB-s\fP or \fB-s+\fP  \fB-s\fP or \fB-s+\fP
157  Behave as if each pattern has the \fB/S\fP modifier; in other words, force each  Behave as if each pattern has the \fB/S\fP modifier; in other words, force each
158  pattern to be studied. If \fB-s+\fP is used, all the JIT compile options are  pattern to be studied. If \fB-s+\fP is used, all the JIT compile options are
159  passed to \fBpcre[16]_study()\fP, causing just-in-time optimization to be set  passed to \fBpcre[16|32]_study()\fP, causing just-in-time optimization to be set
160  up if it is available, for both full and partial matching. Specific JIT compile  up if it is available, for both full and partial matching. Specific JIT compile
161  options can be selected by following \fB-s+\fP with a digit in the range 1 to  options can be selected by following \fB-s+\fP with a digit in the range 1 to
162  7, which selects the JIT compile modes as follows:  7, which selects the JIT compile modes as follows:
# Line 310  sections. Line 323  sections.
323  .sp  .sp
324  The \fB/i\fP, \fB/m\fP, \fB/s\fP, and \fB/x\fP modifiers set the PCRE_CASELESS,  The \fB/i\fP, \fB/m\fP, \fB/s\fP, and \fB/x\fP modifiers set the PCRE_CASELESS,
325  PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when  PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when
326  \fBpcre[16]_compile()\fP is called. These four modifier letters have the same  \fBpcre[16|32]_compile()\fP is called. These four modifier letters have the same
327  effect as they do in Perl. For example:  effect as they do in Perl. For example:
328  .sp  .sp
329    /caseless/i    /caseless/i
# Line 329  options that do not correspond to anythi Line 342  options that do not correspond to anythi
342    \fB/8\fP              PCRE_UTF16          ) when using the 16-bit    \fB/8\fP              PCRE_UTF16          ) when using the 16-bit
343    \fB/?\fP              PCRE_NO_UTF16_CHECK )   library    \fB/?\fP              PCRE_NO_UTF16_CHECK )   library
344  .sp  .sp
345      \fB/8\fP              PCRE_UTF32          ) when using the 32-bit
346      \fB/?\fP              PCRE_NO_UTF32_CHECK )   library
347    .sp
348    \fB/A\fP              PCRE_ANCHORED    \fB/A\fP              PCRE_ANCHORED
349    \fB/C\fP              PCRE_AUTO_CALLOUT    \fB/C\fP              PCRE_AUTO_CALLOUT
350    \fB/E\fP              PCRE_DOLLAR_ENDONLY    \fB/E\fP              PCRE_DOLLAR_ENDONLY
# Line 354  This example sets multiline matching wit Line 370  This example sets multiline matching wit
370  .sp  .sp
371    /^abc/m<CRLF>    /^abc/m<CRLF>
372  .sp  .sp
373  As well as turning on the PCRE_UTF8/16 option, the \fB/8\fP modifier causes  As well as turning on the PCRE_UTF8/16/32 option, the \fB/8\fP modifier causes
374  all non-printing characters in output strings to be printed using the  all non-printing characters in output strings to be printed using the
375  \ex{hh...} notation. Otherwise, those less than 0x100 are output in hex without  \ex{hh...} notation. Otherwise, those less than 0x100 are output in hex without
376  the curly brackets.  the curly brackets.
# Line 373  Searching for all possible matches withi Line 389  Searching for all possible matches withi
389  by the \fB/g\fP or \fB/G\fP modifier. After finding a match, PCRE is called  by the \fB/g\fP or \fB/G\fP modifier. After finding a match, PCRE is called
390  again to search the remainder of the subject string. The difference between  again to search the remainder of the subject string. The difference between
391  \fB/g\fP and \fB/G\fP is that the former uses the \fIstartoffset\fP argument to  \fB/g\fP and \fB/G\fP is that the former uses the \fIstartoffset\fP argument to
392  \fBpcre[16]_exec()\fP to start searching at a new point within the entire  \fBpcre[16|32]_exec()\fP to start searching at a new point within the entire
393  string (which is in effect what Perl does), whereas the latter passes over a  string (which is in effect what Perl does), whereas the latter passes over a
394  shortened substring. This makes a difference to the matching process if the  shortened substring. This makes a difference to the matching process if the
395  pattern begins with a lookbehind assertion (including \eb or \eB).  pattern begins with a lookbehind assertion (including \eb or \eB).
396  .P  .P
397  If any call to \fBpcre[16]_exec()\fP in a \fB/g\fP or \fB/G\fP sequence matches  If any call to \fBpcre[16|32]_exec()\fP in a \fB/g\fP or \fB/G\fP sequence matches
398  an empty string, the next call is done with the PCRE_NOTEMPTY_ATSTART and  an empty string, the next call is done with the PCRE_NOTEMPTY_ATSTART and
399  PCRE_ANCHORED flags set in order to search for another, non-empty, match at the  PCRE_ANCHORED flags set in order to search for another, non-empty, match at the
400  same point. If this second match fails, the start offset is advanced, and the  same point. If this second match fails, the start offset is advanced, and the
# Line 407  modifier because /S+ and /S++ have other Line 423  modifier because /S+ and /S++ have other
423  The \fB/=\fP modifier requests that the values of all potential captured  The \fB/=\fP modifier requests that the values of all potential captured
424  parentheses be output after a match. By default, only those up to the highest  parentheses be output after a match. By default, only those up to the highest
425  one actually used in the match are output (corresponding to the return code  one actually used in the match are output (corresponding to the return code
426  from \fBpcre[16]_exec()\fP). Values in the offsets vector corresponding to  from \fBpcre[16|32]_exec()\fP). Values in the offsets vector corresponding to
427  higher numbers should be set to -1, and these are output as "<unset>". This  higher numbers should be set to -1, and these are output as "<unset>". This
428  modifier gives a way of checking that this is happening.  modifier gives a way of checking that this is happening.
429  .P  .P
# Line 431  below. Line 447  below.
447  .P  .P
448  The \fB/I\fP modifier requests that \fBpcretest\fP output information about the  The \fB/I\fP modifier requests that \fBpcretest\fP output information about the
449  compiled pattern (whether it is anchored, has a fixed first character, and  compiled pattern (whether it is anchored, has a fixed first character, and
450  so on). It does this by calling \fBpcre[16]_fullinfo()\fP after compiling a  so on). It does this by calling \fBpcre[16|32]_fullinfo()\fP after compiling a
451  pattern. If the pattern is studied, the results of that are also output.  pattern. If the pattern is studied, the results of that are also output.
452  .P  .P
453  The \fB/K\fP modifier requests \fBpcretest\fP to show names from backtracking  The \fB/K\fP modifier requests \fBpcretest\fP to show names from backtracking
454  control verbs that are returned from calls to \fBpcre[16]_exec()\fP. It causes  control verbs that are returned from calls to \fBpcre[16|32]_exec()\fP. It causes
455  \fBpcretest\fP to create a \fBpcre[16]_extra\fP block if one has not already  \fBpcretest\fP to create a \fBpcre[16|32]_extra\fP block if one has not already
456  been created by a call to \fBpcre[16]_study()\fP, and to set the  been created by a call to \fBpcre[16|32]_study()\fP, and to set the
457  PCRE_EXTRA_MARK flag and the \fBmark\fP field within it, every time that  PCRE_EXTRA_MARK flag and the \fBmark\fP field within it, every time that
458  \fBpcre[16]_exec()\fP is called. If the variable that the \fBmark\fP field  \fBpcre[16|32]_exec()\fP is called. If the variable that the \fBmark\fP field
459  points to is non-NULL for a match, non-match, or partial match, \fBpcretest\fP  points to is non-NULL for a match, non-match, or partial match, \fBpcretest\fP
460  prints the string to which it points. For a match, this is shown on a line by  prints the string to which it points. For a match, this is shown on a line by
461  itself, tagged with "MK:". For a non-match it is added to the message.  itself, tagged with "MK:". For a non-match it is added to the message.
# Line 450  example, Line 466  example,
466    /pattern/Lfr_FR    /pattern/Lfr_FR
467  .sp  .sp
468  For this reason, it must be the last modifier. The given locale is set,  For this reason, it must be the last modifier. The given locale is set,
469  \fBpcre[16]_maketables()\fP is called to build a set of character tables for  \fBpcre[16|32]_maketables()\fP is called to build a set of character tables for
470  the locale, and this is then passed to \fBpcre[16]_compile()\fP when compiling  the locale, and this is then passed to \fBpcre[16|32]_compile()\fP when compiling
471  the regular expression. Without an \fB/L\fP (or \fB/T\fP) modifier, NULL is  the regular expression. Without an \fB/L\fP (or \fB/T\fP) modifier, NULL is
472  passed as the tables pointer; that is, \fB/L\fP applies only to the expression  passed as the tables pointer; that is, \fB/L\fP applies only to the expression
473  on which it appears.  on which it appears.
474  .P  .P
475  The \fB/M\fP modifier causes the size in bytes of the memory block used to hold  The \fB/M\fP modifier causes the size in bytes of the memory block used to hold
476  the compiled pattern to be output. This does not include the size of the  the compiled pattern to be output. This does not include the size of the
477  \fBpcre[16]\fP block; it is just the actual compiled data. If the pattern is  \fBpcre[16|32]\fP block; it is just the actual compiled data. If the pattern is
478  successfully studied with the PCRE_STUDY_JIT_COMPILE option, the size of the  successfully studied with the PCRE_STUDY_JIT_COMPILE option, the size of the
479  JIT compiled code is also output.  JIT compiled code is also output.
480  .P  .P
481  The \fB/S\fP modifier causes \fBpcre[16]_study()\fP to be called after the  The \fB/S\fP modifier causes \fBpcre[16|32]_study()\fP to be called after the
482  expression has been compiled, and the results used when the expression is  expression has been compiled, and the results used when the expression is
483  matched. There are a number of qualifying characters that may follow \fB/S\fP.  matched. There are a number of qualifying characters that may follow \fB/S\fP.
484  They may appear in any order.  They may appear in any order.
485  .P  .P
486  If \fBS\fP is followed by an exclamation mark, \fBpcre[16]_study()\fP is called  If \fBS\fP is followed by an exclamation mark, \fBpcre[16|32]_study()\fP is called
487  with the PCRE_STUDY_EXTRA_NEEDED option, causing it always to return a  with the PCRE_STUDY_EXTRA_NEEDED option, causing it always to return a
488  \fBpcre_extra\fP block, even when studying discovers no useful information.  \fBpcre_extra\fP block, even when studying discovers no useful information.
489  .P  .P
# Line 478  never studied, independently of \fB-s\fP Line 494  never studied, independently of \fB-s\fP
494  files in a few cases where the output is different when the pattern is studied.  files in a few cases where the output is different when the pattern is studied.
495  .P  .P
496  If the \fB/S\fP modifier is followed by a + character, the call to  If the \fB/S\fP modifier is followed by a + character, the call to
497  \fBpcre[16]_study()\fP is made with all the JIT study options, requesting  \fBpcre[16|32]_study()\fP is made with all the JIT study options, requesting
498  just-in-time optimization support if it is available, for both normal and  just-in-time optimization support if it is available, for both normal and
499  partial matching. If you want to restrict the JIT compiling modes, you can  partial matching. If you want to restrict the JIT compiling modes, you can
500  follow \fB/S+\fP with a digit in the range 1 to 7:  follow \fB/S+\fP with a digit in the range 1 to 7:
# Line 498  Note that there is also an independent \ Line 514  Note that there is also an independent \
514  immediately after \fB/S\fP or \fB/S+\fP because this will be misinterpreted.  immediately after \fB/S\fP or \fB/S+\fP because this will be misinterpreted.
515  .P  .P
516  If JIT studying is successful, the compiled JIT code will automatically be used  If JIT studying is successful, the compiled JIT code will automatically be used
517  when \fBpcre[16]_exec()\fP is run, except when incompatible run-time options  when \fBpcre[16|32]_exec()\fP is run, except when incompatible run-time options
518  are specified. For more details, see the  are specified. For more details, see the
519  .\" HREF  .\" HREF
520  \fBpcrejit\fP  \fBpcrejit\fP
# Line 512  option. This makes it possible to specif Line 528  option. This makes it possible to specif
528  certain patterns.  certain patterns.
529  .P  .P
530  The \fB/T\fP modifier must be followed by a single digit. It causes a specific  The \fB/T\fP modifier must be followed by a single digit. It causes a specific
531  set of built-in character tables to be passed to \fBpcre[16]_compile()\fP. It  set of built-in character tables to be passed to \fBpcre[16|32]_compile()\fP. It
532  is used in the standard PCRE tests to check behaviour with different character  is used in the standard PCRE tests to check behaviour with different character
533  tables. The digit specifies the tables as follows:  tables. The digit specifies the tables as follows:
534  .sp  .sp
# Line 547  ignored. Line 563  ignored.
563  .SH "DATA LINES"  .SH "DATA LINES"
564  .rs  .rs
565  .sp  .sp
566  Before each data line is passed to \fBpcre[16]_exec()\fP, leading and trailing  Before each data line is passed to \fBpcre[16|32]_exec()\fP, leading and trailing
567  white space is removed, and it is then scanned for \e escapes. Some of these  white space is removed, and it is then scanned for \e escapes. Some of these
568  are pretty esoteric features, intended for checking out some of the more  are pretty esoteric features, intended for checking out some of the more
569  complicated features of PCRE. If you are just testing "ordinary" regular  complicated features of PCRE. If you are just testing "ordinary" regular
# Line 566  recognized: Line 582  recognized:
582    \et         tab (\ex09)    \et         tab (\ex09)
583    \ev         vertical tab (\ex0b)    \ev         vertical tab (\ex0b)
584    \ennn       octal character (up to 3 octal digits); always    \ennn       octal character (up to 3 octal digits); always
585                 a byte unless > 255 in UTF-8 or 16-bit mode                 a byte unless > 255 in UTF-8 or 16-bit or 32-bit mode
586    \exhh       hexadecimal byte (up to 2 hex digits)    \exhh       hexadecimal byte (up to 2 hex digits)
587    \ex{hh...}  hexadecimal character (any number of hex digits)    \ex{hh...}  hexadecimal character (any number of hex digits)
588  .\" JOIN  .\" JOIN
589    \eA         pass the PCRE_ANCHORED option to \fBpcre[16]_exec()\fP    \eA         pass the PCRE_ANCHORED option to \fBpcre[16|32]_exec()\fP
590                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
591  .\" JOIN  .\" JOIN
592    \eB         pass the PCRE_NOTBOL option to \fBpcre[16]_exec()\fP    \eB         pass the PCRE_NOTBOL option to \fBpcre[16|32]_exec()\fP
593                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
594  .\" JOIN  .\" JOIN
595    \eCdd       call pcre[16]_copy_substring() for substring dd    \eCdd       call pcre[16|32]_copy_substring() for substring dd
596                 after a successful match (number less than 32)                 after a successful match (number less than 32)
597  .\" JOIN  .\" JOIN
598    \eCname     call pcre[16]_copy_named_substring() for substring    \eCname     call pcre[16|32]_copy_named_substring() for substring
599                 "name" after a successful match (name termin-                 "name" after a successful match (name termin-
600                 ated by next non alphanumeric character)                 ated by next non alphanumeric character)
601  .\" JOIN  .\" JOIN
# Line 595  recognized: Line 611  recognized:
611  .\" JOIN  .\" JOIN
612    \eC*n       pass the number n (may be negative) as callout    \eC*n       pass the number n (may be negative) as callout
613                 data; this is used as the callout return value                 data; this is used as the callout return value
614    \eD         use the \fBpcre[16]_dfa_exec()\fP match function    \eD         use the \fBpcre[16|32]_dfa_exec()\fP match function
615    \eF         only shortest match for \fBpcre[16]_dfa_exec()\fP    \eF         only shortest match for \fBpcre[16|32]_dfa_exec()\fP
616  .\" JOIN  .\" JOIN
617    \eGdd       call pcre[16]_get_substring() for substring dd    \eGdd       call pcre[16|32]_get_substring() for substring dd
618                 after a successful match (number less than 32)                 after a successful match (number less than 32)
619  .\" JOIN  .\" JOIN
620    \eGname     call pcre[16]_get_named_substring() for substring    \eGname     call pcre[16|32]_get_named_substring() for substring
621                 "name" after a successful match (name termin-                 "name" after a successful match (name termin-
622                 ated by next non-alphanumeric character)                 ated by next non-alphanumeric character)
623  .\" JOIN  .\" JOIN
624    \eJdd       set up a JIT stack of dd kilobytes maximum (any    \eJdd       set up a JIT stack of dd kilobytes maximum (any
625                 number of digits)                 number of digits)
626  .\" JOIN  .\" JOIN
627    \eL         call pcre[16]_get_substringlist() after a    \eL         call pcre[16|32]_get_substringlist() after a
628                 successful match                 successful match
629  .\" JOIN  .\" JOIN
630    \eM         discover the minimum MATCH_LIMIT and    \eM         discover the minimum MATCH_LIMIT and
631                 MATCH_LIMIT_RECURSION settings                 MATCH_LIMIT_RECURSION settings
632  .\" JOIN  .\" JOIN
633    \eN         pass the PCRE_NOTEMPTY option to \fBpcre[16]_exec()\fP    \eN         pass the PCRE_NOTEMPTY option to \fBpcre[16|32]_exec()\fP
634                 or \fBpcre[16]_dfa_exec()\fP; if used twice, pass the                 or \fBpcre[16|32]_dfa_exec()\fP; if used twice, pass the
635                 PCRE_NOTEMPTY_ATSTART option                 PCRE_NOTEMPTY_ATSTART option
636  .\" JOIN  .\" JOIN
637    \eOdd       set the size of the output vector passed to    \eOdd       set the size of the output vector passed to
638                 \fBpcre[16]_exec()\fP to dd (any number of digits)                 \fBpcre[16|32]_exec()\fP to dd (any number of digits)
639  .\" JOIN  .\" JOIN
640    \eP         pass the PCRE_PARTIAL_SOFT option to \fBpcre[16]_exec()\fP    \eP         pass the PCRE_PARTIAL_SOFT option to \fBpcre[16|32]_exec()\fP
641                 or \fBpcre[16]_dfa_exec()\fP; if used twice, pass the                 or \fBpcre[16|32]_dfa_exec()\fP; if used twice, pass the
642                 PCRE_PARTIAL_HARD option                 PCRE_PARTIAL_HARD option
643  .\" JOIN  .\" JOIN
644    \eQdd       set the PCRE_MATCH_LIMIT_RECURSION limit to dd    \eQdd       set the PCRE_MATCH_LIMIT_RECURSION limit to dd
645                 (any number of digits)                 (any number of digits)
646    \eR         pass the PCRE_DFA_RESTART option to \fBpcre[16]_dfa_exec()\fP    \eR         pass the PCRE_DFA_RESTART option to \fBpcre[16|32]_dfa_exec()\fP
647    \eS         output details of memory get/free calls during matching    \eS         output details of memory get/free calls during matching
648  .\" JOIN  .\" JOIN
649    \eY         pass the PCRE_NO_START_OPTIMIZE option to \fBpcre[16]_exec()\fP    \eY         pass the PCRE_NO_START_OPTIMIZE option to \fBpcre[16|32]_exec()\fP
650                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
651  .\" JOIN  .\" JOIN
652    \eZ         pass the PCRE_NOTEOL option to \fBpcre[16]_exec()\fP    \eZ         pass the PCRE_NOTEOL option to \fBpcre[16|32]_exec()\fP
653                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
654  .\" JOIN  .\" JOIN
655    \e?         pass the PCRE_NO_UTF[8|16]_CHECK option to    \e?         pass the PCRE_NO_UTF[8|16|32]_CHECK option to
656                 \fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP                 \fBpcre[16|32]_exec()\fP or \fBpcre[16|32]_dfa_exec()\fP
657  .\" JOIN  .\" JOIN
658    \e>dd       start the match at offset dd (optional "-"; then    \e>dd       start the match at offset dd (optional "-"; then
659                 any number of digits); this sets the \fIstartoffset\fP                 any number of digits); this sets the \fIstartoffset\fP
660                 argument for \fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP                 argument for \fBpcre[16|32]_exec()\fP or \fBpcre[16|32]_dfa_exec()\fP
661  .\" JOIN  .\" JOIN
662    \e<cr>      pass the PCRE_NEWLINE_CR option to \fBpcre[16]_exec()\fP    \e<cr>      pass the PCRE_NEWLINE_CR option to \fBpcre[16|32]_exec()\fP
663                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
664  .\" JOIN  .\" JOIN
665    \e<lf>      pass the PCRE_NEWLINE_LF option to \fBpcre[16]_exec()\fP    \e<lf>      pass the PCRE_NEWLINE_LF option to \fBpcre[16|32]_exec()\fP
666                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
667  .\" JOIN  .\" JOIN
668    \e<crlf>    pass the PCRE_NEWLINE_CRLF option to \fBpcre[16]_exec()\fP    \e<crlf>    pass the PCRE_NEWLINE_CRLF option to \fBpcre[16|32]_exec()\fP
669                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
670  .\" JOIN  .\" JOIN
671    \e<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to \fBpcre[16]_exec()\fP    \e<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to \fBpcre[16|32]_exec()\fP
672                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
673  .\" JOIN  .\" JOIN
674    \e<any>     pass the PCRE_NEWLINE_ANY option to \fBpcre[16]_exec()\fP    \e<any>     pass the PCRE_NEWLINE_ANY option to \fBpcre[16|32]_exec()\fP
675                 or \fBpcre[16]_dfa_exec()\fP                 or \fBpcre[16|32]_dfa_exec()\fP
676  .sp  .sp
677  The use of \ex{hh...} is not dependent on the use of the \fB/8\fP modifier on  The use of \ex{hh...} is not dependent on the use of the \fB/8\fP modifier on
678  the pattern. It is recognized always. There may be any number of hexadecimal  the pattern. It is recognized always. There may be any number of hexadecimal
# Line 672  for values less than 256, and causes an Line 688  for values less than 256, and causes an
688  In UTF-16 mode, all 4-digit \ex{hhhh} values are accepted. This makes it  In UTF-16 mode, all 4-digit \ex{hhhh} values are accepted. This makes it
689  possible to construct invalid UTF-16 sequences for testing purposes.  possible to construct invalid UTF-16 sequences for testing purposes.
690  .P  .P
691    In UTF-32 mode, all 4- to 8-digit \ex{...} values are accepted. This makes it
692    possible to construct invalid UTF-32 sequences for testing purposes.
693    .P
694  The escapes that specify line ending sequences are literal strings, exactly as  The escapes that specify line ending sequences are literal strings, exactly as
695  shown. No more than one newline setting should be present in any data line.  shown. No more than one newline setting should be present in any data line.
696  .P  .P
# Line 685  used by the just-in-time optimization co Line 704  used by the just-in-time optimization co
704  is not being used. Providing a stack that is larger than the default 32K is  is not being used. Providing a stack that is larger than the default 32K is
705  necessary only for very complicated patterns.  necessary only for very complicated patterns.
706  .P  .P
707  If \eM is present, \fBpcretest\fP calls \fBpcre[16]_exec()\fP several times,  If \eM is present, \fBpcretest\fP calls \fBpcre[16|32]_exec()\fP several times,
708  with different values in the \fImatch_limit\fP and \fImatch_limit_recursion\fP  with different values in the \fImatch_limit\fP and \fImatch_limit_recursion\fP
709  fields of the \fBpcre[16]_extra\fP data structure, until it finds the minimum  fields of the \fBpcre[16|32]_extra\fP data structure, until it finds the minimum
710  numbers for each parameter that allow \fBpcre[16]_exec()\fP to complete without  numbers for each parameter that allow \fBpcre[16|32]_exec()\fP to complete without
711  error. Because this is testing a specific feature of the normal interpretive  error. Because this is testing a specific feature of the normal interpretive
712  \fBpcre[16]_exec()\fP execution, the use of any JIT optimization that might  \fBpcre[16|32]_exec()\fP execution, the use of any JIT optimization that might
713  have been set up by the \fB/S+\fP qualifier of \fB-s+\fP option is disabled.  have been set up by the \fB/S+\fP qualifier of \fB-s+\fP option is disabled.
714  .P  .P
715  The \fImatch_limit\fP number is a measure of the amount of backtracking  The \fImatch_limit\fP number is a measure of the amount of backtracking
# Line 703  needed to complete the match attempt. Line 722  needed to complete the match attempt.
722  .P  .P
723  When \eO is used, the value specified may be higher or lower than the size set  When \eO is used, the value specified may be higher or lower than the size set
724  by the \fB-O\fP command line option (or defaulted to 45); \eO applies only to  by the \fB-O\fP command line option (or defaulted to 45); \eO applies only to
725  the call of \fBpcre[16]_exec()\fP for the line in which it appears.  the call of \fBpcre[16|32]_exec()\fP for the line in which it appears.
726  .P  .P
727  If the \fB/P\fP modifier was present on the pattern, causing the POSIX wrapper  If the \fB/P\fP modifier was present on the pattern, causing the POSIX wrapper
728  API to be used, the only option-setting sequences that have any effect are \eB,  API to be used, the only option-setting sequences that have any effect are \eB,
# Line 715  to be passed to \fBregexec()\fP. Line 734  to be passed to \fBregexec()\fP.
734  .rs  .rs
735  .sp  .sp
736  By default, \fBpcretest\fP uses the standard PCRE matching function,  By default, \fBpcretest\fP uses the standard PCRE matching function,
737  \fBpcre[16]_exec()\fP to match each data line. PCRE also supports an  \fBpcre[16|32]_exec()\fP to match each data line. PCRE also supports an
738  alternative matching function, \fBpcre[16]_dfa_test()\fP, which operates in a  alternative matching function, \fBpcre[16|32]_dfa_test()\fP, which operates in a
739  different way, and has some restrictions. The differences between the two  different way, and has some restrictions. The differences between the two
740  functions are described in the  functions are described in the
741  .\" HREF  .\" HREF
# Line 735  found. This is always the shortest possi Line 754  found. This is always the shortest possi
754  .rs  .rs
755  .sp  .sp
756  This section describes the output when the normal matching function,  This section describes the output when the normal matching function,
757  \fBpcre[16]_exec()\fP, is being used.  \fBpcre[16|32]_exec()\fP, is being used.
758  .P  .P
759  When a match succeeds, \fBpcretest\fP outputs the list of captured substrings  When a match succeeds, \fBpcretest\fP outputs the list of captured substrings
760  that \fBpcre[16]_exec()\fP returns, starting with number 0 for the string that  that \fBpcre[16|32]_exec()\fP returns, starting with number 0 for the string that
761  matched the whole pattern. Otherwise, it outputs "No match" when the return is  matched the whole pattern. Otherwise, it outputs "No match" when the return is
762  PCRE_ERROR_NOMATCH, and "Partial match:" followed by the partially matching  PCRE_ERROR_NOMATCH, and "Partial match:" followed by the partially matching
763  substring when \fBpcre[16]_exec()\fP returns PCRE_ERROR_PARTIAL. (Note that  substring when \fBpcre[16|32]_exec()\fP returns PCRE_ERROR_PARTIAL. (Note that
764  this is the entire substring that was inspected during the partial match; it  this is the entire substring that was inspected during the partial match; it
765  may include characters before the actual match start if a lookbehind assertion,  may include characters before the actual match start if a lookbehind assertion,
766  \eK, \eb, or \eB was involved.) For any other return, \fBpcretest\fP outputs  \eK, \eb, or \eB was involved.) For any other return, \fBpcretest\fP outputs
# Line 761  at least two. Here is an example of an i Line 780  at least two. Here is an example of an i
780    No match    No match
781  .sp  .sp
782  Unset capturing substrings that are not followed by one that is set are not  Unset capturing substrings that are not followed by one that is set are not
783  returned by \fBpcre[16]_exec()\fP, and are not shown by \fBpcretest\fP. In the  returned by \fBpcre[16|32]_exec()\fP, and are not shown by \fBpcretest\fP. In the
784  following example, there are two capturing substrings, but when the first data  following example, there are two capturing substrings, but when the first data
785  line is matched, the second, unset substring is not shown. An "internal" unset  line is matched, the second, unset substring is not shown. An "internal" unset
786  substring is shown as "<unset>", as for the second data line.  substring is shown as "<unset>", as for the second data line.
# Line 824  the newline sequence setting). Line 843  the newline sequence setting).
843  .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"  .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"
844  .rs  .rs
845  .sp  .sp
846  When the alternative matching function, \fBpcre[16]_dfa_exec()\fP, is used (by  When the alternative matching function, \fBpcre[16|32]_dfa_exec()\fP, is used (by
847  means of the \eD escape sequence or the \fB-dfa\fP command line option), the  means of the \eD escape sequence or the \fB-dfa\fP command line option), the
848  output consists of a list of all the matches that start at the first point in  output consists of a list of all the matches that start at the first point in
849  the subject where there is at least one match. For example:  the subject where there is at least one match. For example:
# Line 1030  result is undefined. Line 1049  result is undefined.
1049  .SH "SEE ALSO"  .SH "SEE ALSO"
1050  .rs  .rs
1051  .sp  .sp
1052  \fBpcre\fP(3), \fBpcre16\fP(3), \fBpcreapi\fP(3), \fBpcrecallout\fP(3),  \fBpcre\fP(3), \fBpcre16\fP(3), \fBpcre32\fP(3), \fBpcreapi\fP(3),
1053    \fBpcrecallout\fP(3),
1054  \fBpcrejit\fP, \fBpcrematching\fP(3), \fBpcrepartial\fP(d),  \fBpcrejit\fP, \fBpcrematching\fP(3), \fBpcrepartial\fP(d),
1055  \fBpcrepattern\fP(3), \fBpcreprecompile\fP(3).  \fBpcrepattern\fP(3), \fBpcreprecompile\fP(3).
1056  .  .

Legend:
Removed from v.1033  
changed lines
  Added in v.1055

  ViewVC Help
Powered by ViewVC 1.1.5