/[pcre]/code/branches/pcre16/doc/html/pcretest.html
ViewVC logotype

Diff of /code/branches/pcre16/doc/html/pcretest.html

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

revision 654 by ph10, Tue Aug 2 11:00:40 2011 UTC revision 691 by ph10, Sun Sep 11 14:31:21 2011 UTC
# Line 115  On Unix-like systems, set the size of th Line 115  On Unix-like systems, set the size of th
115  megabytes.  megabytes.
116  </P>  </P>
117  <P>  <P>
118  <b>-s</b>  <b>-s</b> or <b>-s+</b>
119  Behave as if each pattern has the <b>/S</b> modifier; in other words, force each  Behave as if each pattern has the <b>/S</b> modifier; in other words, force each
120  pattern to be studied. If the <b>/I</b> or <b>/D</b> option is present on a  pattern to be studied. If <b>-s+</b> is used, the PCRE_STUDY_JIT_COMPILE flag is
121  pattern (requesting output about the compiled pattern), information about the  passed to <b>pcre_study()</b>, causing just-in-time optimization to be set up if
122  result of studying is not included when studying is caused only by <b>-s</b> and  it is available. If the <b>/I</b> or <b>/D</b> option is present on a pattern
123  neither <b>-i</b> nor <b>-d</b> is present on the command line. This behaviour  (requesting output about the compiled pattern), information about the result of
124  means that the output from tests that are run with and without <b>-s</b> should  studying is not included when studying is caused only by <b>-s</b> and neither
125  be identical, except when options that output information about the actual  <b>-i</b> nor <b>-d</b> is present on the command line. This behaviour means that
126  running of a match are set. The <b>-M</b>, <b>-t</b>, and <b>-tm</b> options,  the output from tests that are run with and without <b>-s</b> should be
127  which give information about resources used, are likely to produce different  identical, except when options that output information about the actual running
128  output with and without <b>-s</b>. Output may also differ if the <b>/C</b> option  of a match are set. The <b>-M</b>, <b>-t</b>, and <b>-tm</b> options, which give
129  is present on an individual pattern. This uses callouts to trace the the  information about resources used, are likely to produce different output with
130  matching process, and this may be different between studied and non-studied  and without <b>-s</b>. Output may also differ if the <b>/C</b> option is present
131  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,
132  for the same reason. The <b>-s</b> command line option can be overridden for  and this may be different between studied and non-studied patterns. If the
133  specific patterns that should never be studied (see the /S option below).  pattern contains (*MARK) items there may also be differences, for the same
134    reason. The <b>-s</b> command line option can be overridden for specific
135    patterns that should never be studied (see the <b>/S</b> pattern modifier
136    below).
137  </P>  </P>
138  <P>  <P>
139  <b>-t</b>  <b>-t</b>
# Line 296  remainder of the subject string. This is Line 299  remainder of the subject string. This is
299  contains multiple copies of the same substring. If the <b>+</b> modifier appears  contains multiple copies of the same substring. If the <b>+</b> modifier appears
300  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
301  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
302  capture number.  capture number. Note that this modifier must not immediately follow the /S
303    modifier because /S+ has another meaning.
304  </P>  </P>
305  <P>  <P>
306  The <b>/=</b> modifier requests that the values of all potential captured  The <b>/=</b> modifier requests that the values of all potential captured
# Line 372  never studied, independently of <b>-s</b Line 376  never studied, independently of <b>-s</b
376  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.
377  </P>  </P>
378  <P>  <P>
379    If the <b>/S</b> modifier is immediately followed by a + character, the call to
380    <b>pcre_study()</b> is made with the PCRE_STUDY_JIT_COMPILE option, requesting
381    just-in-time optimization support if it is available. Note that there is also a
382    <b>/+</b> modifier; it must not be given immediately after <b>/S</b> because this
383    will be misinterpreted. If JIT studying is successful, it will automatically be
384    used when <b>pcre_exec()</b> is run, except when incompatible run-time options
385    are specified. These include the partial matching options; a complete list is
386    given in the
387    <a href="pcrejit.html"><b>pcrejit</b></a>
388    documentation. See also the <b>\J</b> escape sequence below for a way of
389    setting the size of the JIT stack.
390    </P>
391    <P>
392  The <b>/T</b> modifier must be followed by a single digit. It causes a specific  The <b>/T</b> modifier must be followed by a single digit. It causes a specific
393  set of built-in character tables to be passed to <b>pcre_compile()</b>. It is  set of built-in character tables to be passed to <b>pcre_compile()</b>. It is
394  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 440  recognized: Line 457  recognized:
457    \Gdd       call pcre_get_substring() for substring dd after a successful match (number less than 32)    \Gdd       call pcre_get_substring() for substring dd after a successful match (number less than 32)
458    \Gname     call pcre_get_named_substring() for substring "name" after a successful match (name termin-    \Gname     call pcre_get_named_substring() for substring "name" after a successful match (name termin-
459                 ated by next non-alphanumeric character)                 ated by next non-alphanumeric character)
460      \Jdd       set up a JIT stack of dd kilobytes maximum (any number of digits)
461    \L         call pcre_get_substringlist() after a successful match    \L         call pcre_get_substringlist() after a successful match
462    \M         discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings    \M         discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings
463    \N         pass the PCRE_NOTEMPTY option to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>; if used twice, pass the    \N         pass the PCRE_NOTEMPTY option to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>; if used twice, pass the
# Line 479  passing an empty line as data, since a r Line 497  passing an empty line as data, since a r
497  input.  input.
498  </P>  </P>
499  <P>  <P>
500    The <b>\J</b> escape provides a way of setting the maximum stack size that is
501    used by the just-in-time optimization code. It is ignored if JIT optimization
502    is not being used. Providing a stack that is larger than the default 32K is
503    necessary only for very complicated patterns.
504    </P>
505    <P>
506  If \M is present, <b>pcretest</b> calls <b>pcre_exec()</b> several times, with  If \M is present, <b>pcretest</b> calls <b>pcre_exec()</b> several times, with
507  different values in the <i>match_limit</i> and <i>match_limit_recursion</i>  different values in the <i>match_limit</i> and <i>match_limit_recursion</i>
508  fields of the <b>pcre_extra</b> data structure, until it finds the minimum  fields of the <b>pcre_extra</b> data structure, until it finds the minimum
509  numbers for each parameter that allow <b>pcre_exec()</b> to complete. The  numbers for each parameter that allow <b>pcre_exec()</b> to complete without
510  <i>match_limit</i> number is a measure of the amount of backtracking that takes  error. Because this is testing a specific feature of the normal interpretive
511  place, and checking it out can be instructive. For most simple matches, the  <b>pcre_exec()</b> execution, the use of any JIT optimization that might have
512  number is quite small, but for patterns with very large numbers of matching  been set up by the <b>/S+</b> qualifier of <b>-s+</b> option is disabled.
513  possibilities, it can become large very quickly with increasing length of  </P>
514  subject string. The <i>match_limit_recursion</i> number is a measure of how much  <P>
515  stack (or, if PCRE is compiled with NO_RECURSE, how much heap) memory is needed  The <i>match_limit</i> number is a measure of the amount of backtracking
516  to complete the match attempt.  that takes place, and checking it out can be instructive. For most simple
517    matches, the number is quite small, but for patterns with very large numbers of
518    matching possibilities, it can become large very quickly with increasing length
519    of subject string. The <i>match_limit_recursion</i> number is a measure of how
520    much stack (or, if PCRE is compiled with NO_RECURSE, how much heap) memory is
521    needed to complete the match attempt.
522  </P>  </P>
523  <P>  <P>
524  When \O is used, the value specified may be higher or lower than the size set  When \O is used, the value specified may be higher or lower than the size set
# Line 761  For example: Line 790  For example:
790  See the  See the
791  <a href="pcreprecompile.html"><b>pcreprecompile</b></a>  <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
792  documentation for a discussion about saving and re-using compiled patterns.  documentation for a discussion about saving and re-using compiled patterns.
793    Note that if the pattern was successfully studied with JIT optimization, the
794    JIT data cannot be saved.
795  </P>  </P>
796  <P>  <P>
797  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
# Line 769  written as four bytes in big-endian orde Line 800  written as four bytes in big-endian orde
800  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
801  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
802  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
803  follows immediately after the compiled pattern. After writing the file,  (excluding any JIT data) follows immediately after the compiled pattern. After
804  <b>pcretest</b> expects to read a new pattern.  writing the file, <b>pcretest</b> expects to read a new pattern.
805  </P>  </P>
806  <P>  <P>
807  A saved pattern can be reloaded into <b>pcretest</b> by specifying &#60; and a file  A saved pattern can be reloaded into <b>pcretest</b> by specifying &#60; and a file
# Line 783  For example: Line 814  For example:
814    Compiled pattern loaded from /some/file    Compiled pattern loaded from /some/file
815    No study data    No study data
816  </pre>  </pre>
817  When the pattern has been loaded, <b>pcretest</b> proceeds to read data lines in  If the pattern was previously studied with the JIT optimization, the JIT
818  the usual way.  information cannot be saved and restored, and so is lost. When the pattern has
819    been loaded, <b>pcretest</b> proceeds to read data lines in the usual way.
820  </P>  </P>
821  <P>  <P>
822  You can copy a file written by <b>pcretest</b> to a different host and reload it  You can copy a file written by <b>pcretest</b> to a different host and reload it
# Line 809  result is undefined. Line 841  result is undefined.
841  </P>  </P>
842  <br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>  <br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>
843  <P>  <P>
844  <b>pcre</b>(3), <b>pcreapi</b>(3), <b>pcrecallout</b>(3), <b>pcrematching</b>(3),  <b>pcre</b>(3), <b>pcreapi</b>(3), <b>pcrecallout</b>(3), <b>pcrejit</b>,
845  <b>pcrepartial</b>(d), <b>pcrepattern</b>(3), <b>pcreprecompile</b>(3).  <b>pcrematching</b>(3), <b>pcrepartial</b>(d), <b>pcrepattern</b>(3),
846    <b>pcreprecompile</b>(3).
847  </P>  </P>
848  <br><a name="SEC14" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC14" href="#TOC1">AUTHOR</a><br>
849  <P>  <P>
# Line 823  Cambridge CB2 3QH, England. Line 856  Cambridge CB2 3QH, England.
856  </P>  </P>
857  <br><a name="SEC15" href="#TOC1">REVISION</a><br>  <br><a name="SEC15" href="#TOC1">REVISION</a><br>
858  <P>  <P>
859  Last updated: 01 August 2011  Last updated: 26 August 2011
860  <br>  <br>
861  Copyright &copy; 1997-2011 University of Cambridge.  Copyright &copy; 1997-2011 University of Cambridge.
862  <br>  <br>

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

  ViewVC Help
Powered by ViewVC 1.1.5