Add complex arguments example

CHANGELOG.md

@@ -47,6 +47,7 @@ Ansible Changes By Release
 * lookup plugin macros like $FILE and $ENV now work without returning arrays in variable definitions/playbooks
 * add_host module can set ports and other inventory variables
 * add_host module can add modules to multiple groups (groups=a,b,c), groups now alias for groupname
+* support for complex arguments to modules (within reason)
 
 1.0 "Eruption" -- Feb 1 2013
 

examples/playbooks/complex_args.yml

@@ -0,0 +1,55 @@
+---
+
+# this is a bit of an advanced topic.
+#
+# generally Ansible likes to pass simple key=value arguments to modules.  It occasionally comes up though
+# that you might want to write a module that takes COMPLEX arguments, like lists and dictionaries.
+#
+# happen, at least right now, it should be a Python module, so it can leverage some common code in Ansible that
+# makes this easy.  If you write a non-Python module, you can still pass data across, but only hashes that
+# do not contain lists or other hashes.  If you write the Python module, you can do anything.
+#
+# note that if you were to use BOTH the key=value form and the 'args' form for passing data in, the key=value
+# parameters take a higher priority, so you can use them for defaults, which can be useful.
+
+- hosts: all
+  user: root
+  gather_facts: no
+ 
+  vars:
+    defaults:
+      state: stopped
+    complex:
+      ghostbusters: [ 'egon', 'ray', 'peter', 'winston' ]
+      mice: [ 'pinky', 'brain', 'snowball', 'larry' ]
+ 
+  tasks:
+
+    - name: this is the basic way data passing works for any module
+      action: ping data='Hi Mom'
+
+    - name: of course this can also be written like so, which is shorter
+      ping: data='Hi Mom'
+
+    - name: but what if you have a complex module that needs complicated data?
+      action: ping
+      args:
+         data: 
+           moo: cow
+           asdf: [1,2,3,4]
+
+    - name: can we make that cleaner? sure!
+      action: ping
+      args: { data: $complex }
+
+    - name: or if you prefer... this is equivalent
+      action: ping
+      args: 
+          data: $complex
+
+    - name: here is an example of how it works with defaults, notice the key=value format wins
+      action: service name=httpd state=running
+      args: $defaults
+
+
+