[BACK]Return to pcretest.txt CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc

Diff for /embedaddon/pcre/doc/pcretest.txt between versions 1.1.1.4 and 1.1.1.5

version 1.1.1.4, 2013/07/22 08:25:56 version 1.1.1.5, 2014/06/15 19:46:04
Line 138  COMMAND LINE OPTIONS Line 138  COMMAND LINE OPTIONS
                  compiled.  This  is  equivalent  to adding /M to each regular                   compiled.  This  is  equivalent  to adding /M to each regular
                  expression. The size is given in bytes for both libraries.                   expression. The size is given in bytes for both libraries.
   
       -o osize  Set the number of elements in the output vector that is  used       -O        Behave as if each pattern has the /O modifier, that  is  dis-
                 when  calling pcre[16|32]_exec() or pcre[16|32]_dfa_exec() to                 able auto-possessification for all patterns.
                 be osize. The default value is 45, which  is  enough  for  14
        -o osize  Set  the number of elements in the output vector that is used
                  when calling pcre[16|32]_exec() or pcre[16|32]_dfa_exec()  to
                  be  osize.  The  default  value is 45, which is enough for 14
                  capturing subexpressions for pcre[16|32]_exec() or 22 differ-                   capturing subexpressions for pcre[16|32]_exec() or 22 differ-
                 ent matches for pcre[16|32]_dfa_exec().  The vector size  can                 ent  matches for pcre[16|32]_dfa_exec().  The vector size can
                 be  changed  for individual matching calls by including \O in                 be changed for individual matching calls by including  \O  in
                  the data line (see below).                   the data line (see below).
   
       -p        Behave as if each pattern has  the  /P  modifier;  the  POSIX       -p        Behave  as  if  each  pattern  has the /P modifier; the POSIX
                 wrapper  API  is used to call PCRE. None of the other options                 wrapper API is used to call PCRE. None of the  other  options
                 has any effect when -p is set. This option can be  used  only                 has  any  effect when -p is set. This option can be used only
                  with the 8-bit library.                   with the 8-bit library.
   
       -q        Do  not output the version number of pcretest at the start of       -q        Do not output the version number of pcretest at the start  of
                  execution.                   execution.
   
       -S size   On Unix-like systems, set the size of the run-time  stack  to       -S size   On  Unix-like  systems, set the size of the run-time stack to
                  size megabytes.                   size megabytes.
   
       -s or -s+ Behave  as  if  each  pattern  has  the /S modifier; in other       -s or -s+ Behave as if each pattern  has  the  /S  modifier;  in  other
                 words, force each pattern to be studied. If -s+ is used,  all                 words,  force each pattern to be studied. If -s+ is used, all
                 the  JIT  compile  options are passed to pcre[16|32]_study(),                 the JIT compile options are  passed  to  pcre[16|32]_study(),
                 causing just-in-time optimization to  be  set  up  if  it  is                 causing  just-in-time  optimization  to  be  set  up if it is
                 available,  for  both full and partial matching. Specific JIT                 available, for both full and partial matching.  Specific  JIT
                  compile options can be selected by following -s+ with a digit                   compile options can be selected by following -s+ with a digit
                 in  the  range 1 to 7, which selects the JIT compile modes as                 in the range 1 to 7, which selects the JIT compile  modes  as
                  follows:                   follows:
   
                    1  normal match only                     1  normal match only
