/[pcre]/code/trunk/doc/html/pcrepattern.html

Diff of /code/trunk/doc/html/pcrepattern.html

Parent Directory | Revision Log | View Patch Patch

-revision 834 by ph10,
Tue Dec  6 15:38:01 2011 UTC
+revision 835 by ph10,
Wed Dec 28 16:10:09 2011 UTC
 Line 268 
 one of the following escape sequences th
    \t        tab (hex 09)
    \ddd      character with octal code ddd, or back reference
    \xhh      character with hex code hh
-   \x{hhh..} character with hex code hhh.. (non-JavaScript mode)
+   \x{hhh..} character with hex code hhh..
-   \uhhhh    character with hex code hhhh (JavaScript mode only)
  </pre>
  The precise effect of \cx is as follows: if x is a lower case letter, it
  is converted to upper case. Then bit 6 of the character (hex 40) is inverted.
-Line 281 
 values are valid. A lower case letter is
+Line 280 
 values are valid. A lower case letter is
 xc0 bits are flipped.)
  </P>
  <P>
- By default, after \x, from zero to two hexadecimal digits are read (letters
+ After \x, from zero to two hexadecimal digits are read (letters can be in
- can be in upper or lower case). Any number of hexadecimal digits may appear
+ upper or lower case). Any number of hexadecimal digits may appear between \x{
- between \x{ and }, but the value of the character code must be less than 256
+ and }, but the value of the character code must be less than 256 in non-UTF-8
- in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is, the maximum
+ mode, and less than 2**31 in UTF-8 mode. That is, the maximum value in
- value in hexadecimal is 7FFFFFFF. Note that this is bigger than the largest
+ hexadecimal is 7FFFFFFF. Note that this is bigger than the largest Unicode code
- Unicode code point, which is 10FFFF.
+ point, which is 10FFFF.
  </P>
  <P>
  If characters other than hexadecimal digits appear between \x{ and }, or if
-Line 295 
 initial \x will be interpreted as a basi
+Line 294 
 initial \x will be interpreted as a basi
  following digits, giving a character whose value is zero.
  </P>
  <P>
- If the PCRE_JAVASCRIPT_COMPAT option is set, the interpretation of \x is
- as just described only when it is followed by two hexadecimal digits.
- Otherwise, it matches a literal "x" character. In JavaScript mode, support for
- code points greater than 256 is provided by \u, which must be followed by
- four hexadecimal digits; otherwise it matches a literal "u" character.
- </P>
- <P>
  Characters whose value is less than 256 can be defined by either of the two
- syntaxes for \x (or by \u in JavaScript mode). There is no difference in the
+ syntaxes for \x. There is no difference in the way they are handled. For
- way they are handled. For example, \xdc is exactly the same as \x{dc} (or
+ example, \xdc is exactly the same as \x{dc}.
- \u00dc in JavaScript mode).
  </P>
  <P>
  After \0 up to two further octal digits are read. If there are fewer than two
-Line 347 
 zero, because no more than three octal d
+Line 338 
 zero, because no more than three octal d
  </P>
  <P>
  All the sequences that define a single character value can be used both inside
- and outside character classes. In addition, inside a character class, \b is
+ and outside character classes. In addition, inside a character class, the
- interpreted as the backspace character (hex 08).
+ sequence \b is interpreted as the backspace character (hex 08). The sequences
- </P>
+ \B, \N, \R, and \X are not special inside a character class. Like any other
- <P>
+ unrecognized escape sequences, they are treated as the literal characters "B",
- \N is not allowed in a character class. \B, \R, and \X are not special
+ "N", "R", and "X" by default, but cause an error if the PCRE_EXTRA option is
- inside a character class. Like other unrecognized escape sequences, they are
+ set. Outside a character class, these sequences have different meanings.
- treated as the literal characters "B", "R", and "X" by default, but cause an
- error if the PCRE_EXTRA option is set. Outside a character class, these
- sequences have different meanings.
- </P>
- <br><b>
- Unsupported escape sequences
- </b><br>
- <P>
- In Perl, the sequences \l, \L, \u, and \U are recognized by its string
- handler and used to modify the case of following characters. By default, PCRE
- does not support these escape sequences. However, if the PCRE_JAVASCRIPT_COMPAT
- option is set, \U matches a "U" character, and \u can be used to define a
- character by code point, as described in the previous section.
  </P>
  <br><b>
  Absolute and relative back references
-Line 411 
 Another use of backslash is for specifyi
+Line 389 
 Another use of backslash is for specifyi
  There is also the single sequence \N, which matches a non-newline character.
  This is the same as
  <a href="#fullstopdot">the "." metacharacter</a>
