Quassel IRC

h1. Pattern matching

*WORK IN PROGRESS*

{{toc}}

h2. Upgrade notice

*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.*

When using the client and core with different versions, some ignore rules will be processed differently.

h2. Breakdown of usage

Quassel supports several types of pattern matching for ignore and highlight rules.

h3. Ignore Rules

|_. @Regular expression@ |_. Item        |_. Pattern matching type |

|/2. Unchecked           | @Ignore Rule@ | "Wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Wildcard           |

                         | @Scope@       | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |

|/2. Checked             | @Ignore Rule@ | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |

                         | @Scope@ | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |

_For backwards compatibility, the @Regular expression@ checkbox only affects @Ignore Rule@ and not @Scope@._

h3. Highlight Rules

|_. @RegEx@ |_. Item       |_. Pattern matching type |

|/3. Unchecked | @Rule@    | "Phrase":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Phrase |

               | @Sender@  | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |

               | @Channel@ | "Multiple wildcard":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Multiple-wildcard  |

|/3. Checked | @Rule@      | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |

               | @Sender@  | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |

               | @Channel@ | "Regular expression":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Regular-expression |

_This applies to both @Local Highlights@ and @Remote Highlights@ (or if using Monolithic, @Legacy Highlights@ and @Highlights@)._

h2. Types

h3. Phrase

This matches exactly what you type.

<pre>

word

</pre>

* Matches

** @word@

** @A word.@

** @has a word in it@ 

* Does not match

** @wording@

_Changed in Quassel @0.13@:_

Spaces are matched, too, allowing you to be more specific.

<pre>

 spaced

</pre>

_There's a leading space in the example above._

* Matches

** @, spaced@

** @is spaced out@

* Does not match

** @;spaced@

"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage

h3. Wildcard

_Changed in Quassel @0.13@:_

This uses simple wildcard substitution with @*@ and @?@ to match any characters or a single character, respectively.  The backslash character @\@ allows matching a literal @*@, @?@, or @\@.

<pre>

*Asking questions\?  Nope?

</pre>

* Matches

** @Asking questions? Nopea@

** @Basking questions? Nope.@

* Does not match

** @Asking questions. Nope.@

** @Asking questions? Nopes.@

Implicit wildcard is supported, too, allowing you to match everything *except* for what you specify.

<pre>

!*filter*

</pre>

* Matches

** _Everything, unless it contains something from the below list_

* Does not match

** @filter@

** @filtering@

** @#nofilter yo@

Exclamation points can be escaped at the beginning to match something that starts with @!@ (_this is not required elsewhere_).

<pre>

\!*filter*

</pre>

* Matches

** @!filter@

** @!yes filtering@

* Does not match

** @filter@

The @\@ character can be escaped, too, in case you're matching something that starts with @\!@.

<pre>

\\!*filter*

</pre>

* Matches

** @\!filter@

** @\!yes filtering@

* Does not match

** @filter@

** @!filter@

"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage

h3. Multiple wildcard

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 @;@.

<pre>

alpha; beta*

</pre>

* Matches

** @alpha@

** @betas@

** @beta!@

* Does not match

** @alphamore@

** @nonbeta@

_Changed in Quassel @0.13@:_

More complex wildcard patterns are possible.  Use @\@ to escape special characters.

<pre>

Alice!*; Bob!*@example.com; Carol*!*; !Caroline!*

Dan!*; escaped \; separator; \!not-inverted; \\!slash-prefixed

</pre>

_For ignore rule @Scope@, you can use @;@ and line breaks interchangeably._

* Matches

** @Alice![...]@

** @Bob![...]@example.com@

** @Carol[...]![...]@ except as noted below

** @Dan![...]@

** @escaped ; separator@

** @!not-inverted@

** @\!slash-prefixed@

* Does not match

** @Caroline![...]@

** @Malice![...]

** @John!@

Implicit wildcard is supported, too, allowing you to match everything *except* for what you specify.

<pre>

!Announce*!*; !Wheatley!aperture@*

</pre>

* Matches

** _Everything, unless it contains something from the below list_

* Does not match

** @Announce[...]![...]@

** @Wheatley!aperture@[...]@

"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage

h3. Regular expression

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 @\!@.

The web provides many resources for testing and verifying regular expressions, including https://regex101.com/ .

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.

<pre>

simple.\*escape-match.*

</pre>

* Matches

** @simpleA*escape-match@

** @simpleA*escape-matchBBBB@

* Does not match

** @not above@

** @simpleA*escape-mat@

** @simple*escape-match@

** @simpleABBBBescape-matchBBBB@

Inverted rules are supported, allowing you to match everything *except* for what you specify.

<pre>

!invert.\*escape-match.*

</pre>

* Matches

** _Everything, unless it contains something from the below list_

* Does not match

** @invertA*escape-match@

** @invertA*escape-matchBBBB@

_Changed in Quassel @0.13@:_

Exclamation points can be escaped at the beginning to match something that starts with @!@ (_this is not required elsewhere_).

<pre>

\!simple.\*escape-match.*

</pre>

* Matches

** @!simpleA*escape-matchBBBB@

* Does not match

** @simpleA*escape-matchBBBB@

The @\@ character can be escaped, too, in case you're matching something that starts with @\!@.

<pre>

\\!simple.\*escape-match.*

</pre>

* Matches

** @\!simpleA*escape-matchBBBB@

* Does not match

** @!simpleA*escape-matchBBBB@

"Return to breakdown of usage":https://bugs.quassel-irc.org/projects/quassel-irc/wiki/Pattern_matching#Breakdown-of-usage

h2. Migrating to Quassel @0.13@

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.

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.

h3. Ignore Rules

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 @\!@.

*Example of converting old wildcard rules to new format*

|_. Before             |_. After               |_. Remarks |

| @!literal-matching!@ | @\!literal-matching!@ | Only need to escape @!@ if it's at the start |

| @slashes \ within@   | @slashes \\ within@   |                                              |

| @\! prefixed@        | @\\! prefixed@        |                                              |

The regular expression format now allows for escaping the first @!@ in case you want to literally match it, e.g. @\!regex.*@.

*If your client and core version do not match, they will process some ignore rules differently.*

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@.

h3. Highlight Rules

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.

*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>.

If you want to make use of the new multiple wildcard matching mode, uncheck @RegEx@ and set @Channel@ to a multiple wildcard pattern.

_Example of undoing automatic @RegEx@ conversion to use new wildcard mode_

|_. @RegEx@    |_. Item    |_. Pattern                                             |

|/2. Checked   | @Rule@    | <notextile>(^\|\W)highlight phrase(\W\|$)</notextile> |

               | @Channel@ | <notextile>#quassel(|-*)</notextile>                  |

|/2. Unchecked | @Rule@    | highlight phrase                                      |

               | @Channel@ | #quassel; #quassel-*                                  |

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.

h2. Technical details

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.