Line 173  COMMAND LINE OPTIONS Line 176  COMMAND LINE OPTIONS
                    6  soft and hard partial match                     6  soft and hard partial match
                    7  all three modes (default)                     7  all three modes (default)
   
                 If -s++ is used instead of -s+ (with or without  a  following                 If  -s++  is used instead of -s+ (with or without a following
                 digit),  the  text  "(JIT)" is added to the first output line                 digit), the text "(JIT)" is added to the  first  output  line
                  after a match or no match when JIT-compiled code was actually                   after a match or no match when JIT-compiled code was actually
                  used.                   used.
   
                 Note  that  there  are  pattern options that can override -s,                 Note that there are pattern options  that  can  override  -s,
                  either specifying no studying at all, or suppressing JIT com-                   either specifying no studying at all, or suppressing JIT com-
                  pilation.                   pilation.
   
                 If  the  /I  or /D option is present on a pattern (requesting                 If the /I or /D option is present on  a  pattern  (requesting
                 output about the compiled  pattern),  information  about  the                 output  about  the  compiled  pattern), information about the
                 result  of  studying  is not included when studying is caused                 result of studying is not included when  studying  is  caused
                 only by -s and neither -i nor -d is present  on  the  command                 only  by  -s  and neither -i nor -d is present on the command
                 line.  This  behaviour  means that the output from tests that                 line. This behaviour means that the output  from  tests  that
                 are run with and without -s should be identical, except  when                 are  run with and without -s should be identical, except when
                  options that output information about the actual running of a                   options that output information about the actual running of a
                  match are set.                   match are set.
   
                 The -M, -t, and -tm options,  which  give  information  about                 The  -M,  -t,  and  -tm options, which give information about
                 resources  used,  are likely to produce different output with                 resources used, are likely to produce different  output  with
                 and without -s. Output may also differ if the  /C  option  is                 and  without  -s.  Output may also differ if the /C option is
                  present on an individual pattern. This uses callouts to trace                   present on an individual pattern. This uses callouts to trace
                 the the matching process, and this may be  different  between                 the  the  matching process, and this may be different between
                 studied  and  non-studied  patterns.  If the pattern contains                 studied and non-studied patterns.  If  the  pattern  contains
                 (*MARK) items there may also be  differences,  for  the  same                 (*MARK)  items  there  may  also be differences, for the same
                  reason. The -s command line option can be overridden for spe-                   reason. The -s command line option can be overridden for spe-
                 cific patterns that should never be studied (see the /S  pat-                 cific  patterns that should never be studied (see the /S pat-
                  tern modifier below).                   tern modifier below).
   
       -t        Run  each  compile, study, and match many times with a timer,       -t        Run each compile, study, and match many times with  a  timer,
                 and output resulting time per compile or match (in  millisec-                 and  output  the resulting times per compile, study, or match
                 onds).  Do  not set -m with -t, because you will then get the                 (in milliseconds). Do not set -m with -t,  because  you  will
                 size output a zillion times, and  the  timing  will  be  dis-                 then get the size output a zillion times, and the timing will
                 torted.  You  can  control  the number of iterations that are                 be distorted. You can control the number of  iterations  that
                 used for timing by following -t with a number (as a  separate                 are used for timing by following -t with a number (as a sepa-
                 item on the command line). For example, "-t 1000" would iter-                 rate item on the command line). For example, "-t 1000"  iter-
                 ate 1000 times. The default is to iterate 500000 times.                 ates 1000 times.  The default is to iterate 500000 times.
   
        -tm       This is like -t except that it times only the matching phase,         -tm       This is like -t except that it times only the matching phase,
                  not the compile or study phases.                   not the compile or study phases.
   
          -T -TM    These behave like -t and -tm, but in addition, at the end  of
                    a run, the total times for all compiles, studies, and matches
                    are output.
   
   
 DESCRIPTION  DESCRIPTION
   
       If  pcretest  is  given two filename arguments, it reads from the first       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         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       reads from that file and writes to stdout.  Otherwise,  it  reads  from
       stdin and writes to stdout, and prompts for each line of  input,  using       stdin  and  writes to stdout, and prompts for each line of input, using
        "re>" to prompt for regular expressions, and "data>" to prompt for data         "re>" to prompt for regular expressions, and "data>" to prompt for data
        lines.         lines.
   
       When pcretest is built, a configuration  option  can  specify  that  it       When  pcretest  is  built,  a  configuration option can specify that it
       should  be  linked  with the libreadline library. When this is done, if       should be linked with the libreadline library. When this  is  done,  if
        the input is from a terminal, it is read using the readline() function.         the input is from a terminal, it is read using the readline() function.
       This  provides line-editing and history facilities. The output from the       This provides line-editing and history facilities. The output from  the
        -help option states whether or not readline() will be used.         -help option states whether or not readline() will be used.
   
        The program handles any number of sets of input on a single input file.         The program handles any number of sets of input on a single input file.
       Each  set starts with a regular expression, and continues with any num-       Each set starts with a regular expression, and continues with any  num-
       ber of data lines to be matched against the pattern.       ber of data lines to be matched against that pattern.
   
       Each data line is matched separately and independently. If you want  to       Each  data line is matched separately and independently. If you want to
        do multi-line matches, you have to use the \n escape sequence (or \r or         do multi-line matches, you have to use the \n escape sequence (or \r or
        \r\n, etc., depending on the newline setting) in a single line of input         \r\n, etc., depending on the newline setting) in a single line of input
       to  encode  the  newline  sequences. There is no limit on the length of       to encode the newline sequences. There is no limit  on  the  length  of
       data lines; the input buffer is automatically extended  if  it  is  too       data  lines;  the  input  buffer is automatically extended if it is too
        small.         small.
   
       An  empty  line signals the end of the data lines, at which point a new       An empty line signals the end of the data lines, at which point  a  new
       regular expression is read. The regular expressions are given  enclosed       regular  expression is read. The regular expressions are given enclosed
        in any non-alphanumeric delimiters other than backslash, for example:         in any non-alphanumeric delimiters other than backslash, for example:
   
          /(a|bc)x+yz/           /(a|bc)x+yz/
   
       White  space before the initial delimiter is ignored. A regular expres-       White space before the initial delimiter is ignored. A regular  expres-
       sion may be continued over several input lines, in which case the  new-       sion  may be continued over several input lines, in which case the new-
       line  characters  are included within it. It is possible to include the       line characters are included within it. It is possible to  include  the
        delimiter within the pattern by escaping it, for example         delimiter within the pattern by escaping it, for example
   
          /abc\/def/           /abc\/def/
   
       If you do so, the escape and the delimiter form part  of  the  pattern,       If  you  do  so, the escape and the delimiter form part of the pattern,
       but  since delimiters are always non-alphanumeric, this does not affect       but since delimiters are always non-alphanumeric, this does not  affect
       its interpretation.  If the terminating delimiter is  immediately  fol-       its  interpretation.   If the terminating delimiter is immediately fol-
        lowed by a backslash, for example,         lowed by a backslash, for example,
   
          /abc/\           /abc/\
   
       then  a  backslash  is added to the end of the pattern. This is done to       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       provide  a  way of testing the error condition that arises if a pattern
        finishes with a backslash, because         finishes with a backslash, because
   
          /abc\/           /abc\/
   
       is  interpreted as the first line of a pattern that starts with "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         causing pcretest to read the next line as a continuation of the regular
        expression.         expression.
   
   
 PATTERN MODIFIERS  PATTERN MODIFIERS
   
       A  pattern may be followed by any number of modifiers, which are mostly       A pattern may be followed by any number of modifiers, which are  mostly
       single characters, though some of these can  be  qualified  by  further       single  characters,  though  some  of these can be qualified by further
       characters.   Following Perl usage, these are referred to below as, for       characters.  Following Perl usage, these are referred to below as,  for
       example, "the /i modifier", even though the delimiter  of  the  pattern       example,  "the  /i  modifier", even though the delimiter of the pattern
       need  not  always  be  a slash, and no slash is used when writing modi-       need not always be a slash, and no slash is  used  when  writing  modi-
       fiers. White space may appear between the final pattern  delimiter  and       fiers.  White  space may appear between the final pattern delimiter and
       the  first  modifier,  and between the modifiers themselves. For refer-       the first modifier, and between the modifiers  themselves.  For  refer-
       ence, here is a complete list of  modifiers.  They  fall  into  several       ence,  here  is  a  complete  list of modifiers. They fall into several
        groups that are described in detail in the following sections.         groups that are described in detail in the following sections.
   
          /8              set UTF mode           /8              set UTF mode
