Annotation of embedaddon/pcre/doc/pcretest.txt, revision 1.1.1.4

1.1.1.4 ! misho       1: PCRETEST(1)                 General Commands Manual                PCRETEST(1)
        !             2: 
1.1       misho       3: 
                      4: 
                      5: NAME
                      6:        pcretest - a program for testing Perl-compatible regular expressions.
                      7: 
                      8: SYNOPSIS
                      9: 
                     10:        pcretest [options] [input file [output file]]
                     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
1.1.1.4 ! misho      17:        options, see the pcreapi , pcre16 and pcre32 documentation.
        !            18: 
        !            19:        The input for pcretest is a sequence of regular expression patterns and
        !            20:        strings  to be matched, as described below. The output shows the result
        !            21:        of each match. Options on the command line  and  the  patterns  control
        !            22:        PCRE options and exactly what is output.
        !            23: 
        !            24:        As  PCRE has evolved, it has acquired many different features, and as a
        !            25:        result, pcretest now has rather a lot of obscure  options  for  testing
        !            26:        every possible feature. Some of these options are specifically designed
        !            27:        for use in conjunction with the test script and  data  files  that  are
        !            28:        distributed  as  part of PCRE, and are unlikely to be of use otherwise.
        !            29:        They are all documented here, but without much justification.
        !            30: 
        !            31: 
        !            32: INPUT DATA FORMAT
1.1.1.2   misho      33: 
1.1.1.4 ! misho      34:        Input to pcretest is processed line by line, either by  calling  the  C
        !            35:        library's fgets() function, or via the libreadline library (see below).
        !            36:        In Unix-like environments, fgets() treats any bytes other than  newline
        !            37:        as  data characters. However, in some Windows environments character 26
        !            38:        (hex 1A) causes an immediate end of file, and no further data is  read.
        !            39:        For  maximum  portability,  therefore,  it  is safest to use only ASCII
        !            40:        characters in pcretest input files.
1.1.1.2   misho      41: 
1.1.1.4 ! misho      42: 
        !            43: PCRE's 8-BIT, 16-BIT AND 32-BIT LIBRARIES
1.1.1.2   misho      44: 
                     45:        From release 8.30, two separate PCRE libraries can be built. The origi-
                     46:        nal  one  supports  8-bit  character  strings, whereas the newer 16-bit
1.1.1.4 ! misho      47:        library supports  character  strings  encoded  in  16-bit  units.  From
        !            48:        release  8.32,  a  third  library  can  be  built, supporting character
        !            49:        strings encoded in 32-bit units. The pcretest program can  be  used  to
        !            50:        test all three libraries. However, it is itself still an 8-bit program,
        !            51:        reading 8-bit input and writing 8-bit output.  When testing the  16-bit
        !            52:        or  32-bit  library, the patterns and data strings are converted to 16-
        !            53:        or 32-bit format before being passed to  the  PCRE  library  functions.
        !            54:        Results are converted to 8-bit for output.
        !            55: 
        !            56:        References to functions and structures of the form pcre[16|32]_xx below
        !            57:        mean "pcre_xx when using the 8-bit library, pcre16_xx  when  using  the
        !            58:        16-bit library, or pcre32_xx when using the 32-bit library".
1.1       misho      59: 
                     60: 
                     61: COMMAND LINE OPTIONS
                     62: 
1.1.1.4 ! misho      63:        -8        If  both the 8-bit library has been built, this option causes
        !            64:                  the 8-bit library to be used (which is the default);  if  the
        !            65:                  8-bit  library  has  not  been  built,  this option causes an
        !            66:                  error.
        !            67: 
        !            68:        -16       If both the 8-bit or the 32-bit,  and  the  16-bit  libraries
        !            69:                  have  been built, this option causes the 16-bit library to be
        !            70:                  used. If only the 16-bit library has been built, this is  the
        !            71:                  default  (so  has no effect). If only the 8-bit or the 32-bit
        !            72:                  library has been built, this option causes an error.
        !            73: 
        !            74:        -32       If both the 8-bit or the 16-bit,  and  the  32-bit  libraries
        !            75:                  have  been built, this option causes the 32-bit library to be
        !            76:                  used. If only the 32-bit library has been built, this is  the
        !            77:                  default  (so  has no effect). If only the 8-bit or the 16-bit
        !            78:                  library has been built, this option causes an error.
1.1.1.2   misho      79: 
1.1.1.4 ! misho      80:        -b        Behave as if each pattern has the /B (show byte  code)  modi-
1.1       misho      81:                  fier; the internal form is output after compilation.
                     82: 
                     83:        -C        Output the version number of the PCRE library, and all avail-
1.1.1.4 ! misho      84:                  able  information  about  the  optional  features  that   are
        !            85:                  included,  and  then  exit  with  zero  exit  code. All other
        !            86:                  options are ignored.
1.1.1.2   misho      87: 
                     88:        -C option Output information about a specific build-time  option,  then
                     89:                  exit.  This functionality is intended for use in scripts such
1.1.1.4 ! misho      90:                  as RunTest. The following options output the  value  and  set
        !            91:                  the exit code as indicated:
1.1.1.2   misho      92: 
1.1.1.4 ! misho      93:                    ebcdic-nl  the code for LF (= NL) in an EBCDIC environment:
        !            94:                                 0x15 or 0x25
        !            95:                                 0 if used in an ASCII environment
        !            96:                                 exit code is always 0
        !            97:                    linksize   the configured internal link size (2, 3, or 4)
        !            98:                                 exit code is set to the link size
1.1.1.2   misho      99:                    newline    the default newline setting:
                    100:                                 CR, LF, CRLF, ANYCRLF, or ANY
1.1.1.4 ! misho     101:                                 exit code is always 0
1.1.1.2   misho     102: 
1.1.1.4 ! misho     103:                  The  following  options output 1 for true or 0 for false, and
        !           104:                  set the exit code to the same value:
1.1.1.2   misho     105: 
1.1.1.4 ! misho     106:                    ebcdic     compiled for an EBCDIC environment
1.1.1.2   misho     107:                    jit        just-in-time support is available
                    108:                    pcre16     the 16-bit library was built
1.1.1.4 ! misho     109:                    pcre32     the 32-bit library was built
1.1.1.2   misho     110:                    pcre8      the 8-bit library was built
                    111:                    ucp        Unicode property support is available
1.1.1.4 ! misho     112:                    utf        UTF-8 and/or UTF-16 and/or UTF-32 support
        !           113:                                 is available
        !           114: 
        !           115:                  If an unknown option is given, an error  message  is  output;
        !           116:                  the exit code is 0.
1.1       misho     117: 
1.1.1.4 ! misho     118:        -d        Behave  as  if  each pattern has the /D (debug) modifier; the
        !           119:                  internal form and information about the compiled  pattern  is
1.1       misho     120:                  output after compilation; -d is equivalent to -b -i.
                    121: 
1.1.1.4 ! misho     122:        -dfa      Behave  as if each data line contains the \D escape sequence;
1.1       misho     123:                  this    causes    the    alternative    matching    function,
1.1.1.4 ! misho     124:                  pcre[16|32]_dfa_exec(),  to  be  used instead of the standard
        !           125:                  pcre[16|32]_exec() function (more detail is given below).
1.1       misho     126: 
                    127:        -help     Output a brief summary these options and then exit.
                    128: 
