/[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 75 by nigel, Sat Feb 24 21:40:37 2007 UTC revision 77 by nigel, Sat Feb 24 21:40:45 2007 UTC
# Line 4  pcretest - a program for testing Perl-co Line 4  pcretest - a program for testing Perl-co
4  .SH SYNOPSIS  .SH SYNOPSIS
5  .rs  .rs
6  .sp  .sp
7  .B pcretest "[-C] [-d] [-i] [-m] [-o osize] [-p] [-t] [source]"  .B pcretest "[-C] [-d] [-dfa] [-i] [-m] [-o osize] [-p] [-t] [source]"
8  .ti +5n  .ti +5n
9  .B "[destination]"  .B "[destination]"
10  .P  .P
# Line 31  Output the version number of the PCRE li Line 31  Output the version number of the PCRE li
31  about the optional features that are included, and then exit.  about the optional features that are included, and then exit.
32  .TP 10  .TP 10
33  \fB-d\fP  \fB-d\fP
34  Behave as if each regex had the \fB/D\fP (debug) modifier; the internal  Behave as if each regex has the \fB/D\fP (debug) modifier; the internal
35  form is output after compilation.  form is output after compilation.
36  .TP 10  .TP 10
37    \fB-dfa\fP
38    Behave as if each data line contains the \eD escape sequence; this causes the
39    alternative matching function, \fBpcre_dfa_exec()\fP, to be used instead of the
40    standard \fBpcre_exec()\fP function (more detail is given below).
41    .TP 10
42  \fB-i\fP  \fB-i\fP
43  Behave as if each regex had the \fB/I\fP modifier; information about the  Behave as if each regex has the \fB/I\fP modifier; information about the
44  compiled pattern is given after compilation.  compiled pattern is given after compilation.
45  .TP 10  .TP 10
46  \fB-m\fP  \fB-m\fP
# Line 50  for 14 capturing subexpressions. The vec Line 55  for 14 capturing subexpressions. The vec
55  matching calls by including \eO in the data line (see below).  matching calls by including \eO in the data line (see below).
56  .TP 10  .TP 10
57  \fB-p\fP  \fB-p\fP
58  Behave as if each regex has \fB/P\fP modifier; the POSIX wrapper API is used  Behave as if each regex has the \fB/P\fP modifier; the POSIX wrapper API is
59  to call PCRE. None of the other options has any effect when \fB-p\fP is set.  used to call PCRE. None of the other options has any effect when \fB-p\fP is
60    set.
61  .TP 10  .TP 10
62  \fB-t\fP  \fB-t\fP
63  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 131  not correspond to anything in Perl: Line 137  not correspond to anything in Perl:
137    \fB/A\fP    PCRE_ANCHORED    \fB/A\fP    PCRE_ANCHORED
138    \fB/C\fP    PCRE_AUTO_CALLOUT    \fB/C\fP    PCRE_AUTO_CALLOUT
139    \fB/E\fP    PCRE_DOLLAR_ENDONLY    \fB/E\fP    PCRE_DOLLAR_ENDONLY
140      \fB/f\fP    PCRE_FIRSTLINE
141    \fB/N\fP    PCRE_NO_AUTO_CAPTURE    \fB/N\fP    PCRE_NO_AUTO_CAPTURE
142    \fB/U\fP    PCRE_UNGREEDY    \fB/U\fP    PCRE_UNGREEDY
143    \fB/X\fP    PCRE_EXTRA    \fB/X\fP    PCRE_EXTRA
# Line 257  recognized: Line 264  recognized:
264  .\" JOIN  .\" JOIN
265    \eC*n       pass the number n (may be negative) as callout    \eC*n       pass the number n (may be negative) as callout
266                 data; this is used as the callout return value                 data; this is used as the callout return value
267      \eD         use the \fBpcre_dfa_exec()\fP match function
268      \eF         only shortest match for \fBpcre_dfa_exec()\fP
269  .\" JOIN  .\" JOIN
270    \eGdd       call pcre_get_substring() for substring dd    \eGdd       call pcre_get_substring() for substring dd
271                 after a successful match (number less than 32)                 after a successful match (number less than 32)
# Line 272  recognized: Line 281  recognized:
281  .\" JOIN  .\" JOIN
282    \eOdd       set the size of the output vector passed to    \eOdd       set the size of the output vector passed to
283                 \fBpcre_exec()\fP to dd (any number of digits)                 \fBpcre_exec()\fP to dd (any number of digits)
284    .\" JOIN
285    \eP         pass the PCRE_PARTIAL option to \fBpcre_exec()\fP    \eP         pass the PCRE_PARTIAL option to \fBpcre_exec()\fP
286                   or \fBpcre_dfa_exec()\fP
287      \eR         pass the PCRE_DFA_RESTART option to \fBpcre_dfa_exec()\fP
288    \eS         output details of memory get/free calls during matching    \eS         output details of memory get/free calls during matching
289    \eZ         pass the PCRE_NOTEOL option to \fBpcre_exec()\fP    \eZ         pass the PCRE_NOTEOL option to \fBpcre_exec()\fP
290  .\" JOIN  .\" JOIN
# Line 308  any number of hexadecimal digits inside Line 320  any number of hexadecimal digits inside
320  six bytes, encoded according to the UTF-8 rules.  six bytes, encoded according to the UTF-8 rules.
321  .  .
322  .  .
323  .SH "OUTPUT FROM PCRETEST"  .SH "THE ALTERNATIVE MATCHING FUNCTION"
324  .rs  .rs
325  .sp  .sp
326    By default, \fBpcretest\fP uses the standard PCRE matching function,
327    \fBpcre_exec()\fP to match each data line. From release 6.0, PCRE supports an
328    alternative matching function, \fBpcre_dfa_test()\fP, which operates in a
329    different way, and has some restrictions. The differences between the two
330    functions are described in the
331    .\" HREF
332    \fBpcrematching\fP
333    .\"
334    documentation.
335    .P
336    If a data line contains the \eD escape sequence, or if the command line
337    contains the \fB-dfa\fP option, the alternative matching function is called.
338    This function finds all possible matches at a given point. If, however, the \eF
339    escape sequence is present in the data line, it stops after the first match is
340    found. This is always the shortest possible match.
341    .
342    .
343    .SH "DEFAULT OUTPUT FROM PCRETEST"
344    .rs
345    .sp
346    This section describes the output when the normal matching function,
347    \fBpcre_exec()\fP, is being used.
348    .P
349  When a match succeeds, pcretest outputs the list of captured substrings that  When a match succeeds, pcretest outputs the list of captured substrings that
350  \fBpcre_exec()\fP returns, starting with number 0 for the string that matched  \fBpcre_exec()\fP returns, starting with number 0 for the string that matched
351  the whole pattern. Otherwise, it outputs "No match" or "Partial match"  the whole pattern. Otherwise, it outputs "No match" or "Partial match"
352  when \fBpcre_exec()\fP returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PARTIAL,  when \fBpcre_exec()\fP returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PARTIAL,
353  respectively, and otherwise the PCRE negative error number. Here is an example  respectively, and otherwise the PCRE negative error number. Here is an example
354  of an interactive pcretest run.  of an interactive \fBpcretest\fP run.
355  .sp  .sp
356    $ pcretest    $ pcretest
357    PCRE version 5.00 07-Sep-2004    PCRE version 5.00 07-Sep-2004
# Line 365  prompt is used for continuations), data Line 400  prompt is used for continuations), data
400  included in data by means of the \en escape.  included in data by means of the \en escape.
401  .  .
402  .  .
403    .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"
404    .rs
405    .sp
406    When the alternative matching function, \fBpcre_dfa_exec()\fP, is used (by
407    means of the \eD escape sequence or the \fB-dfa\fP command line option), the
408    output consists of a list of all the matches that start at the first point in
409    the subject where there is at least one match. For example:
410    .sp
411        re> /(tang|tangerine|tan)/
412      data> yellow tangerine\eD
413       0: tangerine
414       1: tang
415       2: tan
416    .sp
417    (Using the normal matching function on this data finds only "tang".) The
418    longest matching string is always given first (and numbered zero).
419    .P
420    If \fB/g\P is present on the pattern, the search for further matches resumes
421    at the end of the longest match. For example:
422    .sp
423        re> /(tang|tangerine|tan)/g
424      data> yellow tangerine and tangy sultana\eD
425       0: tangerine
426       1: tang
427       2: tan
428       0: tang
429       1: tan
430       0: tan
431    .sp
432    Since the matching function does not support substring capture, the escape
433    sequences that are concerned with captured substrings are not relevant.
434    .
435    .
436    .SH "RESTARTING AFTER A PARTIAL MATCH"
437    .rs
438    .sp
439    When the alternative matching function has given the PCRE_ERROR_PARTIAL return,
440    indicating that the subject partially matched the pattern, you can restart the
441    match with additional subject data by means of the \eR escape sequence. For
442    example:
443    .sp
444        re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
445      data> 23ja\eP\eD
446      Partial match: 23ja
447      data> n05\eR\eD
448       0: n05
449    .sp
450    For further information about partial matching, see the
451    .\" HREF
452    \fBpcrepartial\fP
453    .\"
454    documentation.
455    .
456    .
457  .SH CALLOUTS  .SH CALLOUTS
458  .rs  .rs
459  .sp  .sp
460  If the pattern contains any callout requests, \fBpcretest\fP's callout function  If the pattern contains any callout requests, \fBpcretest\fP's callout function
461  is called during matching. By default, it displays the callout number, the  is called during matching. This works with both matching functions. By default,
462  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
463  pattern item to be tested. For example, the output  positions in the text at the callout time, and the next pattern item to be
464    tested. For example, the output
465  .sp  .sp
466    --->pqrabcdef    --->pqrabcdef
467      0    ^  ^     \ed      0    ^  ^     \ed
# Line 396  example: Line 486  example:
486     0: E*     0: E*
487  .sp  .sp
488  The callout function in \fBpcretest\fP returns zero (carry on matching) by  The callout function in \fBpcretest\fP returns zero (carry on matching) by
489  default, but you can use an \eC item in a data line (as described above) to  default, but you can use a \eC item in a data line (as described above) to
490  change this.  change this.
491  .P  .P
492  Inserting callouts can be helpful when using \fBpcretest\fP to check  Inserting callouts can be helpful when using \fBpcretest\fP to check
# Line 471  result is undefined. Line 561  result is undefined.
561  .SH AUTHOR  .SH AUTHOR
562  .rs  .rs
563  .sp  .sp
564  Philip Hazel <ph10@cam.ac.uk>  Philip Hazel
565  .br  .br
566  University Computing Service,  University Computing Service,
567  .br  .br
568  Cambridge CB2 3QG, England.  Cambridge CB2 3QG, England.
569  .P  .P
570  .in 0  .in 0
571  Last updated: 10 September 2004  Last updated: 28 February 2005
572  .br  .br
573  Copyright (c) 1997-2004 University of Cambridge.  Copyright (c) 1997-2005 University of Cambridge.
Legend:
Removed from v.75  
changed lines
  Added in v.77
  ViewVC Help
Powered by ViewVC 1.1.5