Changes between Version 60 and Version 61 of TracQuery

Timestamp:

May 27, 2022, 7:11:08 PM (2 years ago)

Author:

Clemens

Comment:

Improved documentation for query language syntax differences for [query:?] vs. [[TicketQuery]]. See my mailing list discussion with Ryan on 2022-05-25.

TracQuery

@@ -68 +68 @@
 == Query Language
 
-The `query:` TracLinks and the [TicketQuery "[[TicketQuery]]"] macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (`&`). Each filter consists of the ticket field name, an operator and one or more values. Multiple values are separated using a pipe (`|`), meaning the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).
+The `query:` TracLinks and the [TicketQuery "[[TicketQuery]]"] macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (`&`), the `[[TicketQuery]]` macro additionally also accepts commas (`,`).  Each filter consists of the ticket field name, an operator and one or more values. Multiple values are separated using a pipe (`|`), meaning the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).
 
 The available operators are:
@@ -82 +82 @@
 || '''`!$=`''' || the field content does not end with any of the values ||
 
-Filters combining matches and negated matches can be constructed for text fields such as Keywords and CC using the //contains// (`~=`) operator. The `-` operator is used to negate a match and double quotes (//since 1.2.1//) are used for whitespace-separated words in a phrase. For example, `keywords~=word1 word2 -word3 "word4 word5"` matches tickets containing `word1` and `word2`, not `word3` and also `word4 word5`.
+Filters combining matches matches can be constructed for text fields such as Keywords and CC using the //contains// (`~=`) operator. 
+The `!` operator is used to negate a match. 
+
+Note that for `query:` the match operator `=` needs to be on first position when combined with other operators, for example `=!` or `=~`. The `[[TicketQuery]]` macro on the other side accepts both syntax variants, for example `!=` or `~=` as well as `=!` or `=~`.
+
+Double quotes (//since Trac 1.2.1//) are used for whitespace-separated words in a phrase. For example, `keywords~=word1 word2 -word3 "word4 word5"` matches tickets containing `word1` and `word2`, not `word3` and also `word4 word5`.
+
 || '''`status=closed,keywords~=firefox`''' || query closed tickets that contain keyword `firefox` ||
 || '''`status=closed,keywords~=opera`''' || query closed tickets that contain keyword `opera` ||