1.1.1.4 ! misho     129:        -i        Behave as if each pattern has the  /I  modifier;  information
1.1       misho     130:                  about the compiled pattern is given after compilation.
                    131: 
1.1.1.4 ! misho     132:        -M        Behave  as if each data line contains the \M escape sequence;
        !           133:                  this causes PCRE to  discover  the  minimum  MATCH_LIMIT  and
        !           134:                  MATCH_LIMIT_RECURSION  settings by calling pcre[16|32]_exec()
1.1.1.2   misho     135:                  repeatedly with different limits.
                    136: 
1.1.1.4 ! misho     137:        -m        Output the size of each compiled pattern after  it  has  been
        !           138:                  compiled.  This  is  equivalent  to adding /M to each regular
1.1.1.2   misho     139:                  expression. The size is given in bytes for both libraries.
                    140: 
1.1.1.4 ! misho     141:        -o osize  Set the number of elements in the output vector that is  used
        !           142:                  when  calling pcre[16|32]_exec() or pcre[16|32]_dfa_exec() to
        !           143:                  be osize. The default value is 45, which  is  enough  for  14
        !           144:                  capturing subexpressions for pcre[16|32]_exec() or 22 differ-
        !           145:                  ent matches for pcre[16|32]_dfa_exec().  The vector size  can
        !           146:                  be  changed  for individual matching calls by including \O in
        !           147:                  the data line (see below).
        !           148: 
        !           149:        -p        Behave as if each pattern has  the  /P  modifier;  the  POSIX
        !           150:                  wrapper  API  is used to call PCRE. None of the other options
        !           151:                  has any effect when -p is set. This option can be  used  only
1.1.1.2   misho     152:                  with the 8-bit library.
1.1       misho     153: 
1.1.1.4 ! misho     154:        -q        Do  not output the version number of pcretest at the start of
1.1       misho     155:                  execution.
                    156: 
1.1.1.4 ! misho     157:        -S size   On Unix-like systems, set the size of the run-time  stack  to
1.1       misho     158:                  size megabytes.
                    159: 
1.1.1.4 ! misho     160:        -s or -s+ Behave  as  if  each  pattern  has  the /S modifier; in other
        !           161:                  words, force each pattern to be studied. If -s+ is used,  all
        !           162:                  the  JIT  compile  options are passed to pcre[16|32]_study(),
        !           163:                  causing just-in-time optimization to  be  set  up  if  it  is
        !           164:                  available,  for  both full and partial matching. Specific JIT
        !           165:                  compile options can be selected by following -s+ with a digit
        !           166:                  in  the  range 1 to 7, which selects the JIT compile modes as
        !           167:                  follows:
1.1.1.3   misho     168: 
                    169:                    1  normal match only
                    170:                    2  soft partial match only
                    171:                    3  normal match and soft partial match
                    172:                    4  hard partial match only
                    173:                    6  soft and hard partial match
                    174:                    7  all three modes (default)
                    175: 
1.1.1.4 ! misho     176:                  If -s++ is used instead of -s+ (with or without  a  following
        !           177:                  digit),  the  text  "(JIT)" is added to the first output line
1.1.1.3   misho     178:                  after a match or no match when JIT-compiled code was actually
                    179:                  used.
                    180: 
1.1.1.4 ! misho     181:                  Note  that  there  are  pattern options that can override -s,
        !           182:                  either specifying no studying at all, or suppressing JIT com-
        !           183:                  pilation.
        !           184: 
        !           185:                  If  the  /I  or /D option is present on a pattern (requesting
        !           186:                  output about the compiled  pattern),  information  about  the
        !           187:                  result  of  studying  is not included when studying is caused
        !           188:                  only by -s and neither -i nor -d is present  on  the  command
        !           189:                  line.  This  behaviour  means that the output from tests that
        !           190:                  are run with and without -s should be identical, except  when
        !           191:                  options that output information about the actual running of a
        !           192:                  match are set.
        !           193: 
        !           194:                  The -M, -t, and -tm options,  which  give  information  about
        !           195:                  resources  used,  are likely to produce different output with
        !           196:                  and without -s. Output may also differ if the  /C  option  is
        !           197:                  present on an individual pattern. This uses callouts to trace
        !           198:                  the the matching process, and this may be  different  between
        !           199:                  studied  and  non-studied  patterns.  If the pattern contains
        !           200:                  (*MARK) items there may also be  differences,  for  the  same
        !           201:                  reason. The -s command line option can be overridden for spe-
        !           202:                  cific patterns that should never be studied (see the /S  pat-
        !           203:                  tern modifier below).
1.1.1.3   misho     204: 
                    205:        -t        Run  each  compile, study, and match many times with a timer,
                    206:                  and output resulting time per compile or match (in  millisec-
                    207:                  onds).  Do  not set -m with -t, because you will then get the
                    208:                  size output a zillion times, and  the  timing  will  be  dis-
                    209:                  torted.  You  can  control  the number of iterations that are
                    210:                  used for timing by following -t with a number (as a  separate
1.1       misho     211:                  item on the command line). For example, "-t 1000" would iter-
                    212:                  ate 1000 times. The default is to iterate 500000 times.
                    213: 
                    214:        -tm       This is like -t except that it times only the matching phase,
                    215:                  not the compile or study phases.
                    216: 
                    217: 
                    218: DESCRIPTION
                    219: 
1.1.1.3   misho     220:        If  pcretest  is  given two filename arguments, it reads from the first
1.1       misho     221:        and writes to the second. If it is given only one filename argument, it
1.1.1.3   misho     222:        reads  from  that  file  and writes to stdout. Otherwise, it reads from
                    223:        stdin and writes to stdout, and prompts for each line of  input,  using
1.1       misho     224:        "re>" to prompt for regular expressions, and "data>" to prompt for data
                    225:        lines.
                    226: 
1.1.1.3   misho     227:        When pcretest is built, a configuration  option  can  specify  that  it
                    228:        should  be  linked  with the libreadline library. When this is done, if
1.1       misho     229:        the input is from a terminal, it is read using the readline() function.
1.1.1.3   misho     230:        This  provides line-editing and history facilities. The output from the
1.1       misho     231:        -help option states whether or not readline() will be used.
                    232: 
                    233:        The program handles any number of sets of input on a single input file.
1.1.1.3   misho     234:        Each  set starts with a regular expression, and continues with any num-
1.1       misho     235:        ber of data lines to be matched against the pattern.
                    236: 
1.1.1.3   misho     237:        Each data line is matched separately and independently. If you want  to
1.1       misho     238:        do multi-line matches, you have to use the \n escape sequence (or \r or
                    239:        \r\n, etc., depending on the newline setting) in a single line of input
1.1.1.3   misho     240:        to  encode  the  newline  sequences. There is no limit on the length of
                    241:        data lines; the input buffer is automatically extended  if  it  is  too
1.1       misho     242:        small.
                    243: 
1.1.1.3   misho     244:        An  empty  line signals the end of the data lines, at which point a new
                    245:        regular expression is read. The regular expressions are given  enclosed
1.1       misho     246:        in any non-alphanumeric delimiters other than backslash, for example:
                    247: 
                    248:          /(a|bc)x+yz/
                    249: 
1.1.1.3   misho     250:        White  space before the initial delimiter is ignored. A regular expres-
                    251:        sion may be continued over several input lines, in which case the  new-
                    252:        line  characters  are included within it. It is possible to include the
