configliere 0.3.4 → 0.4.4

data/.document

@@ -1,4 +1,7 @@
 README.textile
 lib/**/*.rb
 bin/*
+-
 LICENSE
+CHANGELOG.textile
+VERSION

data/.watchr

@@ -0,0 +1,20 @@
+# -*- ruby -*-
+
+def run_spec(file)
+  unless File.exist?(file)
+    puts "#{file} does not exist"
+    return
+  end
+
+  puts   "Running #{file}"
+  system "bundle exec rspec #{file}"
+  puts
+end
+
+watch("spec/.*/*_spec\.rb") do |match|
+  run_spec match[0]
+end
+
+watch("lib/(.*)\.rb") do |match|
+  run_spec %{spec/#{match[1]}_spec.rb}
+end

data/CHANGELOG.textile

@@ -1,3 +1,98 @@
+h2. Version 0.4.0 2011-05-13: MANY BREAKING CHANGES
+
+Killed many features for great justice.  Configliere should now be much more predictable and lightweight, and has a much stricter API. Unfortunately, this will break backwards compatibility in some ways.
+ 
+h4. Cleanup of the Configliere::Params "Magic Hash" class
+
+* Configliere no longer modifies any core classes
+* All the hash gymnastics have been relocated to DeepHash. 
+* DeepHash now converts *all* keys to symbols, and transparently handles deep keys:
+
+<pre>
+  Settings['foo.bar'] = 1
+  Settings.merge! 'foo.bar' => 1
+  Settings[ [:foo, :bar] ] = 1
+  # => all give { :foo => { :bar => 1 } }
+</pre>
+
+* DeepHash typeconverts objects of type Hash to DeepHash when merged or added.
+* DeepHash added several convenience methods -- @slice/slice!@, @compact/compact!@, @extract/extract!@, @reverse_merge/reverse_merge!@, @assert_valid_keys@.
+
+* Configliere::Params @#defaults@, @#resolve!@, @#validate!@ and @#use@ all return self, so you can say
+
+<pre>Settings.defaults(:hi => :mom).use(:commandline).resolve!.validate!</pre>
+
+* Configliere::Params.use now adds middleware only to the *instance* -- you don't get commandline params in your settings object just becaus some other class use'd it.
+* Configliere::Params middlewares should supply a block to Configliere::Params.on_use to #extend the object, #use related middlewares, etc.
+
+h4. Cleanup of Configliere::Define.
+
+* The prepositional soup of accessor sugar is gone, replaced by three public methods:
+  - @definition_of(param, aspect=nil)@ (without arg, gives the definition hash; with arg, gives that value);
+  - @params_with(aspect)@ (hash of param => aspect_definition)
+  - has_definition?(param) (has #define been called for that param?)
+  see below for what's gone.
+* Specs for the magical getter/setter given when you define a param, and for deep key handling.
+
+* Commandline now tracks commandline arguments that haven't been define'd in @unknown_argvs@. It adopts them all the same, but if you don't like what you see there you're free to raise a warning or error.
+* Single-character flags now take an argument: @-a=hello@ or @-a hello@
+
+h4. Misc
+
+* :encrypted keys are now stored as base64-encoded
+* cleaned up handling of encrypt_pass -- it's no longer publicly readable; set it as a member (Settings[:encrypt_pass]) or through the ENCRYPT_PASS environment variable and it will be adopted in the course of action (and, if a member, deleted). Because of the #use method refactoring, you can have independent settings bundles use encrypted independently.
+* Prompt is now its own middleware:
+
+<pre>
+  Settings.use :prompt
+  pwd = Settings.prompt_for(:password)
+</pre>
+
+* bin/configliere shows off the git-style-binaries aspect, and helps you set encrypted params.
+* Specs documentation is now quite readable
+* Cleaned up the STDERR-capturing part of the specs
+* Added spork and watchr support to the specs.
+
+h4. Killing features for great justice:
+
+* No modifications to core classes. Scripts that were secretly depending on Configliere for blank? etc might now break. deep_merge, deep_set and deep_delete have been moved to a DeepHash class, and the Sash class is gone.
+
+* dashed commandline params are accepted but cause a warning -- they do *not* serve as deep keys. By default Configliere happily accepts them. To change that, make a middleware to either convert --foo-bar to --foo.bar, or convert --foo-bar to --foo_bar.
+
+* config_file now just takes a filename: Instead of a magic handle, scope a segment of the file with the :env option:
+
+<pre>Settings.read('./config/foo.yaml', :env => ENV['RACK_ENV'])</pre>
+
+Stripped out a whole raft of oversweet sugar:
+
+* Settings.argv       Settings.rest
+* Settings.commands?  Settings.params_with(:command).empty?
+* Configliere.new     Configliere::Param.new
+* param_or_ask        Settings.prompt_for (with Settings.use(:prompt))
+* param_definitions   Not publicly accessible, use definition_of(param)
+* described_params    Settings.params_with(:description)
+* type_for            Settings.definition_of(param, :type)
+* typed_params        Settings.params_with(:type)
+* required_params     Settings.params_with(:required)
+* define with :no_help and :no_env_help (instead say @:internal@)
+  
+* Removed the long-deprecated :git_style_binaries synonym for :commands
+
+h2. Version 0.3.4
+
+The jump in minor version number was unintentional.
+
+* handle case wehre file is empty on environment merge
+* read returns self, so can chain
+
+h2. Version 0.2.3
+
+* Added a feature to load only production/development/etc subhash from a config file, so:
+
+<pre>
+  Settings.read(root_path('config/foo.yaml'), :env => ENV['RACK_ENV'])
+</pre>
+
 h2. Version 0.2.1 2011-01-28
 
 * Missing required params include their definition in error message
@@ -13,10 +108,10 @@ h2. Version 0.1.0 2010-07-24
 * Single-letter option flags
 * Can give a ':finally' proc (or hand a block to) Settings.define. Example:
 
-<pre><code>  
+<pre>
     Settings.define :key_pair_file,        :description => 'AWS Key pair file', :finally => lambda{ Settings.key_pair_file = File.expand_path(Settings.key_pair_file.to_s) if Settings.key_pair_file }
     Settings.define :key_pair,             :description => "AWS Key pair name. If not specified, it's taken from key_pair_file's basename", :finally => lambda{ Settings.key_pair ||= File.basename(Settings.key_pair_file.to_s, '.pem') if Settings.key_pair_file }
-</code></pre>  
+</pre>  
 
 h2. Version 0.0.8 2010-05-02
 
@@ -39,10 +134,11 @@ h2. Version 0.0.4 2010-01-16
 h2. Version 0.0.3 2010-01-15
 
 * @Settings.param@ now only works for params that have been @#define@'d :
+
 <pre>
     Settings :no_yuo => 'oops'
     Settings.no_yuo
-    #=> NoMethodError: undefined method `no_yuo' for {:no_yuo=>"oops"}:Configliere::Param
+    #=> NoMethodError: undefined method `no_yuo' for { :no_yuo => "oops" } :Configliere::Param
     Settings.define :happy_param, :default => 'yay'
     Settings.happy_param
     #=> "yay" 

data/Gemfile

@@ -0,0 +1,26 @@
+source "http://rubygems.org"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'bundler',   "~> 1.0.12"
+  gem 'yard',      "~> 0.6.7"
+  gem 'jeweler',   "~> 1.5.2"
+  gem 'rspec',     "~> 2.5.0"
+  gem 'spork',     "~> 0.9.0.rc5"
+  gem 'RedCloth' # for yard
+end
+
+group :development do
+  # purely optional, used in the sample scripts
+  gem 'gorillib',  ">= 0.0.4"
+  gem 'highline',  ">= 1.5.2"
+end
+
+group :optional do
+  # only interesting for coverage testing
+  gem 'rcov',      ">= 0.9.9"
+  gem 'reek'
+  gem 'roodi'
+  gem 'watchr'
+end

data/Gemfile.lock

@@ -0,0 +1,54 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    RedCloth (4.2.7)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    gorillib (0.0.7)
+    highline (1.6.1)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    reek (1.2.8)
+      ruby2ruby (~> 1.2)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    roodi (2.1.0)
+      ruby_parser
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.2)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+    ruby2ruby (1.2.5)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ruby_parser (2.0.6)
+      sexp_processor (~> 3.0)
+    sexp_processor (3.0.5)
+    spork (0.9.0.rc7)
+    watchr (0.7)
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  RedCloth
+  bundler (~> 1.0.12)
+  gorillib (>= 0.0.4)
+  highline (>= 1.5.2)
+  jeweler (~> 1.5.2)
+  rcov (>= 0.9.9)
+  reek
+  roodi
+  rspec (~> 2.5.0)
+  spork (~> 0.9.0.rc5)
+  watchr
+  yard (~> 0.6.7)

data/README.textile

@@ -6,34 +6,45 @@ bq. So, Consigliere of mine, I think you should tell your Don what everyone know
 
 You've got a script. It's got some settings. Some settings are for this module, some are for that module. Most of them don't change. Except on your laptop, where the paths are different.  Or when you're in production mode. Or when you're testing from the command line.
 
-Configliere manages settings from many sources: static constants, simple config files, environment variables, commandline options, straight ruby. You don't have to predefine anything, but you can ask configliere to type-convert, require, document or password-obscure any of its fields. Modules can define config settings independently of each other and the main program.
+Configliere manages settings from many sources: static constants, simple config files, environment variables, commandline options, straight ruby. You don't have to predefine anything, but you can ask configliere to type-convert, require, document or password-obscure any of its fields. Basically: *Settings go in, the right thing happens*.
 
-h3. Example
+h2. Example
 
 Here's a simple example, using params from a config file and the command line. In the script:
 
 <pre>
     #/usr/bin/env ruby
     require 'configliere'
-    Settings.use :commandline, :config_file
+    Settings.use :commandline
 
+    # Supply defaults inline.
     Settings({
-      :dest_time => '1955-11-05',
+      :dest_time => '11-05-1955',
       :delorean => {
         :power_source => 'plutonium',
         :roads_needed => true,
         },
       :username => 'marty',
     })
-    Settings.read 'my_script.yaml'  # reads ~/.configliere/my_script.yaml
+    
+    # Pre-defining params isn't required, but it's easy and expressive to do so:
+    Settings.define :dest_time, :type => DateTime, :description => "Target date"
+    # This defines a 'deep key': it controls Settings[:delorean][:roads_needed]
+    Settings.define 'delorean.roads_needed', :type => :boolean
+
+    # The settings in this file will be merged with the above
+    Settings.read './examples/simple_script.yaml'
+
+    # resolve! the settings: load the commandline, do type conversion, etc.
     Settings.resolve!
-    p Settings</pre>
+    p Settings
+</pre>
 
-We'll override some of the defaults with a config file, in this case ~/.configliere/simple_script.yaml
+We'll override some of the defaults with a config file, in this case ./examples/simple_script.yaml
 
 <pre>
     # Settings for return
-    :dest_time:       1985-11-05
+    :dest_time:       11-05-1985
     :delorean:    
       :power_source:  1.21 jiggawatts
 </pre>
@@ -42,35 +53,72 @@ Output, when run with commandline parameters as shown:
 
 <pre>
     ./time_machine.rb --username=doc_brown --delorean.roads_needed="" --delorean.power_source="Mr. Fusion"
-    {:dest_time=>"1985-11-05", :username=>"doc_brown", :delorean=>{:power_source=>"Mr. Fusion", :roads_needed=>nil}}
+
+    {:delorean => {:power_source=>"Mr. Fusion", :roads_needed=>nil}, :username=>"doc_brown", :dest_time=>#<DateTime: 1985-05-11T00:00:00+00:00>}
 </pre>
 
 For an extensive usage in production, see the "wukong gem.":http://github.com/mrflip/wukong
 
-h3. Design goals:
+h2. Notice
+
+Configliere 4.x now has 100% spec coverage, more powerful commandline handling, zero required dependencies. However, it also strips out several obscure features and much magical code, which breaks said obscure features and magic-dependent code. See the "CHANGELOG.":CHANGELOG.textile for details as you upgrade.
+
+h2. Design goals:
+
+* *Omerta (Code of Silence)*. Most commandline parsers force you to pre-define all your parameters in a centralized and wordy syntax. In configliere, you don't have to pre-define anything -- commandline parameters map directly to values in the Configliere hash. Here's all you need to have full-fledged commandline params:
+
+<pre>
+  $ cat ./shorty.rb
+  require 'configliere'
+  Settings.use(:commandline).resolve!
+  p [Settings, Settings.rest]
+  
+  $ ./shorty.rb --foo=bar go
+  [{:foo=>"bar"}, ["go"]]
+</pre>
 
-* *Don't go outside the family*. Requires almost no external resources and almost no code in your script.
-* *Don't mess with my crew*. Settings for a model over here can be done independently of settings for a model over there, and don't require asking the boss to set something up.
 * *Be willing to sit down with the Five Families*. Takes settings from (at your option):
 ** Pre-defined defaults from constants
-** Simple config files
+** Simple config files 
 ** Environment variables
-** Commandline options
-** Ruby block called when all other options are in place
-* *Code of Silence*. Most commandline parsers force you to pre-define all your parameters in a centralized and wordy syntax. In configliere, you pre-define nothing -- commandline parameters map directly to values in the Configliere hash.
+** Commandline options and git-style command runners
+** Ruby block (called when all other options are in place)
+
+* *Don't go outside the family*. Has no dependencies and requires almost no code in your script. Configliere makes no changes to standard ruby classes.
+
+* *Offer discreet counsel*. Configliere offers many features, but only loads the code you request explicitly by calling @use@.
+
+* *Don't mess with my crew*. Settings for a model over here can be done independently of settings for a model over there, and don't require asking the boss to set something up. You centralize configuration _values_ while distributing configuration _definition_:
+
+<pre>
+    # In lib/handler/mysql.rb
+    Settings.define :mysql_host, :type => String, :description => "MySQL db hostname", :default => 'localhost'
+
+    # In app/routes/homepage.rb
+    Settings.define :background_color, :description => "Homepage background color"
+
+    # In config/app.yaml
+    ---
+    :background_color:  '#eee'
+    :mysql_host:        'brains.infochimps.com'
+</pre>
+
+You can decentralize even more by giving modules their own config files or separate Configliere::Param objects.
+
 * *Can hide your assets*. Rather than storing passwords and API keys in plain sight, configliere has a protection racket that can obscure values when stored to disk.
 
 fuhgeddaboudit.
 
+
 h2. Settings structure
 
-Configliere settings are just a plain old normal hash.
+A Configliere settings object is just a (mostly-)normal hash.
 
 You can define static defaults in your module
 
 <pre>
     Settings({
-      :dest_time => '1955-11-05',
+      :dest_time => '11-05-1955',
       :fluxcapacitor => {
         :speed => 88,
         },
@@ -83,11 +131,11 @@ You can define static defaults in your module
     })
 </pre>
 
-(Note that all simple keys should be symbols, with an exception you're about to see.) Retrieve the settings as:
+All simple keys should be symbols. Retrieve the settings as:
 
 <pre>
     # hash keys
-    Settings[:dest_time]                 #=> '1955-11-05'
+    Settings[:dest_time]                 #=> '11-05-1955'
     # deep keys
     Settings[:delorean][:power_source]   #=> 'plutonium'
     Settings[:delorean][:missing]        #=> nil
@@ -97,199 +145,150 @@ You can define static defaults in your module
     Settings['delorean.missing']         #=> nil
     Settings['delorean.missing.fail']    #=> nil
     # method-like (no deep keys tho, and you have to #define the param; see below)
-    Settings.dest_time                   #=> '1955-11-05'
-</pre>
-
-h3. Shortcut syntax for deep keys
-
-You can use a 'dotted key' like 'delorean.power_source' as simple notation for a deep key: @Settings['delorean.power_source']@ is equivalent to @Settings[:delorean][:power_source]@.  You can use a dotted key in any simple reference:
-
-<pre>
-  Settings['delorean.power_source'] = "Mr. Fusion"
-  Settings[:delorean][:power_source]
-  #=> "Mr. Fusion"
-  Settings.delete('delorean.power_source')
-  #=> "Mr. Fusion"
-  Settings
-  #=> { :delorean => {} }
-</pre>
-
-Intermediate keys "auto-vivify" (automatically create any intervening hashes):
-
-<pre>
-  Settings['one.two.three'] = "To tha Fo'"
-  # Settings is { :one => { :two => { :three => "To tha Fo'" } }, :delorean => { :power_source => "Mr. Fusion" }
-</pre>
-
-Do *not* use a dotted key except as a simple reference. You'll ruin Christmas:
-
-<pre>
-  Settings.defaults :this => "that", "made.of.fail" => "oops"
-  #=> { :this => "that", :"made.of.fail" => "oops" } # !!! BROKEN !!!
-</pre>
-
-This may change once we figure out how to handle it all more cleanly, and how to balance "Keep it Simple, Stupid" with "Keep it Convenient, Kilroy".
-
-h3. Only basic functionality loaded by default
-
-Configliere doesn't load any other functionality by default -- you may not want to load config files, or environment variable handling, and so forth.  You can require each file directly, or call @Configliere.use@ with a list of mixins (:all to load all functionality).
-
-<pre>
-    Configliere.use :config_file, :define # Load config files and pre-define
-    Configliere.use :all                  # all of them
+    Settings.dest_time                   #=> '11-05-1955'
 </pre>
 
 h2. Configuration files
 
-Call @Settings.read(:my_settings_group)@ to read a param group from the YAML global config file (@Configliere::DEFAULT_CONFIG_FILE@ -- normally ~/.configliere.yaml)
+Call @Settings.read(filename)@ to read a YAML config file. 
 
 <pre>
     # Settings for version II.
-    :time_machine:
-      :dest_time:        2015-11-05
-      :delorean:
-        :power_source:    Mr. Fusion
-        :roads_needed:    ~
-</pre>
-
-You can instead supply a path to a config file.  If a bare filename (no '/') is given, configliere looks for the file in @Configliere::DEFAULT_CONFIG_DIR@ (normally ~/.configliere). Otherwise it loads the given file.
-
-<pre>
-    Settings.read(:time_machine)             # looks in ~/.configliere.yaml, and extracts the :time_machine group
-    Settings.read('/etc/time_machine.yaml')  # looks in /etc/time_machine.yaml
-    Settings.read('time_machine.yaml')       # looks in ~/.configliere/time_machine.yaml
-</pre>
-
-When you read directly from a file you should leave off the top-level settings group:
-
-<pre>
-    # Settings for version II.
-    :dest_time:         2015-11-05
+    :dest_time:        11-05-2015
     :delorean:
       :power_source:    Mr. Fusion
       :roads_needed:    ~
 </pre>
 
-Save defaults by inserting a line like:
+If a bare filename (no '/') is given, configliere looks for the file in @Configliere::DEFAULT_CONFIG_DIR@ (normally ~/.configliere). Otherwise it loads the given file.
 
 <pre>
-    Settings.save(:time_machine)            # merges into ~/.configliere.yaml, under :time_machine
-    Settings.save('/etc/time_machine.yaml') # overwrites /etc/time_machine.yaml
-    Settings.save('time_machine.yaml')      # overwrites ~/.configliere/time_machine.yaml
+    Settings.read('/etc/time_machine.yaml')  # looks in /etc/time_machine.yaml
+    Settings.read('time_machine.yaml')       # looks in ~/.configliere/time_machine.yaml
 </pre>
 
-You're free to use as many config files as you like. Loading a config file sets values immediately, so later-loaded files win out over earlier-loaded ones:
+As you can see, you're free to use as many config files as you like. Loading a config file sets values immediately, so later-loaded files win out over earlier-loaded ones.
 
-<pre>
-    Settings.read('time_machine_global.yaml')
-    Settings.read('time_machine_site.yaml')
-</pre>
-
-h2. Environment Variables
+You can save configuration too:
 
 <pre>
-    Settings.env_vars 'DEST_TIME', :password => 'TM_PASS', 'delorean.power_source' => 'POWER_SOURCE'
+    Settings.save!('/etc/time_machine.yaml') # overwrites /etc/time_machine.yaml
+    Settings.save!('time_machine.yaml')      # overwrites ~/.configliere/time_machine.yaml
 </pre>
 
-As usual, dotted keys set the corresponeding nested key (@'delorean.power_source'@ sets @Settings[:delorean][:power_source]@). As shown below, you may also use #define to set up environment variables: @define 'delorean.power_source', :environment => 'POWER_SOURCE'@.
-
-Environment variables are demonstrated in "examples/simple_script.rb":http://github.com/mrflip/configliere/tree/master/examples/simple_script.rb and "examples/env_var_script.rb":http://github.com/mrflip/configliere/tree/master/examples/env_var_script.rb
-
-**NOTE**: The interface to #env_vars has changed since v0.2, see "CHANGELOG.textile":CHANGELOG.textile
-
 h2. Command-line parameters
 
 <pre>
     # Head back
-    time_machine --delorean.power_source='1.21 gigawatt lightning strike' --dest_time=1985-11-05
+    time_machine --delorean.power_source='1.21 gigawatt lightning strike' --dest_time=11-05-1985
     # (in the time_machine script:)
-    Settings.use :commandline
+    Settings.use(:commandline)
     Settings.resolve!
 </pre>
 
 Interpretation of command-line parameters:
-* *name-val params*: @--param=val@ sets @Configliere[:param]@ to val.
+
+* *name-val params*: @--param=val@ sets @Configliere[:param]@ to val. You _must_ use the '=' in there: <code>./my_cmd --filename=bar</code> good, <code>./my_cmd --filename bar</code> bad.
 * *boolean params*: @--param@ sets @Configliere[:param]@ to be true. @--param=""@ sets @Configliere[:param]@ to be nil.
-* *scoped params*: @--group-sub_group-param=val@ sets @Configliere[:group][:subgroup][:param]@ to val (and similarly for boolean parameters).
-** A dash or dot within a parameter name scopes that parameter: @--group.sub_group.param=val@ and @--group-sub_group-param=val@ do the same thing. A _ within a parameter name is left as part of the segment.
-** Only @[\w\.\-]+@ are accepted in parameter names.
+* *single-char flags*: Define a flag for a variable: <code>Settings.define :filename, :flag => "f"</code> allows you to say <code>./my_cmd -f=bar</code>.
+* *scoped params*: A dot within a parameter name scopes that parameter: @--group.sub_group.param=val@ sets @Configliere[:group][:subgroup][:param]@ to val (and similarly for boolean parameters). 
+** Only @[\w\.]+@ are accepted in parameter names. '-' is currently accepted but causes a warning.
 * *Settings.rest*: anything else is stored, in order, in @Settings.rest@.
 * *stop marker*: a @--@ alone stops parameter processing and tosses all remaining params (not including the @--@) into Settings.rest.
 
 Here are some things you don't get:
-* There are no short parameters (-r, etc).
-* Apart from converting @''@ (an explicit blank string) to @nil@, no type coercion is performed on parameters unless requested explicitly (see below).
-* No validation is performed on parameters.
-* No ordering or multiplicity is preserved (you can't say @--file=this --file=that@).
 
-If you want more, you might like the Trollop gem.  If you enjoy wordy nightmares, use "getoptlog":http://linuxdevcenter.com/pub/a/linux/2003/09/18/ruby_csv.html?page=2 from the ruby standard library.
+* Configliere doesn't complain about un-@define@'d commandline argvs. However, it does store each undefine'd argv (when resolve! is called) into @unknown_argvs@, so you can decide what to do about it.
+* Apart from converting @''@ (an explicit blank string) to @nil@, no type coercion is performed on parameters unless requested explicitly (see below).
+* No validation is performed on parameters, but you can insert a middleware with a @validate!()@ method, or use a @:finally@ block.
+* No ordering or multiplicity is preserved: you can't say @--file=this --file=that@. Instead, define the param as an array <code>Settings.define :file, :type => Array</code> and give a simple comma-separated list.
 
-Commandline parameters are demonstrated in "examples/simple_script.rb":http://github.com/mrflip/configliere/tree/master/examples/simple_script.rb and examples/env_var_script.rb":http://github.com/mrflip/configliere/tree/master/examples/env_var_script.rb
+Commandline parameters are demonstrated in "examples/simple_script.rb":http://github.com/mrflip/configliere/tree/master/examples/simple_script.rb and "examples/env_var_script.rb":http://github.com/mrflip/configliere/tree/master/examples/env_var_script.rb
 
-h2. Fancy Parameters
+h2. Defined Parameters
 
 You don't have to pre-define parameters, but you can:
 
 <pre>
-    Settings.use :define
     Settings.define :dest_time, :type => DateTime, :description => 'Arrival time'
     Settings.define 'delorean.power_source', :env_var => 'POWER_SOURCE', :description => 'Delorean subsytem supplying power to the Flux Capacitor.'
     Settings.define :password, :required => true, :encrypted => true
 </pre>
 
-* *:type*: converts params to a desired form.
-* *:description*: documents a param.
-* *:required*: marks params required.
-* *:encrypted*: marks params to be obscured when saved to disk. See [#Encrypted Parameters] below for caveats.
-* *:env_var*: take param from given environment variable if set.
+* @:description@: documents a param.
+* @:type@:        converts params to a desired form.
+* @:required@:    marks params required.
+* @:encrypted@:   marks params to be obscured when saved to disk. See [#Encrypted Parameters] below for caveats.
+* @:env_var@:     take param from given environment variable if set.
 
 Defined parameters are demonstrated in most of the "example scripts":http://github.com/mrflip/configliere/tree/master/examples
 
+h3. Description
+
+If you define a param's description, besides nicely documenting it within your code the description will be stuffed into the output when the --help commandline option is invoked.
+
+<pre>
+  $ ./examples/simple_script
+  usage: simple_script.rb [...--param=val...]
+
+  Params:
+    --delorean.roads_needed   delorean.roads_needed
+    --dest_time=DateTime      Date to travel to [Default: 11-05-1955]
+</pre>
+
 h3. Type Conversion
 
+Parameters defined with a @:type@ and will be type-converted when you call @Settings.resolve!@.
+
 <pre>
     Settings.define :dest_time,     :type => DateTime
     Settings.define :fugeddaboudit, :type => Array
-    Settings :fugeddaboudit => 'badabing,badaboom,hey', :dest_time => '1955-11-05'
+    Settings :fugeddaboudit => 'badabing,badaboom,hey', :dest_time => '11-05-1955'
     Settings.resolve!
     Settings[:fugeddaboudit]   #=> ['badabing', 'badaboom', 'hey']
     Settings[:dest_time]       #=> #<DateTime: 4870833/2,0,2299161>
 </pre>
 
-Configliere can coerce parameter values to Integer, Float, :boolean, Symbol, Array, Date and DateTime. (Make sure to call Settings.resolve! in your script.)
+Configliere can coerce parameter values to Integer, Float, :boolean, Symbol, Array, Date and DateTime. 
 
 * :boolean converts nil to nil ; false, 'false', 0, '0' and '' to false; and everything else to true.
 * Array just does a simple split on ",". It doesn't do any escaping or quoting.
 * Date and DateTime convert unparseable inputs to nil.
+* :filename calls File.expand_path() on the param.
 
-h3. Description
+h3. Required Parameters
 
-If you define a param's description, besides nicely documenting it within your code the description will be stuffed into the output when the --help commandline option is invoked.
+Any required parameter found to be nil raise an error (listing all missing params) when you call Settings.resolve! (See "examples/env_var_script.rb":http://github.com/mrflip/configliere/tree/master/examples/env_var_script.rb)
 
-h3. Required Parameters
+h3. Environment Variables
 
-Any required parameter found to be nil raises an error (listing all missing params). (Make sure to call Settings.resolve! in your script.)
+<pre>
+    Settings.define :dest_time,   :env_var => 'DEST_TIME'
+    Settings.define :environment, :env_var => 'RACK_ENV'
+</pre>
 
 h3. Encrypted Parameters
 
-Define a param to be encrypted and invoke Settings.save!
+Define a param to be encrypted and invoke Settings.save!. It will use Settings.encrypt_pass (or the ENCRYPT_PASS environment variable) to encrypt the data when it is saved to disk. (see "examples/encrypted_script.rb":http://github.com/mrflip/configliere/tree/master/examples/encrypted_script.rb)
 
 <pre>
-   define 'amazon.api.key', :encrypted => true
-   Settings 'amazon.api.key' => 'fnord'
+    Settings.use :encrypted
+    Settings.define 'amazon.api.key', :encrypted => true
+    Settings 'amazon.api.key' => 'fnord'
 </pre>
 
-In this example, the hash saved to disk will contain @{ :amazon => { :api => { :encrypted_key => "...encrypted val..." } } }@. After reading from disk, #resolve! will recover its original value: @{ :amazon => { :api => { :key => "fnord" } } }@. The code currently doesn't look for a collision between a :param and :encrypted_param, so be careful; you can preemptively call resolve_encrypted! to enforce order.
+In this example, the hash saved to disk will contain @{ :amazon => { :api => { :encrypted_key => "...encrypted val..." } } }@. After reading from disk, #resolve! will recover its original value: @{ :amazon => { :api => { :key => "fnord" } } }@.
 
 bq.  There are two kinds of cryptography in this world: cryptography that will stop your kid sister from reading your files, and cryptography that will stop major governments from reading your files. This book is about the latter. -- Preface to Applied Cryptography by Bruce Schneier
 
-Configliere provides the latter.  Anyone with access to the script, its config files and the config file passphrase can recover the plaintext password. Still, there's a difference between immediate access and having to find a paperclip and jimmy open your annoying older brother's stupid journal.
+Configliere provides the former.
 
-Encrypted parameters are demonstrated in "examples/encrypted_script.rb":http://github.com/mrflip/configliere/tree/master/examples/encrypted_script.rb
+Anyone with access to the script, its config files and its normal launch environment can recover the plaintext password; but it at least doesn't appear when you cat the file while giving a presentation.
 
 h2. Ruby Block
 
 <pre>
+    Settings.use :config_block
     Settings.finally do |c|
       c.dest_time = (Time.now + 60) if c.username == 'einstein'
       # you can use hash syntax too
@@ -301,24 +300,49 @@ h2. Ruby Block
     Settings.resolve!    # the finally blocks will be called in order
 </pre>
 
-Configliere 'finally' blocks are invoked when you call @#resolve!@.  They're guaranteed to be called at the end of the resolve chain, and before the validate chain.
+Configliere 'finally' blocks are invoked when you call @resolve!@.  They're guaranteed to be called at the end of the resolve chain, and before the validate chain.
 
 Config blocks are demonstrated in "examples/config_block.rb":http://github.com/mrflip/configliere/tree/master/examples/config_block.rb
 
+h2. Shortcut syntax for deep keys
+
+You can use a 'dotted key' like 'delorean.power_source' as simple notation for a deep key: @Settings['delorean.power_source']@ is equivalent to @Settings[:delorean][:power_source]@.  You can use a dotted key in any simple reference:
+
+<pre>
+  Settings['delorean.power_source'] = "Mr. Fusion"
+  Settings[:delorean][:power_source]
+  #=> "Mr. Fusion"
+  Settings.delete('delorean.power_source')
+  #=> "Mr. Fusion"
+  Settings
+  #=> { :delorean => {} }
+</pre>
+
+Intermediate keys "auto-vivify" (automatically create any intervening hashes):
+
+<pre>
+  Settings['one.two.three'] = "To tha Fo'"
+  # Settings is { :one => { :two => { :three => "To tha Fo'" } }, :delorean => { :power_source => "Mr. Fusion" }
+</pre>
+
 h2. Independent Settings
 
-All of the above examples use the global variable @Settings@, defined in configliere.rb.  You're free to define your own settings universe though:
+All of the above examples use the global variable @Settings@, defined in configliere.rb.  It really works fine in practice, even where several systems intersect. You're free to define your own settings universe though:
 
 <pre>
     class Wolfman
-      cattr_accessor :config
-      self.config = Configliere.new({
-        :moon    => 'full',
-        :nards   => true,
-        })
+      attr_reader :config
+      def self.config() @@config ; end      
+      self.config = Configliere::Param.new({
+          :moon    => 'full',
+          :nards   => true,
+          })
     end
-    teen_wolf = proj.new
+    Wolfman.use :commandline
+
+    teen_wolf = Wolfman.new
     teen_wolf.config.defaults(:give_me => 'keg of beer')
+    
     teen_wolf.config #=> {:moon=>"full", :nards=>true, :give_me=>"keg of beer" }
     Settings         #=> {}
 </pre>