MAN page from Fedora 1 pcre-4.4-1.x86_64.rpm


Section: User Commands (1)


pcretest - a program for testing Perl-compatible regular expressions. 


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

pcretest was written as a test program for the PCRE regular expressionlibrary itself, but it can also be used for experimenting with regularexpressions. This document describes the features of the test program; fordetails of the regular expressions themselves, see thepcrepatterndocumentation. For details of PCRE and its options, see thepcreapidocumentation.



Output the version number of the PCRE library, and all available informationabout the optional features that are included, and then exit.
Behave as if each regex had the /D modifier (see below); the internalform is output after compilation.
Behave as if each regex had the /I modifier; information about thecompiled pattern is given after compilation.
Output the size of each compiled pattern after it has been compiled. This isequivalent to adding /M to each regular expression. For compatibility withearlier 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 PCREto be osize. The default value is 45, which is enough for 14 capturingsubexpressions. The vector size can be changed for individual matching calls byincluding \O in the data line (see below).
Behave as if each regex has /P modifier; the POSIX wrapper API is usedto call PCRE. None of the other options has any effect when -p is set.
Run each compile, study, and match many times with a timer, and outputresulting 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 timingwill be distorted.



If pcretest is given two filename arguments, it reads from the first andwrites to the second. If it is given only one filename argument, it reads fromthat file and writes to stdout. Otherwise, it reads from stdin and writes tostdout, and prompts for each line of input, using "re>" to prompt for regularexpressions, and "data>" to prompt for data lines.

The program handles any number of sets of input on a single input file. Eachset starts with a regular expression, and continues with any number of datalines to be matched against the pattern.

Each line is matched separately and independently. If you want to domultiple-line matches, you have to use the \n escape sequence in a single lineof input to encode the newline characters. The maximum length of data line is30,000 characters.

An empty line signals the end of the data lines, at which point a new regularexpression is read. The regular expressions are given enclosed in anynon-alphameric delimiters other than backslash, for example


White space before the initial delimiter is ignored. A regular expression maybe continued over several input lines, in which case the newline characters areincluded within it. It is possible to include the delimiter within the patternby escaping it, for example


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


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


is interpreted as the first line of a pattern that starts with "abc/", causingpcretest to read the next line as a continuation of the regular expression.



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


These modifier letters have the same effect as they do in Perl. There areothers that set PCRE options that do not correspond to anything in Perl:/A, /E, /N, /U, and /X set PCRE_ANCHORED,PCRE_DOLLAR_ENDONLY, PCRE_NO_AUTO_CAPTURE, PCRE_UNGREEDY, and PCRE_EXTRArespectively.

Searching for all possible matches within each subject string can be requestedby the /g or /G modifier. After finding a match, PCRE is calledagain to search the remainder of the subject string. The difference between/g and /G is that the former uses the startoffset argument topcre_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 shortenedsubstring. This makes a difference to the matching process if the patternbegins with a lookbehind assertion (including \b or \B).

If any call to pcre_exec() in a /g or /G sequence matches anempty string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHOREDflags set in order to search for another, non-empty, match at the same point.If this second match fails, the start offset is advanced by one, and the normalmatch is retried. This imitates the way Perl handles such cases when using the/g modifier or the split() function.

There are a number of other modifiers for controlling the way pcretestoperates.

The /+ modifier requests that as well as outputting the substring thatmatched the entire pattern, pcretest should in addition output the remainder ofthe subject string. This is useful for tests where the subject containsmultiple copies of the same substring.

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


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 thelocale, and this is then passed to pcre_compile() when compiling theregular expression. Without an /L modifier, NULL is passed as the tablespointer; that is, /L applies only to the expression on which it appears.

The /I modifier requests that pcretest output information about thecompiled expression (whether it is anchored, has a fixed first character, andso on). It does this by calling pcre_fullinfo() after compiling anexpression, and outputting the information it gets back. If the pattern isstudied, 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 regular expressions to be output aftercompilation. If the pattern was studied, the information returned is alsooutput.

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

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

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

