/[pcre]/code/tags/pcre-5.0/doc/pcretest.txt
ViewVC logotype

Diff of /code/tags/pcre-5.0/doc/pcretest.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 71 by nigel, Sat Feb 24 21:40:24 2007 UTC revision 73 by nigel, Sat Feb 24 21:40:30 2007 UTC
# Line 1  Line 1 
1  NAME  PCRETEST(1)                                                        PCRETEST(1)
2       pcretest - a program  for  testing  Perl-compatible  regular  
      expressions.  
3    
4    
5    NAME
6           pcretest - a program for testing Perl-compatible regular expressions.
7    
8  SYNOPSIS  SYNOPSIS
9       pcretest [-d] [-i] [-m] [-o osize] [-p] [-t] [source]  [des-         pcretest [-d] [-i] [-m] [-o osize] [-p] [-t] [source] [destination]
      tination]  
10    
11       pcretest was written as a test program for the PCRE  regular         pcretest  was written as a test program for the PCRE regular expression
12       expression  library  itself,  but  it  can  also be used for         library itself, but it can also be used for experimenting with  regular
13       experimenting  with  regular  expressions.   This   document         expressions.  This document describes the features of the test program;
14       describes  the  features of the test program; for details of         for details of the regular expressions themselves, see the  pcrepattern
15       the regular  expressions  themselves,  see  the  pcrepattern         documentation.  For  details  of  PCRE and its options, see the pcreapi
16       documentation.  For details of PCRE and its options, see the         documentation.
      pcreapi documentation.  
17    
18    
19  OPTIONS  OPTIONS
20    
21    
22       -C        Output the version number of the PCRE library, and         -C        Output the version number of the PCRE library, and all avail-
23                 all   available  information  about  the  optional                   able   information  about  the  optional  features  that  are
24                 features that are included, and then exit.                   included, and then exit.
25    
26       -d        Behave as if each regex had the /D  modifier  (see         -d        Behave as if each regex had the /D modifier (see below);  the
27                 below); the internal form is output after compila-                   internal form is output after compilation.
28                 tion.  
29           -i        Behave  as  if  each  regex  had the /I modifier; information
30       -i        Behave as if  each  regex  had  the  /I  modifier;                   about the compiled pattern is given after compilation.
31                 information  about  the  compiled pattern is given  
32                 after compilation.         -m        Output the size of each compiled pattern after  it  has  been
33                     compiled.  This  is  equivalent  to adding /M to each regular
34       -m        Output the size of each compiled pattern after  it                   expression.  For  compatibility  with  earlier  versions   of
35                 has been compiled. This is equivalent to adding /M                   pcretest, -s is a synonym for -m.
36                 to each regular expression. For compatibility with  
37                 earlier  versions of pcretest, -s is a synonym for         -o osize  Set  the number of elements in the output vector that is used
38                 -m.                   when calling PCRE to be osize. The default value is 45, which
39                     is  enough  for  14 capturing subexpressions. The vector size
40       -o osize  Set the number of elements in  the  output  vector                   can be changed for individual matching calls by including  \O
41                 that  is  used  when calling PCRE to be osize. The                   in the data line (see below).
42                 default value is 45, which is enough for  14  cap-  
43                 turing  subexpressions.  The  vector  size  can be         -p        Behave  as  if  each regex has /P modifier; the POSIX wrapper
44                 changed for individual matching calls by including                   API is used to call PCRE. None of the other options  has  any
45                 \O in the data line (see below).                   effect when -p is set.
46    
47       -p        Behave as if each regex has /P modifier; the POSIX         -t        Run  each  compile, study, and match many times with a timer,
48                 wrapper  API  is  used  to  call PCRE. None of the                   and output resulting time per compile or match (in  millisec-
49                 other options has any effect when -p is set.                   onds).  Do  not set -t with -m, because you will then get the
50                     size output 20000 times and the timing will be distorted.
      -t        Run each compile, study, and match many times with  
                a  timer, and output resulting time per compile or  
                match (in milliseconds). Do not set  -t  with  -m,  
                because  you  will  then get the size output 20000  
                times and the timing will be distorted.  
