From e8ef6f14af096cda81a9696722c4d98f27102cae Mon Sep 17 00:00:00 2001
From: Matt Martz <matt@sivel.net>
Date: Thu, 19 Dec 2013 12:11:00 -0600
Subject: [PATCH] Add documentation example of using 'register' with a loop
---
docsite/rst/playbooks_loops.rst | 60 +++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
diff --git a/docsite/rst/playbooks_loops.rst b/docsite/rst/playbooks_loops.rst
index abd0281261..081f5308cc 100644
--- a/docsite/rst/playbooks_loops.rst
+++ b/docsite/rst/playbooks_loops.rst
@@ -318,6 +318,66 @@ That's how!
.. _writing_your_own_iterators:
+Using register with a loop
+``````````````````````````
+
+When using ``register`` with a loop the data strucutre placed in the variable during a loop, will contain a ``results`` attribute, that is a list of all responses from the module.
+
+Here is an example of using ``register`` with ``with_items``
+
+ - shell: echo "{{ item }}"
+ with_items:
+ - one
+ - two
+ register: echo
+
+This differs from the data strucutre returned when using ``register`` without a loop::
+
+ {
+ "changed": true,
+ "msg": "All items completed",
+ "results": [
+ {
+ "changed": true,
+ "cmd": "echo \"one\" ",
+ "delta": "0:00:00.003110",
+ "end": "2013-12-19 12:00:05.187153",
+ "invocation": {
+ "module_args": "echo \"one\"",
+ "module_name": "shell"
+ },
+ "item": "one",
+ "rc": 0,
+ "start": "2013-12-19 12:00:05.184043",
+ "stderr": "",
+ "stdout": "one"
+ },
+ {
+ "changed": true,
+ "cmd": "echo \"two\" ",
+ "delta": "0:00:00.002920",
+ "end": "2013-12-19 12:00:05.245502",
+ "invocation": {
+ "module_args": "echo \"two\"",
+ "module_name": "shell"
+ },
+ "item": "two",
+ "rc": 0,
+ "start": "2013-12-19 12:00:05.242582",
+ "stderr": "",
+ "stdout": "two"
+ }
+ ]
+ }
+
+Subsequent loops over the registered variable to inspect the results may look like::
+
+ - name: Fail if return code is not 0
+ fail:
+ msg: "The command ({{ item.cmd }}) did not have a 0 return code"
+ when: item.rc != 0
+ with_items: echo.results
+
Writing Your Own Iterators
``````````````````````````