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