Merge pull request #33 from bodepd/doc_update

Update Modulefile and Changelog, prepping for 0.10.0 release

CHANGELOG

@@ -1,3 +1,18 @@
+2013-02-15 - Karel Brezina <karel.brezina@gmail.com> - 0.10.0
+ * Added 'ini_subsetting' custom resource type (4351d8b)
+
+2013-03-11 - Dan Bode <dan@puppetlabs.com> - 0.10.0
+ * guard against nil indentation values (5f71d7f)
+
+2013-01-07 - Dan Bode <dan@puppetlabs.com> - 0.10.0
+ * Add purging support to ini file (2f22483)
+
+2013-02-05 - James Sweeny <james.sweeny@puppetlabs.com> - 0.10.0
+ * Fix test to use correct key_val_parameter (b1aff63)
+
+2012-11-06 - Chris Price <chris@puppetlabs.com> - 0.10.0
+ * Added license file w/Apache 2.0 license (5e1d203)
+
 2012-11-02 - Chris Price <chris@puppetlabs.com> - 0.9.0
  * Version 0.9.0 released
 

Modulefile

@@ -1,5 +1,5 @@
 name 'cprice404-inifile'
-version '0.9.0'
+version '0.10.0'
 source 'git://github.com/cprice-puppet/puppetlabs-inifile.git'
 author 'Chris Price'
 description 'Resource types for managing settings in INI files'

README.markdown

@@ -27,7 +27,73 @@ settings that consist of several arguments such as
       value   => '512m',
     }
 
-A few noteworthy features:
+## implementing child providers:
+
+
+The ini_setting class can be overridden by child providers in order to implement the management of ini settings for a specific configuration file.
+
+In order to implement this, you will need to specify your own Type (as shown below). This type needs to implement a namevar (name), and a property called value:
+
+
+  example:
+
+    #my_module/lib/puppet/type/glance_api_config.rb
+    Puppet::Type.newtype(:glance_api_config) do
+      ensurable
+      newparam(:name, :namevar => true) do
+        desc 'Section/setting name to manage from glance-api.conf'
+        # namevar should be of the form section/setting
+        newvalues(/\S+\/\S+/)
+      end
+      newproperty(:value) do
+        desc 'The value of the setting to be defined.'
+        munge do |v|
+          v.to_s.strip
+        end
+      end
+    end
+
+This type also must have a provider that utilizes the ini_setting provider as its parent:
+
+  example:
+
+    # my_module/lib/puppet/provider/glance_api_config/ini_setting.rb
+    Puppet::Type.type(:glance_api_config).provide(
+      :ini_setting,
+      # set ini_setting as the parent provider
+      :parent => Puppet::Type.type(:ini_setting).provider(:ruby)
+    ) do
+      # implement section as the first part of the namevar
+      def section
+        resource[:name].split('/', 2).first
+      end
+      def setting
+        # implement setting as the second part of the namevar
+        resource[:name].split('/', 2).last
+      end
+      # hard code the file path (this allows purging)
+      def self.file_path
+        '/etc/glance/glance-api.conf'
+      end
+    end
+
+
+Now, the individual settings of the /etc/glance/glance-api.conf file can be managed as individual resources:
+
+    glance_api_config { 'HEADER/important_config':
+      value => 'secret_value',
+    }
+
+Provided that self.file_path has been implemented, you can purge with the following puppet syntax:
+
+    resources { 'glance_api_config'
+      purge => true,
+    }
+
+If the above code is added, then the resulting configured file will only contain lines implemented as Puppet resources
+
+
+## A few noteworthy features:
 
  * The module tries *hard* not to manipulate your file any more than it needs to.
    In most cases, it should leave the original whitespace, comments, ordering,

lib/puppet/provider/ini_setting/ruby.rb

@@ -3,6 +3,15 @@ require File.expand_path('../../../util/ini_file', __FILE__)
 Puppet::Type.type(:ini_setting).provide(:ruby) do
 
   def self.instances
+    # this code is here to support purging and the query-all functionality of the
+    # 'puppet resource' command, on a per-file basis.  Users
+    # can create a type for a specific config file with a provider that uses
+    # this as its parent and implements the method
+    # 'self.file_path', and that will provide the value for the path to the
+    # ini file (rather than needing to specify it on each ini setting
+    # declaration).  This allows 'purging' to be used to clear out
+    # all settings from a particular ini file except those included in
+    # the catalog.
     if self.respond_to?(:file_path)
       # figure out what to do about the seperator
       ini_file  = Puppet::Util::IniFile.new(file_path, '=')
@@ -50,14 +59,22 @@ Puppet::Type.type(:ini_setting).provide(:ruby) do
   end
 
   def section
+    # this method is here so that it can be overridden by a child provider
     resource[:section]
   end
 
   def setting
+    # this method is here so that it can be overridden by a child provider
     resource[:setting]
   end
 
   def file_path
+    # this method is here to support purging and sub-classing.
+    # if a user creates a type and subclasses our provider and provides a
+    # 'file_path' method, then they don't have to specify the
+    # path as a parameter for every ini_setting declaration.
+    # This implementation allows us to support that while still
+    # falling back to the parameter value when necessary.
     if self.class.respond_to?(:file_path)
       self.class.file_path
     else