1 files changed, 95 insertions, 0 deletions
diff --git a/srclib/pcre/doc/pcrepartial.3 b/srclib/pcre/doc/pcrepartial.3
new file mode 100644
index 0000000000..3489c18195
--- /dev/null
+++ b/srclib/pcre/doc/pcrepartial.3
@@ -0,0 +1,95 @@
+.TH PCRE 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 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. 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.
+.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 PCRE, the
+PCRE_PARTIAL option cannot be used with all patterns. 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).
+.
+.
+.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\P
+   0: 25jun04
+   1: jun
+  data> 25dec3\P
+  Partial match
+  data> 3ju\P
+  Partial match
+  data> 3juj\P
+  No match
+  data> j\P
+  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.
+.
+.
+.P
+.in 0
+Last updated: 08 September 2004
+.br
+Copyright (c) 1997-2004 University of Cambridge.