SYNOPSIS

       pcretest [-d] [-i] [-m]  [-o  osize]  [-p]  [-t]  [source]
       [destination]

       pcretest  was written as a test program for the PCRE regu­
       lar expression library itself, but it can also be used for
       experimenting  with  regular  expressions.  This  man page
       describes the features of the test program; for details of
       the regular expressions themselves, see the pcre man page.



OPTIONS

       -d        Behave as if each regex had the /D modifier (see
                 below); the internal form is output after compi­
                 lation.

       -i        Behave as if each regex  had  the  /I  modifier;
                 information  about the compiled pattern is given
                 after compilation.

       -m        Output the size of each compiled  pattern  after
                 it  has  been  compiled.  This  is equivalent to
                 adding /M to each regular expression.  For  com­
                 patibility with earlier versions of pcretest, -s
                 is a synonym for -m.

       -o osize  Set the number of elements in the output  vector
                 that  is used when calling PCRE to be osize. The
                 default value is 45, which is enough for 14 cap­
                 turing  subexpressions.  The  vector size can be
                 changed for individual matching calls by includ­
                 ing \O in the data line (see below).

       -p        Behave  as  if  each  regex has /P modifier; the
                 POSIX wrapper API is used to call PCRE. None  of
                 the other options has any effect when -p is set.

       -t        Run each compile, study, and match  20000  times
                 with a timer, and output resulting time per com­
                 pile or match (in milliseconds). Do not  set  -t
                 with -m, because you will then get the size out­
                 put 20000 times and  the  timing  will  be  dis­
                 torted.




DESCRIPTION

       If pcretest is given two filename arguments, it reads from
       the first and writes to the second. If it  is  given  only
       one  filename argument, it reads from that file and writes
       to stdout. Otherwise, it reads from stdin  and  writes  to

       White space before the initial  delimiter  is  ignored.  A
       regular  expression  may  be  continued over several input
       lines, in which case the newline characters  are  included
       within  it. It is possible to include the delimiter within
       the pattern by escaping it, for example

         /abc\/def/

       If you do so, the escape and the delimiter  form  part  of
       the   pattern,   but  since  delimiters  are  always  non-
       alphameric, this does not affect its  interpretation.   If
       the  terminating  delimiter  is  immediately followed by a
       backslash, for example,

         /abc/\

       then a backslash is added to the end of the pattern.  This
       is  done  to  provide a way of testing the error condition
       that arises  if  a  pattern  finishes  with  a  backslash,
       because

         /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.