1.1       misho     253:        delimiter within the pattern by escaping it, for example
                    254: 
                    255:          /abc\/def/
                    256: 
1.1.1.3   misho     257:        If you do so, the escape and the delimiter form part  of  the  pattern,
                    258:        but  since delimiters are always non-alphanumeric, this does not affect
                    259:        its interpretation.  If the terminating delimiter is  immediately  fol-
1.1       misho     260:        lowed by a backslash, for example,
                    261: 
                    262:          /abc/\
                    263: 
1.1.1.3   misho     264:        then  a  backslash  is added to the end of the pattern. This is done to
                    265:        provide a way of testing the error condition that arises if  a  pattern
1.1       misho     266:        finishes with a backslash, because
                    267: 
                    268:          /abc\/
                    269: 
1.1.1.3   misho     270:        is  interpreted as the first line of a pattern that starts with "abc/",
1.1       misho     271:        causing pcretest to read the next line as a continuation of the regular
                    272:        expression.
                    273: 
                    274: 
                    275: PATTERN MODIFIERS
                    276: 
1.1.1.3   misho     277:        A  pattern may be followed by any number of modifiers, which are mostly
1.1.1.4 ! misho     278:        single characters, though some of these can  be  qualified  by  further
        !           279:        characters.   Following Perl usage, these are referred to below as, for
        !           280:        example, "the /i modifier", even though the delimiter  of  the  pattern
        !           281:        need  not  always  be  a slash, and no slash is used when writing modi-
        !           282:        fiers. White space may appear between the final pattern  delimiter  and
        !           283:        the  first  modifier,  and between the modifiers themselves. For refer-
        !           284:        ence, here is a complete list of  modifiers.  They  fall  into  several
        !           285:        groups that are described in detail in the following sections.
        !           286: 
        !           287:          /8              set UTF mode
        !           288:          /9              set PCRE_NEVER_UTF (locks out UTF mode)
        !           289:          /?              disable UTF validity check
        !           290:          /+              show remainder of subject after match
        !           291:          /=              show all captures (not just those that are set)
        !           292: 
        !           293:          /A              set PCRE_ANCHORED
        !           294:          /B              show compiled code
        !           295:          /C              set PCRE_AUTO_CALLOUT
        !           296:          /D              same as /B plus /I
        !           297:          /E              set PCRE_DOLLAR_ENDONLY
        !           298:          /F              flip byte order in compiled pattern
        !           299:          /f              set PCRE_FIRSTLINE
        !           300:          /G              find all matches (shorten string)
        !           301:          /g              find all matches (use startoffset)
        !           302:          /I              show information about pattern
        !           303:          /i              set PCRE_CASELESS
        !           304:          /J              set PCRE_DUPNAMES
        !           305:          /K              show backtracking control names
        !           306:          /L              set locale
        !           307:          /M              show compiled memory size
        !           308:          /m              set PCRE_MULTILINE
        !           309:          /N              set PCRE_NO_AUTO_CAPTURE
        !           310:          /P              use the POSIX wrapper
        !           311:          /S              study the pattern after compilation
        !           312:          /s              set PCRE_DOTALL
        !           313:          /T              select character tables
        !           314:          /U              set PCRE_UNGREEDY
        !           315:          /W              set PCRE_UCP
        !           316:          /X              set PCRE_EXTRA
        !           317:          /x              set PCRE_EXTENDED
        !           318:          /Y              set PCRE_NO_START_OPTIMIZE
        !           319:          /Z              don't show lengths in /B output
        !           320: 
        !           321:          /<any>          set PCRE_NEWLINE_ANY
        !           322:          /<anycrlf>      set PCRE_NEWLINE_ANYCRLF
        !           323:          /<cr>           set PCRE_NEWLINE_CR
        !           324:          /<crlf>         set PCRE_NEWLINE_CRLF
        !           325:          /<lf>           set PCRE_NEWLINE_LF
        !           326:          /<bsr_anycrlf>  set PCRE_BSR_ANYCRLF
        !           327:          /<bsr_unicode>  set PCRE_BSR_UNICODE
        !           328:          /<JS>           set PCRE_JAVASCRIPT_COMPAT
        !           329: 
        !           330: 
        !           331:    Perl-compatible modifiers
1.1       misho     332: 
                    333:        The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE,
1.1.1.4 ! misho     334:        PCRE_DOTALL,   or    PCRE_EXTENDED    options,    respectively,    when
        !           335:        pcre[16|32]_compile()  is  called. These four modifier letters have the
        !           336:        same effect as they do in Perl. For example:
1.1       misho     337: 
                    338:          /caseless/i
                    339: 
1.1.1.4 ! misho     340: 
        !           341:    Modifiers for other PCRE options
        !           342: 
        !           343:        The following table shows additional modifiers for  setting  PCRE  com-
1.1       misho     344:        pile-time options that do not correspond to anything in Perl:
                    345: 
1.1.1.2   misho     346:          /8              PCRE_UTF8           ) when using the 8-bit
                    347:          /?              PCRE_NO_UTF8_CHECK  )   library
                    348: 
                    349:          /8              PCRE_UTF16          ) when using the 16-bit
                    350:          /?              PCRE_NO_UTF16_CHECK )   library
                    351: 
1.1.1.4 ! misho     352:          /8              PCRE_UTF32          ) when using the 32-bit
        !           353:          /?              PCRE_NO_UTF32_CHECK )   library
        !           354: 
        !           355:          /9              PCRE_NEVER_UTF
1.1       misho     356:          /A              PCRE_ANCHORED
                    357:          /C              PCRE_AUTO_CALLOUT
                    358:          /E              PCRE_DOLLAR_ENDONLY
                    359:          /f              PCRE_FIRSTLINE
                    360:          /J              PCRE_DUPNAMES
                    361:          /N              PCRE_NO_AUTO_CAPTURE
                    362:          /U              PCRE_UNGREEDY
                    363:          /W              PCRE_UCP
                    364:          /X              PCRE_EXTRA
                    365:          /Y              PCRE_NO_START_OPTIMIZE
1.1.1.4 ! misho     366:          /<any>          PCRE_NEWLINE_ANY
        !           367:          /<anycrlf>      PCRE_NEWLINE_ANYCRLF
1.1       misho     368:          /<cr>           PCRE_NEWLINE_CR
                    369:          /<crlf>         PCRE_NEWLINE_CRLF
1.1.1.4 ! misho     370:          /<lf>           PCRE_NEWLINE_LF
1.1       misho     371:          /<bsr_anycrlf>  PCRE_BSR_ANYCRLF
                    372:          /<bsr_unicode>  PCRE_BSR_UNICODE
1.1.1.4 ! misho     373:          /<JS>           PCRE_JAVASCRIPT_COMPAT
1.1       misho     374: 
1.1.1.4 ! misho     375:        The  modifiers  that are enclosed in angle brackets are literal strings
        !           376:        as shown, including the angle brackets, but the letters within  can  be
        !           377:        in  either case.  This example sets multiline matching with CRLF as the
1.1       misho     378:        line ending sequence:
                    379: 
                    380:          /^abc/m<CRLF>
                    381: 
1.1.1.4 ! misho     382:        As well as turning on  the  PCRE_UTF8/16/32  option,  the  /8  modifier
        !           383:        causes  all  non-printing  characters  in  output strings to be printed
        !           384:        using the \x{hh...} notation. Otherwise, those less than 0x100 are out-
        !           385:        put in hex without the curly brackets.