Line 307  PATTERN MODIFIERS Line 314  PATTERN MODIFIERS
          /M              show compiled memory size           /M              show compiled memory size
          /m              set PCRE_MULTILINE           /m              set PCRE_MULTILINE
          /N              set PCRE_NO_AUTO_CAPTURE           /N              set PCRE_NO_AUTO_CAPTURE
            /O              set PCRE_NO_AUTO_POSSESS
          /P              use the POSIX wrapper           /P              use the POSIX wrapper
          /S              study the pattern after compilation           /S              study the pattern after compilation
          /s              set PCRE_DOTALL           /s              set PCRE_DOTALL
Line 331  PATTERN MODIFIERS Line 339  PATTERN MODIFIERS
    Perl-compatible modifiers     Perl-compatible modifiers
   
        The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE,         The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE,
       PCRE_DOTALL,   or    PCRE_EXTENDED    options,    respectively,    when       PCRE_DOTALL,    or    PCRE_EXTENDED    options,    respectively,   when
       pcre[16|32]_compile()  is  called. These four modifier letters have the       pcre[16|32]_compile() is called. These four modifier letters  have  the
        same effect as they do in Perl. For example:         same effect as they do in Perl. For example:
   
          /caseless/i           /caseless/i
Line 340  PATTERN MODIFIERS Line 348  PATTERN MODIFIERS
   
    Modifiers for other PCRE options     Modifiers for other PCRE options
   
       The following table shows additional modifiers for  setting  PCRE  com-       The  following  table  shows additional modifiers for setting PCR       The  following  table  shows additional modifiers for setting PCR
        pile-time options that do not correspond to anything in Perl:         pile-time options that do not correspond to anything in Perl:
   
          /8              PCRE_UTF8           ) when using the 8-bit           /8              PCRE_UTF8           ) when using the 8-bit
Line 359  PATTERN MODIFIERS Line 367  PATTERN MODIFIERS
          /f              PCRE_FIRSTLINE           /f              PCRE_FIRSTLINE
          /J              PCRE_DUPNAMES           /J              PCRE_DUPNAMES
          /N              PCRE_NO_AUTO_CAPTURE           /N              PCRE_NO_AUTO_CAPTURE
            /O              PCRE_NO_AUTO_POSSESS
          /U              PCRE_UNGREEDY           /U              PCRE_UNGREEDY
          /W              PCRE_UCP           /W              PCRE_UCP
          /X              PCRE_EXTRA           /X              PCRE_EXTRA