51    
52    
53  DESCRIPTION  DESCRIPTION
54    
55       If pcretest is given two filename arguments, it  reads  from         If pcretest is given two filename arguments, it reads  from  the  first
56       the  first and writes to the second. If it is given only one         and writes to the second. If it is given only one filename argument, it
57       filename argument, it reads from that  file  and  writes  to         reads from that file and writes to stdout.  Otherwise,  it  reads  from
58       stdout. Otherwise, it reads from stdin and writes to stdout,         stdin  and  writes to stdout, and prompts for each line of input, using
59       and prompts for each line of input, using  "re>"  to  prompt         "re>" to prompt for regular expressions, and "data>" to prompt for data
60       for  regular  expressions,  and  "data>"  to prompt for data         lines.
61       lines.  
62           The program handles any number of sets of input on a single input file.
63       The program handles any number of sets of input on a  single         Each set starts with a regular expression, and continues with any  num-
64       input  file.  Each set starts with a regular expression, and         ber of data lines to be matched against the pattern.
65       continues with any  number  of  data  lines  to  be  matched  
66       against the pattern.         Each  line  is  matched separately and independently. If you want to do
67           multiple-line matches, you have to use the \n escape sequence in a sin-
68       Each line is matched separately and  independently.  If  you         gle  line of input to encode the newline characters. The maximum length
69       want  to  do  multiple-line  matches, you have to use the \n         of data line is 30,000 characters.
70       escape sequence in a single line of input to encode the new-  
71       line  characters.  The maximum length of data line is 30,000         An empty line signals the end of the data lines, at which point  a  new
72       characters.         regular  expression is read. The regular expressions are given enclosed
73           in any non-alphameric delimiters other than backslash, for example
74       An empty line signals the end of the data  lines,  at  which  
75       point  a new regular expression is read. The regular expres-           /(a|bc)x+yz/
76       sions are given enclosed in  any  non-alphameric  delimiters  
77       other than backslash, for example         White space before the initial delimiter is ignored. A regular  expres-
78           sion  may be continued over several input lines, in which case the new-
79         /(a|bc)x+yz/         line characters are included within it. It is possible to  include  the
80           delimiter within the pattern by escaping it, for example
81       White space before the initial delimiter is ignored. A regu-  
82       lar expression may be continued over several input lines, in           /abc\/def/
83       which case the newline characters are included within it. It  
84       is  possible  to include the delimiter within the pattern by         If  you  do  so, the escape and the delimiter form part of the pattern,
85       escaping it, for example         but since delimiters are always non-alphameric, this  does  not  affect
86           its  interpretation.   If the terminating delimiter is immediately fol-
87         /abc\/def/         lowed by a backslash, for example,
88    
89       If you do so, the escape and the delimiter form part of  the           /abc/\
90       pattern,  but  since  delimiters  are always non-alphameric,  
91       this does not affect its interpretation.  If the terminating         then a backslash is added to the end of the pattern. This  is  done  to
92       delimiter  is immediately followed by a backslash, for exam-         provide  a  way of testing the error condition that arises if a pattern
93       ple,         finishes with a backslash, because
94    
95         /abc/\           /abc\/
96    
97       then a backslash is added to the end of the pattern. This is         is interpreted as the first line of a pattern that starts with  "abc/",
98       done  to  provide  a way of testing the error condition that         causing pcretest to read the next line as a continuation of the regular
99       arises if a pattern finishes with a backslash, because         expression.
   
        /abc\/  
   
      is interpreted as the first line of a  pattern  that  starts  
      with  "abc/",  causing  pcretest  to read the next line as a  
      continuation of the regular expression.  
