Project

General

Profile

Pattern matching » History » Version 10

digitalcircuit, 09/23/2018 09:29 PM
Fix missing literal closing @, fix regex

1 1 digitalcircuit
h1. Pattern matching
2 1 digitalcircuit
3 1 digitalcircuit
{{toc}}
4 1 digitalcircuit
5 1 digitalcircuit
h2. Upgrade notice
6 1 digitalcircuit
7 6 digitalcircuit
*This changed in Quassel @0.13@.  "Follow the migration guide":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Migrating-to-Quassel-013 if you're upgrading from an earlier version.*
8 1 digitalcircuit
9 1 digitalcircuit
When using the client and core with different versions, some ignore rules will be processed differently.
10 1 digitalcircuit
11 1 digitalcircuit
h2. Breakdown of usage
12 1 digitalcircuit
13 1 digitalcircuit
Quassel supports several types of pattern matching for ignore and highlight rules.
14 1 digitalcircuit
15 1 digitalcircuit
h3. Ignore Rules
16 1 digitalcircuit
17 5 digitalcircuit
|_. @Regular expression@ |_. Item        |_. Pattern matching type |
18 5 digitalcircuit
|/2. Unchecked           | @Ignore Rule@ | "Wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Wildcard           |
19 5 digitalcircuit
                         | @Scope@       | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |
20 5 digitalcircuit
|/2. Checked             | @Ignore Rule@ | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |
21 5 digitalcircuit
                         | @Scope@ | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |
22 1 digitalcircuit
23 1 digitalcircuit
_For backwards compatibility, the @Regular expression@ checkbox only affects @Ignore Rule@ and not @Scope@._
24 1 digitalcircuit
25 1 digitalcircuit
h3. Highlight Rules
26 1 digitalcircuit
27 5 digitalcircuit
|_. @RegEx@ |_. Item       |_. Pattern matching type |
28 5 digitalcircuit
|/3. Unchecked | @Rule@    | "Phrase":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Phrase |
29 5 digitalcircuit
               | @Sender@  | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |
30 5 digitalcircuit
               | @Channel@ | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |
31 5 digitalcircuit
|/3. Checked | @Rule@      | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |
32 5 digitalcircuit
               | @Sender@  | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |
33 5 digitalcircuit
               | @Channel@ | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |
34 1 digitalcircuit
35 1 digitalcircuit
_This applies to both @Local Highlights@ and @Remote Highlights@ (or if using Monolithic, @Legacy Highlights@ and @Highlights@)._
36 1 digitalcircuit
37 1 digitalcircuit
h2. Types
38 1 digitalcircuit
39 1 digitalcircuit
h3. Phrase
40 1 digitalcircuit
41 1 digitalcircuit
This matches exactly what you type.
42 1 digitalcircuit
43 1 digitalcircuit
<pre>
44 1 digitalcircuit
word
45 1 digitalcircuit
</pre>
46 1 digitalcircuit
47 1 digitalcircuit
* Matches
48 1 digitalcircuit
** @word@
49 1 digitalcircuit
** @A word.@
50 1 digitalcircuit
** @has a word in it@ 
51 1 digitalcircuit
* Does not match
52 1 digitalcircuit
** @wording@
53 1 digitalcircuit
54 1 digitalcircuit
_Changed in Quassel @0.13@:_
55 1 digitalcircuit
56 1 digitalcircuit
Spaces are matched, too, allowing you to be more specific.
57 1 digitalcircuit
58 1 digitalcircuit
<pre>
59 1 digitalcircuit
 spaced