1.1.1.2   misho     386: 
1.1.1.4 ! misho     387:        Full  details  of  the PCRE options are given in the pcreapi documenta-
1.1.1.2   misho     388:        tion.
1.1       misho     389: 
                    390:    Finding all matches in a string
                    391: 
1.1.1.4 ! misho     392:        Searching for all possible matches within each subject  string  can  be
        !           393:        requested  by  the  /g  or  /G modifier. After finding a match, PCRE is
1.1       misho     394:        called again to search the remainder of the subject string. The differ-
                    395:        ence between /g and /G is that the former uses the startoffset argument
1.1.1.4 ! misho     396:        to pcre[16|32]_exec() to start searching at  a  new  point  within  the
        !           397:        entire  string  (which is in effect what Perl does), whereas the latter
        !           398:        passes over a shortened substring.  This  makes  a  difference  to  the
        !           399:        matching  process  if  the  pattern  begins with a lookbehind assertion
        !           400:        (including \b or \B).
        !           401: 
        !           402:        If any call to pcre[16|32]_exec() in a /g or  /G  sequence  matches  an
        !           403:        empty  string, the next call is done with the PCRE_NOTEMPTY_ATSTART and
        !           404:        PCRE_ANCHORED flags set in order  to  search  for  another,  non-empty,
        !           405:        match  at  the same point. If this second match fails, the start offset
        !           406:        is advanced, and the normal match is retried.  This  imitates  the  way
1.1       misho     407:        Perl handles such cases when using the /g modifier or the split() func-
1.1.1.4 ! misho     408:        tion. Normally, the start offset is advanced by one character,  but  if
        !           409:        the  newline  convention  recognizes CRLF as a newline, and the current
1.1       misho     410:        character is CR followed by LF, an advance of two is used.
                    411: 
                    412:    Other modifiers
                    413: 
                    414:        There are yet more modifiers for controlling the way pcretest operates.
                    415: 
1.1.1.4 ! misho     416:        The /+ modifier requests that as well as outputting the substring  that
        !           417:        matched  the  entire  pattern,  pcretest  should in addition output the
        !           418:        remainder of the subject string. This is useful  for  tests  where  the
        !           419:        subject  contains multiple copies of the same substring. If the + modi-
        !           420:        fier appears twice, the same action is taken for  captured  substrings.
        !           421:        In  each case the remainder is output on the following line with a plus
        !           422:        character following the capture number. Note that  this  modifier  must
        !           423:        not  immediately follow the /S modifier because /S+ and /S++ have other
1.1.1.3   misho     424:        meanings.
1.1       misho     425: 
1.1.1.4 ! misho     426:        The /= modifier requests that the  values  of  all  potential  captured
        !           427:        parentheses  be  output after a match. By default, only those up to the
1.1.1.2   misho     428:        highest one actually used in the match are output (corresponding to the
1.1.1.4 ! misho     429:        return code from pcre[16|32]_exec()). Values in the offsets vector cor-
        !           430:        responding to higher numbers should be set to -1, and these are  output
        !           431:        as  "<unset>".  This modifier gives a way of checking that this is hap-
        !           432:        pening.
        !           433: 
        !           434:        The /B modifier is a debugging feature. It requests that pcretest  out-
        !           435:        put  a  representation of the compiled code after compilation. Normally
        !           436:        this information contains length and offset values; however, if  /Z  is
        !           437:        also  present,  this data is replaced by spaces. This is a special fea-
        !           438:        ture for use in the automatic test scripts; it ensures  that  the  same
1.1       misho     439:        output is generated for different internal link sizes.
                    440: 
1.1.1.4 ! misho     441:        The  /D modifier is a PCRE debugging feature, and is equivalent to /BI,
1.1       misho     442:        that is, both the /B and the /I modifiers.
                    443: 
1.1.1.4 ! misho     444:        The /F modifier causes pcretest to flip the byte order  of  the  2-byte
1.1.1.2   misho     445:        and 4-byte fields in the compiled pattern. This facility is for testing
1.1.1.4 ! misho     446:        the feature in PCRE that allows it to execute patterns that  were  com-
1.1.1.2   misho     447:        piled on a host with a different endianness. This feature is not avail-
1.1.1.4 ! misho     448:        able when the POSIX interface to PCRE is being used, that is, when  the
1.1.1.2   misho     449:        /P pattern modifier is specified. See also the section about saving and
                    450:        reloading compiled patterns below.
                    451: 
1.1.1.4 ! misho     452:        The /I modifier requests that pcretest  output  information  about  the
        !           453:        compiled  pattern (whether it is anchored, has a fixed first character,
        !           454:        and so on). It does this by calling pcre[16|32]_fullinfo()  after  com-
        !           455:        piling  a  pattern.  If the pattern is studied, the results of that are
        !           456:        also output.
        !           457: 
        !           458:        The /K modifier requests pcretest to show names from backtracking  con-
        !           459:        trol  verbs  that  are  returned  from  calls to pcre[16|32]_exec(). It
        !           460:        causes pcretest to create a pcre[16|32]_extra  block  if  one  has  not
        !           461:        already  been  created by a call to pcre[16|32]_study(), and to set the
        !           462:        PCRE_EXTRA_MARK flag and the mark field  within  it,  every  time  that
        !           463:        pcre[16|32]_exec()  is  called.  If  the  variable  that the mark field
        !           464:        points to is  non-NULL  for  a  match,  non-match,  or  partial  match,
        !           465:        pcretest  prints  the  string  to which it points. For a match, this is
        !           466:        shown on a line by itself, tagged with "MK:". For  a  non-match  it  is
        !           467:        added to the message.
1.1       misho     468: 
1.1.1.2   misho     469:        The  /L modifier must be followed directly by the name of a locale, for
1.1       misho     470:        example,
                    471: 
                    472:          /pattern/Lfr_FR
                    473: 
                    474:        For this reason, it must be the last modifier. The given locale is set,
1.1.1.4 ! misho     475:        pcre[16|32]_maketables()  is  called to build a set of character tables
        !           476:        for the locale, and this is then passed to  pcre[16|32]_compile()  when
        !           477:        compiling  the regular expression. Without an /L (or /T) modifier, NULL
        !           478:        is passed as the tables pointer;  that  is,  /L  applies  only  to  the
        !           479:        expression on which it appears.
1.1.1.2   misho     480: 
                    481:        The  /M  modifier  causes the size in bytes of the memory block used to
                    482:        hold the compiled pattern to be output. This does not include the  size
1.1.1.4 ! misho     483:        of  the  pcre[16|32] block; it is just the actual compiled data. If the
        !           484:        pattern is successfully studied with the PCRE_STUDY_JIT_COMPILE option,
1.1.1.2   misho     485:        the size of the JIT compiled code is also output.
                    486: 
1.1.1.4 ! misho     487:        The  /S  modifier  causes  pcre[16|32]_study()  to  be called after the
        !           488:        expression has been compiled, and the results used when the  expression
        !           489:        is matched. There are a number of qualifying characters that may follow
        !           490:        /S.  They may appear in any order.
        !           491: 
        !           492:        If S is followed by an exclamation mark, pcre[16|32]_study() is  called
        !           493:        with  the PCRE_STUDY_EXTRA_NEEDED option, causing it always to return a
        !           494:        pcre_extra block, even when studying discovers no useful information.
        !           495: 
        !           496:        If /S is followed by a second S character, it suppresses studying, even
        !           497:        if  it  was  requested  externally  by the -s command line option. This
        !           498:        makes it possible to specify that certain patterns are always  studied,
        !           499:        and others are never studied, independently of -s. This feature is used
        !           500:        in the test files in a few cases where the output is different when the
        !           501:        pattern is studied.
        !           502: 
        !           503:        If  the  /S  modifier  is  followed  by  a  +  character,  the  call to
        !           504:        pcre[16|32]_study() is made with all the JIT study options,  requesting
        !           505:        just-in-time  optimization  support if it is available, for both normal
        !           506:        and partial matching. If you want to restrict the JIT compiling  modes,
