From 73f10de386f1ec000028204328c2bd6c131fc7f4 Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Sun, 23 Aug 2015 20:06:06 +0530 Subject: [PATCH] Document the behaviour of _match_one_pattern in some detail The possibilities are complicated enough that I didn't want to make changes without having a complete description of what it actually accepts/matches. Note that this text documents current behaviour, not necessarily the behaviour we want. Some of this is undocumented and may not be intended. --- lib/ansible/inventory/__init__.py | 37 ++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/lib/ansible/inventory/__init__.py b/lib/ansible/inventory/__init__.py index c105b7e5c04..b9a69bb3d29 100644 --- a/lib/ansible/inventory/__init__.py +++ b/lib/ansible/inventory/__init__.py @@ -228,9 +228,40 @@ class Inventory(object): def _match_one_pattern(self, pattern): """ - Takes a single pattern (i.e., not "p1:p2") and returns a list of - matching host names. Does not take negatives or intersections - into account. + Takes a single pattern and returns a list of matching host names. + Ignores intersection (&) and exclusion (!) specifiers. + + The pattern may be: + + 1. A regex starting with ~, e.g. '~[abc]*' + 2. A shell glob pattern with ?/*/[chars]/[!chars], e.g. 'foo' + 3. An ordinary word that matches itself only, e.g. 'foo' + + The pattern is matched using the following rules: + + 1. If it's 'all', it matches all hosts in all groups. + 2. Otherwise, for each known group name: + (a) if it matches the group name, the results include all hosts + in the group or any of its children. + (b) otherwise, if it matches any hosts in the group, the results + include the matching hosts. + + This means that 'foo*' may match one or more groups (thus including all + hosts therein) but also hosts in other groups. + + The built-in groups 'all' and 'ungrouped' are special. No pattern can + match these group names (though 'all' behaves as though it matches, as + described above). The word 'ungrouped' can match a host of that name, + and patterns like 'ungr*' and 'al*' can match either hosts or groups + other than all and ungrouped. + + If the pattern matches one or more group names according to these rules, + it may have an optional range suffix to select a subset of the results. + This is allowed only if the pattern is not a regex, i.e. '~foo[1]' does + not work (the [1] is interpreted as part of the regex), but 'foo*[1]' + would work if 'foo*' matched the name of one or more groups. + + Duplicate matches are always eliminated from the results. """ if pattern.startswith("&") or pattern.startswith("!"):