libnm/match: extend syntax for match patterns with '|', '&', '!' and '\\'th/kernel-cmdline-match

For simple matches like match.interface-name, match.driver, and
match.path, arguably what we had was fine. There each element
(like "eth*") is a wildcard for a single name (like "eth1").

However, for match.kernel-command-line, the elements match individual
command line options, so we should have more flexibility of whether
a parameter is optional or mandatory. Extend the syntax (in a backward
compatible manner) for that.

- the elements can now be prefixed by either '|' or '&'. This makes
  optional or mandatory elements, respectively. The entire match
  evaluates to true if all mandatory elements match (if any) and
  at least one of the optional elements (if any).
  As before, if neither '|' nor '&' is specified, then the element
  is optional (that means, "foo" is the same as "|foo").

- the exclamation mark is still used to invert the match. If used
  alone (like "!foo") it is a shortcut for defining a mandatory match
  ("&!foo").

- the backslash can now be used to escape the special characters
  above. Basically, the special characters ('|', '&', '!') are
  stripped from the start of the element. If what is left afterwards
  is a backslash, it also gets stripped and the remainder is the
  pattern. For example, "\\&foo" has the pattern "&foo" where
  '&' is no longer treated specially. This special handling of
  the backslash is only done at the beginning of the element (after
  the optional special characters). The remaining string is part
  of the pattern, where backslashes might have their own meaning.

1 files changed, 24 insertions, 19 deletions

diff --git a/libnm-core/nm-setting-match.c b/libnm-core/nm-setting-match.c
index 599fcf9916..b9f59a24e9 100644
--- a/libnm-core/nm-setting-match.c
+++ b/libnm-core/nm-setting-match.c
@@ -817,13 +817,19 @@ nm_setting_match_class_init (NMSettingMatchClass *klass)
 	 * NMSettingMatch:interface-name
 	 *
 	 * A list of interface names to match. Each element is a shell wildcard
-	 * pattern.  When an element is prefixed with exclamation mark (!) the
-	 * condition is inverted.
+	 * pattern.
 	 *
-	 * A candidate interface name is considered matching when both these
-	 * conditions are satisfied: (a) any of the elements not prefixed with '!'
-	 * matches or there aren't such elements; (b) none of the elements
-	 * prefixed with '!' match.
+	 * A element can be prefixed with a pipe symbol (|) or an ampersand (&).
+	 * The former means that the element is optional and the latter means that
+	 * it is mandatory. If there are any optional elements, than the match
+	 * evaluates to true if at least one of the optional element matches
+	 * (logical OR). If there are any mandatory elements, then they all
+	 * must match (logical AND). By default, an element is optional. For example
+	 * the element "foo" behaves the same as "|foo". An element can also be inverted
+	 * with exclamation mark (!) between the pipe symbol (or the ampersand) and before
+	 * the pattern. Note that "!foo" is a shortcut for "&!foo". Finally, a backslash
+	 * can be used at the beginning after optional special characters to escape the
+	 * start of the pattern. For example, "&\\!a" is an mandatory match for literally "!a".
 	 *
 	 * Since: 1.14
 	 **/
@@ -845,6 +851,10 @@ nm_setting_match_class_init (NMSettingMatchClass *klass)
 	 * of an assignment. In the latter case, the exact assignment is looked for
 	 * with right and left hand side matching.
 	 *
+	 * See NMSettingMatch:interface-name for how special characters '|', '&',
+	 * '!' and '\\' are used for optional and mandatory matches and inverting the
+	 * pattern.
+	 *
 	 * Since: 1.26
 	 **/
 	obj_properties[PROP_KERNEL_COMMAND_LINE] =
@@ -858,11 +868,10 @@ nm_setting_match_class_init (NMSettingMatchClass *klass)
 	 * NMSettingMatch:driver
 	 *
 	 * A list of driver names to match. Each element is a shell wildcard pattern.
-	 * When an element is prefixed with exclamation mark (!) the condition is
-	 * inverted. A candidate driver name is considered matching when both these
-	 * conditions are satisfied: (a) any of the elements not prefixed with '!'
-	 * matches or there aren't such elements; (b) none of the elements prefixed
-	 * with '!' match.
+	 *
+	 * See NMSettingMatch:interface-name for how special characters '|', '&',
+	 * '!' and '\\' are used for optional and mandatory matches and inverting the
+	 * pattern.
 	 *
 	 * Since: 1.26
 	 **/
@@ -873,7 +882,6 @@ nm_setting_match_class_init (NMSettingMatchClass *klass)
 	                        G_PARAM_READWRITE |
 	                        G_PARAM_STATIC_STRINGS);
 
-
 	/**
 	 * NMSettingMatch:path
 	 *
@@ -891,14 +899,11 @@ nm_setting_match_class_init (NMSettingMatchClass *klass)
 	 * property exported by NetworkManager ("nmcli -f general.path device
 	 * show $dev").
 	 *
-	 * Each element of the list is a shell wildcard pattern. When an
-	 * element is prefixed with exclamation mark (!) the condition is
-	 * inverted.
+	 * Each element of the list is a shell wildcard pattern.
 	 *
-	 * A candidate path is considered matching when both these
-	 * conditions are satisfied: (a) any of the elements not prefixed with '!'
-	 * matches or there aren't such elements; (b) none of the elements
-	 * prefixed with '!' match.
+	 * See NMSettingMatch:interface-name for how special characters '|', '&',
+	 * '!' and '\\' are used for optional and mandatory matches and inverting the
+	 * pattern.
 	 *
 	 * Since: 1.26
 	 **/