+++ /dev/null
-The pcretest program\r
---------------------\r
-\r
-This program is intended for testing PCRE, but it can also be used for\r
-experimenting with regular expressions.\r
-\r
-If it is given two filename arguments, it reads from the first and writes to\r
-the second. If it is given only one filename argument, it reads from that file\r
-and writes to stdout. Otherwise, it reads from stdin and writes to stdout, and\r
-prompts for each line of input, using "re>" to prompt for regular expressions,\r
-and "data>" to prompt for data lines.\r
-\r
-The program handles any number of sets of input on a single input file. Each\r
-set starts with a regular expression, and continues with any number of data\r
-lines to be matched against the pattern. An empty line signals the end of the\r
-data lines, at which point a new regular expression is read. The regular\r
-expressions are given enclosed in any non-alphameric delimiters other than\r
-backslash, for example\r
-\r
- /(a|bc)x+yz/\r
-\r
-White space before the initial delimiter is ignored. A regular expression may\r
-be continued over several input lines, in which case the newline characters are\r
-included within it. See the test input files in the testdata directory for many\r
-examples. It is possible to include the delimiter within the pattern by\r
-escaping it, for example\r
-\r
- /abc\/def/\r
-\r
-If you do so, the escape and the delimiter form part of the pattern, but since\r
-delimiters are always non-alphameric, this does not affect its interpretation.\r
-If the terminating delimiter is immediately followed by a backslash, for\r
-example,\r
-\r
- /abc/\\r
-\r
-then a backslash is added to the end of the pattern. This is done to provide a\r
-way of testing the error condition that arises if a pattern finishes with a\r
-backslash, because\r
-\r
- /abc\/\r
-\r
-is interpreted as the first line of a pattern that starts with "abc/", causing\r
-pcretest to read the next line as a continuation of the regular expression.\r
-\r
-\r
-PATTERN MODIFIERS\r
------------------\r
-\r
-The pattern may be followed by i, m, s, or x to set the PCRE_CASELESS,\r
-PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED options, respectively. For\r
-example:\r
-\r
- /caseless/i\r
-\r
-These modifier letters have the same effect as they do in Perl. There are\r
-others which set PCRE options that do not correspond to anything in Perl: /A,\r
-/E, and /X set PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, and PCRE_EXTRA respectively.\r
-\r
-Searching for all possible matches within each subject string can be requested\r
-by the /g or /G modifier. After finding a match, PCRE is called again to search\r
-the remainder of the subject string. The difference between /g and /G is that\r
-the former uses the startoffset argument to pcre_exec() to start searching at\r
-a new point within the entire string (which is in effect what Perl does),\r
-whereas the latter passes over a shortened substring. This makes a difference\r
-to the matching process if the pattern begins with a lookbehind assertion\r
-(including \b or \B).\r
-\r
-If any call to pcre_exec() in a /g or /G sequence matches an empty string, the\r
-next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED flags set in order\r
-to search for another, non-empty, match at the same point. If this second match\r
-fails, the start offset is advanced by one, and the normal match is retried.\r
-This imitates the way Perl handles such cases when using the /g modifier or the\r
-split() function.\r
-\r
-There are a number of other modifiers for controlling the way pcretest\r
-operates.\r
-\r
-The /+ modifier requests that as well as outputting the substring that matched\r
-the entire pattern, pcretest should in addition output the remainder of the\r
-subject string. This is useful for tests where the subject contains multiple\r
-copies of the same substring.\r
-\r
-The /L modifier must be followed directly by the name of a locale, for example,\r
-\r
- /pattern/Lfr\r
-\r
-For this reason, it must be the last modifier letter. The given locale is set,\r
-pcre_maketables() is called to build a set of character tables for the locale,\r
-and this is then passed to pcre_compile() when compiling the regular\r
-expression. Without an /L modifier, NULL is passed as the tables pointer; that\r
-is, /L applies only to the expression on which it appears.\r
-\r
-The /I modifier requests that pcretest output information about the compiled\r
-expression (whether it is anchored, has a fixed first character, and so on). It\r
-does this by calling pcre_fullinfo() after compiling an expression, and\r
-outputting the information it gets back. If the pattern is studied, the results\r
-of that are also output.\r
-\r
-The /D modifier is a PCRE debugging feature, which also assumes /I. It causes\r
-the internal form of compiled regular expressions to be output after\r
-compilation.\r
-\r
-The /S modifier causes pcre_study() to be called after the expression has been\r
-compiled, and the results used when the expression is matched.\r
-\r
-The /M modifier causes the size of memory block used to hold the compiled\r
-pattern to be output.\r
-\r
-The /P modifier causes pcretest to call PCRE via the POSIX wrapper API rather\r
-than its native API. When this is done, all other modifiers except /i, /m, and\r
-/+ are ignored. REG_ICASE is set if /i is present, and REG_NEWLINE is set if /m\r
-is present. The wrapper functions force PCRE_DOLLAR_ENDONLY always, and\r
-PCRE_DOTALL unless REG_NEWLINE is set.\r
-\r
-The /8 modifier causes pcretest to call PCRE with the PCRE_UTF8 option set.\r
-This turns on the (currently incomplete) support for UTF-8 character handling\r
-in PCRE, provided that it was compiled with this support enabled. This modifier\r
-also causes any non-printing characters in output strings to be printed using\r
-the \x{hh...} notation if they are valid UTF-8 sequences.\r
-\r
-\r
-DATA LINES\r
-----------\r
-\r
-Before each data line is passed to pcre_exec(), leading and trailing whitespace\r
-is removed, and it is then scanned for \ escapes. The following are recognized:\r
-\r
- \a alarm (= BEL)\r
- \b backspace\r
- \e escape\r
- \f formfeed\r
- \n newline\r
- \r carriage return\r
- \t tab\r
- \v vertical tab\r
- \nnn octal character (up to 3 octal digits)\r
- \xhh hexadecimal character (up to 2 hex digits)\r
- \x{hh...} hexadecimal UTF-8 character\r
-\r
- \A pass the PCRE_ANCHORED option to pcre_exec()\r
- \B pass the PCRE_NOTBOL option to pcre_exec()\r
- \Cdd call pcre_copy_substring() for substring dd after a successful\r
- match (any decimal number less than 32)\r
- \Gdd call pcre_get_substring() for substring dd after a successful\r
- match (any decimal number less than 32)\r
- \L call pcre_get_substringlist() after a successful match\r
- \N pass the PCRE_NOTEMPTY option to pcre_exec()\r
- \Odd set the size of the output vector passed to pcre_exec() to dd\r
- (any number of decimal digits)\r
- \Z pass the PCRE_NOTEOL option to pcre_exec()\r
-\r
-A backslash followed by anything else just escapes the anything else. If the\r
-very last character is a backslash, it is ignored. This gives a way of passing\r
-an empty line as data, since a real empty line terminates the data input.\r
-\r
-If /P was present on the regex, causing the POSIX wrapper API to be used, only\r
-\B, and \Z have any effect, causing REG_NOTBOL and REG_NOTEOL to be passed to\r
-regexec() respectively.\r
-\r
-The use of \x{hh...} to represent UTF-8 characters is not dependent on the use\r
-of the /8 modifier on the pattern. It is recognized always. There may be any\r
-number of hexadecimal digits inside the braces. The result is from one to six\r
-bytes, encoded according to the UTF-8 rules.\r
-\r
-\r
-OUTPUT FROM PCRETEST\r
---------------------\r
-\r
-When a match succeeds, pcretest outputs the list of captured substrings that\r
-pcre_exec() returns, starting with number 0 for the string that matched the\r
-whole pattern. Here is an example of an interactive pcretest run.\r
-\r
- $ pcretest\r
- PCRE version 2.06 08-Jun-1999\r
-\r
- re> /^abc(\d+)/\r
- data> abc123\r
- 0: abc123\r
- 1: 123\r
- data> xyz\r
- No match\r
-\r
-If the strings contain any non-printing characters, they are output as \0x\r
-escapes, or as \x{...} escapes if the /8 modifier was present on the pattern.\r
-If the pattern has the /+ modifier, then the output for substring 0 is followed\r
-by the the rest of the subject string, identified by "0+" like this:\r
-\r
- re> /cat/+\r
- data> cataract\r
- 0: cat\r
- 0+ aract\r
-\r
-If the pattern has the /g or /G modifier, the results of successive matching\r
-attempts are output in sequence, like this:\r
-\r
- re> /\Bi(\w\w)/g\r
- data> Mississippi\r
- 0: iss\r
- 1: ss\r
- 0: iss\r
- 1: ss\r
- 0: ipp\r
- 1: pp\r
-\r
-"No match" is output only if the first match attempt fails.\r
-\r
-If any of \C, \G, or \L are present in a data line that is successfully\r
-matched, the substrings extracted by the convenience functions are output with\r
-C, G, or L after the string number instead of a colon. This is in addition to\r
-the normal full list. The string length (that is, the return from the\r
-extraction function) is given in parentheses after each string for \C and \G.\r
-\r
-Note that while patterns can be continued over several lines (a plain ">"\r
-prompt is used for continuations), data lines may not. However newlines can be\r
-included in data by means of the \n escape.\r
-\r
-\r
-COMMAND LINE OPTIONS\r
---------------------\r
-\r
-If the -p option is given to pcretest, it is equivalent to adding /P to each\r
-regular expression: the POSIX wrapper API is used to call PCRE. None of the\r
-following flags has any effect in this case.\r
-\r
-If the option -d is given to pcretest, it is equivalent to adding /D to each\r
-regular expression: the internal form is output after compilation.\r
-\r
-If the option -i is given to pcretest, it is equivalent to adding /I to each\r
-regular expression: information about the compiled pattern is given after\r
-compilation.\r
-\r
-If the option -m is given to pcretest, it outputs the size of each compiled\r
-pattern after it has been compiled. It is equivalent to adding /M to each\r
-regular expression. For compatibility with earlier versions of pcretest, -s is\r
-a synonym for -m.\r
-\r
-If the -t option is given, each compile, study, and match is run 20000 times\r
-while being timed, and the resulting time per compile or match is output in\r
-milliseconds. Do not set -t with -m, because you will then get the size output\r
-20000 times and the timing will be distorted. If you want to change the number\r
-of repetitions used for timing, edit the definition of LOOPREPEAT at the top of\r
-pcretest.c\r
-\r
-Philip Hazel <ph10@cam.ac.uk>\r
-August 2000\r
projects / privoxy.git / blobdiff