100    
101    
102  PATTERN MODIFIERS  PATTERN MODIFIERS
103    
104       The pattern may be followed by i, m, s,  or  x  to  set  the         The pattern may be followed by i, m, s, or x to set the  PCRE_CASELESS,
105       PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED         PCRE_MULTILINE,  PCRE_DOTALL,  or  PCRE_EXTENDED options, respectively.
106       options, respectively. For example:         For example:
107    
108         /caseless/i           /caseless/i
109    
110       These modifier letters have the same effect as  they  do  in         These modifier letters have the same effect as they do in  Perl.  There
111       Perl.  There  are  others  that set PCRE options that do not         are  others that set PCRE options that do not correspond to anything in
112       correspond to anything in Perl:  /A, /E, /N, /U, and /X  set         Perl: /A, /E, /N, /U, and /X  set  PCRE_ANCHORED,  PCRE_DOLLAR_ENDONLY,
113       PCRE_ANCHORED,   PCRE_DOLLAR_ENDONLY,  PCRE_NO_AUTO_CAPTURE,         PCRE_NO_AUTO_CAPTURE, PCRE_UNGREEDY, and PCRE_EXTRA respectively.
114       PCRE_UNGREEDY, and PCRE_EXTRA respectively.  
115           Searching  for  all  possible matches within each subject string can be
116       Searching for  all  possible  matches  within  each  subject         requested by the /g or /G modifier. After  finding  a  match,  PCRE  is
117       string  can  be  requested  by  the /g or /G modifier. After         called again to search the remainder of the subject string. The differ-
118       finding  a  match,  PCRE  is  called  again  to  search  the         ence between /g and /G is that the former uses the startoffset argument
119       remainder  of  the subject string. The difference between /g         to  pcre_exec()  to  start  searching  at a new point within the entire
120       and /G is that the former uses the startoffset  argument  to         string (which is in effect what Perl does), whereas the  latter  passes
121       pcre_exec()  to  start  searching  at a new point within the         over  a  shortened  substring.  This makes a difference to the matching
122       entire string (which is in effect what Perl  does),  whereas         process if the pattern begins with a lookbehind assertion (including \b
123       the  latter  passes over a shortened substring. This makes a         or \B).
124       difference to the matching process  if  the  pattern  begins  
125       with a lookbehind assertion (including \b or \B).         If  any  call  to  pcre_exec()  in a /g or /G sequence matches an empty
126           string, the next call is done with the PCRE_NOTEMPTY and  PCRE_ANCHORED
127       If any call to pcre_exec() in a /g or /G sequence matches an         flags  set in order to search for another, non-empty, match at the same
128       empty  string,  the next call is done with the PCRE_NOTEMPTY         point.  If this second match fails, the start  offset  is  advanced  by
129       and PCRE_ANCHORED flags set in order to search for  another,         one,  and  the normal match is retried. This imitates the way Perl han-
130       non-empty,  match  at  the same point.  If this second match         dles such cases when using the /g modifier or the split() function.
131       fails, the start offset is advanced by one, and  the  normal  
132       match  is  retried.  This imitates the way Perl handles such         There are a number of other modifiers for controlling the way  pcretest
133       cases when using the /g modifier or the split() function.         operates.
134    
135       There are a number of other modifiers  for  controlling  the         The  /+ modifier requests that as well as outputting the substring that
136       way pcretest operates.         matched the entire pattern, pcretest  should  in  addition  output  the
137           remainder  of  the  subject  string. This is useful for tests where the
138       The /+ modifier requests that as well as outputting the sub-         subject contains multiple copies of the same substring.
139       string  that  matched the entire pattern, pcretest should in  
140       addition output the remainder of the subject string. This is         The /L modifier must be followed directly by the name of a locale,  for
141       useful  for tests where the subject contains multiple copies         example,
142       of the same substring.  
143             /pattern/Lfr
144       The /L modifier must be followed directly by the name  of  a  
145       locale, for example,         For  this reason, it must be the last modifier letter. The given locale
146           is set, pcre_maketables() is called to build a set of character  tables
147         /pattern/Lfr         for  the locale, and this is then passed to pcre_compile() when compil-
148           ing the regular expression. Without an /L modifier, NULL is  passed  as
149       For this reason, it must be the last  modifier  letter.  The         the tables pointer; that is, /L applies only to the expression on which
150       given  locale is set, pcre_maketables() is called to build a         it appears.
151       set of character tables for the locale,  and  this  is  then  
152       passed  to pcre_compile() when compiling the regular expres-         The /I modifier requests that pcretest  output  information  about  the
153       sion. Without an /L modifier, NULL is passed as  the  tables         compiled  expression (whether it is anchored, has a fixed first charac-
154       pointer; that is, /L applies only to the expression on which         ter, and so on). It does this by calling pcre_fullinfo() after  compil-
155       it appears.         ing  an expression, and outputting the information it gets back. If the
156           pattern is studied, the results of that are also output.
157       The /I modifier requests that  pcretest  output  information  
158       about the compiled expression (whether it is anchored, has a         The /D modifier is a PCRE debugging feature, which also assumes /I.  It
159       fixed first character, and so on). It does this  by  calling         causes  the  internal form of compiled regular expressions to be output
160       pcre_fullinfo()  after  compiling an expression, and output-         after compilation. If the pattern was studied, the information returned
161       ting the information it gets back. If the  pattern  is  stu-         is also output.
162       died, the results of that are also output.  
163           The  /S  modifier causes pcre_study() to be called after the expression
164       The /D modifier is a  PCRE  debugging  feature,  which  also         has been compiled, and the results used when the expression is matched.
165       assumes /I.  It causes the internal form of compiled regular  
166       expressions to be output after compilation. If  the  pattern         The  /M  modifier causes the size of memory block used to hold the com-
167       was studied, the information returned is also output.         piled pattern to be output.
168    
169       The /S modifier causes pcre_study() to be called  after  the         The /P modifier causes pcretest to call PCRE via the POSIX wrapper  API
170       expression  has been compiled, and the results used when the         rather  than  its  native  API.  When this is done, all other modifiers
171       expression is matched.         except /i, /m, and /+ are ignored. REG_ICASE is set if /i  is  present,
172           and  REG_NEWLINE  is  set if /m is present. The wrapper functions force
173       The /M modifier causes the size of memory block used to hold         PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is  set.
174       the compiled pattern to be output.  
175           The  /8 modifier causes pcretest to call PCRE with the PCRE_UTF8 option
176       The /P modifier causes pcretest to call PCRE via  the  POSIX         set. This turns on support for UTF-8 character handling in  PCRE,  pro-
177       wrapper  API  rather than its native API. When this is done,         vided  that  it  was  compiled with this support enabled. This modifier
178       all other modifiers except  /i,  /m,  and  /+  are  ignored.         also causes any non-printing characters in output strings to be printed
179       REG_ICASE is set if /i is present, and REG_NEWLINE is set if         using the \x{hh...} notation if they are valid UTF-8 sequences.
180       /m    is    present.    The    wrapper    functions    force  
181       PCRE_DOLLAR_ENDONLY    always,    and   PCRE_DOTALL   unless         If  the  /?  modifier  is  used  with  /8,  it  causes pcretest to call
182       REG_NEWLINE is set.         pcre_compile() with the  PCRE_NO_UTF8_CHECK  option,  to  suppress  the
183           checking of the string for UTF-8 validity.
      The /8 modifier  causes  pcretest  to  call  PCRE  with  the  
      PCRE_UTF8  option set. This turns on support for UTF-8 char-  
      acter handling in PCRE, provided that it was  compiled  with  
      this  support  enabled.  This  modifier also causes any non-  
      printing characters in output strings to  be  printed  using  
      the \x{hh...} notation if they are valid UTF-8 sequences.  
   
      If the /? modifier is used with /8, it  causes  pcretest  to  
      call  pcre_compile()  with the PCRE_NO_UTF8_CHECK option, to  
      suppress the checking of the string for UTF-8 validity.  
