lookup_plugins: loop over hashes

Create a lookup plugin named dict that can be used to loop over hashes.
It converts a dict into a list of key-value pairs, with attributes named
"key" and "value."  Also adds a brief explanation and simple example to
the docs.

Signed-off-by: Kent R. Spillner <kspillner@acm.org>

docsite/rst/playbooks_loops.rst

@@ -64,6 +64,31 @@ As with the case of 'with_items' above, you can use previously defined variables
         - users
         - [ 'clientdb', 'employeedb', 'providerdb' ]
 
+.. _looping_over_hashes:
+
+Looping over Hashes
+```````````````````
+
+.. versionadded:: 1.5
+
+Suppose you have the following variable::
+
+    ---
+    users:
+      alice:
+        name: Alice Appleworth
+        telephone: 123-456-7890
+      bob:
+        name: Bob Bananarama
+        telephone: 987-654-3210
+
+And you want to print every user's name and phone number.  You can loop through the elements of a hash using ``with_dict`` like this::
+
+    tasks:
+      - name: Print phone records
+        debug: msg="User {{ item.key }} is {{ item.value.name }} ({{ item.value.telephone }})"
+        with_dict: users
+
 .. _looping_over_fileglobs:
 
 Looping over Fileglobs

lib/ansible/runner/lookup_plugins/dict.py

@@ -0,0 +1,39 @@
+# (c) 2014, Kent R. Spillner <kspillner@acm.org>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+from ansible.utils import safe_eval
+import ansible.utils as utils
+import ansible.errors as errors
+
+def flatten(terms):
+    ret = []
+    for key in terms:
+        ret.append({'key': key, 'value': terms[key]})
+    return ret
+
+class LookupModule(object):
+
+    def __init__(self, basedir=None, **kwargs):
+        self.basedir = basedir
+
+    def run(self, terms, inject=None, **kwargs):
+        terms = utils.listify_lookup_plugin_terms(terms, self.basedir, inject)
+
+        if not isinstance(terms, dict):
+            raise errors.AnsibleError("with_dict expects a dict")
+
+        return flatten(terms)