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

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

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

revision 76 by nigel, Sat Feb 24 21:40:37 2007 UTC revision 77 by nigel, Sat Feb 24 21:40:45 2007 UTC
# Line 18  man page, in case the conversion went wr Line 18  man page, in case the conversion went wr
18  <li><a name="TOC3" href="#SEC3">DESCRIPTION</a>  <li><a name="TOC3" href="#SEC3">DESCRIPTION</a>
19  <li><a name="TOC4" href="#SEC4">PATTERN MODIFIERS</a>  <li><a name="TOC4" href="#SEC4">PATTERN MODIFIERS</a>
20  <li><a name="TOC5" href="#SEC5">DATA LINES</a>  <li><a name="TOC5" href="#SEC5">DATA LINES</a>
21  <li><a name="TOC6" href="#SEC6">OUTPUT FROM PCRETEST</a>  <li><a name="TOC6" href="#SEC6">THE ALTERNATIVE MATCHING FUNCTION</a>
22  <li><a name="TOC7" href="#SEC7">CALLOUTS</a>  <li><a name="TOC7" href="#SEC7">DEFAULT OUTPUT FROM PCRETEST</a>
23  <li><a name="TOC8" href="#SEC8">SAVING AND RELOADING COMPILED PATTERNS</a>  <li><a name="TOC8" href="#SEC8">OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION</a>
24  <li><a name="TOC9" href="#SEC9">AUTHOR</a>  <li><a name="TOC9" href="#SEC9">RESTARTING AFTER A PARTIAL MATCH</a>
25    <li><a name="TOC10" href="#SEC10">CALLOUTS</a>
26    <li><a name="TOC11" href="#SEC11">SAVING AND RELOADING COMPILED PATTERNS</a>
27    <li><a name="TOC12" href="#SEC12">AUTHOR</a>
28  </ul>  </ul>
29  <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>  <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
30  <P>  <P>
31  <b>pcretest [-C] [-d] [-i] [-m] [-o osize] [-p] [-t] [source]</b>  <b>pcretest [-C] [-d] [-dfa] [-i] [-m] [-o osize] [-p] [-t] [source]</b>
32  <b>[destination]</b>  <b>[destination]</b>
33  </P>  </P>
34  <P>  <P>
# Line 47  about the optional features that are inc Line 50  about the optional features that are inc
50  </P>  </P>
51  <P>  <P>
52  <b>-d</b>  <b>-d</b>
53  Behave as if each regex had the <b>/D</b> (debug) modifier; the internal  Behave as if each regex has the <b>/D</b> (debug) modifier; the internal
54  form is output after compilation.  form is output after compilation.
55  </P>  </P>
56  <P>  <P>
57    <b>-dfa</b>
58    Behave as if each data line contains the \D escape sequence; this causes the
59    alternative matching function, <b>pcre_dfa_exec()</b>, to be used instead of the
60    standard <b>pcre_exec()</b> function (more detail is given below).
61    </P>
62    <P>
63  <b>-i</b>  <b>-i</b>
64  Behave as if each regex had the <b>/I</b> modifier; information about the  Behave as if each regex has the <b>/I</b> modifier; information about the
65  compiled pattern is given after compilation.  compiled pattern is given after compilation.
66  </P>  </P>
67  <P>  <P>
# Line 70  matching calls by including \O in the da Line 79  matching calls by including \O in the da
79  </P>  </P>
80  <P>  <P>
81  <b>-p</b>  <b>-p</b>
82  Behave as if each regex has <b>/P</b> modifier; the POSIX wrapper API is used  Behave as if each regex has the <b>/P</b> modifier; the POSIX wrapper API is
83  to call PCRE. None of the other options has any effect when <b>-p</b> is set.  used to call PCRE. None of the other options has any effect when <b>-p</b> is
84    set.
85  </P>  </P>
86  <P>  <P>
87  <b>-t</b>  <b>-t</b>
# Line 152  not correspond to anything in Perl: Line 162  not correspond to anything in Perl:
162    <b>/A</b>    PCRE_ANCHORED    <b>/A</b>    PCRE_ANCHORED
163    <b>/C</b>    PCRE_AUTO_CALLOUT    <b>/C</b>    PCRE_AUTO_CALLOUT
164    <b>/E</b>    PCRE_DOLLAR_ENDONLY    <b>/E</b>    PCRE_DOLLAR_ENDONLY
165      <b>/f</b>    PCRE_FIRSTLINE
166    <b>/N</b>    PCRE_NO_AUTO_CAPTURE    <b>/N</b>    PCRE_NO_AUTO_CAPTURE
167    <b>/U</b>    PCRE_UNGREEDY    <b>/U</b>    PCRE_UNGREEDY
168    <b>/X</b>    PCRE_EXTRA    <b>/X</b>    PCRE_EXTRA
# Line 274  recognized: Line 285  recognized:
285    \C!n       return 1 instead of 0 when callout number n is reached    \C!n       return 1 instead of 0 when callout number n is reached
286    \C!n!m     return 1 instead of 0 when callout number n is reached for the nth time    \C!n!m     return 1 instead of 0 when callout number n is reached for the nth time
287    \C*n       pass the number n (may be negative) as callout data; this is used as the callout return value    \C*n       pass the number n (may be negative) as callout data; this is used as the callout return value
288      \D         use the <b>pcre_dfa_exec()</b> match function
289      \F         only shortest match for <b>pcre_dfa_exec()</b>
290    \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)
291    \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-
292                 ated by next non-alphanumeric character)                 ated by next non-alphanumeric character)
# Line 281  recognized: Line 294  recognized:
294    \M         discover the minimum MATCH_LIMIT setting    \M         discover the minimum MATCH_LIMIT setting
295    \N         pass the PCRE_NOTEMPTY option to <b>pcre_exec()</b>    \N         pass the PCRE_NOTEMPTY option to <b>pcre_exec()</b>
296    \Odd       set the size of the output vector passed to <b>pcre_exec()</b> to dd (any number of digits)    \Odd       set the size of the output vector passed to <b>pcre_exec()</b> to dd (any number of digits)
297    \P         pass the PCRE_PARTIAL option to <b>pcre_exec()</b>    \P         pass the PCRE_PARTIAL option to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>
298      \R         pass the PCRE_DFA_RESTART option to <b>pcre_dfa_exec()</b>
299    \S         output details of memory get/free calls during matching    \S         output details of memory get/free calls during matching
300    \Z         pass the PCRE_NOTEOL option to <b>pcre_exec()</b>    \Z         pass the PCRE_NOTEOL option to <b>pcre_exec()</b>
301    \?         pass the PCRE_NO_UTF8_CHECK option to <b>pcre_exec()</b>    \?         pass the PCRE_NO_UTF8_CHECK option to <b>pcre_exec()</b>
# Line 318  of the /8 modifier on the pattern Line 332  of the /8 modifier on the pattern
332  any number of hexadecimal digits inside the braces. The result is from one to  any number of hexadecimal digits inside the braces. The result is from one to
333  six bytes, encoded according to the UTF-8 rules.  six bytes, encoded according to the UTF-8 rules.
334  </P>  </P>
335  <br><a name="SEC6" href="#TOC1">OUTPUT FROM PCRETEST</a><br>  <br><a name="SEC6" href="#TOC1">THE ALTERNATIVE MATCHING FUNCTION</a><br>
336    <P>
337    By default, <b>pcretest</b> uses the standard PCRE matching function,
338    <b>pcre_exec()</b> to match each data line. From release 6.0, PCRE supports an
339    alternative matching function, <b>pcre_dfa_test()</b>, which operates in a
340    different way, and has some restrictions. The differences between the two
341    functions are described in the
342    <a href="pcrematching.html"><b>pcrematching</b></a>
343    documentation.
344    </P>
345    <P>
346    If a data line contains the \D escape sequence, or if the command line
347    contains the <b>-dfa</b> option, the alternative matching function is called.
348    This function finds all possible matches at a given point. If, however, the \F
349    escape sequence is present in the data line, it stops after the first match is
350    found. This is always the shortest possible match.
351    </P>
352    <br><a name="SEC7" href="#TOC1">DEFAULT OUTPUT FROM PCRETEST</a><br>
353    <P>
354    This section describes the output when the normal matching function,
355    <b>pcre_exec()</b>, is being used.
356    </P>
357  <P>  <P>
358  When a match succeeds, pcretest outputs the list of captured substrings that  When a match succeeds, pcretest outputs the list of captured substrings that
359  <b>pcre_exec()</b> returns, starting with number 0 for the string that matched  <b>pcre_exec()</b> returns, starting with number 0 for the string that matched
360  the whole pattern. Otherwise, it outputs "No match" or "Partial match"  the whole pattern. Otherwise, it outputs "No match" or "Partial match"
361  when <b>pcre_exec()</b> returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PARTIAL,  when <b>pcre_exec()</b> returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PARTIAL,
362  respectively, and otherwise the PCRE negative error number. Here is an example  respectively, and otherwise the PCRE negative error number. Here is an example
363  of an interactive pcretest run.  of an interactive <b>pcretest</b> run.
364  <pre>  <pre>
365    $ pcretest    $ pcretest
366    PCRE version 5.00 07-Sep-2004    PCRE version 5.00 07-Sep-2004
# Line 375  Note that while patterns can be continue Line 410  Note that while patterns can be continue
410  prompt is used for continuations), data lines may not. However newlines can be  prompt is used for continuations), data lines may not. However newlines can be
411  included in data by means of the \n escape.  included in data by means of the \n escape.
412  </P>  </P>
413  <br><a name="SEC7" href="#TOC1">CALLOUTS</a><br>  <br><a name="SEC8" href="#TOC1">OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION</a><br>
414    <P>
415    When the alternative matching function, <b>pcre_dfa_exec()</b>, is used (by
416    means of the \D escape sequence or the <b>-dfa</b> command line option), the
417    output consists of a list of all the matches that start at the first point in
418    the subject where there is at least one match. For example:
419    <pre>
420        re&#62; /(tang|tangerine|tan)/
421      data&#62; yellow tangerine\D
422       0: tangerine
423       1: tang
424       2: tan
425    </pre>
426    (Using the normal matching function on this data finds only "tang".) The
427    longest matching string is always given first (and numbered zero).
428    </P>
429    <P>
430    If \fB/g\P is present on the pattern, the search for further matches resumes
431    at the end of the longest match. For example:
432    <pre>
433        re&#62; /(tang|tangerine|tan)/g
434      data&#62; yellow tangerine and tangy sultana\D
435       0: tangerine
436       1: tang
437       2: tan
438       0: tang
439       1: tan
440       0: tan
441    </pre>
442    Since the matching function does not support substring capture, the escape
443    sequences that are concerned with captured substrings are not relevant.
444    </P>
445    <br><a name="SEC9" href="#TOC1">RESTARTING AFTER A PARTIAL MATCH</a><br>
446    <P>
447    When the alternative matching function has given the PCRE_ERROR_PARTIAL return,
448    indicating that the subject partially matched the pattern, you can restart the
449    match with additional subject data by means of the \R escape sequence. For
450    example:
451    <pre>
452        re&#62; /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
453      data&#62; 23ja\P\D
454      Partial match: 23ja
455      data&#62; n05\R\D
456       0: n05
457    </pre>
458    For further information about partial matching, see the
459    <a href="pcrepartial.html"><b>pcrepartial</b></a>
460    documentation.
461    </P>
462    <br><a name="SEC10" href="#TOC1">CALLOUTS</a><br>
463  <P>  <P>
464  If the pattern contains any callout requests, <b>pcretest</b>'s callout function  If the pattern contains any callout requests, <b>pcretest</b>'s callout function
465  is called during matching. By default, it displays the callout number, the  is called during matching. This works with both matching functions. By default,
466  start and current positions in the text at the callout time, and the next  the called function displays the callout number, the start and current
467  pattern item to be tested. For example, the output  positions in the text at the callout time, and the next pattern item to be
468    tested. For example, the output
469  <pre>  <pre>
470    ---&#62;pqrabcdef    ---&#62;pqrabcdef
471      0    ^  ^     \d      0    ^  ^     \d
# Line 406  example: Line 491  example:
491     0: E*     0: E*
492  </pre>  </pre>
493  The callout function in <b>pcretest</b> returns zero (carry on matching) by  The callout function in <b>pcretest</b> returns zero (carry on matching) by
494  default, but you can use an \C item in a data line (as described above) to  default, but you can use a \C item in a data line (as described above) to
495  change this.  change this.
496  </P>  </P>
497  <P>  <P>
# Line 416  the Line 501  the
501  <a href="pcrecallout.html"><b>pcrecallout</b></a>  <a href="pcrecallout.html"><b>pcrecallout</b></a>
502  documentation.  documentation.
503  </P>  </P>
504  <br><a name="SEC8" href="#TOC1">SAVING AND RELOADING COMPILED PATTERNS</a><br>  <br><a name="SEC11" href="#TOC1">SAVING AND RELOADING COMPILED PATTERNS</a><br>
505  <P>  <P>
506  The facilities described in this section are not available when the POSIX  The facilities described in this section are not available when the POSIX
507  inteface to PCRE is being used, that is, when the <b>/P</b> pattern modifier is  inteface to PCRE is being used, that is, when the <b>/P</b> pattern modifier is
# Line 478  string using a reloaded pattern is likel Line 563  string using a reloaded pattern is likel
563  Finally, if you attempt to load a file that is not in the correct format, the  Finally, if you attempt to load a file that is not in the correct format, the
564  result is undefined.  result is undefined.
565  </P>  </P>
566  <br><a name="SEC9" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC12" href="#TOC1">AUTHOR</a><br>
567  <P>  <P>
568  Philip Hazel &#60;ph10@cam.ac.uk&#62;  Philip Hazel
569  <br>  <br>
570  University Computing Service,  University Computing Service,
571  <br>  <br>
572  Cambridge CB2 3QG, England.  Cambridge CB2 3QG, England.
573  </P>  </P>
574  <P>  <P>
575  Last updated: 10 September 2004  Last updated: 28 February 2005
576  <br>  <br>
577  Copyright &copy; 1997-2004 University of Cambridge.  Copyright &copy; 1997-2005 University of Cambridge.
578  <p>  <p>
579  Return to the <a href="index.html">PCRE index page</a>.  Return to the <a href="index.html">PCRE index page</a>.
580  </p>  </p>

Legend:
Removed from v.76  
changed lines
  Added in v.77

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12