<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Conditional subpatterns</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="regexp.reference.onlyonce.html">Once-only subpatterns</a></div>
<div class="next" style="text-align: right; float: right;"><a href="regexp.reference.comments.html">Comments</a></div>
<div class="up"><a href="reference.pcre.pattern.syntax.html">PCRE regex syntax</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="regexp.reference.conditional" class="section">
<h2 class="title">Conditional subpatterns</h2>
<p class="para">
It is possible to cause the matching process to obey a subpattern
conditionally or to choose between two alternative
subpatterns, depending on the result of an assertion, or
whether a previous capturing subpattern matched or not. The
two possible forms of conditional subpattern are
</p>
<div class="informalexample">
<div class="example-contents">
<div class="cdata"><pre>
(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)
</pre></div>
</div>
</div>
<p class="para">
If the condition is satisfied, the yes-pattern is used; otherwise
the no-pattern (if present) is used. If there are
more than two alternatives in the subpattern, a compile-time
error occurs.
</p>
<p class="para">
There are two kinds of condition. If the text between the
parentheses consists of a sequence of digits, then the
condition is satisfied if the capturing subpattern of that
number has previously matched. Consider the following pattern,
which contains non-significant white space to make it
more readable (assume the <a href="reference.pcre.pattern.modifiers.html" class="link">PCRE_EXTENDED</a>
option) and to divide it into three parts for ease of discussion:
<em>( \( )? [^()]+ (?(1) \) )</em>
</p>
<p class="para">
The first part matches an optional opening parenthesis, and
if that character is present, sets it as the first captured
substring. The second part matches one or more characters
that are not parentheses. The third part is a conditional
subpattern that tests whether the first set of parentheses
matched or not. If they did, that is, if subject started
with an opening parenthesis, the condition is <strong><code>TRUE</code></strong>, and so
the yes-pattern is executed and a closing parenthesis is
required. Otherwise, since no-pattern is not present, the
subpattern matches nothing. In other words, this pattern
matches a sequence of non-parentheses, optionally enclosed
in parentheses.
</p>
<p class="para">
If the condition is the string <em>(R)</em>, it is satisfied if
a recursive call to the pattern or subpattern has been made. At "top
level", the condition is false.
</p>
<p class="para">
If the condition is not a sequence of digits or (R), it must be an
assertion. This may be a positive or negative lookahead or
lookbehind assertion. Consider this pattern, again containing
non-significant white space, and with the two alternatives on
the second line:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="cdata"><pre>
(?(?=[^a-z]*[a-z])
\d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )
</pre></div>
</div>
</div>
<p class="para">
The condition is a positive lookahead assertion that matches
an optional sequence of non-letters followed by a letter. In
other words, it tests for the presence of at least one
letter in the subject. If a letter is found, the subject is
matched against the first alternative; otherwise it is
matched against the second. This pattern matches strings in
one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
letters and dd are digits.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="regexp.reference.onlyonce.html">Once-only subpatterns</a></div>
<div class="next" style="text-align: right; float: right;"><a href="regexp.reference.comments.html">Comments</a></div>
<div class="up"><a href="reference.pcre.pattern.syntax.html">PCRE regex syntax</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