1.1.1.3   misho     507:        you can follow /S+ with a digit in the range 1 to 7:
                    508: 
                    509:          1  normal match only
                    510:          2  soft partial match only
                    511:          3  normal match and soft partial match
                    512:          4  hard partial match only
                    513:          6  soft and hard partial match
                    514:          7  all three modes (default)
                    515: 
                    516:        If /S++ is used instead of /S+ (with or without a following digit), the
1.1.1.4 ! misho     517:        text "(JIT)" is added to the first output line  after  a  match  or  no
1.1.1.3   misho     518:        match when JIT-compiled code was actually used.
                    519: 
1.1.1.4 ! misho     520:        Note  that  there  is  also  an independent /+ modifier; it must not be
1.1.1.3   misho     521:        given immediately after /S or /S+ because this will be misinterpreted.
                    522: 
                    523:        If JIT studying is successful, the compiled JIT code will automatically
1.1.1.4 ! misho     524:        be  used  when pcre[16|32]_exec() is run, except when incompatible run-
        !           525:        time options are specified. For more details, see the pcrejit  documen-
        !           526:        tation.  See also the \J escape sequence below for a way of setting the
        !           527:        size of the JIT stack.
        !           528: 
        !           529:        Finally, if /S is followed by a minus  character,  JIT  compilation  is
        !           530:        suppressed,  even if it was requested externally by the -s command line
        !           531:        option. This makes it possible to specify that JIT is never to be  used
        !           532:        for certain patterns.
1.1.1.2   misho     533: 
                    534:        The  /T  modifier  must be followed by a single digit. It causes a spe-
1.1.1.4 ! misho     535:        cific set of built-in character tables to be passed to pcre[16|32]_com-
1.1.1.2   misho     536:        pile().  It  is used in the standard PCRE tests to check behaviour with
                    537:        different character tables. The digit specifies the tables as follows:
1.1       misho     538: 
                    539:          0   the default ASCII tables, as distributed in
                    540:                pcre_chartables.c.dist
                    541:          1   a set of tables defining ISO 8859 characters
                    542: 
1.1.1.2   misho     543:        In table 1, some characters whose codes are greater than 128 are  iden-
1.1       misho     544:        tified as letters, digits, spaces, etc.
                    545: 
                    546:    Using the POSIX wrapper API
                    547: 
1.1.1.2   misho     548:        The  /P modifier causes pcretest to call PCRE via the POSIX wrapper API
                    549:        rather than its native API. This supports only the 8-bit library.  When
                    550:        /P  is set, the following modifiers set options for the regcomp() func-
                    551:        tion:
1.1       misho     552: 
                    553:          /i    REG_ICASE
                    554:          /m    REG_NEWLINE
                    555:          /N    REG_NOSUB
                    556:          /s    REG_DOTALL     )
                    557:          /U    REG_UNGREEDY   ) These options are not part of
                    558:          /W    REG_UCP        )   the POSIX standard
                    559:          /8    REG_UTF8       )
                    560: 
                    561:        The /+ modifier works as  described  above.  All  other  modifiers  are
                    562:        ignored.
                    563: 
                    564: 
                    565: DATA LINES
                    566: 
1.1.1.4 ! misho     567:        Before  each  data  line  is  passed to pcre[16|32]_exec(), leading and
        !           568:        trailing white space is removed, and it is then scanned for \  escapes.
        !           569:        Some  of  these are pretty esoteric features, intended for checking out
        !           570:        some of the more complicated features of PCRE. If you are just  testing
1.1.1.2   misho     571:        "ordinary"  regular  expressions, you probably don't need any of these.
                    572:        The following escapes are recognized:
1.1       misho     573: 
                    574:          \a         alarm (BEL, \x07)
                    575:          \b         backspace (\x08)
                    576:          \e         escape (\x27)
                    577:          \f         form feed (\x0c)
                    578:          \n         newline (\x0a)
                    579:          \qdd       set the PCRE_MATCH_LIMIT limit to dd
                    580:                       (any number of digits)
                    581:          \r         carriage return (\x0d)
                    582:          \t         tab (\x09)
                    583:          \v         vertical tab (\x0b)
1.1.1.2   misho     584:          \nnn       octal character (up to 3 octal digits); always
1.1.1.4 ! misho     585:                       a byte unless > 255 in UTF-8 or 16-bit or 32-bit mode
1.1       misho     586:          \xhh       hexadecimal byte (up to 2 hex digits)
1.1.1.2   misho     587:          \x{hh...}  hexadecimal character (any number of hex digits)
1.1.1.4 ! misho     588:          \A         pass the PCRE_ANCHORED option to pcre[16|32]_exec()
        !           589:                       or pcre[16|32]_dfa_exec()
        !           590:          \B         pass the PCRE_NOTBOL option to pcre[16|32]_exec()
        !           591:                       or pcre[16|32]_dfa_exec()
        !           592:          \Cdd       call pcre[16|32]_copy_substring() for substring dd
1.1       misho     593:                       after a successful match (number less than 32)
1.1.1.4 ! misho     594:          \Cname     call pcre[16|32]_copy_named_substring() for substring
1.1       misho     595:                       "name" after a successful match (name termin-
                    596:                       ated by next non alphanumeric character)
                    597:          \C+        show the current captured substrings at callout
                    598:                       time
                    599:          \C-        do not supply a callout function
                    600:          \C!n       return 1 instead of 0 when callout number n is
                    601:                       reached
                    602:          \C!n!m     return 1 instead of 0 when callout number n is
                    603:                       reached for the nth time
                    604:          \C*n       pass the number n (may be negative) as callout
                    605:                       data; this is used as the callout return value
1.1.1.4 ! misho     606:          \D         use the pcre[16|32]_dfa_exec() match function
        !           607:          \F         only shortest match for pcre[16|32]_dfa_exec()
        !           608:          \Gdd       call pcre[16|32]_get_substring() for substring dd
1.1       misho     609:                       after a successful match (number less than 32)
1.1.1.4 ! misho     610:          \Gname     call pcre[16|32]_get_named_substring() for substring
1.1       misho     611:                       "name" after a successful match (name termin-
                    612:                       ated by next non-alphanumeric character)
                    613:          \Jdd       set up a JIT stack of dd kilobytes maximum (any
                    614:                       number of digits)
1.1.1.4 ! misho     615:          \L         call pcre[16|32]_get_substringlist() after a
1.1       misho     616:                       successful match
                    617:          \M         discover the minimum MATCH_LIMIT and
                    618:                       MATCH_LIMIT_RECURSION settings
1.1.1.4 ! misho     619:          \N         pass the PCRE_NOTEMPTY option to pcre[16|32]_exec()
        !           620:                       or pcre[16|32]_dfa_exec(); if used twice, pass the