184    
185    
186  CALLOUTS  CALLOUTS
187    
188       If the pattern contains  any  callout  requests,  pcretest's         If  the pattern contains any callout requests, pcretest's callout func-
189       callout function will be called. By default, it displays the         tion will be called. By default, it displays the  callout  number,  and
190       callout number, and the start and current positions  in  the         the  start  and  current positions in the text at the callout time. For
191       text at the callout time. For example, the output         example, the output
192    
193         --->pqrabcdef           --->pqrabcdef
194           0    ^  ^             0    ^  ^
195    
196       indicates that callout number 0 occurred for a match attempt         indicates that callout number 0 occurred for a match  attempt  starting
197       starting at the fourth character of the subject string, when         at  the fourth character of the subject string, when the pointer was at
198       the pointer was at the seventh character. The callout  func-         the seventh character. The callout  function  returns  zero  (carry  on
199       tion returns zero (carry on matching) by default.         matching) by default.
200    
201       Inserting callouts may be helpful  when  using  pcretest  to         Inserting  callouts may be helpful when using pcretest to check compli-
202       check  complicated regular expressions. For further informa-         cated regular expressions. For further information about callouts,  see
203       tion about callouts, see the pcrecallout documentation.         the pcrecallout documentation.
204    
205       For testing the PCRE library, additional control of  callout         For  testing  the PCRE library, additional control of callout behaviour
206       behaviour  is available via escape sequences in the data, as         is available via escape sequences in the data, as described in the fol-
207       described in the following section.  In  particular,  it  is         lowing  section.  In  particular, it is possible to pass in a number as
208       possible to pass in a number as callout data (the default is         callout data (the default is zero). If the callout function receives  a
209       zero). If the callout function receives a  non-zero  number,         non-zero number, it returns that value instead of zero.
      it returns that value instead of zero.  
