Add documentation for the ini lookup plugin.

docsite/rst/playbooks_lookups.rst

@@ -139,6 +139,65 @@ default      empty string   return value if the key is not in the csv file
 
 .. note:: The default delimiter is TAB, *not* comma.
 
+.. _ini_lookup:
+
+The INI File Lookup
+```````````````````
+.. versionadded:: 2.0
+
+The ``ini`` lookup reads the contents of a file in INI format (key1=value1).
+This plugin retrieve the value on the right side after the equal sign ('=') of
+a given section ([section]). You can also read a property file which - in this
+case - does not contain section.
+
+Here's a simple example of an INI file with user/password configuration::
+
+    [production]
+    # My production information
+    user=robert
+    pass=somerandompassword
+
+    [integration]
+    # My integration information
+    user=gertrude
+    pass=anotherpassword
+
+
+We can use the ``ini`` plugin to lookup user configuration::
+
+    - debug: msg="User in integration is {{ lookup('ini', 'user section=integration file=users.ini') }}"
+    - debug: msg="User in production  is {{ lookup('ini', 'user section=production  file=users.ini') }}"
+
+Another example for this plugin is for looking for a value on java properties.
+Here's a simple properties we'll take as an example::
+
+    user.name=robert
+    user.pass=somerandompassword
+
+You can retrieve the ``user.name`` field with the following lookup::
+
+    - debug: msg="user.name is {{ lookup('ini', 'user.name type=property file=user.properties') }}"
+
+The ``ini`` lookup supports several arguments like the csv plugin. The format for passing
+arguments is::
+
+    lookup('ini', 'key [type=<properties|ini>] [section=section] [file=file.ini] [re=true] [default=<defaultvalue>]')
+
+The first value in the argument is the ``key``, which must be an entry that
+appears exactly once on keys. All other arguments are optional.
+
+
+==========   ============   =========================================================================================
+Field        Default        Description
+----------   ------------   -----------------------------------------------------------------------------------------
+type         ini            Type of the file. Can be ini or properties (for java properties).
+file         ansible.ini    Name of the file to load
+section      global         Default section where to lookup for key.
+re           False          The key is a regexp.
+default      empty string   return value if the key is not in the ini file
+==========   ============   =========================================================================================
+
+.. note:: In java properties files, there's no need to specify a section.
 
 .. _more_lookups:
 

docsite/rst/playbooks_loops.rst

@@ -316,6 +316,54 @@ It's uncommonly used::
       debug: msg="at array position {{ item.0 }} there is a value {{ item.1 }}"
       with_indexed_items: some_list
 
+.. _using_ini_with_a_loop:
+
+Using ini file with a loop
+``````````````````````````
+.. versionadded: 2.0
+
+The ini plugin can use regexp to retrieve a set of keys. As a consequence, we can loop over this set. Here is the ini file we'll use::
+
+    [section1]
+    value1=section1/value1
+    value2=section1/value2
+
+    [section2]
+    value1=section2/value1
+    value2=section2/value2
+
+Here is an example of using ``with_ini``::
+
+    - debug: msg="{{item}}"
+      with_ini: value[1-2] section=section1 file=lookup.ini re=true
+
+And here is the returned value::
+
+    {
+          "changed": false, 
+          "msg": "All items completed", 
+          "results": [
+              {
+                  "invocation": {
+                      "module_args": "msg=\"section1/value1\"", 
+                      "module_name": "debug"
+                  }, 
+                  "item": "section1/value1", 
+                  "msg": "section1/value1", 
+                  "verbose_always": true
+              }, 
+              {
+                  "invocation": {
+                      "module_args": "msg=\"section1/value2\"", 
+                      "module_name": "debug"
+                  }, 
+                  "item": "section1/value2", 
+                  "msg": "section1/value2", 
+                  "verbose_always": true
+              }
+          ]
+      }
+
 .. _flattening_a_list:
 
 Flattening A List

test/integration/lookup.ini

@@ -6,8 +6,8 @@ value.dot=Properties with dot
 field.with.space = another space
 
 [section1]
-value1=Another value for section1
-# No value2 in this section
+value1=section1/value1
+value2=section1/value2
 
 [value_section]
 value1=1

test/integration/test_lookup_properties.yml

@@ -28,3 +28,13 @@
       set_fact:
         unknown:  "{{lookup('ini', 'value2           default=unknown section=section1 file=lookup.ini')}}"
     - debug: var=unknown
+    - name: "Looping over section section1"
+      debug: msg="{{item}}"
+      with_ini: value[1-2] section=section1      file=lookup.ini re=true
+    - name: "Looping over section value_section"
+      debug: msg="{{item}}"
+      with_ini: value[1-2] section=value_section file=lookup.ini re=true
+    - debug: msg="{{item}}"
+      with_ini: value[1-2] section=section1 file=lookup.ini re=true
+      register: _
+    - debug: var=_