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

Contents of /code/trunk/doc/pcretest.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 91 - (show annotations) (download)
Sat Feb 24 21:41:34 2007 UTC (7 years, 9 months ago) by nigel
File MIME type: text/plain
File size: 26672 byte(s)
Load pcre-6.7 into code/trunk.

1 PCRETEST(1) PCRETEST(1)
2
3
4 NAME
5 pcretest - a program for testing Perl-compatible regular expressions.
6
7
8 SYNOPSIS
9
10 pcretest [options] [source] [destination]
11
12 pcretest was written as a test program for the PCRE regular expression
13 library itself, but it can also be used for experimenting with regular
14 expressions. This document describes the features of the test program;
15 for details of the regular expressions themselves, see the pcrepattern
16 documentation. For details of the PCRE library function calls and their
17 options, see the pcreapi documentation.
18
19
20 OPTIONS
21
22 -C Output the version number of the PCRE library, and all avail-
23 able information about the optional features that are
24 included, and then exit.
25
26 -d Behave as if each regex has the /D (debug) modifier; the
27 internal form is output after compilation.
28
29 -dfa Behave as if each data line contains the \D escape sequence;
30 this causes the alternative matching function,
31 pcre_dfa_exec(), to be used instead of the standard
32 pcre_exec() function (more detail is given below).
33
34 -i Behave as if each regex has the /I modifier; information
35 about the compiled pattern is given after compilation.
36
37 -m Output the size of each compiled pattern after it has been
38 compiled. This is equivalent to adding /M to each regular
39 expression. For compatibility with earlier versions of
40 pcretest, -s is a synonym for -m.
41
42 -o osize Set the number of elements in the output vector that is used
43 when calling pcre_exec() to be osize. The default value is
44 45, which is enough for 14 capturing subexpressions. The vec-
45 tor size can be changed for individual matching calls by
46 including \O in the data line (see below).
47
48 -p Behave as if each regex has the /P modifier; the POSIX wrap-
49 per API is used to call PCRE. None of the other options has
50 any effect when -p is set.
51
52 -q Do not output the version number of pcretest at the start of
53 execution.
54
55 -S size On Unix-like systems, set the size of the runtime stack to
56 size megabytes.
57
58 -t Run each compile, study, and match many times with a timer,
59 and output resulting time per compile or match (in millisec-
60 onds). Do not set -m with -t, because you will then get the
61 size output a zillion times, and the timing will be dis-
62 torted.
63
64
65 DESCRIPTION
66
67 If pcretest is given two filename arguments, it reads from the first
68 and writes to the second. If it is given only one filename argument, it
69 reads from that file and writes to stdout. Otherwise, it reads from
70 stdin and writes to stdout, and prompts for each line of input, using
71 "re>" to prompt for regular expressions, and "data>" to prompt for data
72 lines.
73
74 The program handles any number of sets of input on a single input file.
75 Each set starts with a regular expression, and continues with any num-
76 ber of data lines to be matched against the pattern.
77
78 Each data line is matched separately and independently. If you want to
79 do multi-line matches, you have to use the \n escape sequence (or \r or
80 \r\n, depending on the newline setting) in a single line of input to
81 encode the newline characters. There is no limit on the length of data
82 lines; the input buffer is automatically extended if it is too small.
83
84 An empty line signals the end of the data lines, at which point a new
85 regular expression is read. The regular expressions are given enclosed
86 in any non-alphanumeric delimiters other than backslash, for example:
87
88 /(a|bc)x+yz/
89
90 White space before the initial delimiter is ignored. A regular expres-
91 sion may be continued over several input lines, in which case the new-
92 line characters are included within it. It is possible to include the
93 delimiter within the pattern by escaping it, for example
94
95 /abc\/def/
96
97 If you do so, the escape and the delimiter form part of the pattern,
98 but since delimiters are always non-alphanumeric, this does not affect
99 its interpretation. If the terminating delimiter is immediately fol-
100 lowed by a backslash, for example,
101
102 /abc/\
103
104 then a backslash is added to the end of the pattern. This is done to
105 provide a way of testing the error condition that arises if a pattern
106 finishes with a backslash, because
107
108 /abc\/
109
110 is interpreted as the first line of a pattern that starts with "abc/",
111 causing pcretest to read the next line as a continuation of the regular
112 expression.
113
114
115 PATTERN MODIFIERS
116
117 A pattern may be followed by any number of modifiers, which are mostly
118 single characters. Following Perl usage, these are referred to below
119 as, for example, "the /i modifier", even though the delimiter of the
120 pattern need not always be a slash, and no slash is used when writing
121 modifiers. Whitespace may appear between the final pattern delimiter
122 and the first modifier, and between the modifiers themselves.
123
124 The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE,
125 PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when pcre_com-
126 pile() is called. These four modifier letters have the same effect as
127 they do in Perl. For example:
128
129 /caseless/i
130
131 The following table shows additional modifiers for setting PCRE options
132 that do not correspond to anything in Perl:
133
134 /A PCRE_ANCHORED
135 /C PCRE_AUTO_CALLOUT
136 /E PCRE_DOLLAR_ENDONLY
137 /f PCRE_FIRSTLINE
138 /J PCRE_DUPNAMES
139 /N PCRE_NO_AUTO_CAPTURE
140 /U PCRE_UNGREEDY
141 /X PCRE_EXTRA
142 /<cr> PCRE_NEWLINE_CR
143 /<lf> PCRE_NEWLINE_LF
144 /<crlf> PCRE_NEWLINE_CRLF
145
146 Those specifying line endings are literal strings as shown. Details of
147 the meanings of these PCRE options are given in the pcreapi documenta-
148 tion.
149
150 Finding all matches in a string
151
152 Searching for all possible matches within each subject string can be
153 requested by the /g or /G modifier. After finding a match, PCRE is
154 called again to search the remainder of the subject string. The differ-
155 ence between /g and /G is that the former uses the startoffset argument
156 to pcre_exec() to start searching at a new point within the entire
157 string (which is in effect what Perl does), whereas the latter passes
158 over a shortened substring. This makes a difference to the matching
159 process if the pattern begins with a lookbehind assertion (including \b
160 or \B).
161
162 If any call to pcre_exec() in a /g or /G sequence matches an empty
163 string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED
164 flags set in order to search for another, non-empty, match at the same
165 point. If this second match fails, the start offset is advanced by
166 one, and the normal match is retried. This imitates the way Perl han-
167 dles such cases when using the /g modifier or the split() function.
168
169 Other modifiers
170
171 There are yet more modifiers for controlling the way pcretest operates.
172
173 The /+ modifier requests that as well as outputting the substring that
174 matched the entire pattern, pcretest should in addition output the
175 remainder of the subject string. This is useful for tests where the
176 subject contains multiple copies of the same substring.
177
178 The /L modifier must be followed directly by the name of a locale, for
179 example,
180
181 /pattern/Lfr_FR
182
183 For this reason, it must be the last modifier. The given locale is set,
184 pcre_maketables() is called to build a set of character tables for the
185 locale, and this is then passed to pcre_compile() when compiling the
186 regular expression. Without an /L modifier, NULL is passed as the
187 tables pointer; that is, /L applies only to the expression on which it
188 appears.
189
190 The /I modifier requests that pcretest output information about the
191 compiled pattern (whether it is anchored, has a fixed first character,
192 and so on). It does this by calling pcre_fullinfo() after compiling a
193 pattern. If the pattern is studied, the results of that are also out-
194 put.
195
196 The /D modifier is a PCRE debugging feature, which also assumes /I. It
197 causes the internal form of compiled regular expressions to be output
198 after compilation. If the pattern was studied, the information returned
199 is also output.
200
201 The /F modifier causes pcretest to flip the byte order of the fields in
202 the compiled pattern that contain 2-byte and 4-byte numbers. This
203 facility is for testing the feature in PCRE that allows it to execute
204 patterns that were compiled on a host with a different endianness. This
205 feature is not available when the POSIX interface to PCRE is being
206 used, that is, when the /P pattern modifier is specified. See also the
207 section about saving and reloading compiled patterns below.
208
209 The /S modifier causes pcre_study() to be called after the expression
210 has been compiled, and the results used when the expression is matched.
211
212 The /M modifier causes the size of memory block used to hold the com-
213 piled pattern to be output.
214
215 The /P modifier causes pcretest to call PCRE via the POSIX wrapper API
216 rather than its native API. When this is done, all other modifiers
217 except /i, /m, and /+ are ignored. REG_ICASE is set if /i is present,
218 and REG_NEWLINE is set if /m is present. The wrapper functions force
219 PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set.
220
221 The /8 modifier causes pcretest to call PCRE with the PCRE_UTF8 option
222 set. This turns on support for UTF-8 character handling in PCRE, pro-
223 vided that it was compiled with this support enabled. This modifier
224 also causes any non-printing characters in output strings to be printed
225 using the \x{hh...} notation if they are valid UTF-8 sequences.
226
227 If the /? modifier is used with /8, it causes pcretest to call
228 pcre_compile() with the PCRE_NO_UTF8_CHECK option, to suppress the
229 checking of the string for UTF-8 validity.
230
231
232 DATA LINES
233
234 Before each data line is passed to pcre_exec(), leading and trailing
235 whitespace is removed, and it is then scanned for \ escapes. Some of
236 these are pretty esoteric features, intended for checking out some of
237 the more complicated features of PCRE. If you are just testing "ordi-
238 nary" regular expressions, you probably don't need any of these. The
239 following escapes are recognized:
240
241 \a alarm (= BEL)
242 \b backspace
243 \e escape
244 \f formfeed
245 \n newline
246 \qdd set the PCRE_MATCH_LIMIT limit to dd
247 (any number of digits)
248 \r carriage return
249 \t tab
250 \v vertical tab
251 \nnn octal character (up to 3 octal digits)
252 \xhh hexadecimal character (up to 2 hex digits)
253 \x{hh...} hexadecimal character, any number of digits
254 in UTF-8 mode
255 \A pass the PCRE_ANCHORED option to pcre_exec()
256 or pcre_dfa_exec()
257 \B pass the PCRE_NOTBOL option to pcre_exec()
258 or pcre_dfa_exec()
259 \Cdd call pcre_copy_substring() for substring dd
260 after a successful match (number less than 32)
261 \Cname call pcre_copy_named_substring() for substring
262 "name" after a successful match (name termin-
263 ated by next non alphanumeric character)
264 \C+ show the current captured substrings at callout
265 time
266 \C- do not supply a callout function
267 \C!n return 1 instead of 0 when callout number n is
268 reached
269 \C!n!m return 1 instead of 0 when callout number n is
270 reached for the nth time
271 \C*n pass the number n (may be negative) as callout
272 data; this is used as the callout return value
273 \D use the pcre_dfa_exec() match function
274 \F only shortest match for pcre_dfa_exec()
275 \Gdd call pcre_get_substring() for substring dd
276 after a successful match (number less than 32)
277 \Gname call pcre_get_named_substring() for substring
278 "name" after a successful match (name termin-
279 ated by next non-alphanumeric character)
280 \L call pcre_get_substringlist() after a
281 successful match
282 \M discover the minimum MATCH_LIMIT and
283 MATCH_LIMIT_RECURSION settings
284 \N pass the PCRE_NOTEMPTY option to pcre_exec()
285 or pcre_dfa_exec()
286 \Odd set the size of the output vector passed to
287 pcre_exec() to dd (any number of digits)
288 \P pass the PCRE_PARTIAL option to pcre_exec()
289 or pcre_dfa_exec()
290 \Qdd set the PCRE_MATCH_LIMIT_RECURSION limit to dd
291 (any number of digits)
292 \R pass the PCRE_DFA_RESTART option to pcre_dfa_exec()
293 \S output details of memory get/free calls during matching
294 \Z pass the PCRE_NOTEOL option to pcre_exec()
295 or pcre_dfa_exec()
296 \? pass the PCRE_NO_UTF8_CHECK option to
297 pcre_exec() or pcre_dfa_exec()
298 \>dd start the match at offset dd (any number of digits);
299 this sets the startoffset argument for pcre_exec()
300 or pcre_dfa_exec()
301 \<cr> pass the PCRE_NEWLINE_CR option to pcre_exec()
302 or pcre_dfa_exec()
303 \<lf> pass the PCRE_NEWLINE_LF option to pcre_exec()
304 or pcre_dfa_exec()
305 \<crlf> pass the PCRE_NEWLINE_CRLF option to pcre_exec()
306 or pcre_dfa_exec()
307
308 The escapes that specify line endings are literal strings, exactly as
309 shown. A backslash followed by anything else just escapes the anything
310 else. If the very last character is a backslash, it is ignored. This
311 gives a way of passing an empty line as data, since a real empty line
312 terminates the data input.
313
314 If \M is present, pcretest calls pcre_exec() several times, with dif-
315 ferent values in the match_limit and match_limit_recursion fields of
316 the pcre_extra data structure, until it finds the minimum numbers for
317 each parameter that allow pcre_exec() to complete. The match_limit num-
318 ber is a measure of the amount of backtracking that takes place, and
319 checking it out can be instructive. For most simple matches, the number
320 is quite small, but for patterns with very large numbers of matching
321 possibilities, it can become large very quickly with increasing length
322 of subject string. The match_limit_recursion number is a measure of how
323 much stack (or, if PCRE is compiled with NO_RECURSE, how much heap)
324 memory is needed to complete the match attempt.
325
326 When \O is used, the value specified may be higher or lower than the
327 size set by the -O command line option (or defaulted to 45); \O applies
328 only to the call of pcre_exec() for the line in which it appears.
329
330 If the /P modifier was present on the pattern, causing the POSIX wrap-
331 per API to be used, the only option-setting sequences that have any
332 effect are \B and \Z, causing REG_NOTBOL and REG_NOTEOL, respectively,
333 to be passed to regexec().
334
335 The use of \x{hh...} to represent UTF-8 characters is not dependent on
336 the use of the /8 modifier on the pattern. It is recognized always.
337 There may be any number of hexadecimal digits inside the braces. The
338 result is from one to six bytes, encoded according to the UTF-8 rules.
339
340
341 THE ALTERNATIVE MATCHING FUNCTION
342
343 By default, pcretest uses the standard PCRE matching function,
344 pcre_exec() to match each data line. From release 6.0, PCRE supports an
345 alternative matching function, pcre_dfa_test(), which operates in a
346 different way, and has some restrictions. The differences between the
347 two functions are described in the pcrematching documentation.
348
349 If a data line contains the \D escape sequence, or if the command line
350 contains the -dfa option, the alternative matching function is called.
351 This function finds all possible matches at a given point. If, however,
352 the \F escape sequence is present in the data line, it stops after the
353 first match is found. This is always the shortest possible match.
354
355
356 DEFAULT OUTPUT FROM PCRETEST
357
358 This section describes the output when the normal matching function,
359 pcre_exec(), is being used.
360
361 When a match succeeds, pcretest outputs the list of captured substrings
362 that pcre_exec() returns, starting with number 0 for the string that
363 matched the whole pattern. Otherwise, it outputs "No match" or "Partial
364 match" when pcre_exec() returns PCRE_ERROR_NOMATCH or PCRE_ERROR_PAR-
365 TIAL, respectively, and otherwise the PCRE negative error number. Here
366 is an example of an interactive pcretest run.
367
368 $ pcretest
369 PCRE version 5.00 07-Sep-2004
370
371 re> /^abc(\d+)/
372 data> abc123
373 0: abc123
374 1: 123
375 data> xyz
376 No match
377
378 If the strings contain any non-printing characters, they are output as
379 \0x escapes, or as \x{...} escapes if the /8 modifier was present on
380 the pattern. If the pattern has the /+ modifier, the output for sub-
381 string 0 is followed by the the rest of the subject string, identified
382 by "0+" like this:
383
384 re> /cat/+
385 data> cataract
386 0: cat
387 0+ aract
388
389 If the pattern has the /g or /G modifier, the results of successive
390 matching attempts are output in sequence, like this:
391
392 re> /\Bi(\w\w)/g
393 data> Mississippi
394 0: iss
395 1: ss
396 0: iss
397 1: ss
398 0: ipp
399 1: pp
400
401 "No match" is output only if the first match attempt fails.
402
403 If any of the sequences \C, \G, or \L are present in a data line that
404 is successfully matched, the substrings extracted by the convenience
405 functions are output with C, G, or L after the string number instead of
406 a colon. This is in addition to the normal full list. The string length
407 (that is, the return from the extraction function) is given in paren-
408 theses after each string for \C and \G.
409
410 Note that while patterns can be continued over several lines (a plain
411 ">" prompt is used for continuations), data lines may not. However new-
412 lines can be included in data by means of the \n escape (or \r or \r\n
413 for those newline settings).
414
415
416 OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION
417
418 When the alternative matching function, pcre_dfa_exec(), is used (by
419 means of the \D escape sequence or the -dfa command line option), the
420 output consists of a list of all the matches that start at the first
421 point in the subject where there is at least one match. For example:
422
423 re> /(tang|tangerine|tan)/
424 data> yellow tangerine\D
425 0: tangerine
426 1: tang
427 2: tan
428
429 (Using the normal matching function on this data finds only "tang".)
430 The longest matching string is always given first (and numbered zero).
431
432 If /gP is present on the pattern, the search for further matches
433 resumes at the end of the longest match. For example:
434
435 re> /(tang|tangerine|tan)/g
436 data> yellow tangerine and tangy sultana\D
437 0: tangerine
438 1: tang
439 2: tan
440 0: tang
441 1: tan
442 0: tan
443
444 Since the matching function does not support substring capture, the
445 escape sequences that are concerned with captured substrings are not
446 relevant.
447
448
449 RESTARTING AFTER A PARTIAL MATCH
450
451 When the alternative matching function has given the PCRE_ERROR_PARTIAL
452 return, indicating that the subject partially matched the pattern, you
453 can restart the match with additional subject data by means of the \R
454 escape sequence. For example:
455
456 re> /^?(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)$/
457 data> 23ja\P\D
458 Partial match: 23ja
459 data> n05\R\D
460 0: n05
461
462 For further information about partial matching, see the pcrepartial
463 documentation.
464
465
466 CALLOUTS
467
468 If the pattern contains any callout requests, pcretest's callout func-
469 tion is called during matching. This works with both matching func-
470 tions. By default, the called function displays the callout number, the
471 start and current positions in the text at the callout time, and the
472 next pattern item to be tested. For example, the output
473
474 --->pqrabcdef
475 0 ^ ^ \d
476
477 indicates that callout number 0 occurred for a match attempt starting
478 at the fourth character of the subject string, when the pointer was at
479 the seventh character of the data, and when the next pattern item was
480 \d. Just one circumflex is output if the start and current positions
481 are the same.
482
483 Callouts numbered 255 are assumed to be automatic callouts, inserted as
484 a result of the /C pattern modifier. In this case, instead of showing
485 the callout number, the offset in the pattern, preceded by a plus, is
486 output. For example:
487
488 re> /\d?[A-E]\*/C
489 data> E*
490 --->E*
491 +0 ^ \d?
492 +3 ^ [A-E]
493 +8 ^^ \*
494 +10 ^ ^
495 0: E*
496
497 The callout function in pcretest returns zero (carry on matching) by
498 default, but you can use a \C item in a data line (as described above)
499 to change this.
500
501 Inserting callouts can be helpful when using pcretest to check compli-
502 cated regular expressions. For further information about callouts, see
503 the pcrecallout documentation.
504
505
506 SAVING AND RELOADING COMPILED PATTERNS
507
508 The facilities described in this section are not available when the
509 POSIX inteface to PCRE is being used, that is, when the /P pattern mod-
510 ifier is specified.
511
512 When the POSIX interface is not in use, you can cause pcretest to write
513 a compiled pattern to a file, by following the modifiers with > and a
514 file name. For example:
515
516 /pattern/im >/some/file
517
518 See the pcreprecompile documentation for a discussion about saving and
519 re-using compiled patterns.
520
521 The data that is written is binary. The first eight bytes are the
522 length of the compiled pattern data followed by the length of the
523 optional study data, each written as four bytes in big-endian order
524 (most significant byte first). If there is no study data (either the
525 pattern was not studied, or studying did not return any data), the sec-
526 ond length is zero. The lengths are followed by an exact copy of the
527 compiled pattern. If there is additional study data, this follows imme-
528 diately after the compiled pattern. After writing the file, pcretest
529 expects to read a new pattern.
530
531 A saved pattern can be reloaded into pcretest by specifing < and a file
532 name instead of a pattern. The name of the file must not contain a <
533 character, as otherwise pcretest will interpret the line as a pattern
534 delimited by < characters. For example:
535
536 re> </some/file
537 Compiled regex loaded from /some/file
538 No study data
539
540 When the pattern has been loaded, pcretest proceeds to read data lines
541 in the usual way.
542
543 You can copy a file written by pcretest to a different host and reload
544 it there, even if the new host has opposite endianness to the one on
545 which the pattern was compiled. For example, you can compile on an i86
546 machine and run on a SPARC machine.
547
548 File names for saving and reloading can be absolute or relative, but
549 note that the shell facility of expanding a file name that starts with
550 a tilde (~) is not available.
551
552 The ability to save and reload files in pcretest is intended for test-
553 ing and experimentation. It is not intended for production use because
554 only a single pattern can be written to a file. Furthermore, there is
555 no facility for supplying custom character tables for use with a
556 reloaded pattern. If the original pattern was compiled with custom
557 tables, an attempt to match a subject string using a reloaded pattern
558 is likely to cause pcretest to crash. Finally, if you attempt to load
559 a file that is not in the correct format, the result is undefined.
560
561
562 AUTHOR
563
564 Philip Hazel
565 University Computing Service,
566 Cambridge CB2 3QG, England.
567
568 Last updated: 29 June 2006
569 Copyright (c) 1997-2006 University of Cambridge.

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12