/[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 87 by nigel, Sat Feb 24 21:41:21 2007 UTC revision 91 by nigel, Sat Feb 24 21:41:34 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] [-dfa] [-i] [-m] [-o osize] [-p] [-t] [source]"  .B pcretest "[options] [source] [destination]"
8  .ti +5n  .sp
 .B "[destination]"  
 .P  
9  \fBpcretest\fP was written as a test program for the PCRE regular expression  \fBpcretest\fP was written as a test program for the PCRE regular expression
10  library itself, but it can also be used for experimenting with regular  library itself, but it can also be used for experimenting with regular
11  expressions. This document describes the features of the test program; for  expressions. This document describes the features of the test program; for
# Line 59  Behave as if each regex has the \fB/P\fP Line 57  Behave as if each regex has the \fB/P\fP
57  used to call PCRE. None of the other options has any effect when \fB-p\fP is  used to call PCRE. None of the other options has any effect when \fB-p\fP is
58  set.  set.
59  .TP 10  .TP 10
60  \fP-q\fP  \fB-q\fP
61  Do not output the version number of \fBpcretest\fP at the start of execution.  Do not output the version number of \fBpcretest\fP at the start of execution.
62  .TP 10  .TP 10
63    \fB-S\fP \fIsize\fP
64    On Unix-like systems, set the size of the runtime stack to \fIsize\fP
65    megabytes.
66    .TP 10
67  \fB-t\fP  \fB-t\fP
68  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
69  resulting time per compile or match (in milliseconds). Do not set \fB-m\fP with  resulting time per compile or match (in milliseconds). Do not set \fB-m\fP with
# Line 83  set starts with a regular expression, an Line 85  set starts with a regular expression, an
85  lines to be matched against the pattern.  lines to be matched against the pattern.
86  .P  .P
87  Each data line is matched separately and independently. If you want to do  Each data line is matched separately and independently. If you want to do
88  multiple-line matches, you have to use the \en escape sequence in a single line  multi-line matches, you have to use the \en escape sequence (or \er or \er\en,
89  of input to encode the newline characters. The maximum length of data line is  depending on the newline setting) in a single line of input to encode the
90  30,000 characters.  newline characters. There is no limit on the length of data lines; the input
91    buffer is automatically extended if it is too small.
92  .P  .P
93  An empty line signals the end of the data lines, at which point a new regular  An empty line signals the end of the data lines, at which point a new regular
94  expression is read. The regular expressions are given enclosed in any  expression is read. The regular expressions are given enclosed in any
95  non-alphanumeric delimiters other than backslash, for example  non-alphanumeric delimiters other than backslash, for example:
96  .sp  .sp
97    /(a|bc)x+yz/    /(a|bc)x+yz/
98  .sp  .sp
# Line 137  effect as they do in Perl. For example: Line 140  effect as they do in Perl. For example:
140  The following table shows additional modifiers for setting PCRE options that do  The following table shows additional modifiers for setting PCRE options that do
141  not correspond to anything in Perl:  not correspond to anything in Perl:
142  .sp  .sp
143    \fB/A\fP    PCRE_ANCHORED    \fB/A\fP       PCRE_ANCHORED
144    \fB/C\fP    PCRE_AUTO_CALLOUT    \fB/C\fP       PCRE_AUTO_CALLOUT
145    \fB/E\fP    PCRE_DOLLAR_ENDONLY    \fB/E\fP       PCRE_DOLLAR_ENDONLY
146    \fB/f\fP    PCRE_FIRSTLINE    \fB/f\fP       PCRE_FIRSTLINE
147    \fB/N\fP    PCRE_NO_AUTO_CAPTURE    \fB/J\fP       PCRE_DUPNAMES
148    \fB/U\fP    PCRE_UNGREEDY    \fB/N\fP       PCRE_NO_AUTO_CAPTURE
149    \fB/X\fP    PCRE_EXTRA    \fB/U\fP       PCRE_UNGREEDY
150      \fB/X\fP       PCRE_EXTRA
151      \fB/<cr>\fP    PCRE_NEWLINE_CR
152      \fB/<lf>\fP    PCRE_NEWLINE_LF
153      \fB/<crlf>\fP  PCRE_NEWLINE_CRLF
154    .sp
155    Those specifying line endings are literal strings as shown. Details of the
156    meanings of these PCRE options are given in the
157    .\" HREF
158    \fBpcreapi\fP
159    .\"
160    documentation.
161    .
162    .
163    .SS "Finding all matches in a string"
164    .rs
165  .sp  .sp
166  Searching for all possible matches within each subject string can be requested  Searching for all possible matches within each subject string can be requested
167  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
# Line 160  flags set in order to search for another Line 178  flags set in order to search for another
178  If this second match fails, the start offset is advanced by one, and the normal  If this second match fails, the start offset is advanced by one, and the normal
179  match is retried. This imitates the way Perl handles such cases when using the  match is retried. This imitates the way Perl handles such cases when using the
180  \fB/g\fP modifier or the \fBsplit()\fP function.  \fB/g\fP modifier or the \fBsplit()\fP function.
181  .P  .
182    .
183    .SS "Other modifiers"
184    .rs
185    .sp
186  There are yet more modifiers for controlling the way \fBpcretest\fP  There are yet more modifiers for controlling the way \fBpcretest\fP
187  operates.  operates.
188  .P  .P
# Line 237  recognized: Line 259  recognized:
259    \ee         escape    \ee         escape
260    \ef         formfeed    \ef         formfeed
261    \en         newline    \en         newline
262    .\" JOIN
263      \eqdd       set the PCRE_MATCH_LIMIT limit to dd
264                   (any number of digits)
265    \er         carriage return    \er         carriage return
266    \et         tab    \et         tab
267    \ev         vertical tab    \ev         vertical tab
# Line 245  recognized: Line 270  recognized:
270  .\" JOIN  .\" JOIN
271    \ex{hh...}  hexadecimal character, any number of digits    \ex{hh...}  hexadecimal character, any number of digits
272                 in UTF-8 mode                 in UTF-8 mode
273    .\" JOIN
274    \eA         pass the PCRE_ANCHORED option to \fBpcre_exec()\fP    \eA         pass the PCRE_ANCHORED option to \fBpcre_exec()\fP
275                   or \fBpcre_dfa_exec()\fP
276    .\" JOIN
277    \eB         pass the PCRE_NOTBOL option to \fBpcre_exec()\fP    \eB         pass the PCRE_NOTBOL option to \fBpcre_exec()\fP
278                   or \fBpcre_dfa_exec()\fP
279  .\" JOIN  .\" JOIN
280    \eCdd       call pcre_copy_substring() for substring dd    \eCdd       call pcre_copy_substring() for substring dd
281                 after a successful match (number less than 32)                 after a successful match (number less than 32)
# Line 279  recognized: Line 308  recognized:
308  .\" JOIN  .\" JOIN
309    \eL         call pcre_get_substringlist() after a    \eL         call pcre_get_substringlist() after a
310                 successful match                 successful match
311    .\" JOIN
312    \eM         discover the minimum MATCH_LIMIT and    \eM         discover the minimum MATCH_LIMIT and
313                 MATCH_LIMIT_RECURSION settings                 MATCH_LIMIT_RECURSION settings
314    .\" JOIN
315    \eN         pass the PCRE_NOTEMPTY option to \fBpcre_exec()\fP    \eN         pass the PCRE_NOTEMPTY option to \fBpcre_exec()\fP
316                   or \fBpcre_dfa_exec()\fP
317  .\" JOIN  .\" JOIN
318    \eOdd       set the size of the output vector passed to    \eOdd       set the size of the output vector passed to
319                 \fBpcre_exec()\fP to dd (any number of digits)                 \fBpcre_exec()\fP to dd (any number of digits)
320  .\" JOIN  .\" JOIN
321    \eP         pass the PCRE_PARTIAL option to \fBpcre_exec()\fP    \eP         pass the PCRE_PARTIAL option to \fBpcre_exec()\fP
322                 or \fBpcre_dfa_exec()\fP                 or \fBpcre_dfa_exec()\fP
323    .\" JOIN
324      \eQdd       set the PCRE_MATCH_LIMIT_RECURSION limit to dd
325                   (any number of digits)
326    \eR         pass the PCRE_DFA_RESTART option to \fBpcre_dfa_exec()\fP    \eR         pass the PCRE_DFA_RESTART option to \fBpcre_dfa_exec()\fP
327    \eS         output details of memory get/free calls during matching    \eS         output details of memory get/free calls during matching
328    .\" JOIN
329    \eZ         pass the PCRE_NOTEOL option to \fBpcre_exec()\fP    \eZ         pass the PCRE_NOTEOL option to \fBpcre_exec()\fP
330                   or \fBpcre_dfa_exec()\fP
331  .\" JOIN  .\" JOIN
332    \e?         pass the PCRE_NO_UTF8_CHECK option to    \e?         pass the PCRE_NO_UTF8_CHECK option to
333                 \fBpcre_exec()\fP                 \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP
334    \e>dd       start the match at offset dd (any number of digits);    \e>dd       start the match at offset dd (any number of digits);
335    .\" JOIN
336                 this sets the \fIstartoffset\fP argument for \fBpcre_exec()\fP                 this sets the \fIstartoffset\fP argument for \fBpcre_exec()\fP
337                   or \fBpcre_dfa_exec()\fP
338    .\" JOIN
339      \e<cr>      pass the PCRE_NEWLINE_CR option to \fBpcre_exec()\fP
340                   or \fBpcre_dfa_exec()\fP
341    .\" JOIN
342      \e<lf>      pass the PCRE_NEWLINE_LF option to \fBpcre_exec()\fP
343                   or \fBpcre_dfa_exec()\fP
344    .\" JOIN
345      \e<crlf>    pass the PCRE_NEWLINE_CRLF option to \fBpcre_exec()\fP
346                   or \fBpcre_dfa_exec()\fP
347  .sp  .sp
348    The escapes that specify line endings are literal strings, exactly as shown.
349  A backslash followed by anything else just escapes the anything else. If the  A backslash followed by anything else just escapes the anything else. If the
350  very last character is a backslash, it is ignored. This gives a way of passing  very last character is a backslash, it is ignored. This gives a way of passing
351  an empty line as data, since a real empty line terminates the data input.  an empty line as data, since a real empty line terminates the data input.
# Line 405  parentheses after each string for \fB\eC Line 454  parentheses after each string for \fB\eC
454  .P  .P
455  Note that while patterns can be continued over several lines (a plain ">"  Note that while patterns can be continued over several lines (a plain ">"
456  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
457  included in data by means of the \en escape.  included in data by means of the \en escape (or \er or \er\en for those newline
458    settings).
459  .  .
460  .  .
461  .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"  .SH "OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION"
# Line 576  University Computing Service, Line 626  University Computing Service,
626  Cambridge CB2 3QG, England.  Cambridge CB2 3QG, England.
627  .P  .P
628  .in 0  .in 0
629  Last updated: 18 January 2006  Last updated: 29 June 2006
630  .br  .br
631  Copyright (c) 1997-2006 University of Cambridge.  Copyright (c) 1997-2006 University of Cambridge.
Legend:
Removed from v.87  
changed lines
  Added in v.91
  ViewVC Help
Powered by ViewVC 1.1.5