210    
211    
212  DATA LINES  DATA LINES
213    
214       Before each data line is passed to pcre_exec(), leading  and         Before  each  data  line is passed to pcre_exec(), leading and trailing
215       trailing whitespace is removed, and it is then scanned for \         whitespace is removed, and it is then scanned for \  escapes.  Some  of
216       escapes.  Some  of  these  are  pretty  esoteric   features,         these  are  pretty esoteric features, intended for checking out some of
217       intended  for  checking  out  some  of  the more complicated         the more complicated features of PCRE. If you are just  testing  "ordi-
218       features of PCRE. If you are just testing "ordinary" regular         nary"  regular  expressions,  you probably don't need any of these. The
219       expressions,  you probably don't need any of these. The fol-         following escapes are recognized:
220       lowing escapes are recognized:  
221             \a         alarm (= BEL)
222         \a         alarm (= BEL)           \b         backspace
223         \b         backspace           \e         escape
224         \e         escape           \f         formfeed
225         \f         formfeed           \n         newline
226         \n         newline           \r         carriage return
227         \r         carriage return           \t         tab
228         \t         tab           \v         vertical tab
229         \v         vertical tab           \nnn       octal character (up to 3 octal digits)
230         \nnn       octal character (up to 3 octal digits)           \xhh       hexadecimal character (up to 2 hex digits)
231         \xhh       hexadecimal character (up to 2 hex digits)           \x{hh...}  hexadecimal character, any number of digits
232         \x{hh...}  hexadecimal character, any number of digits                        in UTF-8 mode
233                      in UTF-8 mode           \A         pass the PCRE_ANCHORED option to pcre_exec()
234         \A         pass the PCRE_ANCHORED option to pcre_exec()           \B         pass the PCRE_NOTBOL option to pcre_exec()
235         \B         pass the PCRE_NOTBOL option to pcre_exec()           \Cdd       call pcre_copy_substring() for substring dd
236         \Cdd       call pcre_copy_substring() for substring dd                        after a successful match (any decimal number
237                      after a successful match (any decimal number                        less than 32)
238                      less than 32)           \Cname     call pcre_copy_named_substring() for substring
239         \Cname     call pcre_copy_named_substring() for substring                        "name" after a successful match (name termin-
240                          ated by next non alphanumeric character)
241                      "name" after a successful match (name termin-           \C+        show the current captured substrings at callout
242                      ated by next non alphanumeric character)                        time
243         \C+        show the current captured substrings at callout           \C-        do not supply a callout function
244                      time           \C!n       return 1 instead of 0 when callout number n is
245         \C-        do not supply a callout function                        reached
246         \C!n       return 1 instead of 0 when callout number n is           \C!n!m     return 1 instead of 0 when callout number n is
247                      reached                        reached for the nth time
248         \C!n!m     return 1 instead of 0 when callout number n is           \C*n       pass the number n (may be negative) as callout
249                      reached for the nth time                        data
250         \C*n       pass the number n (may be negative) as callout           \Gdd       call pcre_get_substring() for substring dd
251                      data                        after a successful match (any decimal number
252         \Gdd       call pcre_get_substring() for substring dd                        less than 32)
253                      after a successful match (any decimal number           \Gname     call pcre_get_named_substring() for substring
254                      less than 32)                        "name" after a successful match (name termin-
255         \Gname     call pcre_get_named_substring() for substring                        ated by next non-alphanumeric character)
256                      "name" after a successful match (name termin-           \L         call pcre_get_substringlist() after a
257                      ated by next non-alphanumeric character)                        successful match
258         \L         call pcre_get_substringlist() after a           \M         discover the minimum MATCH_LIMIT setting
259                      successful match           \N         pass the PCRE_NOTEMPTY option to pcre_exec()
260         \M         discover the minimum MATCH_LIMIT setting           \Odd       set the size of the output vector passed to
261         \N         pass the PCRE_NOTEMPTY option to pcre_exec()                        pcre_exec() to dd (any number of decimal
262         \Odd       set the size of the output vector passed to                        digits)
263                      pcre_exec() to dd (any number of decimal           \S         output details of memory get/free calls during matching
264                      digits)           \Z         pass the PCRE_NOTEOL option to pcre_exec()
265         \Z         pass the PCRE_NOTEOL option to pcre_exec()           \?         pass the PCRE_NO_UTF8_CHECK option to
266         \?         pass the PCRE_NO_UTF8_CHECK option to                        pcre_exec()
267                      pcre_exec()  
268           If \M is present, pcretest calls pcre_exec() several times,  with  dif-
269       If \M is present, pcretest calls pcre_exec() several  times,         ferent  values  in  the match_limit field of the pcre_extra data struc-
270       with  different  values  in  the  match_limit  field  of the         ture, until it finds the minimum number that is needed for  pcre_exec()
271       pcre_extra data structure, until it finds the minimum number         to  complete.  This  number is a measure of the amount of recursion and
272       that is needed for pcre_exec() to complete. This number is a         backtracking that takes place, and checking it out can be  instructive.
273       measure of the amount of  recursion  and  backtracking  that         For  most  simple  matches, the number is quite small, but for patterns
274       takes  place,  and  checking  it out can be instructive. For         with very large numbers of matching possibilities, it can become  large
275       most simple matches, the number is quite small, but for pat-         very quickly with increasing length of subject string.
276       terns  with very large numbers of matching possibilities, it  
277       can become large very quickly with increasing length of sub-         When  \O is used, it may be higher or lower than the size set by the -O
278       ject string.         option (or defaulted to 45); \O applies only to the call of pcre_exec()
279           for the line in which it appears.
280       When \O is used, it may be higher or lower than the size set  
281       by  the  -O  option (or defaulted to 45); \O applies only to         A  backslash  followed by anything else just escapes the anything else.
282       the call of pcre_exec() for the line in which it appears.         If the very last character is a backslash, it is ignored. This gives  a
283           way  of  passing  an empty line as data, since a real empty line termi-
284       A backslash followed by anything else just escapes the  any-         nates the data input.
285       thing else. If the very last character is a backslash, it is  
286       ignored. This gives a way of passing an empty line as  data,         If /P was present on the regex, causing the POSIX  wrapper  API  to  be
287       since a real empty line terminates the data input.         used,  only  0  causing  REG_NOTBOL  and  REG_NOTEOL  to  be  passed to
288           regexec() respectively.
289       If /P was present on the regex, causing  the  POSIX  wrapper  
290       API  to  be  used,  only  B,  and Z have any effect, causing         The use of \x{hh...} to represent UTF-8 characters is not dependent  on
291       REG_NOTBOL and REG_NOTEOL to be passed to regexec()  respec-         the  use  of  the  /8 modifier on the pattern. It is recognized always.
292       tively.         There may be any number of hexadecimal digits inside  the  braces.  The
293       The use of \x{hh...} to represent UTF-8  characters  is  not         result  is from one to six bytes, encoded according to the UTF-8 rules.
      dependent  on  the use of the /8 modifier on the pattern. It  
      is recognized always. There may be any number of hexadecimal  
      digits  inside  the  braces.  The  result is from one to six  
      bytes, encoded according to the UTF-8 rules.  