- when PCRE_DOTALL is not set. Perl also uses \N to match characters by name;
+ when PCRE_DOTALL is not set.
- PCRE does not support this.
  </P>
  <P>
  Each pair of lower and upper case escape sequences partitions the complete set
-Line 986 
 special meaning in a character class.
+Line 963 
 special meaning in a character class.
  <P>
  The escape sequence \N behaves like a dot, except that it is not affected by
  the PCRE_DOTALL option. In other words, it matches any character except one
- that signifies the end of a line. Perl also uses \N to match characters by
+ that signifies the end of a line.
- name; PCRE does not support this.
  </P>
  <br><a name="SEC7" href="#TOC1">MATCHING A SINGLE BYTE</a><br>
  <P>
-Line 1003 
 processing unless the PCRE_NO_UTF8_CHECK
+Line 979 
 processing unless the PCRE_NO_UTF8_CHECK
  </P>
  <P>
  PCRE does not allow \C to appear in lookbehind assertions
- <a href="#lookbehind">(described below)</a>
+ <a href="#lookbehind">(described below),</a>
- in UTF-8 mode, because this would make it impossible to calculate the length of
+ because in UTF-8 mode this would make it impossible to calculate the length of
  the lookbehind.
  </P>
  <P>
-Line 1950 
 match. If there are insufficient charact
+Line 1926 
 match. If there are insufficient charact
  assertion fails.
  </P>
  <P>
- In UTF-8 mode, PCRE does not allow the \C escape (which matches a single byte,
+ PCRE does not allow the \C escape (which matches a single byte in UTF-8 mode)
- even in UTF-8 mode) to appear in lookbehind assertions, because it makes it
+ to appear in lookbehind assertions, because it makes it impossible to calculate
- impossible to calculate the length of the lookbehind. The \X and \R escapes,
+ the length of the lookbehind. The \X and \R escapes, which can match
- which can match different numbers of bytes, are also not permitted.
+ different numbers of bytes, are also not permitted.
  </P>
  <P>
  <a href="#subpatternsassubroutines">"Subroutine"</a>
-Line 2535 
 failing negative assertion, they cause a
+Line 2511 
 failing negative assertion, they cause a
  If any of these verbs are used in an assertion or in a subpattern that is
  called as a subroutine (whether or not recursively), their effect is confined
  to that subpattern; it does not extend to the surrounding pattern, with one
- exception: the name from a *(MARK), (*PRUNE), or (*THEN) that is encountered in
+ exception: a *MARK that is encountered in a positive assertion <i>is</i> passed
- a successful positive assertion <i>is</i> passed back when a match succeeds
+ back (compare capturing parentheses in assertions). Note that such subpatterns
- (compare capturing parentheses in assertions). Note that such subpatterns are
+ are processed as anchored at the point where they are tested. Note also that
- processed as anchored at the point where they are tested. Note also that Perl's
+ Perl's treatment of subroutines is different in some cases.
- treatment of subroutines is different in some cases.
  </P>
  <P>
  The new verbs make use of what was previously invalid syntax: an opening
-Line 2561 
 the start-of-match optimizations by sett
+Line 2536 
 the start-of-match optimizations by sett
  when calling <b>pcre_compile()</b> or <b>pcre_exec()</b>, or by starting the
  pattern with (*NO_START_OPT).
  </P>
- <P>
- Experiments with Perl suggest that it too has similar optimizations, sometimes
- leading to anomalous results.
- </P>
  <br><b>
  Verbs that act immediately
  </b><br>
-Line 2612 
 A name is always required with this verb
+Line 2583 
 A name is always required with this verb
  (*MARK) as you like in a pattern, and their names do not have to be unique.
  </P>
  <P>
- When a match succeeds, the name of the last-encountered (*MARK) on the matching
+ When a match succeeds, the name of the last-encountered (*MARK) is passed back
- path is passed back to the caller via the <i>pcre_extra</i> data structure, as
+ to the caller via the <i>pcre_extra</i> data structure, as described in the
- described in the
  <a href="pcreapi.html#extradata">section on <i>pcre_extra</i></a>
  in the
  <a href="pcreapi.html"><b>pcreapi</b></a>
- documentation. Here is an example of <b>pcretest</b> output, where the /K
+ documentation. No data is returned for a partial match. Here is an example of
- modifier requests the retrieval and outputting of (*MARK) data:
+ <b>pcretest</b> output, where the /K modifier requests the retrieval and
+ outputting of (*MARK) data:
  <pre>
-     re&#62; /X(*MARK:A)Y|X(*MARK:B)Z/K
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
-   data&#62; XY
+   XY
 : XY
    MK: A
    XZ
-Line 2640 
 passed back if it is the last-encountere
+Line 2611 
 passed back if it is the last-encountere
  assertions.
  </P>
  <P>
