From dcab59814d6e71e3621bf5671c937d41f0f8a9f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pl=C3=ADchal?= Date: Wed, 5 Jun 2024 10:41:48 +0200 Subject: [PATCH] Extend the `filter()` documentation slightly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Petr Šplíchal --- fmf/utils.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/fmf/utils.py b/fmf/utils.py index a16ce1c..65443b4 100644 --- a/fmf/utils.py +++ b/fmf/utils.py @@ -215,13 +215,21 @@ 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::