<!doctypehtml><html lang=en><meta charset=utf-8><title>
   Regex Tutorial - Alternation with The Vertical Bar
  </title><meta content=width=device-width,initial-scale=1 name=viewport><meta content="Jan Goyvaerts"name=author><meta content="In a regular expression, the vertical bar or pipe symbol tells the regex engine to match any of two or more options"name=description><meta name=keywords><link href=regex.css rel=stylesheet><script src=theme.js></script><link title="Regex Guru"href=http://www.regexguru.com/feed/ rel=alternate type=application/rss+xml><body bgcolor=white text=black><div id=top></div><div id=btntop><div id=btngrid><a href=quickstart.html target=_top> <div>Quick Start</div> </a><a href=tutorial.html target=_top> <div>Tutorial</div> </a><a href=tools.html target=_top> <div>Tools & Languages</div> </a><a href=examples.html target=_top> <div>Examples</div> </a><a href=refflavors.html target=_top> <div>Reference</div> </a><a href=books.html target=_top> <div>Book Reviews</div> </a></div></div><div id=contents><div id=side><table cellpadding=4 cellspacing=0 class=side><tbody><tr><td class=sideheader>Regex Tutorial<tr><td><a href=tutorial.html target=_top> Introduction </a><tr><td><a href=tutorialcnt.html target=_top> Table of Contents </a><tr><td><a href=characters.html target=_top> Special Characters </a><tr><td><a href=nonprint.html target=_top> Non-Printable Characters </a><tr><td><a href=engine.html target=_top> Regex Engine Internals </a><tr><td><a href=charclass.html target=_top> Character Classes </a><tr><td><a href=charclasssubtract.html target=_top> Character Class Subtraction </a><tr><td><a href=charclassintersect.html target=_top> Character Class Intersection </a><tr><td><a href=shorthand.html target=_top> Shorthand Character Classes </a><tr><td><a href=dot.html target=_top> Dot </a><tr><td><a href=anchors.html target=_top> Anchors </a><tr><td><a href=wordboundaries.html target=_top> Word Boundaries </a><tr><td><a href=alternation.html target=_top> Alternation </a><tr><td><a href=optional.html target=_top> Optional Items </a><tr><td><a href=repeat.html target=_top> Repetition </a><tr><td><a href=brackets.html target=_top> Grouping & Capturing </a><tr><td><a href=backref.html target=_top> Backreferences </a><tr><td><a href=backref2.html target=_top> Backreferences, part 2 </a><tr><td><a href=named.html target=_top> Named Groups </a><tr><td><a href=backrefrel.html target=_top> Relative Backreferences </a><tr><td><a href=branchreset.html target=_top> Branch Reset Groups </a><tr><td><a href=freespacing.html target=_top> Free-Spacing & Comments </a><tr><td><a href=unicode.html target=_top> Unicode </a><tr><td><a href=modifiers.html target=_top> Mode Modifiers </a><tr><td><a href=atomic.html target=_top> Atomic Grouping </a><tr><td><a href=possessive.html target=_top> Possessive Quantifiers </a><tr><td><a href=lookaround.html target=_top> Lookahead & Lookbehind </a><tr><td><a href=lookaround2.html target=_top> Lookaround, part 2 </a><tr><td><a href=keep.html target=_top> Keep Text out of The Match </a><tr><td><a href=conditional.html target=_top> Conditionals </a><tr><td><a href=balancing.html target=_top> Balancing Groups </a><tr><td><a href=recurse.html target=_top> Recursion </a><tr><td><a href=subroutine.html target=_top> Subroutines </a><tr><td><a href=recurseinfinite.html target=_top> Infinite Recursion </a><tr><td><a href=recurserepeat.html target=_top> Recursion & Quantifiers </a><tr><td><a href=recursecapture.html target=_top> Recursion & Capturing </a><tr><td><a href=recursebackref.html target=_top> Recursion & Backreferences </a><tr><td><a href=recursebacktrack.html target=_top> Recursion & Backtracking </a><tr><td><a href=posixbrackets.html target=_top> POSIX Bracket Expressions </a><tr><td><a href=zerolength.html target=_top> Zero-Length Matches </a><tr><td><a href=continue.html target=_top> Continuing Matches </a></table><table cellpadding=4 cellspacing=0 class=side><tbody><tr><td class=sideheader>More on This Site<tr><td><a href=index.html target=_top> Introduction </a><tr><td><a href=quickstart.html target=_top> Regular Expressions Quick Start </a><tr><td><a href=tutorial.html target=_top> Regular Expressions Tutorial </a><tr><td><a href=replacetutorial.html target=_top> Replacement Strings Tutorial </a><tr><td><a href=tools.html target=_top> Applications and Languages </a><tr><td><a href=examples.html target=_top> Regular Expressions Examples </a><tr><td><a href=refflavors.html target=_top> Regular Expressions Reference </a><tr><td><a href=refreplace.html target=_top> Replacement Strings Reference </a><tr><td><a href=books.html target=_top> Book Reviews </a><tr><td><a href=print.html target=_top> Printable PDF </a><tr><td><a href=about.html target=_top> About This Site </a><tr><td><a href=updates.html target=_top> RSS Feed & Blog </a></table></div><div class=bodytext><div class=topad style=height:130px><a href=https://www.regexbuddy.com/create.html target=_top> <picture><source media="(max-width: 370px)"srcset="ads/320/rxbtutorial100.png 1x, ads/320/rxbtutorial150.png 1.5x, ads/320/rxbtutorial200.png 2x, ads/320/rxbtutorial250.png 2.5x, ads/320/rxbtutorial300.png 3x, ads/320/rxbtutorial350.png 3.5x, ads/320/rxbtutorial400.png 4x"><source media="(max-width: 500px)"srcset="ads/360/rxbtutorial100.png 1x, ads/360/rxbtutorial150.png 1.5x, ads/360/rxbtutorial200.png 2x, ads/360/rxbtutorial250.png 2.5x, ads/360/rxbtutorial300.png 3x, ads/360/rxbtutorial350.png 3.5x, ads/360/rxbtutorial400.png 4x"><source media="(max-width: 660px)"srcset="ads/480/rxbtutorial100.png 1x, ads/480/rxbtutorial150.png 1.5x, ads/480/rxbtutorial200.png 2x, ads/480/rxbtutorial250.png 2.5x, ads/480/rxbtutorial300.png 3x, ads/480/rxbtutorial350.png 3.5x, ads/480/rxbtutorial400.png 4x"><source media="(max-width: 747px)"srcset="ads/640/rxbtutorial100.png 1x, ads/640/rxbtutorial150.png 1.5x, ads/640/rxbtutorial200.png 2x, ads/640/rxbtutorial250.png 2.5x, ads/640/rxbtutorial300.png 3x, ads/640/rxbtutorial350.png 3.5x, ads/640/rxbtutorial400.png 4x"><img alt="RegexBuddy—Better than a regular expression tutorial!"srcset="ads/728/rxbtutorial100.png 1x, ads/728/rxbtutorial125.png 1.25x, ads/728/rxbtutorial150.png 1.5x, ads/728/rxbtutorial175.png 1.75x, ads/728/rxbtutorial200.png 2x, ads/728/rxbtutorial250.png 2.5x, ads/728/rxbtutorial300.png 3x, ads/728/rxbtutorial350.png 3.5x, ads/728/rxbtutorial400.png 4x"src=ads/728/rxbtutorial100.png></picture> </a></div><div class=bulb><h1>Alternation with The Vertical Bar or Pipe Symbol</h1><script>showbulb();</script></div><p>I already explained how you can use <a href=charclass.html target=_top> character classes </a> to match a single character out of several possible characters. Alternation is similar. You can use alternation to match a single regular expression out of several possible regular expressions.<p>If you want to search for the literal text <tt class=syntax> <span class=regexplain> cat </span> </tt> or <tt class=syntax> <span class=regexplain> dog </span> </tt> , separate both options with a vertical bar or pipe symbol: <tt class=syntax> <span class=regexplain> cat </span> <span class=regexspecial> | </span> <span class=regexplain> dog </span> </tt> . If you want more options, simply expand the list: <tt class=syntax> <span class=regexplain> cat </span> <span class=regexspecial> | </span> <span class=regexplain> dog </span> <span class=regexspecial> | </span> <span class=regexplain> mouse </span> <span class=regexspecial> | </span> <span class=regexplain> fish </span> </tt> .<p>The alternation operator has the lowest precedence of all regex operators. That is, it tells the regex engine to match either everything to the left of the vertical bar, or everything to the right of the vertical bar. If you want to limit the reach of the alternation, you need to use parentheses for grouping. If we want to improve the first example to match whole words only, we would need to use <tt class=syntax> <span class=regexspecial> \b </span> <span class=regexnest1> ( </span> <span class=regexplain> cat </span> <span class=regexnest1> | </span> <span class=regexplain> dog </span> <span class=regexnest1> ) </span> <span class=regexspecial> \b </span> </tt> . This tells the regex engine to find a <a href=wordboundaries.html target=_top> word boundary </a> , then either <tt class=syntax> <span class=regexplain> cat </span> </tt> or <tt class=syntax> <span class=regexplain> dog </span> </tt> , and then another word boundary. If we had omitted the parentheses then the regex engine would have searched for a word boundary followed by <tt class=syntax> <span class=regexplain> cat </span> </tt> , or, <tt class=syntax> <span class=regexplain> dog </span> </tt> followed by a word boundary.</p><a name=eager> </a><h2>Remember That The Regex Engine Is Eager</h2><p>I already explained that <a href=engine.html target=_top> the regex engine is eager </a> . It stops searching as soon as it finds a valid match. The consequence is that in certain situations, the order of the alternatives matters. Suppose you want to use a regex to match a list of function names in a programming language: Get, GetValue, Set or SetValue. The obvious solution is <tt class=syntax> <span class=regexplain> Get </span> <span class=regexspecial> | </span> <span class=regexplain> GetValue </span> <span class=regexspecial> | </span> <span class=regexplain> Set </span> <span class=regexspecial> | </span> <span class=regexplain> SetValue </span> </tt> . Let’s see how this works out when the string is <tt class=string> SetValue </tt> .<p>The regex engine starts at the first token in the regex, <tt class=syntax> <span class=regexplain> G </span> </tt> , and at the first character in the string, <tt class=string> S </tt> . The match fails. However, the regex engine studied the entire regular expression before starting. So it knows that this regular expression uses alternation, and that the entire regex has not failed yet. So it continues with the second option, being the second <tt class=syntax> <span class=regexplain> G </span> </tt> in the regex. The match fails again. The next token is the first <tt class=syntax> <span class=regexplain> S </span> </tt> in the regex. The match succeeds, and the engine continues with the next character in the string, as well as the next token in the regex. The next token in the regex is the <tt class=syntax> <span class=regexplain> e </span> </tt> after the <tt class=syntax> <span class=regexplain> S </span> </tt> that just successfully matched. <tt class=syntax> <span class=regexplain> e </span> </tt> matches <tt class=match> e </tt> . The next token, <tt class=syntax> <span class=regexplain> t </span> </tt> matches <tt class=match> t </tt> .<p>At this point, the third option in the alternation has been successfully matched. Because the regex engine is eager, it considers the entire alternation to have been successfully matched as soon as one of the options has. In this example, there are no other tokens in the regex outside the alternation, so the entire regex has successfully matched <tt class=match> Set </tt> in <tt class=string> SetValue </tt> .<p>Contrary to what we intended, the regex did not match the entire string. There are several solutions. One option is to take into account that the regex engine is eager, and change the order of the options. If we use <tt class=syntax> <span class=regexplain> GetValue </span> <span class=regexspecial> | </span> <span class=regexplain> Get </span> <span class=regexspecial> | </span> <span class=regexplain> SetValue </span> <span class=regexspecial> | </span> <span class=regexplain> Set </span> </tt> , <tt class=syntax> <span class=regexplain> SetValue </span> </tt> is attempted before <tt class=syntax> <span class=regexplain> Set </span> </tt> , and the engine matches the entire string. We could also combine the four options into two and use the <a href=optional.html target=_top> question mark </a> to make part of them optional: <tt class=syntax> <span class=regexplain> Get </span> <span class=regexnest1> ( </span> <span class=regexplain> Value </span> <span class=regexnest1> ) </span> <span class=regexspecial> ? </span> <span class=regexspecial> | </span> <span class=regexplain> Set </span> <span class=regexnest1> ( </span> <span class=regexplain> Value </span> <span class=regexnest1> ) </span> <span class=regexspecial> ? </span> </tt> . Because the question mark is greedy, <tt class=syntax> <span class=regexplain> SetValue </span> </tt> is be attempted before <tt class=syntax> <span class=regexplain> Set </span> </tt> .<p>The best option is probably to express the fact that we only want to match complete words. We do not want to match Set or SetValue if the string is <tt class=string> SetValueFunction </tt> . So the solution is <tt class=syntax> <span class=regexspecial> \b </span> <span class=regexnest1> ( </span> <span class=regexplain> Get </span> <span class=regexnest1> | </span> <span class=regexplain> GetValue </span> <span class=regexnest1> | </span> <span class=regexplain> Set </span> <span class=regexnest1> | </span> <span class=regexplain> SetValue </span> <span class=regexnest1> ) </span> <span class=regexspecial> \b </span> </tt> or <tt class=syntax> <span class=regexspecial> \b </span> <span class=regexnest1> ( </span> <span class=regexplain> Get </span> <span class=regexnest2> ( </span> <span class=regexplain> Value </span> <span class=regexnest2> ) </span> <span class=regexspecial> ? </span> <span class=regexnest1> | </span> <span class=regexplain> Set </span> <span class=regexnest2> ( </span> <span class=regexplain> Value </span> <span class=regexnest2> ) </span> <span class=regexspecial> ? </span> <span class=regexnest1> ) </span> <span class=regexspecial> \b </span> </tt> . Since all options have the same end, we can optimize this further to <tt class=syntax> <span class=regexspecial> \b </span> <span class=regexnest1> ( </span> <span class=regexplain> Get </span> <span class=regexnest1> | </span> <span class=regexplain> Set </span> <span class=regexnest1> ) </span> <span class=regexnest1> ( </span> <span class=regexplain> Value </span> <span class=regexnest1> ) </span> <span class=regexspecial> ? </span> <span class=regexspecial> \b </span> </tt> .<h2>Text-Directed Engine Returns the Longest Match</h2><p>Alternation is where <a href=engine.html target=_top> regex-directed and text-directed engines differ </a> . When a text-directed engine attempts <tt class=syntax> <span class=regexplain> Get </span> <span class=regexspecial> | </span> <span class=regexplain> GetValue </span> <span class=regexspecial> | </span> <span class=regexplain> Set </span> <span class=regexspecial> | </span> <span class=regexplain> SetValue </span> </tt> on <tt class=string> SetValue </tt> , it tries all permutations of the regex at the start of the string. It does so efficiently, without any backtracking. It sees that the regex can find a match at the start of the string, and that the matched text can be either <tt class=string> Set </tt> or <tt class=string> SetValue </tt> . Because the text-directed engine evaluates the regex as a whole, it has no concept of one alternative being listed before another. But it has to make a choice as to which match to return. It always returns the longest match, in this case <tt class=match> SetValue </tt> .<h2>POSIX Requires The Longest Match</h2><p>The <a href=posix.html target=_top> POSIX standard </a> leaves it up to the implementation to choose a text-directed or regex-directed engine. A BRE that includes backreferences needs to be evaluated using a regex-directed engine. But a BRE without backreferences or an ERE can be evaluated using a text-directed engine. But the POSIX standard does mandate that the longest match be returned, even when a regex-directed engine is used. Such an engine cannot be eager. It has to continue trying all alternatives even after a match is found, in order to find the longest one. This can result in very poor performance when a regex contains multiple quantifiers or a combination of quantifiers and alternation, as all combinations have to be tried to find the longest match.<p>The <a href=tcl.html target=_top> Tcl </a> and <a href=gnu.html target=_top> GNU </a> flavors also work this way.<h2>Make a Donation</h2><p>Did this website just save you a trip to the bookstore? Please <a href=https://www.regular-expressions.info/donate.html> make a donation </a> to support this site, and you'll get a <b> lifetime of advertisement-free access </b> to this site!<div id=cntmobi><p>|  <a href=quickstart.html> Quick Start </a>  |  <a href=tutorial.html> Tutorial </a>  |  <a href=tools.html> Tools & Languages </a>  |  <a href=examples.html> Examples </a>  |  <a href=refflavors.html> Reference </a>  |  <a href=books.html> Book Reviews </a>  |<p>|  <a href=tutorial.html> Introduction </a>  |  <a href=tutorialcnt.html> Table of Contents </a>  |  <a href=characters.html> Special Characters </a>  |  <a href=nonprint.html> Non-Printable Characters </a>  |  <a href=engine.html> Regex Engine Internals </a>  |  <a href=charclass.html> Character Classes </a>  |  <a href=charclasssubtract.html> Character Class Subtraction </a>  |  <a href=charclassintersect.html> Character Class Intersection </a>  |  <a href=shorthand.html> Shorthand Character Classes </a>  |  <a href=dot.html> Dot </a>  |  <a href=anchors.html> Anchors </a>  |  <a href=wordboundaries.html> Word Boundaries </a>  |  <a href=alternation.html> Alternation </a>  |  <a href=optional.html> Optional Items </a>  |  <a href=repeat.html> Repetition </a>  |  <a href=brackets.html> Grouping & Capturing </a>  |  <a href=backref.html> Backreferences </a>  |  <a href=backref2.html> Backreferences, part 2 </a>  |  <a href=named.html> Named Groups </a>  |  <a href=backrefrel.html> Relative Backreferences </a>  |  <a href=branchreset.html> Branch Reset Groups </a>  |  <a href=freespacing.html> Free-Spacing & Comments </a>  |  <a href=unicode.html> Unicode </a>  |  <a href=modifiers.html> Mode Modifiers </a>  |  <a href=atomic.html> Atomic Grouping </a>  |  <a href=possessive.html> Possessive Quantifiers </a>  |  <a href=lookaround.html> Lookahead & Lookbehind </a>  |  <a href=lookaround2.html> Lookaround, part 2 </a>  |  <a href=keep.html> Keep Text out of The Match </a>  |  <a href=conditional.html> Conditionals </a>  |  <a href=balancing.html> Balancing Groups </a>  |  <a href=recurse.html> Recursion </a>  |  <a href=subroutine.html> Subroutines </a>  |  <a href=recurseinfinite.html> Infinite Recursion </a>  |  <a href=recurserepeat.html> Recursion & Quantifiers </a>  |  <a href=recursecapture.html> Recursion & Capturing </a>  |  <a href=recursebackref.html> Recursion & Backreferences </a>  |  <a href=recursebacktrack.html> Recursion & Backtracking </a>  |  <a href=posixbrackets.html> POSIX Bracket Expressions </a>  |  <a href=zerolength.html> Zero-Length Matches </a>  |  <a href=continue.html> Continuing Matches </a>  |</div><div id=copyright><p class=copyright>Page URL: <a href=https://www.regular-expressions.info/alternation.html target=_top> https://www.regular-expressions.info/alternation.html </a> <br> Page last updated: 22 November 2019 <br> Site last updated: 02 September 2021 <br> Copyright © 2003-2021 Jan Goyvaerts. All rights reserved.</div></div></div>