/[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 654 by ph10, Tue Aug 2 11:00:40 2011 UTC revision 678 by ph10, Sun Aug 28 15:23:03 2011 UTC
# Line 81  Do not output the version number of \fBp Line 81  Do not output the version number of \fBp
81  On Unix-like systems, set the size of the run-time stack to \fIsize\fP  On Unix-like systems, set the size of the run-time stack to \fIsize\fP
82  megabytes.  megabytes.
83  .TP 10  .TP 10
84  \fB-s\fP  \fB-s\fP or \fB-s+\fP
85  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
86  pattern to be studied. If the \fB/I\fP or \fB/D\fP option is present on a  pattern to be studied. If \fB-s+\fP is used, the PCRE_STUDY_JIT_COMPILE flag is
87  pattern (requesting output about the compiled pattern), information about the  passed to \fBpcre_study()\fP, causing just-in-time optimization to be set up if
88  result of studying is not included when studying is caused only by \fB-s\fP and  it is available. If the \fB/I\fP or \fB/D\fP option is present on a pattern
89  neither \fB-i\fP nor \fB-d\fP is present on the command line. This behaviour  (requesting output about the compiled pattern), information about the result of
90  means that the output from tests that are run with and without \fB-s\fP should  studying is not included when studying is caused only by \fB-s\fP and neither
91  be identical, except when options that output information about the actual  \fB-i\fP nor \fB-d\fP is present on the command line. This behaviour means that
92  running of a match are set. The \fB-M\fP, \fB-t\fP, and \fB-tm\fP options,  the output from tests that are run with and without \fB-s\fP should be
93  which give information about resources used, are likely to produce different  identical, except when options that output information about the actual running
94  output with and without \fB-s\fP. Output may also differ if the \fB/C\fP option  of a match are set. The \fB-M\fP, \fB-t\fP, and \fB-tm\fP options, which give
95  is present on an individual pattern. This uses callouts to trace the the  information about resources used, are likely to produce different output with
96  matching process, and this may be different between studied and non-studied  and without \fB-s\fP. Output may also differ if the \fB/C\fP option is present
97  patterns. If the pattern contains (*MARK) items there may also be differences,  on an individual pattern. This uses callouts to trace the the matching process,
98  for the same reason. The \fB-s\fP command line option can be overridden for  and this may be different between studied and non-studied patterns. If the
99  specific patterns that should never be studied (see the /S option below).  pattern contains (*MARK) items there may also be differences, for the same
100    reason. The \fB-s\fP command line option can be overridden for specific
101    patterns that should never be studied (see the \fB/S\fP pattern modifier
102    below).
103  .TP 10  .TP 10
104  \fB-t\fP  \fB-t\fP
105  Run each compile, study, and match many times with a timer, and output  Run each compile, study, and match many times with a timer, and output
# Line 259  remainder of the subject string. This is Line 262  remainder of the subject string. This is
262  contains multiple copies of the same substring. If the \fB+\fP modifier appears  contains multiple copies of the same substring. If the \fB+\fP modifier appears
263  twice, the same action is taken for captured substrings. In each case the  twice, the same action is taken for captured substrings. In each case the
264  remainder is output on the following line with a plus character following the  remainder is output on the following line with a plus character following the
265  capture number.  capture number. Note that this modifier must not immediately follow the /S
266    modifier because /S+ has another meaning.
267  .P  .P
268  The \fB/=\fP modifier requests that the values of all potential captured  The \fB/=\fP modifier requests that the values of all potential captured
269  parentheses be output after a match by \fBpcre_exec()\fP. By default, only  parentheses be output after a match by \fBpcre_exec()\fP. By default, only
# Line 325  it possible to specify that certain patt Line 329  it possible to specify that certain patt
329  never studied, independently of \fB-s\fP. This feature is used in the test  never studied, independently of \fB-s\fP. This feature is used in the test
330  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.
331  .P  .P
332    If the \fB/S\fP modifier is immediately followed by a + character, the call to
333    \fBpcre_study()\fP is made with the PCRE_STUDY_JIT_COMPILE option, requesting
334    just-in-time optimization support if it is available. Note that there is also a
335    \fB/+\fP modifier; it must not be given immediately after \fB/S\fP because this
336    will be misinterpreted. If JIT studying is successful, it will automatically be
337    used when \fBpcre_exec()\fP is run, except when incompatible run-time options
338    are specified. These include the partial matching options; a complete list is
339    given in the
340    .\" HREF
341    \fBpcrejit\fP
342    .\"
343    documentation. See also the \fB\eJ\fP escape sequence below for a way of
344    setting the size of the JIT stack.
345    .P
346  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
347  set of built-in character tables to be passed to \fBpcre_compile()\fP. It is  set of built-in character tables to be passed to \fBpcre_compile()\fP. It is
348  used in the standard PCRE tests to check behaviour with different character  used in the standard PCRE tests to check behaviour with different character
# Line 420  recognized: Line 438  recognized:
438                 "name" after a successful match (name termin-                 "name" after a successful match (name termin-
439                 ated by next non-alphanumeric character)                 ated by next non-alphanumeric character)
440  .\" JOIN  .\" JOIN
441      \eJdd       set up a JIT stack of dd kilobytes maximum (any
442                   number of digits)
443    .\" JOIN
444    \eL         call pcre_get_substringlist() after a    \eL         call pcre_get_substringlist() after a
445                 successful match                 successful match
446  .\" JOIN  .\" JOIN
# Line 485  the very last character is a backslash, Line 506  the very last character is a backslash,
506  passing an empty line as data, since a real empty line terminates the data  passing an empty line as data, since a real empty line terminates the data
507  input.  input.
508  .P  .P
509    The \fB\eJ\fP escape provides a way of setting the maximum stack size that is
510    used by the just-in-time optimization code. It is ignored if JIT optimization
511    is not being used. Providing a stack that is larger than the default 32K is
512    necessary only for very complicated patterns.
513    .P
514  If \eM is present, \fBpcretest\fP calls \fBpcre_exec()\fP several times, with  If \eM is present, \fBpcretest\fP calls \fBpcre_exec()\fP several times, with
515  different values in the \fImatch_limit\fP and \fImatch_limit_recursion\fP  different values in the \fImatch_limit\fP and \fImatch_limit_recursion\fP
516  fields of the \fBpcre_extra\fP data structure, until it finds the minimum  fields of the \fBpcre_extra\fP data structure, until it finds the minimum
517  numbers for each parameter that allow \fBpcre_exec()\fP to complete. The  numbers for each parameter that allow \fBpcre_exec()\fP to complete without
518  \fImatch_limit\fP number is a measure of the amount of backtracking that takes  error. Because this is testing a specific feature of the normal interpretive
519  place, and checking it out can be instructive. For most simple matches, the  \fBpcre_exec()\fP execution, the use of any JIT optimization that might have
520  number is quite small, but for patterns with very large numbers of matching  been set up by the \fB/S+\fP qualifier of \fB-s+\fP option is disabled.
521  possibilities, it can become large very quickly with increasing length of  .P
522  subject string. The \fImatch_limit_recursion\fP number is a measure of how much  The \fImatch_limit\fP number is a measure of the amount of backtracking
523  stack (or, if PCRE is compiled with NO_RECURSE, how much heap) memory is needed  that takes place, and checking it out can be instructive. For most simple
524  to complete the match attempt.  matches, the number is quite small, but for patterns with very large numbers of
525    matching possibilities, it can become large very quickly with increasing length
526    of subject string. The \fImatch_limit_recursion\fP number is a measure of how
527    much stack (or, if PCRE is compiled with NO_RECURSE, how much heap) memory is
528    needed to complete the match attempt.
529  .P  .P
530  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
531  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
# Line 765  function to distinguish printing and non Line 795  function to distinguish printing and non
795  .sp  .sp
796  The facilities described in this section are not available when the POSIX  The facilities described in this section are not available when the POSIX
797  interface to PCRE is being used, that is, when the \fB/P\fP pattern modifier is  interface to PCRE is being used, that is, when the \fB/P\fP pattern modifier is
798  specified.  specified.
799  .P  .P
800  When the POSIX interface is not in use, you can cause \fBpcretest\fP to write a  When the POSIX interface is not in use, you can cause \fBpcretest\fP to write a
801  compiled pattern to a file, by following the modifiers with > and a file name.  compiled pattern to a file, by following the modifiers with > and a file name.
# Line 778  See the Line 808  See the
808  \fBpcreprecompile\fP  \fBpcreprecompile\fP
809  .\"  .\"
810  documentation for a discussion about saving and re-using compiled patterns.  documentation for a discussion about saving and re-using compiled patterns.
811    Note that if the pattern was successfully studied with JIT optimization, the
812    JIT data cannot be saved.
813  .P  .P
814  The data that is written is binary. The first eight bytes are the length of the  The data that is written is binary. The first eight bytes are the length of the
815  compiled pattern data followed by the length of the optional study data, each  compiled pattern data followed by the length of the optional study data, each
# Line 785  written as four bytes in big-endian orde Line 817  written as four bytes in big-endian orde
817  there is no study data (either the pattern was not studied, or studying did not  there is no study data (either the pattern was not studied, or studying did not
818  return any data), the second length is zero. The lengths are followed by an  return any data), the second length is zero. The lengths are followed by an
819  exact copy of the compiled pattern. If there is additional study data, this  exact copy of the compiled pattern. If there is additional study data, this
820  follows immediately after the compiled pattern. After writing the file,  (excluding any JIT data) follows immediately after the compiled pattern. After
821  \fBpcretest\fP expects to read a new pattern.  writing the file, \fBpcretest\fP expects to read a new pattern.
822  .P  .P
823  A saved pattern can be reloaded into \fBpcretest\fP by specifying < and a file  A saved pattern can be reloaded into \fBpcretest\fP by specifying < and a file
824  name instead of a pattern. The name of the file must not contain a < character,  name instead of a pattern. The name of the file must not contain a < character,
# Line 798  For example: Line 830  For example:
830    Compiled pattern loaded from /some/file    Compiled pattern loaded from /some/file
831    No study data    No study data
832  .sp  .sp
833  When the pattern has been loaded, \fBpcretest\fP proceeds to read data lines in  If the pattern was previously studied with the JIT optimization, the JIT
834  the usual way.  information cannot be saved and restored, and so is lost. When the pattern has
835    been loaded, \fBpcretest\fP proceeds to read data lines in the usual way.
836  .P  .P
837  You can copy a file written by \fBpcretest\fP to a different host and reload it  You can copy a file written by \fBpcretest\fP to a different host and reload it
838  there, even if the new host has opposite endianness to the one on which the  there, even if the new host has opposite endianness to the one on which the
# Line 823  result is undefined. Line 856  result is undefined.
856  .SH "SEE ALSO"  .SH "SEE ALSO"
857  .rs  .rs
858  .sp  .sp
859  \fBpcre\fP(3), \fBpcreapi\fP(3), \fBpcrecallout\fP(3), \fBpcrematching\fP(3),  \fBpcre\fP(3), \fBpcreapi\fP(3), \fBpcrecallout\fP(3), \fBpcrejit\fP,
860  \fBpcrepartial\fP(d), \fBpcrepattern\fP(3), \fBpcreprecompile\fP(3).  \fBpcrematching\fP(3), \fBpcrepartial\fP(d), \fBpcrepattern\fP(3),
861    \fBpcreprecompile\fP(3).
862  .  .
863  .  .
864  .SH AUTHOR  .SH AUTHOR
# Line 841  Cambridge CB2 3QH, England. Line 875  Cambridge CB2 3QH, England.
875  .rs  .rs
876  .sp  .sp
877  .nf  .nf
878  Last updated: 01 August 2011  Last updated: 26 August 2011
879  Copyright (c) 1997-2011 University of Cambridge.  Copyright (c) 1997-2011 University of Cambridge.
880  .fi  .fi

Legend:
Removed from v.654  
changed lines
  Added in v.678

  ViewVC Help
Powered by ViewVC 1.1.5