mixlib-config 2.0.0.rc.2 → 2.0.0.rc.3

data/README.md

@@ -1,41 +1,129 @@
-## Mixlib::Config
+# Mixlib::Config #
 
 Mixlib::Config provides a class-based configuration object, as used in Chef.  To use in your project:
 
-  require 'rubygems'
+```ruby
   require 'mixlib/config'
 
-  class MyConfig
-    extend(Mixlib::Config)
-    configure do |c|
-      c[:first_value] = 'something'
-      c[:other_value] = 'something_else'
-    end
+  module MyConfig
+    extend Mixlib::Config
+    config_strict_mode true
+    default :first_value, 'something'
+    default :other_value, 'something_else'
   end
+```
 
-Or...
+You can use this to provide a configuration file for a user.  For example, if you do this:
 
-  class MyConfig
-    extend(Mixlib::Config)
+```ruby
+  MyConfig.from_file('~/.myconfig.rb')
+```
 
-    first_value 'something'
-    other_value 'something_else'
-  end
+A user could write a Ruby config file that looked like this:
+
+```ruby
+  first_value 'hi'
+  second_value "#{first_value}!  10 times 10 is #{10*10}!"
+```
 
-To check a configuration variable:
+Inside your app, you can check configuration values with this syntax:
 
+```ruby
   MyConfig.first_value   # returns 'something'
   MyConfig[:first_value] # returns 'something'
+```
+And you can modify configuration values with this syntax:
 
-To change a configuration variable at runtime:
-
+```ruby
   MyConfig.first_value('foobar')    # sets first_value to 'foobar'
+  MyConfig.first_value = 'foobar'   # sets first_value to 'foobar'
   MyConfig[:first_value] = 'foobar' # sets first_value to 'foobar'
+```
+
+## Nested Configuration ##
+
+Often you want to be able to group configuration options to provide a common context.  Mixlib::Config supports this thus:
+
+```ruby
+  require 'mixlib/config'
+
+  module MyConfig
+    extend Mixlib::Config
+    config_context :logging do
+      default :base_filename, 'mylog'
+      default :max_log_files, 10
+    end
+  end
+```
+
+The user can write their config file like this:
+
+```ruby
+  logging.base_filename 'superlog'
+  logging.max_log_files 2
+```
+
+You can access these variables thus:
+
+```ruby
+  MyConfig.logging.base_filename
+  MyConfig[:logging][:max_log_files]
+```
+
+## Default Values ##
+
+Mixlib::Config has a powerful default value facility.  In addition to being able to specify explicit default values, you can even specify Ruby code blocks that will run if the config value is not set.  This can allow you to build options whose values are based on other options.
+
+```ruby
+  require 'mixlib/config'
+
+  module MyConfig
+    extend Mixlib::Config
+    config_strict_mode true
+    default :verbosity, 1
+    default(:print_network_requests) { verbosity >= 2 }
+    default(:print_ridiculously_unimportant_stuff) { verbosity >= 10 }
+  end
+```
+
+This allows the user to quickly specify a number of values with one default, while still allowing them to override anything:
+
+```ruby
+  verbosity 5
+  print_network_requests false
+```
+
+## Strict Mode ##
+
+Misspellings are a common configuration problem, and Mixlib::Config has an answer: `config_strict_mode`.  Setting `config_strict_mode` to `true` will cause any misspelled or incorrect configuration option references to throw `Mixlib::Config::UnknownConfigOptionError`.
+
+```ruby
+  require 'mixlib/config'
+
+  module MyConfig
+    extend Mixlib::Config
+    config_strict_mode true
+    default :filename, '~/output.txt'
+    configurable :server_url # configurable declares an option with no default value
+    config_context :logging do
+      default :base_name, 'log'
+      default :max_files, 20
+    end
+  end
+```
+
+Now if a user types `fielname "~/output-mine.txt"` in their configuration file, it will toss an exception telling them that the option "fielname" is unknown.  If you do not set config_strict_mode, the fielname option will be merrily set and the application just won't know about it.
+
+Different config_contexts can have different strict modes; but they inherit the strict mode of their parent if you don't explicitly set it.  So setting it once at the top level is sufficient.  In the above example, `logging.base_naem 'mylog'` will raise an error.
+
+In conclusion: *always set config_strict_mode to true*.  You know you want to.
+
+## Testing and Reset ##
 
-You should populate your class with the default values for every configuration variable that might be accessed. If you try and access a variable that does not exist, Mixlib::Config will throw an <ArgumentError>.
+Testing your application with different sets of arguments can by simplified with `reset`. Call `MyConfig.reset` before each test and all configuration will be reset to its default value.  There's no need to explicitly unset all your options between each run.
 
-To load a ruby configuration file (which will evaluate in the context of your configuration class):
+NOTE: if you have arrays of arrays, or other deep nesting, we suggest you use code blocks to set up your default values (`default(:option) { [ [ 1, 2 ], [ 3, 4 ] ] }`).  Deep children will not always be reset to their default values.
 
