243 lines
9.6 KiB
HTML
243 lines
9.6 KiB
HTML
<html>
|
|
<head>
|
|
<title>pcrepartial specification</title>
|
|
</head>
|
|
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
|
|
<h1>pcrepartial man page</h1>
|
|
<p>
|
|
Return to the <a href="index.html">PCRE index page</a>.
|
|
</p>
|
|
<p>
|
|
This page is part of the PCRE HTML documentation. It was generated automatically
|
|
from the original man page. If there is any nonsense in it, please consult the
|
|
man page, in case the conversion went wrong.
|
|
<br>
|
|
<ul>
|
|
<li><a name="TOC1" href="#SEC1">PARTIAL MATCHING IN PCRE</a>
|
|
<li><a name="TOC2" href="#SEC2">RESTRICTED PATTERNS FOR PCRE_PARTIAL</a>
|
|
<li><a name="TOC3" href="#SEC3">EXAMPLE OF PARTIAL MATCHING USING PCRETEST</a>
|
|
<li><a name="TOC4" href="#SEC4">MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()</a>
|
|
<li><a name="TOC5" href="#SEC5">AUTHOR</a>
|
|
<li><a name="TOC6" href="#SEC6">REVISION</a>
|
|
</ul>
|
|
<br><a name="SEC1" href="#TOC1">PARTIAL MATCHING IN PCRE</a><br>
|
|
<P>
|
|
In normal use of PCRE, if the subject string that is passed to
|
|
<b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> 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>
|
|
<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 <i>ddmmmyy</i>, defined by this pattern:
|
|
<pre>
|
|
^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$
|
|
</pre>
|
|
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>
|
|
<P>
|
|
PCRE supports the concept of partial matching by means of the PCRE_PARTIAL
|
|
option, which can be set when calling <b>pcre_exec()</b> or
|
|
<b>pcre_dfa_exec()</b>. When this flag is set for <b>pcre_exec()</b>, 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>
|
|
<P>
|
|
When PCRE_PARTIAL is set for <b>pcre_dfa_exec()</b>, 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>
|
|
<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.
|
|
</P>
|
|
<br><a name="SEC2" href="#TOC1">RESTRICTED PATTERNS FOR PCRE_PARTIAL</a><br>
|
|
<P>
|
|
Because of the way certain internal optimizations are implemented in the
|
|
<b>pcre_exec()</b> function, the PCRE_PARTIAL option cannot be used with all
|
|
patterns. These restrictions do not apply when <b>pcre_dfa_exec()</b> is used.
|
|
For <b>pcre_exec()</b>, repeated single characters such as
|
|
<pre>
|
|
a{2,4}
|
|
</pre>
|
|
and repeated single metasequences such as
|
|
<pre>
|
|
\d+
|
|
</pre>
|
|
are not permitted if the maximum number of occurrences is greater than one.
|
|
Optional items such as \d? (where the maximum is one) are permitted.
|
|
Quantifiers with any values are permitted after parentheses, so the invalid
|
|
examples above can be coded thus:
|
|
<pre>
|
|
(a){2,4}
|
|
(\d)+
|
|
</pre>
|
|
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>
|
|
<P>
|
|
If PCRE_PARTIAL is set for a pattern that does not conform to the restrictions,
|
|
<b>pcre_exec()</b> returns the error code PCRE_ERROR_BADPARTIAL (-13).
|
|
You can use the PCRE_INFO_OKPARTIAL call to <b>pcre_fullinfo()</b> to find out
|
|
if a compiled pattern can be used for partial matching.
|
|
</P>
|
|
<br><a name="SEC3" href="#TOC1">EXAMPLE OF PARTIAL MATCHING USING PCRETEST</a><br>
|
|
<P>
|
|
If the escape sequence \P is present in a <b>pcretest</b> data line, the
|
|
PCRE_PARTIAL flag is used for the match. Here is a run of <b>pcretest</b> that
|
|
uses the date example quoted above:
|
|
<pre>
|
|
re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
|
|
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
|
|
</pre>
|
|
The first data string is matched completely, so <b>pcretest</b> 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
|
|
<b>pcre_dfa_exec()</b> matching (by means of the \D escape sequence), produces
|
|
the following output:
|
|
<pre>
|
|
re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
|
|
data> 25jun04\P\D
|
|
0: 25jun04
|
|
data> 23dec3\P\D
|
|
Partial match: 23dec3
|
|
data> 3ju\P\D
|
|
Partial match: 3ju
|
|
data> 3juj\P\D
|
|
No match
|
|
data> j\P\D
|
|
No match
|
|
</pre>
|
|
Notice that in this case the portion of the string that was matched is made
|
|
available.
|
|
</P>
|
|
<br><a name="SEC4" href="#TOC1">MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()</a><br>
|
|
<P>
|
|
When a partial match has been found using <b>pcre_dfa_exec()</b>, it is possible
|
|
to continue the match by providing additional subject data and calling
|
|
<b>pcre_dfa_exec()</b> 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 <b>pcretest</b>, using the \R escape
|
|
sequence to set the PCRE_DFA_RESTART option (\P and \D are as above):
|
|
<pre>
|
|
re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
|
|
data> 23ja\P\D
|
|
Partial match: 23ja
|
|
data> n05\R\D
|
|
0: n05
|
|
</pre>
|
|
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>
|
|
<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 <b>pcre_dfa_exec()</b>. However, some care is needed for certain
|
|
types of pattern.
|
|
</P>
|
|
<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>
|
|
<P>
|
|
2. If the pattern contains backward assertions (including \b or \B), 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>
|
|
<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 <b>pcre_dfa_exec()</b>. This means that as soon as the shortest match has
|
|
been found, continuation to a new subject segment is no longer possible.
|
|
Consider this <b>pcretest</b> example:
|
|
<pre>
|
|
re> /dog(sbody)?/
|
|
data> do\P\D
|
|
Partial match: do
|
|
data> gsb\R\P\D
|
|
0: g
|
|
data> dogsbody\D
|
|
0: dogsbody
|
|
1: dog
|
|
</pre>
|
|
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>
|
|
<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>
|
|
<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:
|
|
<pre>
|
|
1234|3789
|
|
</pre>
|
|
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:
|
|
<pre>
|
|
1234|ABCD
|
|
</pre>
|
|
where no string can be a partial match for both alternatives.
|
|
</P>
|
|
<br><a name="SEC5" href="#TOC1">AUTHOR</a><br>
|
|
<P>
|
|
Philip Hazel
|
|
<br>
|
|
University Computing Service
|
|
<br>
|
|
Cambridge CB2 3QH, England.
|
|
<br>
|
|
</P>
|
|
<br><a name="SEC6" href="#TOC1">REVISION</a><br>
|
|
<P>
|
|
Last updated: 04 June 2007
|
|
<br>
|
|
Copyright © 1997-2007 University of Cambridge.
|
|
<br>
|
|
<p>
|
|
Return to the <a href="index.html">PCRE index page</a>.
|
|
</p>
|