Skip to content

Commit

Permalink
Extend filter documentation slightly
Browse files Browse the repository at this point in the history
Even though the original filter description is correct and does not contain
any factual flaws it might be confusing to people. There changes address two
pain points (from my point of view):

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

2. Filter supports regular expressions but currently there is a limitation by
design (a limitation that can actually be removed). Use of '|' and '&' in the
regexp is not allowed - it leads to filter error. This should be fixed but until
then it'd better be documented.

Signed-off-by: Ondrej Moris <[email protected]>
  • Loading branch information
The-Mule committed May 13, 2024
1 parent 29190c7 commit abdfcdf
Showing 1 changed file with 14 additions and 4 deletions.
18 changes: 14 additions & 4 deletions fmf/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -214,15 +214,23 @@ def filter(filter, data, sensitive=True, regexp=False):
"""
Return true if provided filter matches given dictionary of values
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 (DNF) form with '|' used for OR,
'&' for AND and '-' for negation. Individual values are prefixed
with 'value:', leading/trailing white-space is stripped. For
example:
tag: Tier1 | tag: Tier2 | tag: Tier3
category: Sanity, Security & tag: -destructive
Even though parentheses are only allowed in keys or values they are
not needed for DNF as the correct 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
Note that multiple comma-separated values can be used as a syntactic
sugar to shorten the filter notation::
sugar to shorten the filter notation:
tag: A, B, C ---> tag: A | tag: B | tag: C
Expand All @@ -236,6 +244,8 @@ def filter(filter, data, sensitive=True, regexp=False):
filter is not found in the data dictionary. Set option 'sensitive'
to False to enable case-insensitive matching. If 'regexp' option is
True, regular expressions can be used in the filter values as well.
However, using either '|' or '&' in the regular expression is not
allowed.
"""

def match_value(pattern, text):
Expand Down

0 comments on commit abdfcdf

Please sign in to comment.