Rename var lookup to vars and add tests

lib/ansible/plugins/lookup/vars.py

@@ -4,55 +4,57 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
-    lookup: var
+    lookup: vars
     author: Ansible Core
     version_added: "2.5"
-    short_description: Lookup templated value of variable
+    short_description: Lookup templated value of variables
     description:
       - Retrieves the value of an Ansible variable.
     options:
       _term:
-        description: The variable name to look up.
+        description: The variable names to look up.
         required: True
       default:
         description:
-            - What to return when the variable is undefined.
-            - If no default is set, it will result in an error if the variable is undefined.
+            - What to return if a variable is undefined.
+            - If no default is set, it will result in an error if any of the variables is undefined.
 """
 
 EXAMPLES = """
 - name: Show value of 'variablename'
-  debug: msg="{{ lookup('var', 'variabl' + myvar)}}"
+  debug: msg="{{ lookup('vars', 'variabl' + myvar)}}"
   vars:
     variablename: hello
     myvar: ename
 
 - name: Show default empty since i dont have 'variablnotename'
-  debug: msg="{{ lookup('var', 'variabl' + myvar, default='')}}"
+  debug: msg="{{ lookup('vars', 'variabl' + myvar, default='')}}"
   vars:
     variablename: hello
     myvar: notename
 
 - name: Produce an error since i dont have 'variablnotename'
-  debug: msg="{{ lookup('var', 'variabl' + myvar)}}"
+  debug: msg="{{ lookup('vars', 'variabl' + myvar)}}"
   ignore_errors: True
   vars:
     variablename: hello
     myvar: notename
 
-- name:  find some 'prefixed vars' in loop
-  debug: msg="{{ lookup('var', 'ansible_play_' + item) }}"
+- name: find several related variables:
+  debug: msg="{{ lookup('vars', 'ansible_play_hosts', 'ansible_play_batch', 'ansible_play_hosts_all') }}"
+
+- name: alternate way to find some 'prefixed vars' in loop
+  debug: msg="{{ lookup('vars', 'ansible_play_' + item) }}"
   loop:
     - hosts
     - batch
     - hosts_all
-
 """
 
 RETURN = """
 _value:
   description:
-    - valueof the variable requested
+    - valueof the variables requested.
 """
 
 from ansible.errors import AnsibleError, AnsibleUndefinedVariable

test/integration/targets/lookups/tasks/main.yml

@@ -286,3 +286,22 @@
 - assert:
     that:
       - "hello_world|trim == 'Hello world!'"
+
+# Vars lookups
+
+- name: Test that we can give it a single value and receive a single value
+  set_fact:
+    var_host: '{{ lookup("vars", "ansible_host") }}'
+
+- assert:
+    that:
+      - 'var_host == ansible_host'
+
+- name: Test that we can give a list of values to var and receive a list of values back
+  set_fact:
+    var_host_info: '{{ query("vars", "ansible_host", "ansible_user") }}'
+
+- assert:
+    that:
+      - 'var_host_info[0] == ansible_host'
+      - 'var_host_info[1] == ansible_user'