294    
295    
296  OUTPUT FROM PCRETEST  OUTPUT FROM PCRETEST
297    
298       When a match succeeds, pcretest outputs the list of captured         When a match succeeds, pcretest outputs the list of captured substrings
299       substrings  that pcre_exec() returns, starting with number 0         that  pcre_exec()  returns,  starting with number 0 for the string that
300       for the string that matched the whole pattern.  Here  is  an         matched the whole  pattern.  Here  is  an  example  of  an  interactive
301       example of an interactive pcretest run.         pcretest run.
302    
303         $ pcretest           $ pcretest
304         PCRE version 4.00 08-Jan-2003           PCRE version 4.00 08-Jan-2003
305    
306           re> /^abc(\d+)/             re> /^abc(\d+)/
307         data> abc123           data> abc123
308          0: abc123            0: abc123
309          1: 123            1: 123
310         data> xyz           data> xyz
311         No match           No match
312    
313       If the strings contain any non-printing characters, they are         If  the strings contain any non-printing characters, they are output as
314       output  as  \0x  escapes,  or  as  \x{...} escapes if the /8         \0x escapes, or as \x{...} escapes if the /8 modifier  was  present  on
315       modifier was present on the pattern. If the pattern has  the         the  pattern.  If  the pattern has the /+ modifier, then the output for
316       /+  modifier, then the output for substring 0 is followed by         substring 0 is followed by the the rest of the subject string,  identi-
317       the the rest of the subject string, identified by "0+"  like         fied by "0+" like this:
318       this:  
319               re> /cat/+
320           re> /cat/+           data> cataract
321         data> cataract            0: cat
322          0: cat            0+ aract
323          0+ aract  
324           If  the  pattern  has  the /g or /G modifier, the results of successive
325       If the pattern has the /g or /G  modifier,  the  results  of         matching attempts are output in sequence, like this:
326       successive  matching  attempts  are output in sequence, like  
327       this:             re> /\Bi(\w\w)/g
328             data> Mississippi
329           re> /\Bi(\w\w)/g            0: iss
330         data> Mississippi            1: ss
331          0: iss            0: iss
332          1: ss            1: ss
333          0: iss            0: ipp
334          1: ss            1: pp
335          0: ipp  
336          1: pp         "No match" is output only if the first match attempt fails.
337    
338       "No match" is output only if the first match attempt fails.         If any of the sequences \C, \G, or \L are present in a data  line  that
339           is  successfully  matched,  the substrings extracted by the convenience
340       If any of the sequences \C, \G, or \L are present in a  data         functions are output with C, G, or L after the string number instead of
341       line  that is successfully matched, the substrings extracted         a colon. This is in addition to the normal full list. The string length
342       by the convenience functions are output  with  C,  G,  or  L         (that is, the return from the extraction function) is given  in  paren-
343       after the string number instead of a colon. This is in addi-         theses after each string for \C and \G.
344       tion to the normal full list. The string  length  (that  is,  
345       the  return  from  the  extraction  function)  is  given  in         Note  that  while patterns can be continued over several lines (a plain
346       parentheses after each string for \C and \G.         ">" prompt is used for continuations), data lines may not. However new-
347           lines can be included in data by means of the \n escape.
      Note that while patterns can be continued over several lines  
      (a  plain  ">" prompt is used for continuations), data lines  
      may not. However newlines can be included in data  by  means  
      of the \n escape.  
348    
349    
350  AUTHOR  AUTHOR
351    
352       Philip Hazel <ph10@cam.ac.uk>         Philip Hazel <ph10@cam.ac.uk>
353       University Computing Service,         University Computing Service,
354       Cambridge CB2 3QG, England.         Cambridge CB2 3QG, England.
355    
356  Last updated: 20 August 2003  Last updated: 09 December 2003
357  Copyright (c) 1997-2003 University of Cambridge.  Copyright (c) 1997-2003 University of Cambridge.
Legend:
Removed from v.71  
changed lines
  Added in v.73
  ViewVC Help
Powered by ViewVC 1.1.5