Extend the filter() documentation slightly

People tend to try using parentheses in their filter expressions for obvious reasons. But it is not possible. I feel like this should be mentioned in the documentation. In fact, with DNF you never need parentheses to express any expression and I think this fact also needs to be noted there. Signed-off-by: Ondrej Moris <[email protected]> Co-authored-by: Petr Šplíchal <[email protected]>
teemtee · Jun 5, 2024 · bfeb539 · bfeb539
1 parent bf511f5
commit bfeb539
Showing 1 changed file with 10 additions and 3 deletions.
diff --git a/fmf/utils.py b/fmf/utils.py
@@ -215,13 +215,20 @@ def filter(filter, data, sensitive=True, regexp=False, name=None):
     """
     Apply advanced filter on the provided data dictionary
 
-    Filter supports disjunctive normal form with '|' used for OR, '&'
-    for AND and '-' for negation. Individual values are prefixed with
-    'value:', leading/trailing white-space is stripped. For example::
+    Filter supports disjunctive normal form (DNF) with '|' used for OR,
+    '&' for AND and '-' for negation. Individual values are prefixed
+    with 'key:', leading/trailing white-space is stripped. For example::
 
         tag: Tier1 | tag: Tier2 | tag: Tier3
         category: Sanity, Security & tag: -destructive
 
+    Grouping boolean expressions using parentheses is not supported but
+    the correct DNF order of precedence of operators is respected
+    (negation first, AND next and then OR). For example, to express
+    ``(tag: A | tag: B) & tag: C`` use the following filter::
+
+        tag: A & tag: C | tag: B & tag: C
+
     Use the back slash character ``\\`` to escape the boolean
     operators if you need to specify them as part of the filter
     expressions::