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