-  MyConfig.from_file('your_config_file.rb')
+Report bugs [here](https://tickets.opscode.com).
 
 Enjoy!

data/lib/mixlib/config.rb

@@ -28,10 +28,10 @@ module Mixlib
       class << base; attr_accessor :configuration; end
       class << base; attr_accessor :configurables; end
       class << base; attr_accessor :config_contexts; end
+      class << base; attr_accessor :config_parent; end
       base.configuration = Hash.new
       base.configurables = Hash.new
       base.config_contexts = Array.new
-      base.config_strict_mode false
     end
 
     # Loads a given ruby file, and runs instance_eval against it in the context of the current
@@ -208,6 +208,7 @@ module Mixlib
     def config_context(symbol, &block)
       context = Class.new
       context.extend(::Mixlib::Config)
+      context.config_parent = self
       config_contexts << context
       if block
         context.instance_eval(&block)
@@ -238,7 +239,15 @@ module Mixlib
     #
     def config_strict_mode(value = NOT_PASSED)
       if value == NOT_PASSED
-        @config_strict_mode
+        if @config_strict_mode.nil?
+          if config_parent
+            config_parent.config_strict_mode
+          else
+            false
+          end
+        else
+          @config_strict_mode
+        end
       else
         self.config_strict_mode = value
       end
@@ -258,8 +267,8 @@ module Mixlib
     # <ArgumentError>:: if value is set to something other than true, false, or :warn
     #
     def config_strict_mode=(value)
-      if ![ true, false, :warn ].include?(value)
-        raise ArgumentError, "config_strict_mode must be true, false or :warn"
+      if ![ true, false, :warn, nil ].include?(value)
+        raise ArgumentError, "config_strict_mode must be true, false, nil or :warn"
       end
       @config_strict_mode = value
     end

data/lib/mixlib/config/configurable.rb

@@ -43,7 +43,12 @@ module Mixlib
         elsif @default
           @default.call
         else
-          @default_value
+          begin
+            # Some things cannot be dup'd, and you won't know this till after the fact
+            config[@symbol] = @default_value.dup
+          rescue TypeError
+            @default_value
+          end
         end
       end
 

data/lib/mixlib/config/version.rb

@@ -19,7 +19,7 @@
 module Mixlib
   module Config
 
-    VERSION = "2.0.0.rc.2"
+    VERSION = "2.0.0.rc.3"
 
   end
 end

data/spec/mixlib/config_spec.rb

@@ -177,7 +177,7 @@ describe Mixlib::Config do
 
   end
 
-  describe "When a default value exists" do
+  describe "When config has a default value" do
     before :each do
       @klass = Class.new
       @klass.extend(::Mixlib::Config)
@@ -210,7 +210,52 @@ describe Mixlib::Config do
     end
   end
 
-  describe "When a default value block exists" do
+  describe "When config has an array default value" do
+    before :each do
+      @klass = Class.new
+      @klass.extend(::Mixlib::Config)
+      @klass.class_eval { default :attr, [] }
+    end
+
+    it "reset clears it to its default" do
+      @klass.attr << 'x'
+      @klass.attr.should == [ 'x' ]
+      @klass.reset
+      @klass.attr.should == []
+    end
+  end
+
+  describe "When config has a hash default value" do
+    before :each do
+      @klass = Class.new
+      @klass.extend(::Mixlib::Config)
+      @klass.class_eval { default :attr, {} }
+    end
+
+    it "reset clears it to its default" do
+      @klass.attr[:x] = 10
+      @klass.attr[:x].should == 10
+      @klass.reset
+      @klass.attr[:x].should == nil
+    end
+  end
+
+  describe "When config has a string default value" do
+    before :each do
+      @klass = Class.new
+      @klass.extend(::Mixlib::Config)
+      @klass.class_eval { default :attr, 'hello' }
+    end
+
+    it "reset clears it to its default" do
+      @klass.attr << ' world'
+      @klass.attr.should == 'hello world'
+      @klass.reset
+      @klass.attr.should == 'hello'
+    end
+  end
+
+  describe "When config has a a default value block" do
     before :each do
       @klass = Class.new
       @klass.extend(::Mixlib::Config)
@@ -447,8 +492,8 @@ describe Mixlib::Config do
       lambda { StrictClass3.y = 10 }.should raise_error(Mixlib::Config::UnknownConfigOptionError)
     end
 
-    it "The nested class allows you to set arbitrary config options" do
-      StrictClass3.c.y = 10
+    it "The nested class does not allow you to set arbitrary config options" do
+      lambda { StrictClass3.y = 10 }.should raise_error(Mixlib::Config::UnknownConfigOptionError)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixlib-config
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc.2
+  version: 2.0.0.rc.3
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-11 00:00:00.000000000 Z
+date: 2013-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake