# Pattern Matching

If we want to be able to allow people to dial through Asterisk and have Asterisk connect them to outside resources, we need a way to match on any possible phone number that the caller might dial. For situations like this, Asterisk offers pattern matching. Pattern
matching allows you to create one extension in your dialplan that matches many different numbers. This is enormously useful.

### (Pattern-matching syntax)

When using pattern matching, certain letters and symbols represent what we are trying to match. Patterns always start with an underscore (_). This tells Asterisk that we’re matching on a pattern, and not on an explicit extension name.
After the underscore, you can use one or more of the following characters:
X
Matches any single digit from 0 to 9.
Z
Matches any single digit from 1 to 9.
N
Matches any single digit from 2 to 9.
[15-7]
Matches a single character from the range of digits specified. In this case, the patternmatches a single 1, as well as any number in the range 5, 6, 7.
(period) Wildcard match; matches one or more characters, no matter what they are.
!(bang) Wildcard match; matches zero or more characters, no matter what they are.
To use pattern matching in your dialplan, simply put the pattern in the place of the extension name (or number):
exten => _NXX,1,Playback(silence/1&auth-thankyou)
In this example, the pattern matches any three-digit extension from 200 through 999(the N matches any digit between 2 and 9, and each X matches a digit between 0 and 9). That is to say, if a caller dialed any three-digit extension between 200 and 999 in this context, he would hear the sound file auth-thankyou.gsm.
One other important thing to know about pattern matching is that if Asterisk finds more than one pattern that matches the dialed extension, it will use the most specific one (going from left to right). Say you had defined the following two patterns, and a caller dialed 555-1212:
exten => _555XXXX,1,Playback(silence/1&digits/1)
exten => _55512XX,1,Playback(silence/1&digits/2)
In this case the second extension would be selected, because it is more specific.

### (Pattern-matching example)

This pattern matches any seven-digit number, as long as the first digit is 2 or higher:
_NXXXXXX
The preceding pattern would be compatible with any North American Numbering Plan local seven-digit number. In areas with 10-digit dialing, that pattern would look like this:
_NXXNXXXXXX
Note that neither of these two patterns would handle long-distance calls.
Let’s try another:
_1NXXNXXXXXX
This one will match the number 1, followed by an area code between 200 and 999, then any seven-digit number. In the NANP calling area, you would use this pattern to match any long-distance number.
And finally this one:
_011.
Note the period on the end. This pattern matches any number that starts with 011 and has at least one more digit. In the NANP, this indicates an international phone number. (We’ll be using these patterns in the next section to add outbound dialing capabilities to our dialplan.)

#### Using the \${EXTEN} channel variable

So what happens if you want to use pattern matching but need to know which digits were actually dialed? Enter the \${EXTEN}
channel variable. Whenever you dial an ex‐ tension, Asterisk sets the \${EXTEN} channel variable to the digits that were dialed. We can use an application called SayDigits() to test this out:
same => n,SayDigits(\${EXTEN})
In this example, the SayDigits() application will read back to you the three-digit extension you dialed.
Often, it’s useful to manipulate the \${EXTEN} by stripping a certain number of digits off the front of the extension. This is accomplished by using the syntax \${EXTEN:x}, where x is where you want the returned string to start, from left to right. For example, if the value of\${EXTEN} is 95551212, \${EXTEN:1} equals 5551212. Let’s try another example:
same => n,SayDigits(\${EXTEN:1})
In this example, the SayDigits() application would start at the second digit, and thus read back only the last two digits of the dialed extension.

# Includes

Asterisk has an important feature that allows extensions from one context to be available from within another context. This is accomplished through use of the include directive. The include directive allows us to control access to different sections of the dialplan.
The include statement takes the following form, where context is the name of the remote context we want to include in the current context:
include =>context
Including one context within another context allows extensions within the included context to be dialable.
When we include other contexts within our current context, we have to be mindful of the order in which we are including them. Asterisk will first try to match the dialed extension in the current context. If unsuccessful, it will then try the first included context
(including any contexts included in that context), and then continue to the other included contexts in the order in which they were included.