diff -r 000000000000 -r 7f656887cf89 libraries/spcre/libpcre/pcre/doc/pcrepartial.3
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libraries/spcre/libpcre/pcre/doc/pcrepartial.3	Wed Jun 23 15:52:26 2010 +0100
@@ -0,0 +1,219 @@
+.TH PCREPARTIAL 3
+.SH NAME
+PCRE - Perl-compatible regular expressions
+.SH "PARTIAL MATCHING IN PCRE"
+.rs
+.sp
+In normal use of PCRE, if the subject string that is passed to
+\fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP matches as far as it goes, but is
+too short to match the entire pattern, PCRE_ERROR_NOMATCH is returned. There
+are circumstances where it might be helpful to distinguish this case from other
+cases in which there is no match.
+.P
+Consider, for example, an application where a human is required to type in data
+for a field with specific formatting requirements. An example might be a date
+in the form \fIddmmmyy\fP, defined by this pattern:
+.sp
+  ^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$
+.sp
+If the application sees the user's keystrokes one by one, and can check that
+what has been typed so far is potentially valid, it is able to raise an error
+as soon as a mistake is made, possibly beeping and not reflecting the
+character that has been typed. This immediate feedback is likely to be a better
+user interface than a check that is delayed until the entire string has been
+entered.
+.P
+PCRE supports the concept of partial matching by means of the PCRE_PARTIAL
+option, which can be set when calling \fBpcre_exec()\fP or
+\fBpcre_dfa_exec()\fP. When this flag is set for \fBpcre_exec()\fP, the return
+code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if at any time
+during the matching process the last part of the subject string matched part of
+the pattern. Unfortunately, for non-anchored matching, it is not possible to
+obtain the position of the start of the partial match. No captured data is set
+when PCRE_ERROR_PARTIAL is returned.
+.P
+When PCRE_PARTIAL is set for \fBpcre_dfa_exec()\fP, the return code
+PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the end of the
+subject is reached, there have been no complete matches, but there is still at
+least one matching possibility. The portion of the string that provided the
+partial match is set as the first matching string.
+.P
+Using PCRE_PARTIAL disables one of PCRE's optimizations. PCRE remembers the
+last literal byte in a pattern, and abandons matching immediately if such a
+byte is not present in the subject string. This optimization cannot be used
+for a subject string that might match only partially.
+.
+.
+.SH "RESTRICTED PATTERNS FOR PCRE_PARTIAL"
+.rs
+.sp
+Because of the way certain internal optimizations are implemented in the
+\fBpcre_exec()\fP function, the PCRE_PARTIAL option cannot be used with all
+patterns. These restrictions do not apply when \fBpcre_dfa_exec()\fP is used.
+For \fBpcre_exec()\fP, repeated single characters such as
+.sp
+  a{2,4}
+.sp
+and repeated single metasequences such as
+.sp
+  \ed+
+.sp
+are not permitted if the maximum number of occurrences is greater than one.
+Optional items such as \ed? (where the maximum is one) are permitted.
+Quantifiers with any values are permitted after parentheses, so the invalid
+examples above can be coded thus:
+.sp
+  (a){2,4}
+  (\ed)+
+.sp
+These constructions run more slowly, but for the kinds of application that are
+envisaged for this facility, this is not felt to be a major restriction.
+.P
+If PCRE_PARTIAL is set for a pattern that does not conform to the restrictions,
+\fBpcre_exec()\fP returns the error code PCRE_ERROR_BADPARTIAL (-13).
+You can use the PCRE_INFO_OKPARTIAL call to \fBpcre_fullinfo()\fP to find out
+if a compiled pattern can be used for partial matching.
+.
+.
+.SH "EXAMPLE OF PARTIAL MATCHING USING PCRETEST"
+.rs
+.sp
+If the escape sequence \eP is present in a \fBpcretest\fP data line, the
+PCRE_PARTIAL flag is used for the match. Here is a run of \fBpcretest\fP that
+uses the date example quoted above:
+.sp
+    re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/
+  data> 25jun04\eP
+   0: 25jun04
+   1: jun
+  data> 25dec3\eP
+  Partial match
+  data> 3ju\eP
+  Partial match
+  data> 3juj\eP
+  No match
+  data> j\eP
+  No match
+.sp
+The first data string is matched completely, so \fBpcretest\fP shows the
+matched substrings. The remaining four strings do not match the complete
+pattern, but the first two are partial matches. The same test, using
+\fBpcre_dfa_exec()\fP matching (by means of the \eD escape sequence), produces
+the following output:
+.sp
+    re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/
+  data> 25jun04\eP\eD
+   0: 25jun04
+  data> 23dec3\eP\eD
+  Partial match: 23dec3
+  data> 3ju\eP\eD
+  Partial match: 3ju
+  data> 3juj\eP\eD
+  No match
+  data> j\eP\eD
+  No match
+.sp
+Notice that in this case the portion of the string that was matched is made
+available.
+.
+.
+.SH "MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()"
+.rs
+.sp
+When a partial match has been found using \fBpcre_dfa_exec()\fP, it is possible
+to continue the match by providing additional subject data and calling
+\fBpcre_dfa_exec()\fP again with the same compiled regular expression, this
+time setting the PCRE_DFA_RESTART option. You must also pass the same working
+space as before, because this is where details of the previous partial match
+are stored. Here is an example using \fBpcretest\fP, using the \eR escape
+sequence to set the PCRE_DFA_RESTART option (\eP and \eD are as above):
+.sp
+    re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/
+  data> 23ja\eP\eD
+  Partial match: 23ja
+  data> n05\eR\eD
+   0: n05
+.sp
+The first call has "23ja" as the subject, and requests partial matching; the
+second call has "n05" as the subject for the continued (restarted) match.
+Notice that when the match is complete, only the last part is shown; PCRE does
+not retain the previously partially-matched string. It is up to the calling
+program to do that if it needs to.
+.P
+You can set PCRE_PARTIAL with PCRE_DFA_RESTART to continue partial matching
+over multiple segments. This facility can be used to pass very long subject
+strings to \fBpcre_dfa_exec()\fP. However, some care is needed for certain
+types of pattern.
+.P
+1. If the pattern contains tests for the beginning or end of a line, you need
+to pass the PCRE_NOTBOL or PCRE_NOTEOL options, as appropriate, when the
+subject string for any call does not contain the beginning or end of a line.
+.P
+2. If the pattern contains backward assertions (including \eb or \eB), you need
+to arrange for some overlap in the subject strings to allow for this. For
+example, you could pass the subject in chunks that are 500 bytes long, but in
+a buffer of 700 bytes, with the starting offset set to 200 and the previous 200
+bytes at the start of the buffer.
+.P
+3. Matching a subject string that is split into multiple segments does not
+always produce exactly the same result as matching over one single long string.
+The difference arises when there are multiple matching possibilities, because a
+partial match result is given only when there are no completed matches in a
+call to \fBpcre_dfa_exec()\fP. This means that as soon as the shortest match has
+been found, continuation to a new subject segment is no longer possible.
+Consider this \fBpcretest\fP example:
+.sp
+    re> /dog(sbody)?/
+  data> do\eP\eD
+  Partial match: do
+  data> gsb\eR\eP\eD
+   0: g
+  data> dogsbody\eD
+   0: dogsbody
+   1: dog
+.sp
+The pattern matches the words "dog" or "dogsbody". When the subject is
+presented in several parts ("do" and "gsb" being the first two) the match stops
+when "dog" has been found, and it is not possible to continue. On the other
+hand, if "dogsbody" is presented as a single string, both matches are found.
+.P
+Because of this phenomenon, it does not usually make sense to end a pattern
+that is going to be matched in this way with a variable repeat.
+.P
+4. Patterns that contain alternatives at the top level which do not all
+start with the same pattern item may not work as expected. For example,
+consider this pattern:
+.sp
+  1234|3789
+.sp
+If the first part of the subject is "ABC123", a partial match of the first
+alternative is found at offset 3. There is no partial match for the second
+alternative, because such a match does not start at the same point in the
+subject string. Attempting to continue with the string "789" does not yield a
+match because only those alternatives that match at one point in the subject
+are remembered. The problem arises because the start of the second alternative
+matches within the first alternative. There is no problem with anchored
+patterns or patterns such as:
+.sp
+  1234|ABCD
+.sp
+where no string can be a partial match for both alternatives.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 04 June 2007
+Copyright (c) 1997-2007 University of Cambridge.
+.fi