From c0bd14095914287e0ad7ab73ad6a9927e0c5a7f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yannig=20Perr=C3=A9?= Date: Wed, 5 Aug 2015 11:09:40 +0200 Subject: [PATCH] Add documentation for the ini lookup plugin. --- docsite/rst/playbooks_lookups.rst | 59 +++++++++++++++++++++ docsite/rst/playbooks_loops.rst | 48 +++++++++++++++++ test/integration/lookup.ini | 4 +- test/integration/test_lookup_properties.yml | 10 ++++ 4 files changed, 119 insertions(+), 2 deletions(-) diff --git a/docsite/rst/playbooks_lookups.rst b/docsite/rst/playbooks_lookups.rst index ac770dab39b..9659e86ad80 100644 --- a/docsite/rst/playbooks_lookups.rst +++ b/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=] [section=section] [file=file.ini] [re=true] [default=]') + +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: diff --git a/docsite/rst/playbooks_loops.rst b/docsite/rst/playbooks_loops.rst index e71c81cefc2..56e43dd7d36 100644 --- a/docsite/rst/playbooks_loops.rst +++ b/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 diff --git a/test/integration/lookup.ini b/test/integration/lookup.ini index ce0dbf84860..16500fd8990 100644 --- a/test/integration/lookup.ini +++ b/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 diff --git a/test/integration/test_lookup_properties.yml b/test/integration/test_lookup_properties.yml index 4e085c14978..4d22ce642c4 100644 --- a/test/integration/test_lookup_properties.yml +++ b/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=_