Merge pull request #13345 from amenonsen/extract

Add an 'extract' filter

docsite/rst/playbooks_filters.rst

@@ -352,6 +352,39 @@ override those in `b`, and so on.
 This behaviour does not depend on the value of the `hash_behaviour`
 setting in `ansible.cfg`.
 
+.. _extract_filter:
+
+Extracting values from containers
+---------------------------------
+
+.. versionadded:: 2.0
+
+The `extract` filter is used to map from a list of indices to a list of
+values from a container (hash or array)::
+
+    {{ [0,2]|map('extract', ['x','y','z'])|list }}
+    {{ ['x','y']|map('extract', {'x': 42, 'y': 31})|list }}
+
+The results of the above expressions would be::
+
+    ['x', 'z']
+    [42, 31]
+
+The filter can take another argument::
+
+    {{ groups['x']|map('extract', hostvars, 'ec2_ip_address')|list }}
+
+This takes the list of hosts in group 'x', looks them up in `hostvars`,
+and then looks up the `ec2_ip_address` of the result. The final result
+is a list of IP addresses for the hosts in group 'x'.
+
+The third argument to the filter can also be a list, for a recursive
+lookup inside the container::
+
+    {{ ['a']|map('extract', b, ['x','y'])|list }}
+
+This would return a list containing the value of `b['a']['x']['y']`.
+
 .. _comment_filter:
 
 Comment Filter