Update docs for 2.0

1 files changed, 108 insertions, 20 deletions

diff --git a/README.md b/README.md
index 980f551..ed92d3c 100644
--- a/README.md
+++ b/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>.
+If your app is configured with Mixlib::Config, testing options becomes easy!  Simply 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: resetting objects, arrays and hashes to their defaults is a little tricky because the original value can be mutated with `MyConfig.array_option << 'x'` adding 'x' to the array.  We strive to truly reset values, calling `dup` on default values on first use to prevent the original default value being changed.  However, because of how `dup` works, nested arrays and nested hashes won't reset all children.  If you have arrays of objects, 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 ] ] }`).
 
-  MyConfig.from_file('your_config_file.rb')
+Report bugs [here](https://tickets.opscode.com).
 
 Enjoy!