<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Pattern+Matching">Pattern Matching</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~rmudgett">Richard Mudgett</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Reworked and added more information.<br />
</div>
<br/>
<h4>Changes (65)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-changed-lines" >The next concept we'll cover is called _pattern matching_. <span class="diff-added-words"style="background-color: #dfd;"> </span> Pattern matching allows us to create extension patterns in our dialplan that match more than one possible dialed number. <span class="diff-added-words"style="background-color: #dfd;"> </span> Pattern matching saves us from having to create an extension in the dialplan for every possible number that might be dialed. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >When Alice dials a number on her phone, Asterisk first looks for an extension (in the context specified by the channel driver configuration) that matches exactly what Alice dialed. <span class="diff-added-words"style="background-color: #dfd;"> </span> If there's no exact match, Asterisk then looks for a pattern <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">match</span> that matches. <span class="diff-added-words"style="background-color: #dfd;"> </span> After we show the syntax and some basic examples of pattern matching, we'll explain how Asterisk finds the best match if there are two or more patterns which match the dialed number. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >Pattern matches always begin with an underscore. <span class="diff-added-words"style="background-color: #dfd;"> </span> This is how Asterisk recognizes that the extension is a pattern and not just an extension with a funny name. <span class="diff-added-words"style="background-color: #dfd;"> </span> Within the pattern, we use various <span class="diff-changed-words">letter<span class="diff-added-chars"style="background-color: #dfd;">s</span></span> and characters to represent sets or ranges of numbers. <span class="diff-added-words"style="background-color: #dfd;"> </span> Here are the most common letters: <br></td></tr>
<tr><td class="diff-unchanged" > <br>h4. X <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The letter <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">*X*&nbsp;represents</span> <span class="diff-added-words"style="background-color: #dfd;">*X* or *x* represents</span> a single digit from 0 to 9. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h4. Z <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The letter <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">*Z*&nbsp;represents</span> <span class="diff-added-words"style="background-color: #dfd;">*Z* or *z* represents</span> any digit from 1 to 9. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h4. N <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The letter <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">*N*&nbsp;represents</span> <span class="diff-added-words"style="background-color: #dfd;">*N* or *n* represents</span> a single digit from 2 to 9. <br></td></tr>
<tr><td class="diff-unchanged" > <br>Now let's look at a sample pattern. If you wanted to match all four-digit numbers that had the first two digits as six and four, you would create an extension that looks like: <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{noformat}exten => _64XX,1,SayDigits(${EXTEN}) <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">exten => _64XX,1,SayDigits(${EXTEN}) <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >In this example, each *X* represents a single digit, with any value from zero to nine. <span class="diff-added-words"style="background-color: #dfd;"> </span> We're essentially saying "The first digit must be a six, the second digit must be a four, the third digit can be anything from zero to nine, and the fourth digit can be anything from zero to nine". <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >If we want to be more specific about a range of numbers, we can put those numbers or number ranges in square <span class="diff-changed-words">brackets<span class="diff-added-chars"style="background-color: #dfd;"> to define a character set</span>.<span class="diff-added-chars"style="background-color: #dfd;"> </span></span> For example, what if we wanted the second digit to be either a three or a four? <span class="diff-added-words"style="background-color: #dfd;"> </span> One way would be to create two patterns (*\_64XX* and *\_63XX*), but a more compact method would be to do <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">*\_6\[docs:34\]XX*.</span> <span class="diff-added-words"style="background-color: #dfd;">*\_6\[34\]XX*. </span> This specifies that the first digit must be a six, the second digit can be either a three or a four, and that the last two digits can be anything from zero to nine. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >You can also use ranges within square brackets. <span class="diff-added-words"style="background-color: #dfd;"> </span> For example, <span class="diff-changed-words">*\[<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">docs:</span>1-468\]*</span> would match a single digit from one through four or six or eight. <span class="diff-added-words"style="background-color: #dfd;"> </span> It does not match any number from one to four hundred sixty-eight\! <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Within Asterisk patterns, we can also use a couple of other characters to represent ranges of numbers. The period character (*.*) within a pattern matches on one or more remaining digits in the pattern. It typically appears at the end of a pattern match, especially when you want to match extensions of an indeterminate length. As an example, the pattern *\_9876*. would match any number that began with *9876* and had at least one more character or digit. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Within Asterisk patterns, we can also use a couple of other characters to represent ranges of numbers. The period character (*.*) at the end of a pattern matches one or more remaining *characters*. You put it at the end of a pattern when you want to match extensions of an indeterminate length. As an example, the pattern *\_9876.* would match any number that began with *9876* and had at least one more character or digit. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The exclamation mark (*\!*) character is similar to the period and also matches one more more remaining characters, but is used in overlap dialing. For example, *\_9876\!* would match any number that began with *9876*, and would respond that the number was complete as soon as there was an unambiguous match. <br>{warning:title=Be Careful With Wildcards in Pattern Matches }Please be extremely cautious when using the period and exclamation mark characters in your pattern matches. They match more than just digits, they also match on characters as well, and if you're not careful to filter the input from your callers, a malicious caller might try to use these wildcards to bypass security boundaries on your system. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The exclamation mark (*\!*) character is similar to the period and matches zero or more remaining characters. It is used in overlap dialing to dial through Asterisk. For example, *\_9876\!* would match any number that began with *9876* including *9876*, and would respond that the number was complete as soon as there was an unambiguous match. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">For a more complete explanation of this topic and how you can protect yourself, please refer to the *README-SERIOUSLY.bestpractices.txt* file in the Asterisk source code.{warning} <br>Now let's show what happens when there is more than one pattern that matches the dialed number. How does Asterisk know which pattern to choose as the best match? <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{tip} <br>Asterisk treats a period or exclamation mark as the end of a pattern. If you want a period or exclamation mark in your pattern as a plain character you should put it into a character set: *\[.\]* or *\[\!\]*. <br>{tip} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Asterisk uses a simple set of rules to determine the best match. They are: <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{warning:title=Be Careful With Wildcards in Pattern Matches } <br>Please be extremely cautious when using the period and exclamation mark characters in your pattern matches. They match more than just digits. They match on characters. If you're not careful to filter the input from your callers, a malicious caller might try to use these wildcards to bypass security boundaries on your system. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"># Examine the first digit eliminate any patterns which don't match the first digit of the dialed number <br># Sort the remaining patterns based on the most constrained match for the current digit. By most constrained, we mean the pattern that has the fewest possible matches for this digit. As an example, the *N* character has 8 possible matches (two through nine), while an *X* has ten possible matches. <br># In the case of a match, sort the patterns in ASCII sort order. For example, *\_\[docs:234\]X* and *\_\[docs:345\]X* have three possible matches in the first digit, but *234* comes before *345* in ASCII sort order. <br># Move on to the next digit (moving digit by digit from left to right), and eliminate any patterns which don't match the current digit of the dialed number. Then continue back at step number two. <br># After you've examined all the digits, return the match that has been sorted to the top of the list. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">For a more complete explanation of this topic and how you can protect yourself, please refer to the *README-SERIOUSLY.bestpractices.txt* file in the Asterisk source code. <br>{warning} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Let's look at an example to better understand how this works. Let's assume Alice dials extension 6401, and she has the following patterns in her dialplan: <br>{noformat}exten => _64XX,1,SayAlpha(A) <br>exten => _640X,1,SayAlpha(B) <br>exten => _64NX,1,SayAlpha(C) <br>exten => _6XX1,1,SayAlpha(D){noformat} <br>Can you tell (without reading ahead) which one would match? <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Now let's show what happens when there is more than one pattern that matches the dialed number. How does Asterisk know which pattern to choose as the best match? <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Let's walk step by step through the rules explained above, and see what happens when Alice dials *6401*. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Asterisk uses a simple set of rules to sort the extensions and patterns so that the best match is found first. The best match is simply the most specific pattern. The sorting rules are: <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 1 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"># The dash (*-*) character is ignored in extensions and patterns except when it is used in a pattern to specify a range in a character set. It has no effect in matching or sorting extensions. <br># Non-pattern extensions are sorted in ASCII sort order before patterns. <br># Patterns are sorted by the most constrained character set per digit first. By most constrained, we mean the pattern that has the fewest possible matches for a digit. As an example, the *N* character has eight possible matches (two through nine), while *X* has ten possible matches (zero through nine) so *N* sorts first. <br># Character sets that have the same number of characters are sorted in ASCII sort order as if the sets were strings of the set characters. As an example, *X* is *0123456789* and *\[a-j\]* is *abcdefghij* so *X* sorts first. This sort ordering is important if the character sets overlap as with *\[0-4\]* and *\[4-8\]*. <br># The period (*.*) wildcard sorts after character sets. <br># The exclamation mark (*\!*) wildcard sorts after the period wildcard. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">We look at the first digit, and all the patterns match. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Let's look at an example to better understand how this works. Let's assume Alice dials extension *6421*, and she has the following patterns in her dialplan: <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 2 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>exten => _6XX1,1,SayAlpha(A) <br>exten => _64XX,1,SayAlpha(B) <br>exten => _640X,1,SayAlpha(C) <br>exten => _6.,1,SayAlpha(D) <br>exten => _64NX,1,SayAlpha(E) <br>exten => _6[45]NX,1,SayAlpha(F) <br>exten => _6[34]NX,1,SayAlpha(G) <br>{noformat} <br>Can you tell (without reading ahead) which one would match? <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Each of the patterns have the same number of possible matches on this digit (one match --- the number six). <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Using the sorting rules explained above, the extensions sort as follows: <br>*\_640X* sorts before *\_64NX* because of rule 3 at position 4. (0 before N) <br>*\_64NX* sorts before *\_64XX* because of rule 3 at position 4. (N before X) <br>*\_64XX* sorts before *\_6\[34\]NX* because of rule 3 at position 3. (4 before \[34\]) <br>*\_6\[34\]NX* sorts before *\_6\[45\]NX* because of rule 4 at position 3. (\[34\] before \[45\]) <br>*\_6\[45\]NX* sorts before *\_6XX1* because of rule 3 at position 3. (\[45\] before X) <br>*\_6XX1* sorts before *\_6.* because of rule 5 at position 3. (X before .) <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 3 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat:title=Sorted extensions} <br>exten => _640X,1,SayAlpha(C) <br>exten => _64NX,1,SayAlpha(E) <br>exten => _64XX,1,SayAlpha(B) <br>exten => _6[34]NX,1,SayAlpha(G) <br>exten => _6[45]NX,1,SayAlpha(F) <br>exten => _6XX1,1,SayAlpha(A) <br>exten => _6.,1,SayAlpha(D) <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">We sort the patterns in ASCII sort order. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">When Alice dials *6421*, Asterisk searches through its list of sorted extensions and uses the first matching extension. In this case *\_64NX* is found. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 4 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">To verify that Asterisk actually does sort the extensions in the manner that we've shown, add the following extensions to the *\[users\]* context of your own dialplan. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">We move on to the second digit. There are no patterns that can be eliminated based on the second digit, so we go back to rule two for this digit. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>exten => _6XX1,1,SayAlpha(A) <br>exten => _64XX,1,SayAlpha(B) <br>exten => _640X,1,SayAlpha(C) <br>exten => _6.,1,SayAlpha(D) <br>exten => _64NX,1,SayAlpha(E) <br>exten => _6[45]NX,1,SayAlpha(F) <br>exten => _6[34]NX,1,SayAlpha(G) <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 2 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Reload the dialplan, and then type *dialplan show 6421@users* at the Asterisk CLI. Asterisk will show you all extensions that match in the *\[users\]* context. If you were to dial extension *6421* in the *\[users\]* context the first found extension will execute. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The three patterns with a *4* in the second digit are more constrained than the *X*, so they get sorted to the top. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>server*CLI> dialplan show 6421@users <br>[ Context 'users' created by 'pbx_config' ] <br> '_64NX' => 1. SayAlpha(E) [pbx_config] <br> '_64XX' => 1. SayAlpha(B) [pbx_config] <br> '_6[34]NX' => 1. SayAlpha(G) [pbx_config] <br> '_6[45]NX' => 1. SayAlpha(F) [pbx_config] <br> '_6XX1' => 1. SayAlpha(A) [pbx_config] <br> '_6.' => 1. SayAlpha(D) [pbx_config] <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 3 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">-= 6 extensions (6 priorities) in 1 context. =- <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The top three patterns get sorted in ASCII sort order, since they are tied in the number of possible matches. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>server*CLI> dialplan show users <br>[ Context 'users' created by 'pbx_config' ] <br> '_640X' => 1. SayAlpha(C) [pbx_config] <br> '_64NX' => 1. SayAlpha(E) [pbx_config] <br> '_64XX' => 1. SayAlpha(B) [pbx_config] <br> '_6[34]NX' => 1. SayAlpha(G) [pbx_config] <br> '_6[45]NX' => 1. SayAlpha(F) [pbx_config] <br> '_6XX1' => 1. SayAlpha(A) [pbx_config] <br> '_6.' => 1. SayAlpha(D) [pbx_config] <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 4 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">-= 7 extensions (7 priorities) in 1 context. =- <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">We move on to the third digit. The third pattern (the one that would call *SayAlpha(C)*) is eliminated, because the third digit of this pattern (the *N*) doesn't match the third dialed digit (the *0*). The other patterns match, so we now go back to rule two. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">You can dial extension *6421* to try it out on your own. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 2 <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{warning:title=Be Careful with Pattern Matching } <br>Please be aware that because of the way auto-fallthrough works, if Asterisk can't find the next priority number for the current extension or pattern match, it will also look for that same priority in a less specific pattern match. Consider the following example: <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The second pattern (the one that would call *SayAlpha(B)*) is the most constrained, as it only has a single possibility, so it gets sorted to the top. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">{noformat}</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h5. Rule 3 <br> <br>There are no ties at the top of the sorting table, so we can move on to rule four. <br> <br>h5. Rule 4 <br> <br>We move on to the fourth digit. Since all the remaining patterns match, the second pattern remains at the top of the sorting table. You might be asking yourself... "What about the fourth pattern? Isn't it more constrained?" Remember that it was less constrained in an earlier digit, so it would only match if none of the other patterns above it in the sorting table matched on this digit. <br> <br>h5. Step 5 <br> <br>Since we have run out of digits, we know that Asterisk will match on the second pattern, as it is the one at the top of the sorting table. <br> <br>To verify that Asterisk actually does sort the extensions in the manner that we've described, add the following extensions to the *\[docs:users\]* context of your own dialplan. <br>{noformat}exten => _64XX,1,SayAlpha(A) <br></td></tr>
<tr><td class="diff-changed-lines" >exten => <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">_640X,1,SayAlpha(B)</span> <span class="diff-added-words"style="background-color: #dfd;">6410,1,SayDigits(987)</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">exten => _64NX,1,SayAlpha(C) <br>exten => _6XX1,1,SayAlpha(D){noformat} <br>Reload the dialplan, and then type *dialplan show 6104@users* at the Asterisk CLI. Asterisk will show you what would match if you were to dial extension *6104* in the *\[docs:users\]* context. <br>{noformat}server*CLI> dialplan show 6401@users <br>[ Context 'users' created by 'pbx_config' ] <br> '_640X' => 1. SayAlpha(B) [pbx_config] <br> '_64XX' => 1. SayAlpha(A) [pbx_config] <br> '_6XX1' => 1. SayAlpha(D) [pbx_config] <br> <br>-= 3 extensions (3 priorities) in 1 context. =-{noformat} <br>You can then dial extension *6104*&nbsp;to try it out on your own. <br>{warning:title=Be Careful with Pattern Matching }Please be aware that because of the way auto-fallthrough works, if Asterisk can't find the next priority number for the current extension or pattern match, it will also look for that same priority in a less specific pattern match. Consider the following example: <br>{code:lang=javascript}exten => 6410,1,SayDigits(987) <br></td></tr>
<tr><td class="diff-unchanged" >exten => _641X,1,SayDigits(12345) <br>exten => _641X,n,SayDigits(54321) <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{code}</span> <span class="diff-added-words"style="background-color: #dfd;">{noformat}</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">If you were to dial extension 6410, you'd hear "nine eight seven five four three two one". <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">If you were to dial extension *6410*, you'd hear "nine eight seven five four three two one". <br> <br></td></tr>
<tr><td class="diff-changed-lines" >We strongly recommend you make the *Hangup()* application be the last priority of any extension to avoid this problem, unless you purposely want to fall through to a less specific <span class="diff-changed-words">match.<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">{warning}</span></span> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{warning} <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>The next concept we'll cover is called <em>pattern matching</em>. Pattern matching allows us to create extension patterns in our dialplan that match more than one possible dialed number. Pattern matching saves us from having to create an extension in the dialplan for every possible number that might be dialed.</p>
<p>When Alice dials a number on her phone, Asterisk first looks for an extension (in the context specified by the channel driver configuration) that matches exactly what Alice dialed. If there's no exact match, Asterisk then looks for a pattern that matches. After we show the syntax and some basic examples of pattern matching, we'll explain how Asterisk finds the best match if there are two or more patterns which match the dialed number.</p>
<p>Pattern matches always begin with an underscore. This is how Asterisk recognizes that the extension is a pattern and not just an extension with a funny name. Within the pattern, we use various letters and characters to represent sets or ranges of numbers. Here are the most common letters:</p>
<h4><a name="PatternMatching-X"></a>X</h4>
<p>The letter <b>X</b> or <b>x</b> represents a single digit from 0 to 9.</p>
<h4><a name="PatternMatching-Z"></a>Z</h4>
<p>The letter <b>Z</b> or <b>z</b> represents any digit from 1 to 9.</p>
<h4><a name="PatternMatching-N"></a>N</h4>
<p>The letter <b>N</b> or <b>n</b> represents a single digit from 2 to 9.</p>
<p>Now let's look at a sample pattern. If you wanted to match all four-digit numbers that had the first two digits as six and four, you would create an extension that looks like:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>exten => _64XX,1,SayDigits(${EXTEN})
</pre>
</div></div>
<p>In this example, each <b>X</b> represents a single digit, with any value from zero to nine. We're essentially saying "The first digit must be a six, the second digit must be a four, the third digit can be anything from zero to nine, and the fourth digit can be anything from zero to nine".</p>
<p>If we want to be more specific about a range of numbers, we can put those numbers or number ranges in square brackets to define a character set. For example, what if we wanted the second digit to be either a three or a four? One way would be to create two patterns (<b>_64XX</b> and <b>_63XX</b>), but a more compact method would be to do <b>_6[34]XX</b>. This specifies that the first digit must be a six, the second digit can be either a three or a four, and that the last two digits can be anything from zero to nine.</p>
<p>You can also use ranges within square brackets. For example, <b>[1-468]</b> would match a single digit from one through four or six or eight. It does not match any number from one to four hundred sixty-eight!</p>
<p>Within Asterisk patterns, we can also use a couple of other characters to represent ranges of numbers. The period character (<b>.</b>) at the end of a pattern matches one or more remaining <b>characters</b>. You put it at the end of a pattern when you want to match extensions of an indeterminate length. As an example, the pattern <b>_9876.</b> would match any number that began with <b>9876</b> and had at least one more character or digit.</p>
<p>The exclamation mark (<b>!</b>) character is similar to the period and matches zero or more remaining characters. It is used in overlap dialing to dial through Asterisk. For example, <b>_9876!</b> would match any number that began with <b>9876</b> including <b>9876</b>, and would respond that the number was complete as soon as there was an unambiguous match.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Asterisk treats a period or exclamation mark as the end of a pattern. If you want a period or exclamation mark in your pattern as a plain character you should put it into a character set: <b>[.]</b> or <b>[!]</b>.</td></tr></table></div>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Be Careful With Wildcards in Pattern Matches</b><br />Please be extremely cautious when using the period and exclamation mark characters in your pattern matches. They match more than just digits. They match on characters. If you're not careful to filter the input from your callers, a malicious caller might try to use these wildcards to bypass security boundaries on your system.
<p>For a more complete explanation of this topic and how you can protect yourself, please refer to the <b>README-SERIOUSLY.bestpractices.txt</b> file in the Asterisk source code.</p></td></tr></table></div>
<p>Now let's show what happens when there is more than one pattern that matches the dialed number. How does Asterisk know which pattern to choose as the best match?</p>
<p>Asterisk uses a simple set of rules to sort the extensions and patterns so that the best match is found first. The best match is simply the most specific pattern. The sorting rules are:</p>
<ol>
<li>The dash (<b>-</b>) character is ignored in extensions and patterns except when it is used in a pattern to specify a range in a character set. It has no effect in matching or sorting extensions.</li>
<li>Non-pattern extensions are sorted in ASCII sort order before patterns.</li>
<li>Patterns are sorted by the most constrained character set per digit first. By most constrained, we mean the pattern that has the fewest possible matches for a digit. As an example, the <b>N</b> character has eight possible matches (two through nine), while <b>X</b> has ten possible matches (zero through nine) so <b>N</b> sorts first.</li>
<li>Character sets that have the same number of characters are sorted in ASCII sort order as if the sets were strings of the set characters. As an example, <b>X</b> is <b>0123456789</b> and <b>[a-j]</b> is <b>abcdefghij</b> so <b>X</b> sorts first. This sort ordering is important if the character sets overlap as with <b>[0-4]</b> and <b>[4-8]</b>.</li>
<li>The period (<b>.</b>) wildcard sorts after character sets.</li>
<li>The exclamation mark (<b>!</b>) wildcard sorts after the period wildcard.</li>
</ol>
<p>Let's look at an example to better understand how this works. Let's assume Alice dials extension <b>6421</b>, and she has the following patterns in her dialplan:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>exten => _6XX1,1,SayAlpha(A)
exten => _64XX,1,SayAlpha(B)
exten => _640X,1,SayAlpha(C)
exten => _6.,1,SayAlpha(D)
exten => _64NX,1,SayAlpha(E)
exten => _6[45]NX,1,SayAlpha(F)
exten => _6[34]NX,1,SayAlpha(G)
</pre>
</div></div>
<p>Can you tell (without reading ahead) which one would match?</p>
<p>Using the sorting rules explained above, the extensions sort as follows:<br/>
<b>_640X</b> sorts before <b>_64NX</b> because of rule 3 at position 4. (0 before N)<br/>
<b>_64NX</b> sorts before <b>_64XX</b> because of rule 3 at position 4. (N before X)<br/>
<b>_64XX</b> sorts before <b>_6[34]NX</b> because of rule 3 at position 3. (4 before [34])<br/>
<b>_6[34]NX</b> sorts before <b>_6[45]NX</b> because of rule 4 at position 3. ([34] before [45])<br/>
<b>_6[45]NX</b> sorts before <b>_6XX1</b> because of rule 3 at position 3. ([45] before X)<br/>
<b>_6XX1</b> sorts before <b>_6.</b> because of rule 5 at position 3. (X before .)</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedHeader panelHeader" style="border-bottom-width: 1px;"><b>Sorted extensions</b></div><div class="preformattedContent panelContent">
<pre>exten => _640X,1,SayAlpha(C)
exten => _64NX,1,SayAlpha(E)
exten => _64XX,1,SayAlpha(B)
exten => _6[34]NX,1,SayAlpha(G)
exten => _6[45]NX,1,SayAlpha(F)
exten => _6XX1,1,SayAlpha(A)
exten => _6.,1,SayAlpha(D)
</pre>
</div></div>
<p>When Alice dials <b>6421</b>, Asterisk searches through its list of sorted extensions and uses the first matching extension. In this case <b>_64NX</b> is found.</p>
<p>To verify that Asterisk actually does sort the extensions in the manner that we've shown, add the following extensions to the <b>[users]</b> context of your own dialplan.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>exten => _6XX1,1,SayAlpha(A)
exten => _64XX,1,SayAlpha(B)
exten => _640X,1,SayAlpha(C)
exten => _6.,1,SayAlpha(D)
exten => _64NX,1,SayAlpha(E)
exten => _6[45]NX,1,SayAlpha(F)
exten => _6[34]NX,1,SayAlpha(G)
</pre>
</div></div>
<p>Reload the dialplan, and then type <b>dialplan show 6421@users</b> at the Asterisk CLI. Asterisk will show you all extensions that match in the <b>[users]</b> context. If you were to dial extension <b>6421</b> in the <b>[users]</b> context the first found extension will execute.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>server*CLI> dialplan show 6421@users
[ Context 'users' created by 'pbx_config' ]
'_64NX' => 1. SayAlpha(E) [pbx_config]
'_64XX' => 1. SayAlpha(B) [pbx_config]
'_6[34]NX' => 1. SayAlpha(G) [pbx_config]
'_6[45]NX' => 1. SayAlpha(F) [pbx_config]
'_6XX1' => 1. SayAlpha(A) [pbx_config]
'_6.' => 1. SayAlpha(D) [pbx_config]
-= 6 extensions (6 priorities) in 1 context. =-
</pre>
</div></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>server*CLI> dialplan show users
[ Context 'users' created by 'pbx_config' ]
'_640X' => 1. SayAlpha(C) [pbx_config]
'_64NX' => 1. SayAlpha(E) [pbx_config]
'_64XX' => 1. SayAlpha(B) [pbx_config]
'_6[34]NX' => 1. SayAlpha(G) [pbx_config]
'_6[45]NX' => 1. SayAlpha(F) [pbx_config]
'_6XX1' => 1. SayAlpha(A) [pbx_config]
'_6.' => 1. SayAlpha(D) [pbx_config]
-= 7 extensions (7 priorities) in 1 context. =-
</pre>
</div></div>
<p>You can dial extension <b>6421</b> to try it out on your own.</p>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Be Careful with Pattern Matching</b><br />Please be aware that because of the way auto-fallthrough works, if Asterisk can't find the next priority number for the current extension or pattern match, it will also look for that same priority in a less specific pattern match. Consider the following example:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>exten => 6410,1,SayDigits(987)
exten => _641X,1,SayDigits(12345)
exten => _641X,n,SayDigits(54321)
</pre>
</div></div>
<p>If you were to dial extension <b>6410</b>, you'd hear "nine eight seven five four three two one".</p>
<p>We strongly recommend you make the <b>Hangup()</b> application be the last priority of any extension to avoid this problem, unless you purposely want to fall through to a less specific match.</p></td></tr></table></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Pattern+Matching">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=4817353&revisedVersion=12&originalVersion=11">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Pattern+Matching?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>