Merge pull request redhat-openstack#180 from jbondpdx/1.4.x

Edits to new Function: `create_ini_settings` in README

Author: hunner

README.markdown

@@ -25,10 +25,9 @@ Many applications use INI-style configuration files to store their settings. Thi
 
 ###Beginning with inifile
 
-
 To manage a single setting in an INI file, add the `ini_setting` type to a class:
 
-~~~
+~~~puppet
 ini_setting { "sample setting":
   ensure  => present,
   path    => '/tmp/foo.ini',
@@ -51,9 +50,12 @@ The inifile module tries hard not to manipulate your file any more than it needs
 
 Use the `ini_subsetting` type:
 
+~~~puppet
+JAVA_ARGS="-Xmx512m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof"
 ~~~
-JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/pe-puppetdb/puppetdb-oom.hprof "
 
+
+~~~puppet
 ini_subsetting {'sample subsetting':
   ensure            => present,
   section           => '',
@@ -67,11 +69,12 @@ ini_subsetting {'sample subsetting':
 
 ###Use a non-standard section header
 
-~~~
+~~~puppet
 default:
    minage = 1
-   maxage = 13
+~~~
 
+~~~puppet
 ini_setting { 'default minage':
   ensure         => present,
   path           => '/etc/security/users',
@@ -85,7 +88,6 @@ ini_setting { 'default minage':
 
 ###Implement child providers
 
-
 You might want to create child providers that inherit the `ini_setting` provider, for one or both of these purposes:
 
  * Make a custom resource to manage an application that stores its settings in INI files, without recreating the code to manage the files themselves.
@@ -94,7 +96,7 @@ You might want to create child providers that inherit the `ini_setting` provider
 
 To implement child providers, first specify a custom type. Have it implement a namevar called `name` and a property called `value`:
 
-~~~
+~~~ruby
 #my_module/lib/puppet/type/glance_api_config.rb
 Puppet::Type.newtype(:glance_api_config) do
   ensurable
@@ -114,7 +116,7 @@ end
 
 Your type also needs a provider that uses the `ini_setting` provider as its parent:
 
-~~~
+~~~ruby
 # my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
 Puppet::Type.type(:glance_api_config).provide(
   :ini_setting,
@@ -138,20 +140,128 @@ end
 
 Now the settings in /etc/glance/glance-api.conf file can be managed as individual resources:
 
-~~~
+~~~puppet
 glance_api_config { 'HEADER/important_config':
   value => 'secret_value',
 }
 ~~~
 
 If you've implemented self.file_path, you can have Puppet purge the file of all lines that aren't implemented as Puppet resources:
 
-~~~
+~~~puppet
 resources { 'glance_api_config'
   purge => true,
 }
 ~~~
 
+### Manage multiple ini_settings
+
+To manage multiple ini_settings, use the [`create_ini_settings`](#function-create_ini_settings) function.
+
+~~~puppet
+$defaults = { 'path' => '/tmp/foo.ini' }
+$example = { 'section1' => { 'setting1' => 'value1' } }
+create_ini_settings($example, $defaults)
+~~~
+
+results in:
+
+~~~puppet
+ini_setting { '[section1] setting1':
+  ensure  => present,
+  section => 'section1',
+  setting => 'setting1',
+  value   => 'value1',
+  path    => '/tmp/foo.ini',
+}
+~~~
+
+To include special parameters, the following code:
+
+~~~puppet
+$defaults = { 'path' => '/tmp/foo.ini' }
+$example = {
+  'section1' => {
+    'setting1'  => 'value1',
+    'settings2' => {
+      'ensure' => 'absent'
+    }
+  }
+}
+create_ini_settings($example, $defaults)
+~~~
+
+results in:
+
+~~~puppet
+ini_setting { '[section1] setting1':
+  ensure  => present,
+  section => 'section1',
+  setting => 'setting1',
+  value   => 'value1',
+  path    => '/tmp/foo.ini',
+}
+ini_setting { '[section1] setting2':
+  ensure  => absent,
+  section => 'section1',
+  setting => 'setting2',
+  path    => '/tmp/foo.ini',
+}
+~~~
+
+#### Manage multiple ini_settings with Hiera
+
+This example requires Puppet 3.x/4.x, as it uses automatic retrieval of Hiera data for class parameters and `puppetlabs/stdlib`.
+
+For the profile `example`:
+
+~~~puppet
+class profile::example (
+  $settings,
+) {
+    validate_hash($settings)
+    $defaults = { 'path' => '/tmp/foo.ini' }
+    create_ini_settings($settings, $defaults)
+}
+~~~
+
+Provide this in your Hiera data:
+
+~~~puppet
+profile::example::settings:
+  section1:
+    setting1: value1
+    setting2: value2
+    setting3:
+      ensure: absent
+~~~
+
+Results in:
+
+~~~puppet
+ini_setting { '[section1] setting1':
+  ensure  => present,
+  section => 'section1',
+  setting => 'setting1',
+  value   => 'value1',
+  path    => '/tmp/foo.ini',
+}
+ini_setting { '[section1] setting2':
+  ensure  => present,
+  section => 'section1',
+  setting => 'setting2',
+  value   => 'value2',
+  path    => '/tmp/foo.ini',
+}
+ini_setting { '[section1] setting3':
+  ensure  => absent,
+  section => 'section1',
+  setting => 'setting3',
+  path    => '/tmp/foo.ini',
+}
+~~~
+
+
 ##Reference
 
 ###Public Types
@@ -164,9 +274,6 @@ resources { 'glance_api_config'
 
  * [`create_ini_settings`](#function-create_ini_settings)
 
-
-
-
 ### Type: ini_setting
 
 Manages a setting within an INI file.
@@ -207,12 +314,9 @@ Determines whether the specified setting should exist. Valid options: 'present'
 
 ##### `section_suffix`
 
-*Optional.*  Designates the string that will appear after the section's name.  Default value: "]"
-
-**NOTE:** The way this type finds all sections in the file is by looking for lines like `${section_prefix}${title}${section_suffix}`
-
-
+*Optional.*  Designates the string that will appear after the section's name.  Default value: "]".
 
+**NOTE:** This type finds all sections in the file by looking for lines like `${section_prefix}${title}${section_suffix}`.
 
 ### Type: ini_subsetting
 
@@ -248,7 +352,6 @@ Specifies whether the subsetting should be present. Valid options: 'present' and
 
 *Required.* Designates a subsetting to manage within the specified setting. Valid options: a string.
 
-
 ##### `subsetting_separator`
 
 *Optional.* Specifies a string to use between subsettings. Valid options: a string. Default value: " ".
@@ -257,142 +360,40 @@ Specifies whether the subsetting should be present. Valid options: 'present' and
 
 *Optional.* Supplies a value for the specified subsetting. Valid options: a string. Default value: undefined.
 
-
-
-
 ### Function: create_ini_settings
 
-`create_ini_settings($settings, $defaults)`
+Manages multiple `ini_setting` resources from a hash. Note that this cannot be used with ini_subsettings.
 
-Manage multiple ini_setting resources from a hash with comfort. You can provide a hash in your manifest and feed it from Hiera. This can however not be used with ini_subsettings!
+`create_ini_settings($settings, $defaults)`
 
-#### Parameters
+#### Arguments
 
-##### `$settings`
+##### First argument: `settings`
 
-*Required.* Specify a hash with the ini_setting resources.
+*Required.* Specify a hash representing the `ini_setting` resources you want to create.
 
-###### Example
-~~~
-defaults = { 'path' => '/tmp/foo.ini' }
-$example = { 'section1' => { 'setting1' => 'value1' } }
-create_ini_settings($example, $defaults)
-~~~
-results in a resource
-~~~
-ini_setting { '[section1] setting1':
-    ensure  => present,
-    section => 'section1',
-    setting => 'setting1',
-    value   => 'value1',
-    path    => '/tmp/foo.ini'
-}
-~~~
+##### Second argument: `defaults`
 
-###### Example with special parameters
-~~~
-defaults = { 'path' => '/tmp/foo.ini' }
-$example = { 'section1' => {
-                'setting1' => 'value1',
-                'settings2' => {
-                        'ensure' => 'absent'
-                    }
-                }
-           }
-create_ini_settings($example, $defaults)
-~~~
-results in resources
-~~~
-ini_setting { '[section1] setting1':
-    ensure  => present,
-    section => 'section1',
-    setting => 'setting1',
-    value   => 'value1',
-    path    => '/tmp/foo.ini',
-}
-ini_setting { '[section1] setting2':
-    ensure  => absent,
-    section => 'section1',
-    setting => 'setting2',
-    path    => '/tmp/foo.ini',
+*Optional.* Accepts a hash to be used as the values for any attributes not defined in the first argument.
+ 
+~~~puppet
+$example = {
+  'section1' => {
+    'setting1' => {
+      'value' => 'value1', 'path' => '/tmp/foo.ini' 
+    } 
+  } 
 }
 ~~~
 
-##### `$defaults`
-
-*Optional, but recommended.* 
-
-This works exactly like `create_resources` defaults parameter. Use it to not repeat yourself to often
-and write settings more densely. Example usage see parameter `$settings` above.
-
-If you omit this parameter, you will need to add the `path` and `value` attribute to every single setting as a hash 
-(`$example = { 'section1' => { 'setting1' => { 'value' => 'value1', 'path' => '/tmp/foo.ini' } } }`).
-This most certainly is not what you want, but if you need it it's there.
-
 Default value: '{}'.
 
-#### Example with Hiera
-This example will need Puppet 3.x/4.x as it uses automatic retrieval of Hiera data for class parameters and
-`puppetlabs/stdlib` (you use that one already, don't you?).
-
-Of course you may use `hiera_hash` when on Puppet 2.x or other use cases. Remember this is only one example,
-feel free to live your creativity on writing manifests.
-
-Imagine a profile `example`:
-~~~
-class profile::example (
-    $settings,
-) {
-    validate_hash($settings)
-    $defaults = { 'path' => '/tmp/foo.ini' }
-    create_ini_settings($settings, $defaults)
-}
-~~~
-
-Now provide this in your Hiera data:
-~~~
-profile::example::settings:
-    section1:
-        setting1: value1
-        setting2: value2
-        setting3:
-            ensure: absent
-~~~
-
-This will result in resources:
-~~~
-ini_setting { '[section1] setting1':
-    ensure  => present,
-    section => 'section1',
-    setting => 'setting1',
-    value   => 'value1',
-    path    => '/tmp/foo.ini',
-}
-ini_setting { '[section1] setting2':
-    ensure  => present,
-    section => 'section1',
-    setting => 'setting2',
-    value   => 'value2',
-    path    => '/tmp/foo.ini',
-}
-ini_setting { '[section1] setting3':
-    ensure  => absent,
-    section => 'section1',
-    setting => 'setting3',
-    path    => '/tmp/foo.ini',
-}
-~~~
-
-
-
 ##Limitations
 
 This module has been tested on [all PE-supported platforms](https://forge.puppetlabs.com/supported#compat-matrix), and no issues have been identified. Additionally, it is tested (but not supported) on Windows 7, Mac OS X 10.9, and Solaris 12.
 
 ##Development
 
-#Development
-
 Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
 
 We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.