1.1       misho     621:                       PCRE_NOTEMPTY_ATSTART option
                    622:          \Odd       set the size of the output vector passed to
1.1.1.4 ! misho     623:                       pcre[16|32]_exec() to dd (any number of digits)
        !           624:          \P         pass the PCRE_PARTIAL_SOFT option to pcre[16|32]_exec()
        !           625:                       or pcre[16|32]_dfa_exec(); if used twice, pass the
1.1       misho     626:                       PCRE_PARTIAL_HARD option
                    627:          \Qdd       set the PCRE_MATCH_LIMIT_RECURSION limit to dd
                    628:                       (any number of digits)
1.1.1.4 ! misho     629:          \R         pass the PCRE_DFA_RESTART option to pcre[16|32]_dfa_exec()
1.1       misho     630:          \S         output details of memory get/free calls during matching
1.1.1.4 ! misho     631:          \Y            pass    the    PCRE_NO_START_OPTIMIZE     option     to
        !           632:        pcre[16|32]_exec()
        !           633:                       or pcre[16|32]_dfa_exec()
        !           634:          \Z         pass the PCRE_NOTEOL option to pcre[16|32]_exec()
        !           635:                       or pcre[16|32]_dfa_exec()
        !           636:          \?         pass the PCRE_NO_UTF[8|16|32]_CHECK option to
        !           637:                       pcre[16|32]_exec() or pcre[16|32]_dfa_exec()
1.1       misho     638:          \>dd       start the match at offset dd (optional "-"; then
                    639:                       any number of digits); this sets the startoffset
1.1.1.4 ! misho     640:                       argument         for        pcre[16|32]_exec()        or
        !           641:        pcre[16|32]_dfa_exec()
        !           642:          \<cr>      pass the PCRE_NEWLINE_CR option to pcre[16|32]_exec()
        !           643:                       or pcre[16|32]_dfa_exec()
        !           644:          \<lf>      pass the PCRE_NEWLINE_LF option to pcre[16|32]_exec()
        !           645:                       or pcre[16|32]_dfa_exec()
        !           646:          \<crlf>    pass the PCRE_NEWLINE_CRLF option to pcre[16|32]_exec()
        !           647:                       or pcre[16|32]_dfa_exec()
        !           648:          \<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to pcre[16|32]_exec()
        !           649:                       or pcre[16|32]_dfa_exec()
        !           650:          \<any>     pass the PCRE_NEWLINE_ANY option to pcre[16|32]_exec()
        !           651:                       or pcre[16|32]_dfa_exec()
1.1.1.2   misho     652: 
                    653:        The use of \x{hh...} is not dependent on the use of the /8 modifier  on
                    654:        the  pattern. It is recognized always. There may be any number of hexa-
                    655:        decimal digits inside the braces; invalid  values  provoke  error  mes-
                    656:        sages.
                    657: 
                    658:        Note  that  \xhh  specifies one byte rather than one character in UTF-8
                    659:        mode; this makes it possible to construct invalid UTF-8  sequences  for
                    660:        testing  purposes.  On the other hand, \x{hh} is interpreted as a UTF-8
                    661:        character in UTF-8 mode, generating more than one byte if the value  is
                    662:        greater  than  127.   When testing the 8-bit library not in UTF-8 mode,
                    663:        \x{hh} generates one byte for values less than 256, and causes an error
                    664:        for greater values.
                    665: 
                    666:        In UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it
                    667:        possible to construct invalid UTF-16 sequences for testing purposes.
1.1       misho     668: 
1.1.1.4 ! misho     669:        In UTF-32 mode, all 4- to 8-digit \x{...}  values  are  accepted.  This
        !           670:        makes  it  possible  to  construct invalid UTF-32 sequences for testing
        !           671:        purposes.
        !           672: 
1.1.1.2   misho     673:        The escapes that specify line ending  sequences  are  literal  strings,
1.1       misho     674:        exactly as shown. No more than one newline setting should be present in
                    675:        any data line.
                    676: 
1.1.1.2   misho     677:        A backslash followed by anything else just escapes the  anything  else.
                    678:        If  the very last character is a backslash, it is ignored. This gives a
                    679:        way of passing an empty line as data, since a real  empty  line  termi-
1.1       misho     680:        nates the data input.
                    681: 
1.1.1.2   misho     682:        The  \J escape provides a way of setting the maximum stack size that is
                    683:        used by the just-in-time optimization code. It is ignored if JIT  opti-
                    684:        mization  is  not being used. Providing a stack that is larger than the
1.1       misho     685:        default 32K is necessary only for very complicated patterns.
                    686: 
1.1.1.4 ! misho     687:        If \M is present, pcretest calls pcre[16|32]_exec() several times, with
1.1.1.2   misho     688:        different values in the match_limit and match_limit_recursion fields of
1.1.1.4 ! misho     689:        the pcre[16|32]_extra data structure, until it finds the  minimum  num-
        !           690:        bers for each parameter that allow pcre[16|32]_exec() to complete with-
        !           691:        out error. Because this is testing a specific  feature  of  the  normal
        !           692:        interpretive pcre[16|32]_exec() execution, the use of any JIT optimiza-
        !           693:        tion that might have been set up by the /S+ qualifier of -s+ option  is
        !           694:        disabled.
        !           695: 
        !           696:        The  match_limit number is a measure of the amount of backtracking that
        !           697:        takes place, and checking it out can be instructive.  For  most  simple
        !           698:        matches,  the  number  is quite small, but for patterns with very large
        !           699:        numbers of matching possibilities, it can  become  large  very  quickly
        !           700:        with  increasing  length  of  subject string. The match_limit_recursion
        !           701:        number is a measure of how much stack (or, if  PCRE  is  compiled  with
        !           702:        NO_RECURSE,  how  much  heap)  memory  is  needed to complete the match
1.1       misho     703:        attempt.
                    704: 
1.1.1.4 ! misho     705:        When \O is used, the value specified may be higher or  lower  than  the
1.1       misho     706:        size set by the -O command line option (or defaulted to 45); \O applies
1.1.1.4 ! misho     707:        only to the call  of  pcre[16|32]_exec()  for  the  line  in  which  it
        !           708:        appears.
1.1       misho     709: 
1.1.1.2   misho     710:        If  the /P modifier was present on the pattern, causing the POSIX wrap-
                    711:        per API to be used, the only option-setting  sequences  that  have  any
                    712:        effect  are  \B,  \N,  and  \Z,  causing  REG_NOTBOL, REG_NOTEMPTY, and
1.1       misho     713:        REG_NOTEOL, respectively, to be passed to regexec().
                    714: 
                    715: 
                    716: THE ALTERNATIVE MATCHING FUNCTION
                    717: 
                    718:        By  default,  pcretest  uses  the  standard  PCRE  matching   function,
1.1.1.4 ! misho     719:        pcre[16|32]_exec()  to  match  each  data  line.  PCRE also supports an
        !           720:        alternative matching function, pcre[16|32]_dfa_test(),  which  operates
        !           721:        in  a different way, and has some restrictions. The differences between
        !           722:        the two functions are described in the pcrematching documentation.
1.1       misho     723: 
                    724:        If a data line contains the \D escape sequence, or if the command  line
1.1.1.2   misho     725:        contains  the  -dfa  option, the alternative matching function is used.
1.1       misho     726:        This function finds all possible matches at a given point. If, however,
                    727:        the  \F escape sequence is present in the data line, it stops after the
                    728:        first match is found. This is always the shortest possible match.
                    729: 
                    730: 
                    731: DEFAULT OUTPUT FROM PCRETEST
                    732: 
                    733:        This section describes the output when the  normal  matching  function,