- After a partial match or a failed match, the name of the last encountered
+ A name may also be returned after a failed match if the final path through the
- (*MARK) in the entire match process is returned. For example:
+ pattern involves (*MARK). However, unless (*MARK) used in conjunction with
+ (*COMMIT), this is unlikely to happen for an unanchored pattern because, as the
+ starting point for matching is advanced, the final check is often with an empty
+ string, causing a failure before (*MARK) is reached. For example:
  <pre>
-     re&#62; /X(*MARK:A)Y|X(*MARK:B)Z/K
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
-   data&#62; XP
+   XP
+   No match
+ </pre>
+ There are three potential starting points for this match (starting with X,
+ starting with P, and with an empty string). If the pattern is anchored, the
+ result is different:
+ <pre>
+   /^X(*MARK:A)Y|^X(*MARK:B)Z/K
+   XP
    No match, mark = B
  </pre>
- Note that in this unanchored example the mark is retained from the match
+ PCRE's start-of-match optimizations can also interfere with this. For example,
- attempt that started at the letter "X". Subsequent match attempts starting at
+ if, as a result of a call to <b>pcre_study()</b>, it knows the minimum
- "P" and then with an empty string do not get as far as the (*MARK) item, but
+ subject length for a match, a shorter subject will not be scanned at all.
- nevertheless do not reset it.
+ </P>
+ <P>
+ Note that similar anomalies (though different in detail) exist in Perl, no
+ doubt for the same reasons. The use of (*MARK) data after a failed match of an
+ unanchored pattern is not recommended, unless (*COMMIT) is involved.
  </P>
  <br><b>
  Verbs that act after backtracking
-Line 2689 
 Note that (*COMMIT) at the start of a pa
+Line 2675 
 Note that (*COMMIT) at the start of a pa
  unless PCRE's start-of-match optimizations are turned off, as shown in this
  <b>pcretest</b> example:
  <pre>
-     re&#62; /(*COMMIT)abc/
+   /(*COMMIT)abc/
-   data&#62; xyzabc
+   xyzabc
 : abc
    xyzabc\Y
    No match
-Line 2711 
 reached, or when matching to the right o
+Line 2697 
 reached, or when matching to the right o
  the right, backtracking cannot cross (*PRUNE). In simple cases, the use of
  (*PRUNE) is just an alternative to an atomic group or possessive quantifier,
  but there are some uses of (*PRUNE) that cannot be expressed in any other way.
- The behaviour of (*PRUNE:NAME) is the same as (*MARK:NAME)(*PRUNE). In an
+ The behaviour of (*PRUNE:NAME) is the same as (*MARK:NAME)(*PRUNE) when the
- anchored pattern (*PRUNE) has the same effect as (*COMMIT).
+ match fails completely; the name is passed back if this is the final attempt.
+ (*PRUNE:NAME) does not pass back a name if the match succeeds. In an anchored
+ pattern (*PRUNE) has the same effect as (*COMMIT).
  <pre>
    (*SKIP)
  </pre>
-Line 2738 
 following pattern fails to match, the pr
+Line 2726 
 following pattern fails to match, the pr
  searched for the most recent (*MARK) that has the same name. If one is found,
  the "bumpalong" advance is to the subject position that corresponds to that
  (*MARK) instead of to where (*SKIP) was encountered. If no (*MARK) with a
- matching name is found, the (*SKIP) is ignored.
+ matching name is found, normal "bumpalong" of one character happens (that is,
+ the (*SKIP) is ignored).
  <pre>
    (*THEN) or (*THEN:NAME)
  </pre>
-Line 2752 
 be used for a pattern-based if-then-else
+Line 2741 
 be used for a pattern-based if-then-else
  If the COND1 pattern matches, FOO is tried (and possibly further items after
  the end of the group if FOO succeeds); on failure, the matcher skips to the
  second alternative and tries COND2, without backtracking into COND1. The
- behaviour of (*THEN:NAME) is exactly the same as (*MARK:NAME)(*THEN).
+ behaviour of (*THEN:NAME) is exactly the same as (*MARK:NAME)(*THEN) if the
- If (*THEN) is not inside an alternation, it acts like (*PRUNE).
+ overall match fails. If (*THEN) is not inside an alternation, it acts like
+ (*PRUNE).
  </P>
  <P>
  Note that a subpattern that does not contain a | character is just a part of
-Line 2829 
 Cambridge CB2 3QH, England.
+Line 2819 
 Cambridge CB2 3QH, England.
  </P>
  <br><a name="SEC28" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 29 November 2011
+ Last updated: 19 October 2011
  <br>
  Copyright &copy; 1997-2011 University of Cambridge.
  <br>

 Legend:



Removed from v.834
 


changed lines


 
Added in v.835
 Legend:



Removed from v.834
 


changed lines


 
Added in v.835
-Removed from v.834
+Added in v.835

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12