Line 372  PATTERN MODIFIERS Line 381  PATTERN MODIFIERS
          /<bsr_unicode>  PCRE_BSR_UNICODE           /<bsr_unicode>  PCRE_BSR_UNICODE
          /<JS>           PCRE_JAVASCRIPT_COMPAT           /<JS>           PCRE_JAVASCRIPT_COMPAT
   
       The  modifiers  that are enclosed in angle brackets are literal strings       The modifiers that are enclosed in angle brackets are  literal  strings
       as shown, including the angle brackets, but the letters within  can  be       as  shown,  including the angle brackets, but the letters within can be
       in  either case.  This example sets multiline matching with CRLF as the       in either case.  This example sets multiline matching with CRLF as  the
        line ending sequence:         line ending sequence:
   
          /^abc/m<CRLF>           /^abc/m<CRLF>
   
       As well as turning on  the  PCRE_UTF8/16/32  option,  the  /8  modifier       As  well  as  turning  on  the  PCRE_UTF8/16/32 option, the /8 modifier
       causes  all  non-printing  characters  in  output strings to be printed       causes all non-printing characters in  output  strings  to  be  printed
        using the \x{hh...} notation. Otherwise, those less than 0x100 are out-         using the \x{hh...} notation. Otherwise, those less than 0x100 are out-
        put in hex without the curly brackets.         put in hex without the curly brackets.
   
       Full  details  of  the PCRE options are given in the pcreapi documenta-       Full details of the PCRE options are given in  the  pcreapi  documenta-
        tion.         tion.
   
    Finding all matches in a string     Finding all matches in a string
   
       Searching for all possible matches within each subject  string  can  be       Searching  for  all  possible matches within each subject string can be
       requested  by  the  /g  or  /G modifier. After finding a match, PCRE is       requested by the /g or /G modifier. After  finding  a  match,  PCRE  is
        called again to search the remainder of the subject string. The differ-         called again to search the remainder of the subject string. The differ-
        ence between /g and /G is that the former uses the startoffset argument         ence between /g and /G is that the former uses the startoffset argument
       to pcre[16|32]_exec() to start searching at  a  new  point  within  the       to  pcre[16|32]_exec()  to  start  searching  at a new point within the
       entire  string  (which is in effect what Perl does), whereas the latter       entire string (which is in effect what Perl does), whereas  the  latter
       passes over a shortened substring.  This  makes  a  difference  to  the       passes  over  a  shortened  substring.  This  makes a difference to the
       matching  process  if  the  pattern  begins with a lookbehind assertion       matching process if the pattern  begins  with  a  lookbehind  assertion
        (including \b or \B).         (including \b or \B).
   
       If any call to pcre[16|32]_exec() in a /g or  /G  sequence  matches  an       If  any  call  to  pcre[16|32]_exec() in a /g or /G sequence matches an
       empty  string, the next call is done with the PCRE_NOTEMPTY_ATSTART and       empty string, the next call is done with the PCRE_NOTEMPTY_ATSTART  and
       PCRE_ANCHORED flags set in order  to  search  for  another,  non-empty,       PCRE_ANCHORED  flags  set  in  order  to search for another, non-empty,
       match  at  the same point. If this second match fails, the start offset       match at the same point. If this second match fails, the  start  offset
       is advanced, and the normal match is retried.  This  imitates  the  way       is  advanced,  and  the  normal match is retried. This imitates the way
        Perl handles such cases when using the /g modifier or the split() func-         Perl handles such cases when using the /g modifier or the split() func-
       tion. Normally, the start offset is advanced by one character,  but  if       tion.  Normally,  the start offset is advanced by one character, but if
       the  newline  convention  recognizes CRLF as a newline, and the current       the newline convention recognizes CRLF as a newline,  and  the  current
        character is CR followed by LF, an advance of two is used.         character is CR followed by LF, an advance of two is used.
   
    Other modifiers     Other modifiers
   
        There are yet more modifiers for controlling the way pcretest operates.         There are yet more modifiers for controlling the way pcretest operates.
   
       The /+ modifier requests that as well as outputting the substring  that       The  /+ modifier requests that as well as outputting the substring that
       matched  the  entire  pattern,  pcretest  should in addition output the       matched the entire pattern, pcretest  should  in  addition  output  the
       remainder of the subject string. This is useful  for  tests  where  the       remainder  of  the  subject  string. This is useful for tests where the
       subject  contains multiple copies of the same substring. If the + modi-       subject contains multiple copies of the same substring. If the +  modi-
       fier appears twice, the same action is taken for  captured  substrings.       fier  appears  twice, the same action is taken for captured substrings.
       In  each case the remainder is output on the following line with a plus       In each case the remainder is output on the following line with a  plus
       character following the capture number. Note that  this  modifier  must       character  following  the  capture number. Note that this modifier must
       not  immediately follow the /S modifier because /S+ and /S++ have other       not immediately follow the /S modifier because /S+ and /S++ have  other
        meanings.         meanings.
   
       The /= modifier requests that the  values  of  all  potential  captured       The  /=  modifier  requests  that  the values of all potential captured
       parentheses  be  output after a match. By default, only those up to the       parentheses be output after a match. By default, only those up  to  the
        highest one actually used in the match are output (corresponding to the         highest one actually used in the match are output (corresponding to the
        return code from pcre[16|32]_exec()). Values in the offsets vector cor-         return code from pcre[16|32]_exec()). Values in the offsets vector cor-
       responding to higher numbers should be set to -1, and these are  output       responding  to higher numbers should be set to -1, and these are output
       as  "<unset>".  This modifier gives a way of checking that this is hap-       as "<unset>". This modifier gives a way of checking that this  is  hap-
        pening.         pening.
   
       The /B modifier is a debugging feature. It requests that pcretest  out-       The  /B modifier is a debugging feature. It requests that pcretest out-
       put  a  representation of the compiled code after compilation. Normally       put a representation of the compiled code after  compilation.  Normally
       this information contains length and offset values; however, if  /Z  is       this  information  contains length and offset values; however, if /Z is
       also  present,  this data is replaced by spaces. This is a special fea-       also present, this data is replaced by spaces. This is a  special  fea-
       ture for use in the automatic test scripts; it ensures  that  the  same       ture  for  use  in the automatic test scripts; it ensures that the same
        output is generated for different internal link sizes.         output is generated for different internal link sizes.
   
       The  /D modifier is a PCRE debugging feature, and is equivalent to /BI,       The /D modifier is a PCRE debugging feature, and is equivalent to  /BI,
        that is, both the /B and the /I modifiers.         that is, both the /B and the /I modifiers.
   
       The /F modifier causes pcretest to flip the byte order  of  the  2-byte       The  /F  modifier  causes pcretest to flip the byte order of the 2-byte
        and 4-byte fields in the compiled pattern. This facility is for testing         and 4-byte fields in the compiled pattern. This facility is for testing
       the feature in PCRE that allows it to execute patterns that  were  com-       the  feature  in PCRE that allows it to execute patterns that wer       the  feature  in PCRE that allows it to execute patterns that wer
        piled on a host with a different endianness. This feature is not avail-         piled on a host with a different endianness. This feature is not avail-
       able when the POSIX interface to PCRE is being used, that is, when  the       able  when the POSIX interface to PCRE is being used, that is, when the
        /P pattern modifier is specified. See also the section about saving and         /P pattern modifier is specified. See also the section about saving and
        reloading compiled patterns below.         reloading compiled patterns below.
   
       The /I modifier requests that pcretest  output  information  about  the       The  /I  modifier  requests  that pcretest output information about the
       compiled  pattern (whether it is anchored, has a fixed first character,       compiled pattern (whether it is anchored, has a fixed first  character,
       and so on). It does this by calling pcre[16|32]_fullinfo()  after  com-       and  so  on). It does this by calling pcre[16|32]_fullinfo() after com-
       piling  a  pattern.  If the pattern is studied, the results of that are       piling a pattern. If the pattern is studied, the results  of  that  are
        also output.         also output.
   
       The /K modifier requests pcretest to show names from backtracking  con-       The  /K modifier requests pcretest to show names from backtracking con-
       trol  verbs  that  are  returned  from  calls to pcre[16|32]_exec(). It       trol verbs that are  returned  from  calls  to  pcre[16|32]_exec().  It
       causes pcretest to create a pcre[16|32]_extra  block  if  one  has  not       causes  pcretest  to  create  a  pcre[16|32]_extra block if one has not
       already  been  created by a call to pcre[16|32]_study(), and to set the       already been created by a call to pcre[16|32]_study(), and to  set  the
       PCRE_EXTRA_MARK flag and the mark field  within  it,  every  time  that       PCRE_EXTRA_MARK  flag  and  the  mark  field within it, every time that
       pcre[16|32]_exec()  is  called.  If  the  variable  that the mark field       pcre[16|32]_exec() is called. If  the  variable  that  the  mark  field
       points to is  non-NULL  for  a  match,  non-match,  or  partial  match,       points  to  is  non-NULL  for  a  match,  non-match,  or partial match,
       pcretest  prints  the  string  to which it points. For a match, this is       pcretest prints the string to which it points. For  a  match,  this  is
       shown on a line by itself, tagged with "MK:". For  a  non-match  it  is       shown  on  a  line  by itself, tagged with "MK:". For a non-match it is
        added to the message.         added to the message.
   
       The  /L modifier must be followed directly by the name of a locale, for       The /L modifier must be followed directly by the name of a locale,  for
        example,         example,
   
          /pattern/Lfr_FR           /pattern/Lfr_FR
   
        For this reason, it must be the last modifier. The given locale is set,         For this reason, it must be the last modifier. The given locale is set,
       pcre[16|32]_maketables()  is  called to build a set of character tables       pcre[16|32]_maketables() is called to build a set of  character  tables
       for the locale, and this is then passed to  pcre[16|32]_compile()  when       for  the  locale, and this is then passed to pcre[16|32]_compile() when
       compiling  the regular expression. Without an /L (or /T) modifier, NULL       compiling the regular expression. Without an /L (or /T) modifier,  NULL
       is passed as the tables pointer;  that  is,  /L  applies  only  to  the       is  passed  as  the  tables  pointer;  that  is, /L applies only to the
        expression on which it appears.         expression on which it appears.
   
       The  /M  modifier  causes the size in bytes of the memory block used to       The /M modifier causes the size in bytes of the memory  block  used  to
       hold the compiled pattern to be output. This does not include the  size       hold  the compiled pattern to be output. This does not include the size
       of  the  pcre[16|32] block; it is just the actual compiled data. If the       of the pcre[16|32] block; it is just the actual compiled data.  If  the
        pattern is successfully studied with the PCRE_STUDY_JIT_COMPILE option,         pattern is successfully studied with the PCRE_STUDY_JIT_COMPILE option,
        the size of the JIT compiled code is also output.         the size of the JIT compiled code is also output.
   
       The  /S  modifier  causes  pcre[16|32]_study()  to  be called after the       The /S modifier causes  pcre[16|32]_study()  to  be  called  after  the
       expression has been compiled, and the results used when the  expression       expression  has been compiled, and the results used when the expression
        is matched. There are a number of qualifying characters that may follow         is matched. There are a number of qualifying characters that may follow
        /S.  They may appear in any order.         /S.  They may appear in any order.
   
       If S is followed by an exclamation mark, pcre[16|32]_study() is  called       If /S is followed by an exclamation mark, pcre[16|32]_study() is called
       with  the PCRE_STUDY_EXTRA_NEEDED option, causing it always to return a       with the PCRE_STUDY_EXTRA_NEEDED option, causing it always to return  a
        pcre_extra block, even when studying discovers no useful information.         pcre_extra block, even when studying discovers no useful information.
   
        If /S is followed by a second S character, it suppresses studying, even         If /S is followed by a second S character, it suppresses studying, even
       if  it  was  requested  externally  by the -s command line option. This       if it was requested externally by the  -s  command  line  option.  This
       makes it possible to specify that certain patterns are always  studied,       makes  it possible to specify that certain patterns are always studied,
        and others are never studied, independently of -s. This feature is used         and others are never studied, independently of -s. This feature is used
        in the test files in a few cases where the output is different when the         in the test files in a few cases where the output is different when the
        pattern is studied.         pattern is studied.
   
       If  the  /S  modifier  is  followed  by  a  +  character,  the  call to       If the  /S  modifier  is  followed  by  a  +  character,  the  call  to
       pcre[16|32]_study() is made with all the JIT study options,  requesting       pcre[16|32]_study()  is made with all the JIT study options, requesting
       just-in-time  optimization  support if it is available, for both normal       just-in-time optimization support if it is available, for  both  normal
       and partial matching. If you want to restrict the JIT compiling  modes,       and  partial matching. If you want to restrict the JIT compiling modes,
        you can follow /S+ with a digit in the range 1 to 7:         you can follow /S+ with a digit in the range 1 to 7:
   
          1  normal match only           1  normal match only