60 1 digitalcircuit
</pre>
61 1 digitalcircuit
62 1 digitalcircuit
_There's a leading space in the example above._
63 1 digitalcircuit
64 1 digitalcircuit
* Matches
65 1 digitalcircuit
** @, spaced@
66 1 digitalcircuit
** @is spaced out@
67 1 digitalcircuit
* Does not match
68 1 digitalcircuit
** @;spaced@
69 1 digitalcircuit
70 3 digitalcircuit
"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage
71 2 digitalcircuit
72 1 digitalcircuit
h3. Wildcard
73 1 digitalcircuit
74 1 digitalcircuit
_Changed in Quassel @0.13@:_
75 1 digitalcircuit
76 2 digitalcircuit
This uses simple wildcard substitution with @*@ and @?@ to match any characters or a single character, respectively.  The backslash character @\@ allows matching a literal @*@, @?@, or @\@.
77 1 digitalcircuit
78 1 digitalcircuit
<pre>
79 1 digitalcircuit
*Asking questions\?  Nope?
80 1 digitalcircuit
</pre>
81 1 digitalcircuit
82 1 digitalcircuit
* Matches
83 1 digitalcircuit
** @Asking questions? Nopea@
84 1 digitalcircuit
** @Basking questions? Nope.@
85 1 digitalcircuit
* Does not match
86 1 digitalcircuit
** @Asking questions. Nope.@
87 1 digitalcircuit
** @Asking questions? Nopes.@
88 1 digitalcircuit
89 1 digitalcircuit
Implicit wildcard is supported, too, allowing you to match everything *except* for what you specify.
90 1 digitalcircuit
91 1 digitalcircuit
<pre>
92 1 digitalcircuit
!*filter*
93 1 digitalcircuit
</pre>
94 1 digitalcircuit
95 1 digitalcircuit
* Matches
96 1 digitalcircuit
** _Everything, unless it contains something from the below list_
97 1 digitalcircuit
* Does not match
98 1 digitalcircuit
** @filter@
99 1 digitalcircuit
** @filtering@
100 1 digitalcircuit
** @#nofilter yo@
101 1 digitalcircuit
102 1 digitalcircuit
Exclamation points can be escaped at the beginning to match something that starts with @!@ (_this is not required elsewhere_).
103 1 digitalcircuit
104 1 digitalcircuit
<pre>
105 1 digitalcircuit
\!*filter*
106 1 digitalcircuit
</pre>
107 1 digitalcircuit
108 1 digitalcircuit
* Matches
109 1 digitalcircuit
** @!filter@
110 1 digitalcircuit
** @!yes filtering@
111 1 digitalcircuit
* Does not match
112 1 digitalcircuit
** @filter@
113 1 digitalcircuit
114 1 digitalcircuit
The @\@ character can be escaped, too, in case you're matching something that starts with @\!@.
115 1 digitalcircuit
116 1 digitalcircuit
<pre>
117 1 digitalcircuit
\\!*filter*
118 1 digitalcircuit
</pre>
119 1 digitalcircuit
120 1 digitalcircuit
* Matches
121 1 digitalcircuit
** @\!filter@
122 1 digitalcircuit
** @\!yes filtering@
123 1 digitalcircuit
* Does not match
124 1 digitalcircuit
** @filter@
125 1 digitalcircuit
** @!filter@
126 1 digitalcircuit
127 3 digitalcircuit
"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage
128 2 digitalcircuit
129 1 digitalcircuit
h3. Multiple wildcard
130 1 digitalcircuit
131 3 digitalcircuit
This allows matching multiple "wildcard patterns":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Wildcard all in one rule by separating each wildcard with semicolons @;@.
132 2 digitalcircuit
133 2 digitalcircuit
<pre>
134 2 digitalcircuit
alpha; beta*
135 2 digitalcircuit
</pre>
136 2 digitalcircuit
137 2 digitalcircuit
* Matches
138 2 digitalcircuit
** @alpha@
139 2 digitalcircuit
** @betas@
140 2 digitalcircuit
** @beta!@
141 2 digitalcircuit
* Does not match
142 2 digitalcircuit
** @alphamore@
143 2 digitalcircuit
** @nonbeta@
144 2 digitalcircuit
145 2 digitalcircuit
_Changed in Quassel @0.13@:_
146 2 digitalcircuit
147 2 digitalcircuit
More complex wildcard patterns are possible.  Use @\@ to escape special characters.
148 2 digitalcircuit
149 2 digitalcircuit
<pre>
150 2 digitalcircuit
Alice!*; Bob!*@example.com; Carol*!*; !Caroline!*
151 2 digitalcircuit
Dan!*; escaped \; separator; \!not-inverted; \\!slash-prefixed
152 2 digitalcircuit
</pre>
153 2 digitalcircuit
154 2 digitalcircuit
_For ignore rule @Scope@, you can use @;@ and line breaks interchangeably._
155 2 digitalcircuit
156 2 digitalcircuit
* Matches
157 2 digitalcircuit
** @Alice![...]@
158 2 digitalcircuit
** @Bob![...]@example.com@
159 2 digitalcircuit
** @Carol[...]![...]@ except as noted below
160 2 digitalcircuit
** @Dan![...]@
161 2 digitalcircuit
** @escaped ; separator@
162 2 digitalcircuit
** @!not-inverted@
163 2 digitalcircuit
** @\!slash-prefixed@
164 2 digitalcircuit
* Does not match
165 2 digitalcircuit
** @Caroline![...]@
166 10 digitalcircuit
** @Malice![...]@
167 2 digitalcircuit
** @John!@
168 2 digitalcircuit
169 2 digitalcircuit
Implicit wildcard is supported, too, allowing you to match everything *except* for what you specify.
170 2 digitalcircuit
171 2 digitalcircuit
<pre>
172 2 digitalcircuit
!Announce*!*; !Wheatley!aperture@*
173 2 digitalcircuit
</pre>
174 2 digitalcircuit
175 2 digitalcircuit
* Matches
176 2 digitalcircuit
** _Everything, unless it contains something from the below list_
177 2 digitalcircuit
* Does not match
178 2 digitalcircuit
** @Announce[...]![...]@
179 10 digitalcircuit
** @Wheatley!aperture@@[...]
180 2 digitalcircuit
181 3 digitalcircuit
"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage
182 2 digitalcircuit
183 1 digitalcircuit
h3. Regular expression
184 1 digitalcircuit
185 2 digitalcircuit
This matches using the full regular expression language, best for complex rules and those already familiar with how regular expressions work.  Quassel offers a non-standard @!@ prefix to invert the rule; if not desired, escape as @\!@.
186 2 digitalcircuit
187 2 digitalcircuit
The web provides many resources for testing and verifying regular expressions, including https://regex101.com/ .
188 2 digitalcircuit
189 2 digitalcircuit
Some differences exist from Perl due to design choices and limitations of the Qt framework.  These are documented on the Qt documentation site for "QRegularExpression":https://doc.qt.io/qt-5/qregularexpression.html#unsupported-perl-compatible-regular-expressions-features with Qt 5, and "QRegExp":https://doc.qt.io/qt-5/qregexp.html#notes-for-perl-users for Qt 4.  If you're not sure, you're likely using a Qt 5 build.
190 2 digitalcircuit
191 2 digitalcircuit
<pre>
192 2 digitalcircuit
simple.\*escape-match.*
193 2 digitalcircuit
</pre>
194 2 digitalcircuit
195 2 digitalcircuit
* Matches
196 2 digitalcircuit
** @simpleA*escape-match@
197 2 digitalcircuit
** @simpleA*escape-matchBBBB@
198 2 digitalcircuit
* Does not match
199 2 digitalcircuit
** @not above@
200 2 digitalcircuit
** @simpleA*escape-mat@
201 2 digitalcircuit
** @simple*escape-match@
202 2 digitalcircuit
** @simpleABBBBescape-matchBBBB@
203 2 digitalcircuit
204 2 digitalcircuit
Inverted rules are supported, allowing you to match everything *except* for what you specify.
205 2 digitalcircuit
206 2 digitalcircuit
<pre>
207 2 digitalcircuit
!invert.\*escape-match.*
208 2 digitalcircuit
</pre>
209 2 digitalcircuit
210 2 digitalcircuit
* Matches
211 2 digitalcircuit
** _Everything, unless it contains something from the below list_
212 2 digitalcircuit
* Does not match
213 2 digitalcircuit
** @invertA*escape-match@
214 2 digitalcircuit
** @invertA*escape-matchBBBB@
215 2 digitalcircuit
216 2 digitalcircuit
_Changed in Quassel @0.13@:_
217 2 digitalcircuit
218 2 digitalcircuit
Exclamation points can be escaped at the beginning to match something that starts with @!@ (_this is not required elsewhere_).
219 2 digitalcircuit
220 2 digitalcircuit
<pre>
221 2 digitalcircuit
\!simple.\*escape-match.*
222 2 digitalcircuit
</pre>
223 2 digitalcircuit
224 2 digitalcircuit
* Matches
225 2 digitalcircuit
** @!simpleA*escape-matchBBBB@
226 2 digitalcircuit
* Does not match
227 2 digitalcircuit
** @simpleA*escape-matchBBBB@
228 2 digitalcircuit
229 2 digitalcircuit
The @\@ character can be escaped, too, in case you're matching something that starts with @\!@.
230 2 digitalcircuit
231 2 digitalcircuit
<pre>
232 2 digitalcircuit
\\!simple.\*escape-match.*
233 2 digitalcircuit
</pre>
234 2 digitalcircuit
235 1 digitalcircuit
* Matches
236 2 digitalcircuit
** @\!simpleA*escape-matchBBBB@
237 1 digitalcircuit
* Does not match
238 1 digitalcircuit
** @!simpleA*escape-matchBBBB@
239 1 digitalcircuit
240 1 digitalcircuit
"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage
241 1 digitalcircuit
242 4 digitalcircuit
h2. Migrating to Quassel @0.13@
243 1 digitalcircuit
244 4 digitalcircuit
Quassel @0.13@ introduced new behavior for pattern matching to provide more flexibility and to improve performance.  Unfortunately, due to the complexity of automatically migrating (_patches welcome!_), you might have to manually migrate some ignore and highlight rules.
245 1 digitalcircuit
246 7 digitalcircuit
If you're writing new rules, you can start at the "breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage.
247 7 digitalcircuit
248 1 digitalcircuit
h3. Ignore Rules
249 1 digitalcircuit
250 4 digitalcircuit
The wildcard matching mode now allows inverting the match with @!@, and escaping @*@ and @?@ with @\@, so you can match a phrase containing question marks or asterisks.  However, this means @\@ must now be escaped as @\\@, and @!@ at the start must be escaped as @\!@.
251 2 digitalcircuit
252 4 digitalcircuit
*Example of converting old wildcard rules to new format*
253 5 digitalcircuit
|_. Before             |_. After               |_. Remarks |
254 4 digitalcircuit
| @!literal-matching!@ | @\!literal-matching!@ | Only need to escape @!@ if it's at the start |
255 5 digitalcircuit
| @slashes \ within@   | @slashes \\ within@   |                                              |
256 5 digitalcircuit
| @\! prefixed@        | @\\! prefixed@        |                                              |
257 4 digitalcircuit
258 4 digitalcircuit
The regular expression format now allows for escaping the first @!@ in case you want to literally match it, e.g. @\!regex.*@.
259 4 digitalcircuit
260 8 digitalcircuit
*If your client and core version do not match, they will process some ignore rules differently.*
261 4 digitalcircuit
262 8 digitalcircuit
If you've upgraded your Quassel client to @0.13@ and upgrading the Quassel core to @0.13@ is not yet feasible, you can workaround this for ignore rules that start with @!@ or contain @\@ by migrating them as above.  For @Permanent@ ignore rules, the core will keep pattern matching according to pre-@0.13@ behavior, which likely won't cause issues.  If it does, you can temporarily change the affected ignore rules to @Dynamic@.
263 4 digitalcircuit
264 1 digitalcircuit
h3. Highlight Rules
265 4 digitalcircuit
266 4 digitalcircuit
The @RegEx@ checkbox now affects the @Channel@ column, too, switching between multiple wildcard and regular expressions "as described above":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching/edit#Highlight-Rules.
267 4 digitalcircuit
268 8 digitalcircuit
*Your existing highlight rules are automatically migrated to @RegEx@ if you've specified anything in the @Channel@ column.*  Any affected rules will surround the phrase like so, <notextile>(^\|\W)original phrase(\W\|$)</notextile>.
269 1 digitalcircuit
270 8 digitalcircuit
If you want to make use of the new multiple wildcard matching mode, uncheck @RegEx@ and set @Channel@ to a multiple wildcard pattern.
271 4 digitalcircuit
272 8 digitalcircuit
_Example of undoing automatic @RegEx@ conversion to use new wildcard mode_
273 8 digitalcircuit
274 5 digitalcircuit
|_. @RegEx@    |_. Item    |_. Pattern                                             |
275 5 digitalcircuit
|/2. Checked   | @Rule@    | <notextile>(^\|\W)highlight phrase(\W\|$)</notextile> |
276 10 digitalcircuit
               | @Channel@ | <notextile>#quassel(|-.*)</notextile>                  |
277 5 digitalcircuit
|/2. Unchecked | @Rule@    | highlight phrase                                      |
278 4 digitalcircuit
               | @Channel@ | #quassel; #quassel-*                                  |
279 1 digitalcircuit
280 4 digitalcircuit
With the @Remote Highlights@ feature in Quassel @0.13@, the @Sender@ column behaves the same way as the @Channel@ column, switching modes according to the @RegEx@ checkbox.
281 1 digitalcircuit
282 1 digitalcircuit
h2. Technical details
283 1 digitalcircuit
284 8 digitalcircuit
For all the technical details and source code changes, take a look at "Quassel pull request #415":https://github.com/quassel/quassel/pull/415.  @MultiPhrase@ is not covered here as it's only used inside Quassel for nickname matching.