The Barracuda Phone System uses Perl-compatible regular expressions for pattern matching in outbound gateways. The vast majority of all patterns that must be matched in outbound routes are digit-based only, therefore, the following tables focus on matching number patterns.
Basic Usage
Regular expressions use a combination of standard and meta-characters to create a pattern against which to match a specific string. Characters in the regular expression can mean different things depending on the context. For the sake of simplicity, this article focuses on the basic operation of regular expressions.
The basic use of a regular expression is in a pattern match. The system compares a regular expression to a string of characters to determine if the string of characters matches the pattern described by the regular expression. The answer is either yes or no. Sometimes a yes is called a positive match and a no is called a negative match.
Sample Patterns
Table 1 lists common characters in a regular expression.
Table 1. Regular Expression Common Characters.
Character | Meaning |
---|---|
1 | Match only the digit 1 |
5 | Match only the digit 5 |
411 | Match digit sequence 411 |
^411 | Match string beginning with 411 |
411$ | Match string ending with 411 |
^411$ | Match exact string 411(1) |
[0-9] | Match any digit between 0 and 9 |
[2-9] | Match any digit between 2 and 9 |
[456] | Match either the digit 4, 5, or 6 |
# | Match the # sign |
\* | Match a literal * (2) |
\d | Match any digit between 0 and 9 |
^ | Match at beginning of string |
$ | Match at end of string |
+ | Match one or more of the preceding character |
* | Match zero or more of the preceding character |
{n} | Match exactly n of the preceding character |
Notes: (2) Note the backslash; this is different than a bare asterisk '*' |
The list of characters in Table 1 is by no means comprehensive, however it is a good representation of the kinds of characters that appear in regular expression number routes. Table 2 lists examples of how these expressions might be used in matching patterns for outbound dialing, illustrating some simple patterns, strings, and whether there is a match.
Table 2. Sample Patterns.
Pattern | Dialed Number | Match? | Notes |
---|---|---|---|
411 | 411 | Yes | |
411 | 4085550411 | Yes | Matches any number that includes 411 |
^411$ | 411 | Yes | |
^411$ | 4085550411 | No | Matches only the exact dialed 411 |
^5[0-9][0-9][0-9] | 5000 | Yes | Matches any four digit number beginning with 5 |
^5\d\d\d$ | 5000 | Yes | Same as previous pattern, \d matches any digit |
^5\d{3}$ | 5000 | Yes | Same as previous pattern, \d{3} same as \d\d\d |
^71\d\d$ | 7150 | Yes | |
^71\d\d$ | 7050 | No | Matches only dialed numbers from 7100 to 7199 |
^\d{7}$ | 5551212 | Yes | |
^\d{10}$ | 4085551212 | Yes |
The examples in Table 2 demonstrate the syntax for specifying dialed patterns.
Syntax Rules
To match an exact dial string, use ^ and $ at the beginning and end of your regular expression. The caret (^) means "match at the beginning of the string" and the dollar sign ($) means match at the end of the string. Reviewing the 411 examples in the previous table, the following syntax rules apply:
- The pattern 411 means match any string that contains 411
- The pattern ^411 means match any string that begins with 411
- The pattern 411$ means match any string that ends with 411
- The pattern ^411$ means match any string that matches exactly 411
- To match a range of numbers, use a combination of literal numbers and meta-characters.
Consider these examples:
- The pattern 7\d\d\d matches 7000 through 7999
- The pattern 74\d\d matches 7400 through 7499
- The pattern 745\d matches 7450 through 7459
- 408\d{7} matches calls made to area code 408
- 212\d{7} matches calls made to area code 212
Replacing and Trimming Digits
In some cases you may want to add or remove digits before they are sent out, for example, "dial 9 to get an outside line." Table 3 lists examples of inserting digits.
Table 3. Inserting Digits.
Pattern | Dialed Digits | Digits Actually Sent Out |
---|---|---|
^9(1\d{10}):::$1 | 918005551212 | 18005551212 |
^9(\d{7}):::$1 | 95551212 | 5551212 |
In the examples in Table 3, the leading digit 9 is matched, but not captured. Instead, all digits dialed after the 9 are captured. The expression ":::$1" means to replace what was actually dialed with what was captured inside the "(" and ")" characters.
In some cases you may want to allow users to dial 9 (or not) and dial 1 (or not) and then have the system dial appropriately. For example, some carriers absolutely require you to send 1 + area code + phone number for all calls, even local ones. Others require all 10 digits of the phone number but do not want the leading 1. Table 4 lists some sample regular expressions for such situations:
Table 4. Sample Regular Expressions.
Pattern | Dialed Digits | Sent Digits | Application |
---|---|---|---|
^9?1?(\d{10})$:::$1 | 918005551212 | 8005551212 | Dialing 9 or 1 optional, send only 10 digits |
^9?1?(\d{10})$:::1$1 | 918005551212 | 18005551212 | Dialing 9 or 1 optional, send 1 + 10 digits |
^9?(\d{7})$:::408$1 | 95551212 | 4085551212 | Dialing 9 optional, user’s 7 digits, system adds and sends area code |
^9?(\d{7})$:::1408$1 | 95551212 | 14085551212 | Dialing 9 optional, user’s 7 digits, system adds/sends 1+area code |
Regular Expression Caveats
There are occasions when regular expression matches may not function in the expected manner. Other times there are unintended consequences of using a specific pattern. One such caveat has to do with vanity numbers. For example, the outbound route pattern ^1?(\d{10})$:::1$1 (optional 1 plus exactly 10 digits) works for any typical North American 10-digit phone number, whether or not the caller dials a leading 1. But a vanity number such as 1-800-ANTI-SPAM has 1 plus 11 digits which fails to match. Therefore, dialing 1 plus 800-2684-7726 fails. There are two ways in which to prevent this:
- Educate your users on vanity numbers in your locale. In North America that would mean simply dialing the first 10 digits following the 1. In the case of 1-800-ANTI-SPAM the call simply dials 1-800-268-4772.
- Write a pattern that explicitly handles these kinds of numbers. In North America this may mean matching an extra digit but not actually capturing it. The above pattern could be modified in the following manner:
^1?(\d{10})\d?$:::1$1
You can also modify the NANPA pattern to handle an extra digit:
^1?([2-9]\d{2}[2-9]\d{6})\d?$:::1$1
Both of the modified patterns allow an extra digit in the dialed which is not captured (it is ignored) so only the first 10 digits after the optional leading 1 are compared for a match.
Handling E.164 Formatted Numbers
Many contacts and phone numbers are in E.164 format. The primary characteristic of E.164 numbers is a leading + in the phone number. Examples of E.164 formatted numbers include:
- +14083425300 (USA)
- +443300100295 (UK)
- +34912901271 (Spain)
- +61731887519 (Australia)
- +27878204656 (South Africa)
When the Barracuda Phone System receives an inbound call it automatically strips the leading + character because once the call is at the destination the + character serves no purpose. Outbound calls behave differently. Sometimes a registered endpoint sends a phone number that has a leading plus character. For example, a contact dialed from the Communication Command Center could contain a leading +. In this situation the Barracuda Phone System does not strip a leading + from an outbound dialed sequence. Outbound routes that might see E.164 formatted numbers must account for the leading plus. Table 5 lists regular expression patterns you can use to accomplish this.
Table 5. Regular Expression Patterns to use with E.164 Formatted Numbers.
Expression | Description |
---|---|
^\+? | Meaning match an optional leading plus character |
^\+(\d{5,15})$:::$1 | A full E.164 Barracuda Phone System route which strips off the leading plus and sends only numeric digits to the destination |
.