Line 514  PATTERN MODIFIERS Line 523  PATTERN MODIFIERS
          7  all three modes (default)           7  all three modes (default)
   
        If /S++ is used instead of /S+ (with or without a following digit), the         If /S++ is used instead of /S+ (with or without a following digit), the
       text "(JIT)" is added to the first output line  after  a  match  or  no       text  "(JIT)"  is  added  to  the first output line after a match or no
        match when JIT-compiled code was actually used.         match when JIT-compiled code was actually used.
   
       Note  that  there  is  also  an independent /+ modifier; it must not be       Note that there is also an independent /+  modifier;  it  must  not  be
        given immediately after /S or /S+ because this will be misinterpreted.         given immediately after /S or /S+ because this will be misinterpreted.
   
        If JIT studying is successful, the compiled JIT code will automatically         If JIT studying is successful, the compiled JIT code will automatically
       be  used  when pcre[16|32]_exec() is run, except when incompatible run-       be used when pcre[16|32]_exec() is run, except when  incompatible  run-
       time options are specified. For more details, see the pcrejit  documen-       time  options are specified. For more details, see the pcrejit documen-
       tation.  See also the \J escape sequence below for a way of setting the       tation. See also the \J escape sequence below for a way of setting  the
        size of the JIT stack.         size of the JIT stack.
   
       Finally, if /S is followed by a minus  character,  JIT  compilation  is       Finally,  if  /S  is  followed by a minus character, JIT compilation is
       suppressed,  even if it was requested externally by the -s command line       suppressed, even if it was requested externally by the -s command  line
       option. This makes it possible to specify that JIT is never to be  used       option.  This makes it possible to specify that JIT is never to be used
        for certain patterns.         for certain patterns.
   
       The  /T  modifier  must be followed by a single digit. It causes a spe-       The /T modifier must be followed by a single digit. It  causes  a  spe-
        cific set of built-in character tables to be passed to pcre[16|32]_com-         cific set of built-in character tables to be passed to pcre[16|32]_com-
       pile().  It  is used in the standard PCRE tests to check behaviour with       pile(). It is used in the standard PCRE tests to check  behaviour  with
        different character tables. The digit specifies the tables as follows:         different character tables. The digit specifies the tables as follows:
   
          0   the default ASCII tables, as distributed in           0   the default ASCII tables, as distributed in
                pcre_chartables.c.dist                 pcre_chartables.c.dist
          1   a set of tables defining ISO 8859 characters           1   a set of tables defining ISO 8859 characters
   
       In table 1, some characters whose codes are greater than 128 are  iden-       In  table 1, some characters whose codes are greater than 128 are iden-
        tified as letters, digits, spaces, etc.         tified as letters, digits, spaces, etc.
   
    Using the POSIX wrapper API     Using the POSIX wrapper API
   
       The  /P modifier causes pcretest to call PCRE via the POSIX wrapper API       The /P modifier causes pcretest to call PCRE via the POSIX wrapper  API
       rather than its native API. This supports only the 8-bit library.  When       rather  than its native API. This supports only the 8-bit library. When
       /P  is set, the following modifiers set options for the regcomp() func-       /P is set, the following modifiers set options for the regcomp()  func-
        tion:         tion:
   
          /i    REG_ICASE           /i    REG_ICASE
