Load pcre-6.0 into code/trunk.

git-svn-id: svn://vcs.exim.org/pcre/code/trunk@77 2f5784b3-3f2a-0410-8824-cb99058d5e15

1 files changed, 103 insertions, 14 deletions

diff --git a/doc/pcrepartial.3 b/doc/pcrepartial.3
index 3489c18..ffc0c6e 100644
--- a/doc/pcrepartial.3
+++ b/doc/pcrepartial.3
@@ -5,10 +5,10 @@ PCRE - Perl-compatible regular expressions
 .rs
 .sp
 In normal use of PCRE, if the subject string that is passed to
-\fBpcre_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.
+\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
@@ -24,10 +24,19 @@ 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. When this is done, the
-return code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if at any
-time during the matching process the entire subject string matched part of the
-pattern. No captured data is set when this occurs.
+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
@@ -38,9 +47,10 @@ 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 PCRE, the
-PCRE_PARTIAL option cannot be used with all patterns. Repeated single
-characters such as
+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
@@ -85,11 +95,90 @@ uses the date example quoted above:
 .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.
+pattern, but the first two are partial matches. The same test, using DFA
+matching (by means of the \eD escape sequence), produces the following output:
+.sp
+    re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+  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 PCRE_DFA_RESTART option and the same
+working space (where details of the previous partial match are stored). Here is
+an example using \fBpcretest\fP, where the \eR escape sequence sets the
+PCRE_DFA_RESTART option and the \eD escape sequence requests the use of
+\fBpcre_dfa_exec()\fP:
+.sp
+    re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+  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
+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 were 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
 .in 0
-Last updated: 08 September 2004
+Last updated: 28 February 2005
 .br
-Copyright (c) 1997-2004 University of Cambridge.
+Copyright (c) 1997-2005 University of Cambridge.