1.1.1.4 ! misho     734:        pcre[16|32]_exec(), is being used.
1.1       misho     735: 
                    736:        When a match succeeds, pcretest outputs the list of captured substrings
1.1.1.4 ! misho     737:        that pcre[16|32]_exec() returns, starting with number 0 for the  string
1.1.1.2   misho     738:        that  matched  the whole pattern. Otherwise, it outputs "No match" when
                    739:        the return is PCRE_ERROR_NOMATCH, and "Partial match:" followed by  the
1.1.1.4 ! misho     740:        partially    matching   substring   when   pcre[16|32]_exec()   returns
1.1.1.2   misho     741:        PCRE_ERROR_PARTIAL. (Note that this is the entire  substring  that  was
                    742:        inspected  during  the  partial match; it may include characters before
                    743:        the actual match start if a lookbehind assertion, \K,  \b,  or  \B  was
                    744:        involved.)  For  any  other  return, pcretest outputs the PCRE negative
                    745:        error number and a short descriptive phrase. If the error is  a  failed
                    746:        UTF  string check, the offset of the start of the failing character and
                    747:        the reason code are also output, provided that the size of  the  output
                    748:        vector  is  at least two. Here is an example of an interactive pcretest
                    749:        run.
1.1       misho     750: 
                    751:          $ pcretest
                    752:          PCRE version 8.13 2011-04-30
                    753: 
                    754:            re> /^abc(\d+)/
                    755:          data> abc123
                    756:           0: abc123
                    757:           1: 123
                    758:          data> xyz
                    759:          No match
                    760: 
                    761:        Unset capturing substrings that are not followed by one that is set are
1.1.1.4 ! misho     762:        not  returned  by pcre[16|32]_exec(), and are not shown by pcretest. In
        !           763:        the following example, there are two capturing substrings, but when the
1.1.1.2   misho     764:        first  data  line is matched, the second, unset substring is not shown.
                    765:        An "internal" unset substring is shown as "<unset>", as for the  second
1.1       misho     766:        data line.
                    767: 
                    768:            re> /(a)|(b)/
                    769:          data> a
                    770:           0: a
                    771:           1: a
                    772:          data> b
                    773:           0: b
                    774:           1: <unset>
                    775:           2: b
                    776: 
1.1.1.2   misho     777:        If  the strings contain any non-printing characters, they are output as
                    778:        \xhh escapes if the value is less than 256 and UTF  mode  is  not  set.
                    779:        Otherwise they are output as \x{hh...} escapes. See below for the defi-
                    780:        nition of non-printing characters. If the pattern has the /+  modifier,
                    781:        the  output  for substring 0 is followed by the the rest of the subject
                    782:        string, identified by "0+" like this:
1.1       misho     783: 
                    784:            re> /cat/+
                    785:          data> cataract
                    786:           0: cat
                    787:           0+ aract
                    788: 
1.1.1.2   misho     789:        If the pattern has the /g or /G modifier,  the  results  of  successive
1.1       misho     790:        matching attempts are output in sequence, like this:
                    791: 
                    792:            re> /\Bi(\w\w)/g
                    793:          data> Mississippi
                    794:           0: iss
                    795:           1: ss
                    796:           0: iss
                    797:           1: ss
                    798:           0: ipp
                    799:           1: pp
                    800: 
1.1.1.2   misho     801:        "No  match" is output only if the first match attempt fails. Here is an
                    802:        example of a failure message (the offset 4 that is specified by \>4  is
1.1       misho     803:        past the end of the subject string):
                    804: 
                    805:            re> /xyz/
                    806:          data> xyz\>4
                    807:          Error -24 (bad offset value)
                    808: 
1.1.1.2   misho     809:        If  any  of the sequences \C, \G, or \L are present in a data line that
                    810:        is successfully matched, the substrings extracted  by  the  convenience
1.1       misho     811:        functions are output with C, G, or L after the string number instead of
                    812:        a colon. This is in addition to the normal full list. The string length
1.1.1.2   misho     813:        (that  is,  the return from the extraction function) is given in paren-
1.1       misho     814:        theses after each string for \C and \G.
                    815: 
                    816:        Note that whereas patterns can be continued over several lines (a plain
                    817:        ">" prompt is used for continuations), data lines may not. However new-
1.1.1.2   misho     818:        lines can be included in data by means of the \n escape (or  \r,  \r\n,
1.1       misho     819:        etc., depending on the newline sequence setting).
                    820: 
                    821: 
                    822: OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION
                    823: 
1.1.1.4 ! misho     824:        When the alternative matching function, pcre[16|32]_dfa_exec(), is used
1.1.1.2   misho     825:        (by means of the \D escape sequence or the -dfa command  line  option),
                    826:        the  output  consists  of  a  list of all the matches that start at the
                    827:        first point in the subject where there is at least one match. For exam-
                    828:        ple:
1.1       misho     829: 
                    830:            re> /(tang|tangerine|tan)/
                    831:          data> yellow tangerine\D
                    832:           0: tangerine
                    833:           1: tang
                    834:           2: tan
                    835: 
                    836:        (Using  the  normal  matching function on this data finds only "tang".)
                    837:        The longest matching string is always given first (and numbered  zero).
                    838:        After a PCRE_ERROR_PARTIAL return, the output is "Partial match:", fol-
                    839:        lowed by the partially matching  substring.  (Note  that  this  is  the
                    840:        entire  substring  that  was inspected during the partial match; it may
                    841:        include characters before the actual match start if a lookbehind asser-
                    842:        tion, \K, \b, or \B was involved.)
                    843: 
                    844:        If /g is present on the pattern, the search for further matches resumes
                    845:        at the end of the longest match. For example:
                    846: 
                    847:            re> /(tang|tangerine|tan)/g
                    848:          data> yellow tangerine and tangy sultana\D
                    849:           0: tangerine
                    850:           1: tang
                    851:           2: tan
                    852:           0: tang
                    853:           1: tan
                    854:           0: tan
                    855: 
                    856:        Since the matching function does not  support  substring  capture,  the
                    857:        escape  sequences  that  are concerned with captured substrings are not
                    858:        relevant.
                    859: 
                    860: 
                    861: RESTARTING AFTER A PARTIAL MATCH
                    862: 
                    863:        When the alternative matching function has given the PCRE_ERROR_PARTIAL
                    864:        return,  indicating that the subject partially matched the pattern, you
                    865:        can restart the match with additional subject data by means of  the  \R
                    866:        escape sequence. For example:
                    867: 
                    868:            re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
                    869:          data> 23ja\P\D
                    870:          Partial match: 23ja
                    871:          data> n05\R\D
                    872:           0: n05
                    873: 
                    874:        For  further  information  about  partial matching, see the pcrepartial
                    875:        documentation.
                    876: 
                    877: 
                    878: CALLOUTS
                    879: 
                    880:        If the pattern contains any callout requests, pcretest's callout  func-
                    881:        tion  is  called  during  matching. This works with both matching func-
                    882:        tions. By default, the called function displays the callout number, the
                    883:        start  and  current  positions in the text at the callout time, and the
1.1.1.2   misho     884:        next pattern item to be tested. For example:
1.1       misho     885: 
                    886:          --->pqrabcdef
                    887:            0    ^  ^     \d
                    888: 