Line 558  PATTERN MODIFIERS Line 567  PATTERN MODIFIERS
          /W    REG_UCP        )   the POSIX standard           /W    REG_UCP        )   the POSIX standard
          /8    REG_UTF8       )           /8    REG_UTF8       )
   
       The /+ modifier works as  described  above.  All  other  modifiers  are       The  /+  modifier  works  as  described  above. All other modifiers are
        ignored.         ignored.
   
      Locking out certain modifiers
   
          PCRE can be compiled with or without support for certain features  such
          as  UTF-8/16/32  or Unicode properties. Accordingly, the standard tests
          are split up into a number of different files  that  are  selected  for
          running  depending  on  which features are available. When updating the
          tests, it is all too easy to put a new test into the wrong file by mis-
          take;  for example, to put a test that requires UTF support into a file
          that is used when it is not available. To help detect such mistakes  as
          early  as  possible, there is a facility for locking out specific modi-
          fiers. If an input line for pcretest starts with the string "< forbid "
          the  following  sequence  of characters is taken as a list of forbidden
          modifiers. For example, in the test files that must not use UTF or Uni-
          code property support, this line appears:
   
            < forbid 8W
   
          This  locks out the /8 and /W modifiers. An immediate error is given if
          they are subsequently encountered. If the character string  contains  <
          but  not  >,  all  the  multi-character modifiers that begin with < are
          locked out. Otherwise, such modifiers must be  explicitly  listed,  for
          example:
   
            < forbid <JS><cr>
   
          There must be a single space between < and "forbid" for this feature to
          be recognised. If there is not, the line is  interpreted  either  as  a
          request  to  re-load  a pre-compiled pattern (see "SAVING AND RELOADING
          COMPILED PATTERNS" below) or, if there is a another < character,  as  a
          pattern that uses < as its delimiter.
   
   
 DATA LINES  DATA LINES
   
        Before  each  data  line  is  passed to pcre[16|32]_exec(), leading and         Before  each  data  line  is  passed to pcre[16|32]_exec(), leading and
Line 583  DATA LINES Line 623  DATA LINES
          \v         vertical tab (\x0b)           \v         vertical tab (\x0b)
          \nnn       octal character (up to 3 octal digits); always           \nnn       octal character (up to 3 octal digits); always
                       a byte unless > 255 in UTF-8 or 16-bit or 32-bit mode                        a byte unless > 255 in UTF-8 or 16-bit or 32-bit mode
            \o{dd...}  octal character (any number of octal digits}
          \xhh       hexadecimal byte (up to 2 hex digits)           \xhh       hexadecimal byte (up to 2 hex digits)
          \x{hh...}  hexadecimal character (any number of hex digits)           \x{hh...}  hexadecimal character (any number of hex digits)
          \A         pass the PCRE_ANCHORED option to pcre[16|32]_exec()           \A         pass the PCRE_ANCHORED option to pcre[16|32]_exec()
Line 974  SAVING AND RELOADING COMPILED PATTERNS Line 1015  SAVING AND RELOADING COMPILED PATTERNS
        writing the file, pcretest expects to read a new pattern.         writing the file, pcretest expects to read a new pattern.
   
        A  saved  pattern  can  be reloaded into pcretest by specifying < and a         A  saved  pattern  can  be reloaded into pcretest by specifying < and a
       file name instead of a pattern. The name of the file must not contain a       file name instead of a pattern. There must be no space  between  <  and
       < character, as otherwise pcretest will interpret the line as a pattern       the  file  name,  which  must  not  contain a < character, as otherwise
       delimited by < characters.  For example:       pcretest will interpret the line as a pattern delimited  by  <  charac-
        ters. For example:
   
           re> </some/file            re> </some/file
          Compiled pattern loaded from /some/file           Compiled pattern loaded from /some/file
          No study data           No study data
   
       If the pattern was previously studied with the  JIT  optimization,  the       If  the  pattern  was previously studied with the JIT optimization, the
       JIT  information cannot be saved and restored, and so is lost. When the       JIT information cannot be saved and restored, and so is lost. When  the
       pattern has been loaded, pcretest proceeds to read data  lines  in  the       pattern  has  been  loaded, pcretest proceeds to read data lines in the
        usual way.         usual way.
   
       You  can copy a file written by pcretest to a different host and reload       You can copy a file written by pcretest to a different host and  reload
       it there, even if the new host has opposite endianness to  the  one  on       it  there,  even  if the new host has opposite endianness to the one on
       which  the pattern was compiled. For example, you can compile on an i86       which the pattern was compiled. For example, you can compile on an  i86
       machine and run on a SPARC machine. When a pattern  is  reloaded  on  a       machine  and  run  on  a SPARC machine. When a pattern is reloaded on a
        host with different endianness, the confirmation message is changed to:         host with different endianness, the confirmation message is changed to:
   
          Compiled pattern (byte-inverted) loaded from /some/file           Compiled pattern (byte-inverted) loaded from /some/file
   
        The test suite contains some saved pre-compiled patterns with different         The test suite contains some saved pre-compiled patterns with different
       endianness. These are reloaded using "<!" instead  of  just  "<".  This       endianness.  These  are  reloaded  using "<!" instead of just "<". This
        suppresses the "(byte-inverted)" text so that the output is the same on         suppresses the "(byte-inverted)" text so that the output is the same on
       all hosts. It also forces debugging output once the  pattern  has  been       all  hosts.  It  also forces debugging output once        all  hosts.  It  also forces debugging output once the pattern has been
        reloaded.         reloaded.
   
       File  names  for  saving and reloading can be absolute or relative, but       File names for saving and reloading can be absolute  or  relative,  but
       note that the shell facility of expanding a file name that starts  with       note  that the shell facility of expanding a file name that starts with
        a tilde (~) is not available.         a tilde (~) is not available.
   
       The  ability to save and reload files in pcretest is intended for test-       The ability to save and reload files in pcretest is intended for  test-
       ing and experimentation. It is not intended for production use  because       ing  and experimentation. It is not intended for production use because
       only  a  single pattern can be written to a file. Furthermore, there is       only a single pattern can be written to a file. Furthermore,  there  is
       no facility for supplying  custom  character  tables  for  use  with  a       no  facility  for  supplying  custom  character  tables  for use with a
       reloaded  pattern.  If  the  original  pattern was compiled with custom       reloaded pattern. If the original  pattern  was  compiled  with  custom
       tables, an attempt to match a subject string using a  reloaded  pattern       tables,  an  attempt to match a subject string using a reloaded pattern
       is  likely to cause pcretest to crash.  Finally, if you attempt to load       is likely to cause pcretest to crash.  Finally, if you attempt to  load
        a file that is not in the correct format, the result is undefined.         a file that is not in the correct format, the result is undefined.
   
   
 SEE ALSO  SEE ALSO
   
       pcre(3), pcre16(3),  pcre32(3),  pcreapi(3),  pcrecallout(3),  pcrejit,       pcre(3),  pcre16(3),  pcre32(3),  pcreapi(3),  pcrecallout(3), pcrejit,
        pcrematching(3), pcrepartial(d), pcrepattern(3), pcreprecompile(3).         pcrematching(3), pcrepartial(d), pcrepattern(3), pcreprecompile(3).
   
   
Line 1030  AUTHOR Line 1072  AUTHOR
   
 REVISION  REVISION
   
       Last updated: 26 April 2013       Last updated: 12 November 2013
        Copyright (c) 1997-2013 University of Cambridge.         Copyright (c) 1997-2013 University of Cambridge.
Removed from v.1.1.1.4  
changed lines
  Added in v.1.1.1.5

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