docs: rewrite pattern matching documentation #58
Conversation
arthursimas1
force-pushed
the
docs-pattern-matching
branch
from
d7d6d3d to
2bcff2e
Compare
| A numeric range can be used to match against a dialed number. This is also called a Character Set | ||
|
|
||
| !!! note | ||
| The only characters with special meaning within a set are the `-` character, to define a range between two characters, the `\` character to escape a special character available within a set, and |
There was a problem hiding this comment.
What is the other character with special meaning? Notice the final and ...
There was a problem hiding this comment.
The only characters with special meaning within a set are the
-character, to define a range between two characters, the\character to escape a special character available within a set, and the]character which closes the set. The treatment of the\character in pattern matching is somewhat haphazard and may not escape any special character meaning correctly.
|
|
||
| !!! warning 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: | ||
| 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 next priority in a less specific pattern match. |
There was a problem hiding this comment.
If I write it as "it will look for that next priority in a less specific pattern match", does it still represents the correct behaviour? I thought it's clearer.
There was a problem hiding this comment.
I would leave it as "same"
Edit: or you could remove the word entirely:
- it will also look for that same priority in a less specific
+ it will look for that priority in a less specific
|
@arthursimas1 Thanks for the contribution! It's a lot so it'll probably take us a few days to get through it. |
|
Yeah, I perfectly understand. Take your time! (just don't forget about it 😂) |
|
|
||
| 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. | ||
|
|
||
| Special Characters Used in Pattern Matching | ||
| =========================================== | ||
| **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 a *family* of dial numbers. |
There was a problem hiding this comment.
(optional) Family might come with some semantic connotations. I think 'set' or 'pattern' would be more neutral here.
There was a problem hiding this comment.
changed to "collection". thank you!
| - | ||
| **Examples**: | ||
| * `_gr[ae]y`: Matches `gray`, `grey` | ||
| * `_[1-468]`: Matches `1`, `2`, `3`, `4`, `6`, `8`. It does not match any number from one to four hundred sixty-eight! |
|
|
||
| * . The '.' character matches one or more characters | ||
| * ! The '!' character matches zero or more characters immediately | ||
| * `!`: Matches zero or more characters *immediately*. Equivalent to RegEx's `*` quantifier. The behaviour of this wildcard is |
There was a problem hiding this comment.
Thanks. I forgot to complete the writing of that one when trying to understand the difference between . and ! regardless of the character count. Now I need more clarification from devs.
There was a problem hiding this comment.
I don't know regex well so I can't comment on your addition of referencing RegEx (I'd probably opt to leave it out so there is no confusion over the dialplan being regex).
What are you seeking clarification on exactly?
|
|
||
|
|
||
| **Examples**: | ||
| * `_9876.`: Matches any number that began with `9876` and has at least one more character or digit, *e.g* `98760`, `9876a`, `9876xxx`... | ||
|
|
||
| The exclamation mark wildcard (!), behaves specially and will be further explained below in 'Other Special Characters' below. |
There was a problem hiding this comment.
It might make sense to mention this directly in line 48 where "! " is being defined, and not separately here.
There was a problem hiding this comment.
I tried to explain better the line 48 and added another example regarding the ! wildcard. Please, have a look.
|
|
||
|
|
||
| Auto-Fallthrough |
There was a problem hiding this comment.
I find this rather surprising and subtle and wonder whether this behavior should be linked to more prominently from a more top-level location?
There was a problem hiding this comment.
I found this behaviour hidden in that page and made a special section for that. If you'd like to propose a more specific change to make it more prominent...
|
|
| * `!`: Matches zero or more characters *immediately*. Equivalent to RegEx's `*` quantifier. This wildcard behaves specially. 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. | ||
| * `.`: Matches one or more characters. Equivalent to RegEx's `+` quantifier. |
There was a problem hiding this comment.
- Only
!is used for overlap dialing or.can also be used? Is this the difference that the old text was talking about? - I couldn't find nothing regarding overlap dialing on the Asterisk docs. Does this page exist? We could link it here. If it's missing, we can write something in that matter (example)
There was a problem hiding this comment.
@InterLinked1 Can you give your thoughts on this since you probably have insight into overlap dialing?
There was a problem hiding this comment.
I don't think there's anything special dialplan wise for overlap dialing. It's not really an Asterisk concept, it's a standard thing in industry. This is something that exists for both ISDN and SIP, but in a SIP context, it allows a phone to not have a digit map configured locally corresponding to the dialplan in Asterisk, and instead it just sends an INVITE after each digit and Asterisk sends a 484 or 486 (I think) if the destination doesn't match an extension. In the case of simple switch, it's actually very direct, sig_analog just calls the PBX functions to see if an unambiguous match was been reached yet (or an ambiguous one, with a timeout).
Basically, it makes it work similarly to native dialing in Asterisk, like with chan_dahdi's simple switch, or the DISA application, etc. It will start executing an extension if that is the only unambiguous match that remains.
If you have a pattern like _X! for example, that would match almost anything, so that would break overlap dialing really, so typically you don't want to use broad patterns like that in the incoming context for an endpoint. However, I do use them all the time in other contexts that are "in the middle", like for routing purposes, where you just want to match anything that goes through a context.
So to answer your question, you typically don't use wildcard pattern matches for the incoming context since that makes overlap dialing impossible, since anything would immediately match rather than the specific things that should be valid. These are useful, but not for overlap dialing per se, more just for pattern matching in general, where you might want to watch things starting with something, regardless of what comes after. So they really can be though of just in terms of their regex equivalents.
For example, _X! will match any numeric extension, although _X. would not match single-digit extensions.
Neither of these would match the extension, say, #, but something like _[sA-D0-9*#]! would (this is my default pattern match I use to catch everything).
Sorry for rambling, hope that answered the question but if not... I can clarify.
|
@jms72 I really appreciate the time you spent to review this. Thank you! |
| @@ -54,20 +54,20 @@ Within each extension, there must be one or more *priorities*. A priority is sim | |||
|
|
|||
|
|
|||
|
|
|||
| ``` | |||
There was a problem hiding this comment.
The "tip" just above this line (I can't mark it directly in this review because you didn't change it, should read:
!!! tip
Priority numbers must begin with 1, and must increment sequentially. If Asterisk can't find the next priority number, it will terminate the call. We call this *auto-fallthrough*. Consider the example below:
[//]: # (end-tip)
| * `_gr[ae]y`: Matches `gray`, `grey` | ||
| * `_[1-468]`: Matches `1`, `2`, `3`, `4`, `6`, `8`. Note that it does **NOT** match numbers from one to four hundred sixty-eight! | ||
| * `_a[c-e]`: Matches `ac`, `ad`, `ae` | ||
| * `_[127-9ac-e]`: Matches `1`, `2`, `7`, `8`, `9`, `a`, `c`, `d`, `e` |
There was a problem hiding this comment.
These aren't getting rendered correctly. You may need a blank line between **Examples**: and the first bullet:
| **Examples**: | ||
| * `_6[34]XX`: Short form of `_64XX` and `_63XX`, matches `6400`, `6300`, `6401`, `6301`, `6420`, `6320`, `6433`, `6333`, ... | ||
| * `_6[34X]`: Matches `63`, `64`, `6X`. The `X`, `N`, and `Z` convenience notations have no special meaning within a set, they represent the literal character. |
There was a problem hiding this comment.
Same issue with this bulleted list, not getting rendered as a list.
gtjoseph
force-pushed
the
main
branch
3 times, most recently
from
55ca168 to
59a13c5
Compare
|
I'm closing and re-opening this PR so it triggers the new workflow job that does a temporary build. |
|
Thanks all for the review! I'll take a look into it in the following days (the PR isn't abandoned!) |
This PR proposes a rewrite in the pattern matching documentation for better clarity and organization.
I first started to fix the final section about Matching on Caller ID, but then I realized that the whole document could be further improved.
I'm willing to change it based on your suggestions.
I need some clarification:
The only characters with special meaning within a set are the '-' character, to define a range between two characters, the '\' character to escape a special character available within a set, andWhat is the other character with special meaning? Notice the final and ...
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.If I write it as "it will look for that next priority in a less specific pattern match", does it still represents the correct behaviour? I thought it's clearer.
Only
!is used for overlap dialing or.can also be used? Is this the difference that the old text was talking about?I couldn't find nothing regarding overlap dialing on the Asterisk docs. Does this page exist? We could link it here. If it's missing, we can write something in that matter (example)
Resolves: #56