1.1.1.2   misho     889:        This output indicates that  callout  number  0  occurred  for  a  match
                    890:        attempt  starting  at  the fourth character of the subject string, when
                    891:        the pointer was at the seventh character of the data, and when the next
                    892:        pattern  item  was  \d.  Just one circumflex is output if the start and
                    893:        current positions are the same.
1.1       misho     894: 
                    895:        Callouts numbered 255 are assumed to be automatic callouts, inserted as
                    896:        a  result  of the /C pattern modifier. In this case, instead of showing
                    897:        the callout number, the offset in the pattern, preceded by a  plus,  is
                    898:        output. For example:
                    899: 
                    900:            re> /\d?[A-E]\*/C
                    901:          data> E*
                    902:          --->E*
                    903:           +0 ^      \d?
                    904:           +3 ^      [A-E]
                    905:           +8 ^^     \*
                    906:          +10 ^ ^
                    907:           0: E*
                    908: 
                    909:        If a pattern contains (*MARK) items, an additional line is output when-
                    910:        ever a change of latest mark is passed to  the  callout  function.  For
                    911:        example:
                    912: 
                    913:            re> /a(*MARK:X)bc/C
                    914:          data> abc
                    915:          --->abc
                    916:           +0 ^       a
                    917:           +1 ^^      (*MARK:X)
                    918:          +10 ^^      b
                    919:          Latest Mark: X
                    920:          +11 ^ ^     c
                    921:          +12 ^  ^
                    922:           0: abc
                    923: 
                    924:        The  mark  changes between matching "a" and "b", but stays the same for
                    925:        the rest of the match, so nothing more is output. If, as  a  result  of
                    926:        backtracking,  the  mark  reverts to being unset, the text "<unset>" is
                    927:        output.
                    928: 
                    929:        The callout function in pcretest returns zero (carry  on  matching)  by
                    930:        default,  but you can use a \C item in a data line (as described above)
                    931:        to change this and other parameters of the callout.
                    932: 
                    933:        Inserting callouts can be helpful when using pcretest to check  compli-
                    934:        cated  regular expressions. For further information about callouts, see
                    935:        the pcrecallout documentation.
                    936: 
                    937: 
                    938: NON-PRINTING CHARACTERS
                    939: 
                    940:        When pcretest is outputting text in the compiled version of a  pattern,
                    941:        bytes  other  than 32-126 are always treated as non-printing characters
                    942:        are are therefore shown as hex escapes.
                    943: 
                    944:        When pcretest is outputting text that is a matched part  of  a  subject
                    945:        string,  it behaves in the same way, unless a different locale has been
                    946:        set for the  pattern  (using  the  /L  modifier).  In  this  case,  the
                    947:        isprint() function to distinguish printing and non-printing characters.
                    948: 
                    949: 
                    950: SAVING AND RELOADING COMPILED PATTERNS
                    951: 
                    952:        The  facilities  described  in  this section are not available when the
                    953:        POSIX interface to PCRE is being used, that is,  when  the  /P  pattern
                    954:        modifier is specified.
                    955: 
                    956:        When the POSIX interface is not in use, you can cause pcretest to write
                    957:        a compiled pattern to a file, by following the modifiers with >  and  a
                    958:        file name.  For example:
                    959: 
                    960:          /pattern/im >/some/file
                    961: 
                    962:        See  the pcreprecompile documentation for a discussion about saving and
                    963:        re-using compiled patterns.  Note that if the pattern was  successfully
                    964:        studied with JIT optimization, the JIT data cannot be saved.
                    965: 
                    966:        The  data  that  is  written  is  binary. The first eight bytes are the
                    967:        length of the compiled pattern data  followed  by  the  length  of  the
                    968:        optional  study  data,  each  written as four bytes in big-endian order
                    969:        (most significant byte first). If there is no study  data  (either  the
                    970:        pattern was not studied, or studying did not return any data), the sec-
                    971:        ond length is zero. The lengths are followed by an exact  copy  of  the
                    972:        compiled  pattern.  If  there is additional study data, this (excluding
                    973:        any JIT data) follows immediately after  the  compiled  pattern.  After
                    974:        writing the file, pcretest expects to read a new pattern.
                    975: 
                    976:        A  saved  pattern  can  be reloaded into pcretest by specifying < and a
                    977:        file name instead of a pattern. The name of the file must not contain a
                    978:        < character, as otherwise pcretest will interpret the line as a pattern
                    979:        delimited by < characters.  For example:
                    980: 
                    981:           re> </some/file
                    982:          Compiled pattern loaded from /some/file
                    983:          No study data
                    984: 
                    985:        If the pattern was previously studied with the  JIT  optimization,  the
                    986:        JIT  information cannot be saved and restored, and so is lost. When the
                    987:        pattern has been loaded, pcretest proceeds to read data  lines  in  the
                    988:        usual way.
                    989: 
                    990:        You  can copy a file written by pcretest to a different host and reload
                    991:        it there, even if the new host has opposite endianness to  the  one  on
                    992:        which  the pattern was compiled. For example, you can compile on an i86
1.1.1.2   misho     993:        machine and run on a SPARC machine. When a pattern  is  reloaded  on  a
                    994:        host with different endianness, the confirmation message is changed to:
                    995: 
                    996:          Compiled pattern (byte-inverted) loaded from /some/file
                    997: 
                    998:        The test suite contains some saved pre-compiled patterns with different
                    999:        endianness. These are reloaded using "<!" instead  of  just  "<".  This
                   1000:        suppresses the "(byte-inverted)" text so that the output is the same on
                   1001:        all hosts. It also forces debugging output once the  pattern  has  been
                   1002:        reloaded.
1.1       misho    1003: 
1.1.1.2   misho    1004:        File  names  for  saving and reloading can be absolute or relative, but
                   1005:        note that the shell facility of expanding a file name that starts  with
1.1       misho    1006:        a tilde (~) is not available.
                   1007: 
1.1.1.2   misho    1008:        The  ability to save and reload files in pcretest is intended for test-
                   1009:        ing and experimentation. It is not intended for production use  because
                   1010:        only  a  single pattern can be written to a file. Furthermore, there is
                   1011:        no facility for supplying  custom  character  tables  for  use  with  a
                   1012:        reloaded  pattern.  If  the  original  pattern was compiled with custom
                   1013:        tables, an attempt to match a subject string using a  reloaded  pattern
                   1014:        is  likely to cause pcretest to crash.  Finally, if you attempt to load
1.1       misho    1015:        a file that is not in the correct format, the result is undefined.
                   1016: 
                   1017: 
                   1018: SEE ALSO
                   1019: 
1.1.1.4 ! misho    1020:        pcre(3), pcre16(3),  pcre32(3),  pcreapi(3),  pcrecallout(3),  pcrejit,
        !          1021:        pcrematching(3), pcrepartial(d), pcrepattern(3), pcreprecompile(3).
1.1       misho    1022: 
                   1023: 
                   1024: AUTHOR
                   1025: 
                   1026:        Philip Hazel
                   1027:        University Computing Service
                   1028:        Cambridge CB2 3QH, England.
                   1029: 
                   1030: 
                   1031: REVISION
                   1032: 
1.1.1.4 ! misho    1033:        Last updated: 26 April 2013
        !          1034:        Copyright (c) 1997-2013 University of Cambridge.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>