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