PATTERN MODIFIERS

       The  pattern  may  be followed by i, m, s, or x to set the
       PCRE_CASELESS,     PCRE_MULTILINE,     PCRE_DOTALL,     or
       PCRE_EXTENDED options, respectively. For example:

         /caseless/i

       These  modifier letters have the same effect as they do in
       Perl. There are others which set PCRE options that do  not
       correspond  to  anything  in  Perl:  /A,  /E,  and  /X set
       PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, and PCRE_EXTRA respec­
       tively.

       Searching  for  all  possible  matches within each subject
       string can be requested by the /g or  /G  modifier.  After
       finding  a  match,  PCRE  is  called  again  to search the
       remainder of the subject string. The difference between /g
       and /G is that the former uses the startoffset argument to
       pcre_exec() to start searching at a new point  within  the
       entire string (which is in effect what Perl does), whereas
       the latter passes over a shortened substring. This makes a
       difference  to  the matching process if the pattern begins
       The /+ modifier requests that as well  as  outputting  the
       substring that matched the entire pattern, pcretest should
       in addition output the remainder of  the  subject  string.
       This is useful for tests where the subject contains multi­
       ple copies of the same substring.

       The /L modifier must be followed directly by the name of a
       locale, for example,

         /pattern/Lfr

       For  this reason, it must be the last modifier letter. The
       given locale is set, pcre_maketables() is called to  build
       a set of character tables for the locale, and this is then
       passed  to  pcre_compile()  when  compiling  the   regular
       expression.  Without an /L modifier, NULL is passed as the
       tables pointer; that is, /L applies only to the expression
       on which it appears.

       The  /I modifier requests that pcretest output information
       about the compiled expression (whether it is anchored, has
       a fixed first character, and so on). It does this by call­
       ing pcre_fullinfo() after  compiling  an  expression,  and
       outputting the information it gets back. If the pattern is
       studied, the results of that are also output.

       The /D modifier is a PCRE debugging  feature,  which  also
       assumes /I.  It causes the internal form of compiled regu­
       lar expressions to be output after compilation.

       The /S modifier causes pcre_study() to be called after the
       expression  has  been  compiled, and the results used when
       the expression is matched.

       The /M modifier causes the size of memory  block  used  to
       hold the compiled pattern to be output.

       The /P modifier causes pcretest to call PCRE via the POSIX
       wrapper API rather than its native API. When this is done,
       all  other  modifiers  except  /i, /m, and /+ are ignored.
       REG_ICASE is set if /i is present, and REG_NEWLINE is  set
       if  /m  is  present. The wrapper functions force PCRE_DOL­
       LAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE  is
       set.

       The  /8  modifier  causes  pcretest  to call PCRE with the
       PCRE_UTF8 option set. This turns on the (currently  incom­
       plete)  support for UTF-8 character handling in PCRE, pro­
       vided 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.
         \t         tab
         \v         vertical tab
         \nnn       octal character (up to 3 octal digits)
         \xhh       hexadecimal character (up to 2 hex digits)
         \x{hh...}  hexadecimal UTF-8 character

         \A         pass the PCRE_ANCHORED option to pcre_exec()
         \B         pass the PCRE_NOTBOL option to pcre_exec()
         \Cdd       call pcre_copy_substring() for substring dd
                       after a successful match (any decimal num­
       ber
                       less than 32)
         \Gdd       call pcre_get_substring() for substring dd
                       after a successful match (any decimal num­
       ber
                       less than 32)
         \L         call pcre_get_substringlist() after a
                       successful match
         \N         pass the PCRE_NOTEMPTY option to pcre_exec()
         \Odd       set the size of the output vector passed to
                       pcre_exec() to dd (any number of decimal
                       digits)
         \Z         pass the PCRE_NOTEOL option to pcre_exec()

       When  \O  is used, it may be higher or lower than the size
       set by the -O option (or defaulted to 45); \O applies only
       to  the  call  of  pcre_exec()  for  the  line in which it
       appears.

       A backslash followed by anything  else  just  escapes  the
       anything  else. If the very last character is a backslash,
       it is ignored. This gives a way of passing an  empty  line
       as  data,  since  a  real  empty  line terminates the data
       input.

       If /P was present on the regex, causing the POSIX  wrapper
       API  to  be used, only 0 causing REG_NOTBOL and REG_NOTEOL
       to be passed to regexec() respectively.

       The use of \x{hh...} to represent UTF-8 characters is  not
       dependent on the use of the /8 modifier on the pattern. It
       is recognized always. There may be any number of hexadeci­
       mal  digits  inside  the braces. The result is from one to
       six bytes, encoded according to the UTF-8 rules.




OUTPUT FROM PCRETEST

       When a match succeeds, pcretest outputs the list  of  cap­
       tured  substrings  that pcre_exec() returns, starting with
       number 0 for the string that matched  the  whole  pattern.
       Here is an example of an interactive pcretest run.
       the /+ modifier, then the output for substring 0  is  fol­
       lowed by the the rest of the subject string, identified by
       "0+" like this:

           re> /cat/+
         data> cataract
          0: cat
          0+ aract

       If the pattern has the /g or /G modifier, the  results  of
       successive  matching attempts are output in sequence, like
       this:

           re> /\Bi(\w\w)/g
         data> Mississippi
          0: iss
          1: ss
          0: iss
          1: ss
          0: ipp
          1: pp

       "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 is  successfully  matched,  the  substrings
       extracted  by the convenience functions are output with C,
       G, or L after the string number instead of a  colon.  This
       is  in addition to the normal full list. The string length
       (that is, the return  from  the  extraction  function)  is
       given in parentheses after each string for \C and \G.

       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.




AUTHOR

       Philip Hazel <ph10@cam.ac.uk>
       University Computing Service,
       New Museums Site,
       Cambridge CB2 3QG, England.
       Phone: +44 1223 334714

       Last updated: 15 August 2001
       Copyright (c) 1997-2001 University of Cambridge.




Man(1) output converted with man2html