The /8 modifier causes pcretest to call PCRE with the PCRE_UTF8option set. This turns on support for UTF-8 character handling in PCRE,provided that it was compiled with this support enabled. This modifier alsocauses 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 tocall pcre_compile() with the PCRE_NO_UTF8_CHECK option, to suppress thechecking of the string for UTF-8 validity.



If the pattern contains any callout requests, pcretest's callout functionwill be called. By default, it displays the callout number, and the start andcurrent positions in the text at the callout time. For example, the output

    0    ^  ^

indicates that callout number 0 occurred for a match attempt starting at thefourth character of the subject string, when the pointer was at the seventhcharacter. The callout function returns zero (carry on matching) by default.

Inserting callouts may be helpful when using pcretest to checkcomplicated regular expressions. For further information about callouts, seethepcrecalloutdocumentation.

For testing the PCRE library, additional control of callout behaviour isavailable via escape sequences in the data, as described in the followingsection. In particular, it is possible to pass in a number as callout data (thedefault is zero). If the callout function receives a non-zero number, itreturns that value instead of zero.



Before each data line is passed to pcre_exec(), leading and trailingwhitespace is removed, and it is then scanned for \ escapes. Some of these arepretty esoteric features, intended for checking out some of the morecomplicated features of PCRE. If you are just testing "ordinary" regularexpressions, you probably don't need any of these. The following escapes arerecognized:

  \a         alarm (= BEL)
  \b         backspace
  \e         escape
  \f         formfeed
  \n         newline
  \r         carriage return
  \t         tab
  \v         vertical tab
  \nnn       octal character (up to 3 octal digits)
  \xhh       hexadecimal character (up to 2 hex digits)
  \x{hh...}  hexadecimal character, any number of digits
               in UTF-8 mode
  \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 number
               less than 32)
  \Cname     call pcre_copy_named_substring() for substring
               "name" after a successful match (name termin-
               ated by next non alphanumeric character)
  \C+        show the current captured substrings at callout
  \C-        do not supply a callout function
  \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
               reached for the nth time
  \C*n       pass the number n (may be negative) as callout
  \Gdd       call pcre_get_substring() for substring dd
               after a successful match (any decimal number
               less than 32)
  \Gname     call pcre_get_named_substring() for substring
               "name" after a successful match (name termin-
               ated by next non-alphanumeric character)
  \L         call pcre_get_substringlist() after a
               successful match
  \M         discover the minimum MATCH_LIMIT setting
  \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
  \Z         pass the PCRE_NOTEOL option to pcre_exec()
  \?         pass the PCRE_NO_UTF8_CHECK option to

If \M is present, pcretest calls pcre_exec() several times, withdifferent values in the match_limit field of the pcre_extra datastructure, until it finds the minimum number that is needed forpcre_exec() to complete. This number is a measure of the amount ofrecursion and backtracking that takes place, and checking it out can beinstructive. For most simple matches, the number is quite small, but forpatterns with very large numbers of matching possibilities, it can become largevery quickly with increasing length of subject string.

When \O is used, it may be higher or lower than the size set by the -Ooption (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 thevery last character is a backslash, it is ignored. This gives a way of passingan 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 B, and Z have any effect, causing REG_NOTBOL and REG_NOTEOLto be passed to regexec() respectively.

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



When a match succeeds, pcretest outputs the list of captured substrings thatpcre_exec() returns, starting with number 0 for the string that matchedthe whole pattern. Here is an example of an interactive pcretest run.

  $ pcretest
  PCRE version 4.00 08-Jan-2003

    re> /^abc(\d+)/
  data> abc123
   0: abc123
   1: 123
  data> xyz
  No match

If the strings contain any non-printing characters, they are output as \0xescapes, or as \x{...} escapes if the /8 modifier was present on thepattern. If the pattern has the /+ modifier, then the output forsubstring 0 is followed 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 successivematching 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 adata line that is successfully matched, the substrings extracted by theconvenience functions are output with C, G, or L after the string numberinstead of a colon. This is in addition to the normal full list. The stringlength (that is, the return from the extraction function) is given inparentheses 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 beincluded in data by means of the \n escape.



Philip Hazel <>
University Computing Service,
Cambridge CB2 3QG, England.

Last updated: 20 August 2003
Copyright (c) 1997-2003 University of Cambridge.




This document was created byman2html,using the manual pages.