configliere 0.0.1 → 0.0.2

data/README.textile

@@ -6,7 +6,38 @@ 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 is a no-fuss library for flexibly managing your configuration settings. Design goals:
+Configliere manage 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.
+
+h3. Example
+
+Here's a simple example, using params from a config file and the command line. A config file, in ~/.configliere/simple_script.yaml
+
+<pre>
+    :cat:     hat
+    :spider:  tuffet
+    :sprats:
+      :jack:  lean</pre>
+
+A simple script:
+
+<pre>
+    #/usr/bin/env ruby
+    require 'configliere'
+    
+    Settings.use(:commandline, :config_file, 
+      :dish => 'spoon', :cow => 'moon')
+    Settings.read 'my_script.yaml'
+    Settings.resolve!
+
+    p Settings</pre>
+
+Output:
+
+<pre>
+    ./simple_script.rb --sprats.wife=fat --spider=drainspout
+    {:spider=>"drainspout", :cat=>"hat", :sprats=>{:wife=>"fat", :jack=>"lean"}, :cow=>"moon"}  </pre>
+
+h3. Design goals:
 
 * *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.
@@ -27,6 +58,7 @@ Configliere settings are just a plain old normal hash.
 
 You can define static defaults in your module
 
+<pre>
     Settings.defaults({
       :dest_time => '1955-11-05',
       :fluxcapacitor => {
@@ -39,70 +71,87 @@ You can define static defaults in your module
       :username => 'marty',
       :password => '',
     })
+</pre>
     
 Retrieve them as:
 
-  # hash keys       
-  Config[:dest_time]                 #=> '1955-11-05'
-  # deep keys
-  Config[:delorean][:power_source]   #=> 'plutonium'
-  Config[:delorean][:missing]        #=> nil
-  Config[:delorean][:missing][:fail] #=> raises an error
-  # dotted keys resolve to deep keys
-  Config['delorean.power_source']    #=> 'plutonium'
-  Config['delorean.missing']         #=> nil
-  Config['delorean.missing.fail']    #=> nil
-  # method-like (can't use this with deep keys)
-  Settings.dest_time                   #=> '1955-11-05'
-
-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 the mixins to require (:all to load all functionality).
-
-    Configliere.use :param_store, :define # Load config files and pre-define 
+<pre>
+    # hash keys       
+    Config[:dest_time]                 #=> '1955-11-05'
+    # deep keys
+    Config[:delorean][:power_source]   #=> 'plutonium'
+    Config[:delorean][:missing]        #=> nil
+    Config[:delorean][:missing][:fail] #=> raises an error
+    # dotted keys resolve to deep keys
+    Config['delorean.power_source']    #=> 'plutonium'
+    Config['delorean.missing']         #=> nil
+    Config['delorean.missing.fail']    #=> nil
+    # method-like (no deep keys tho)
+    Settings.dest_time                 #=> '1955-11-05'
+</pre>
+
+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
+</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(:my_settings_group)@ to read a param group from the YAML global config file (@Configliere::DEFAULT_CONFIG_FILE@ -- normally ~/.configliere.yaml)
 
+<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.
+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
     :delorean:
       :power_source:    Mr. Fusion
       :roads_needed:    ~
+</pre>
 
 You can save defaults with
 
+<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
+</pre>
     
 h2. Environment Variables
 
+<pre>
     Settings.use_environment 'DEST_TIME', 'TM_PASS' => 'password', 'POWER_SOURCE' => 'delorean.power_source'
+</pre>
 
-As usual, dotted keys set the corresponeding nested key ('delorean.power_source' sets Config[:delorean][:power_source])
+As usual, dotted keys set the corresponeding nested key ('delorean.power_source' sets Config[:delorean][:power_source]). You can alternatively set up environment variables with @define 'delorean.power_source', :environment => 'POWER_SOURCE'@ - see below.
 
 h2. Command-line parameters
 
+<pre>
     # Head back
     time_machine --delorean-power_source='1.21 gigawatt lightning strike' --dest_time=1985-11-05 
     # (in the time_machine script:)
     Settings.use :commandline
+</pre>
 
 Interpretation of command-line parameters:
 * *name-val params*: @--param=val@ sets @Configliere[:param]@ to val.
@@ -115,7 +164,7 @@ Interpretation of command-line parameters:
 
 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).
+* 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@).
 
@@ -125,15 +174,39 @@ h2. Fancy Parameters
 
 You don't have to pre-define parameters, but you can:
 
+<pre>
     Settings.use :define
-    Settings.define :dest_time, :type => Date, :description => 'Arrival time. If only a date is given, the current time of day on that date is assumed.'
-    Settings.define 'delorean.power_source', :description => 'Delorean subsytem supplying power to the Flux Capacitor.'
-    Settings.define :password, :required => true, :obscure => true
+    Settings.define :dest_time, :type => Date, :description => 'Arrival time'
+    Settings.define 'delorean.power_source', :environment => '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. It understands Date, Time, Integer, :boolean and Symbol. :blank => nil and :blank => false. Make sure to call Settings.resolve! in your script.
-* *:description* documents a param.
-* *:required* marks params required. 
-* *:encrypted* marks params to be obscured when saved to disk. See [#Encrypted Parameters] below for caveats.
+* *: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.
+* *:environment*: take param from given environment variable if set.
+
+h3. Type Conversion
+
+<pre>
+    Settings.define :dest_time,     :type => DateTime
+    Settings.define :fugeddaboudit, :type => Array
+    Settings :fugeddaboudit => 'badabing,badaboom,hey', :dest_time => '1955-11-05'
+    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.)
+
+* :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.
+
+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.
 
 h3. Required Parameters
 
@@ -141,31 +214,40 @@ Any required parameter found to be nil raises an error (listing all missing para
 
 h3. Encrypted Parameters
 
-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
+Define a param to be encrypted and invoke Settings.save!
+
+<pre>
+   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.
+
+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 having to find a paperclip and jimmy open your annoying brother's stupid journal and being able to open to any page.
+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.
 
 h2. Ruby Block
 
+<pre>
     Settings.finally do |c|
       c.dest_time = (Time.now + 60) if c.username == 'einstein'
       # you can use hash syntax too
       c[:dest_time] = (Time.now + 60) if c[:username] == 'einstein'
     end
     #
-    # ... rest of setup
+    # ... rest of setup ...
     #
     Settings.resolve!    # the finally blocks will be called in order
+</pre>
 
-Configliere 'finally' blocks are called after everything but required parameter    
+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.
 
 h2. Independent Settings
 
-All of the above uses the Settings global variable defined in configliere.rb.  However, you're free to define your own settings universe. 
+All of the above examples use the global variable @Settings@, defined in configliere.rb.  You're free to define your own settings universe though:
 
+<pre>
     module MyProject
       cattr_accessor :config
       self.config = Configliere.new({
@@ -175,6 +257,7 @@ All of the above uses the Settings global variable defined in configliere.rb.  H
     end
     pr = proj.new
     pr.config   #=> {:helicity => 'homotopic', :froebenius_matrix => 'unitary' }
+</pre>
 
 Values in here don't overlap with the Settings object or any other settings universe. However, every one that pulls in commandline params gets a full copy of the commandline params.
 

data/Rakefile

@@ -10,29 +10,14 @@ begin
 
    "" So, Consigliere of mine, I think you should tell your Don what everyone knows. "" -- Don Corleone
 
-Configliere's wise counsel takes care of these problems. Design goals:
-
-* *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
-** 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.
-* *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.
+Configliere manage 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.
 } #'
     gem.email = "flip@infochimps.org"
     gem.homepage = "http://github.com/mrflip/configliere"
     gem.authors = ["mrflip"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "yard", ">= 0"
-    gem.add_dependency "highline", ">= 0"
-    gem.add_dependency "yaml", ">= 0"
-    gem.add_dependency "openssl", ">= 0"
+    # gem.add_dependency "highline", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/configliere.gemspec

@@ -5,30 +5,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{configliere}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["mrflip"]
-  s.date = %q{2010-01-06}
+  s.date = %q{2010-01-08}
   s.default_executable = %q{configliere}
   s.description = %q{ 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.
 
    "" So, Consigliere of mine, I think you should tell your Don what everyone knows. "" -- Don Corleone
 
-Configliere's wise counsel takes care of these problems. Design goals:
-
-* *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
-** 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.
-* *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.
+Configliere manage 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.
 }
   s.email = %q{flip@infochimps.org}
   s.executables = ["configliere"]
@@ -54,23 +41,24 @@ fuhgeddaboudit.
      "lib/configliere/commandline.rb",
      "lib/configliere/commandline/commands.rb",
      "lib/configliere/commandline/options.rb",
-     "lib/configliere/config_blocks.rb",
+     "lib/configliere/config_block.rb",
+     "lib/configliere/config_file.rb",
      "lib/configliere/core_ext.rb",
+     "lib/configliere/core_ext/blank.rb",
      "lib/configliere/core_ext/hash.rb",
      "lib/configliere/crypter.rb",
      "lib/configliere/define.rb",
      "lib/configliere/encrypted.rb",
      "lib/configliere/environment.rb",
      "lib/configliere/param.rb",
-     "lib/configliere/param_store.rb",
      "spec/configliere/commandline_spec.rb",
-     "spec/configliere/config_blocks_spec.rb",
+     "spec/configliere/config_block_spec.rb",
+     "spec/configliere/config_file_spec.rb",
      "spec/configliere/crypter_spec.rb",
      "spec/configliere/define_spec.rb",
      "spec/configliere/encrypted_spec.rb",
      "spec/configliere/environment_spec.rb",
      "spec/configliere/param_spec.rb",
-     "spec/configliere/param_store_spec.rb",
      "spec/configliere_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb"
@@ -82,13 +70,13 @@ fuhgeddaboudit.
   s.summary = %q{Wise, discreet configuration management}
   s.test_files = [
     "spec/configliere/commandline_spec.rb",
-     "spec/configliere/config_blocks_spec.rb",
+     "spec/configliere/config_block_spec.rb",
+     "spec/configliere/config_file_spec.rb",
      "spec/configliere/crypter_spec.rb",
      "spec/configliere/define_spec.rb",
      "spec/configliere/encrypted_spec.rb",
      "spec/configliere/environment_spec.rb",
      "spec/configliere/param_spec.rb",
-     "spec/configliere/param_store_spec.rb",
      "spec/configliere_spec.rb",
      "spec/spec_helper.rb",
      "examples/commandline_script.rb",
@@ -102,22 +90,13 @@ fuhgeddaboudit.
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<yard>, [">= 0"])
-      s.add_runtime_dependency(%q<highline>, [">= 0"])
-      s.add_runtime_dependency(%q<yaml>, [">= 0"])
-      s.add_runtime_dependency(%q<openssl>, [">= 0"])
     else
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<yard>, [">= 0"])
-      s.add_dependency(%q<highline>, [">= 0"])
-      s.add_dependency(%q<yaml>, [">= 0"])
-      s.add_dependency(%q<openssl>, [">= 0"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<yard>, [">= 0"])
-    s.add_dependency(%q<highline>, [">= 0"])
-    s.add_dependency(%q<yaml>, [">= 0"])
-    s.add_dependency(%q<openssl>, [">= 0"])
   end
 end
 

data/examples/simple_script.rb

@@ -1,21 +1,19 @@
 #!/usr/bin/env ruby
-require 'rubygems' ; $: << File.dirname(__FILE__)+'/../lib'
+$: << File.dirname(__FILE__)+'/../lib'
 require 'configliere'
-SCRIPT_DIR = File.dirname(__FILE__)
 
 # Intro text
 puts %Q{
 This is a demo of the Configliere interface. It takse settings
 Try running it as
-   ./examples/simple_script.rb --cat=hat
+  ./examples/simple_script.rb --sprats.wife=fat --spider=drainspout
 with those args, we
-  expect: {:things=>["thing_1", "thing_2"], :rate_per_hour=>10, :cat=>"hat"}
+  expect: {:spider=>"drainspout", :cat=>"hat", :sprats=>{:wife=>"fat", :jack=>"lean"}, :cow=>"moon"}
 }
 
-# Configuration
-Settings.use :commandline, :param_store, :config_blocks
-Settings.read SCRIPT_DIR+'/simple_script.yaml'
-
+Settings.use(:commandline, :config_file,
+      :cat => 'bag', :cow => 'moon')
+Settings.read File.dirname(__FILE__)+'/simple_script.yaml'
 Settings.resolve!
 
 # Print results

data/examples/simple_script.yaml

@@ -1,5 +1,5 @@
 --- 
-:things: 
-- thing_1
-- thing_2
-:rate_per_hour: 10
+:cat:     hat
+:spider:  tuffet
+:sprats:
+  :jack:  lean

data/lib/configliere.rb

@@ -14,7 +14,7 @@ module Configliere
     Configliere::Param.new *args, &block
   end
 
-  ALL_MIXINS = [:define, :encrypted, :environment, :param_store, :commandline, :config_blocks]
+  ALL_MIXINS = [:define, :encrypted, :environment, :config_file, :commandline, :config_block]
   def self.use *mixins
     mixins = ALL_MIXINS if mixins.include?(:all)
     mixins.each do |mixin|

data/lib/configliere/commandline.rb

@@ -74,9 +74,9 @@ module Configliere
 
     def help
       help_str  = [ usage ]
-      help_str += [ "\nParams:", descriptions.map{|param, desc| "  %-20s %s"%[param.to_s+':', desc]}.join("\n"), ] if respond_to?(:descriptions)
+      help_str += [ "\nParams:", descriptions.sort_by{|p,d| p.to_s }.map{|param, desc| "  --%-25s %s"%[param.to_s+':', desc]}.join("\n"), ] if respond_to?(:descriptions)
       # help_str += ["\nCommands", commands.map{|cmd, desc| "  %-20s %s"%[cmd.to_s+':', desc]}.join("\n")] if respond_to?(:commands)
-      help_str += [ "\nEnvironment Variables:", params_from_environment.map{|param, env| "  %-20s %s"%[env.to_s+':', param]}.join("\n"), ] if respond_to?(:params_from_environment)
+      help_str += [ "\nEnvironment Variables can be used to set:", params_from_environment.map{|param, env| "  %-27s %s"%[env.to_s+':', param]}.join("\n"), ] if respond_to?(:params_from_environment)
       help_str.join("\n")
     end
 

data/lib/configliere/{config_blocks.rb → config_block.rb}

@@ -1,6 +1,6 @@
 Configliere.use :define
 module Configliere
-  module Block
+  module ConfigBlock
     # Config blocks to be executed at end of resolution (just before validation)
     attr_accessor :final_blocks
     def final_blocks
@@ -36,6 +36,6 @@ module Configliere
   end
 
   Param.class_eval do
-    include Configliere::Block
+    include Configliere::ConfigBlock
   end
 end

data/lib/configliere/{param_store.rb → config_file.rb}

@@ -1,12 +1,12 @@
 require 'yaml'
 module Configliere
   #
-  # ParamStore -- load configuration from a simple YAML file
+  # ConfigFile -- load configuration from a simple YAML file
   #
-  module ParamStore
+  module ConfigFile
     # Load params from disk.
     # * file is in YAML format, as a hash of handle => param_hash pairs
-    # * filename defaults to ParamStore::DEFAULT_CONFIG_FILE (~/.configliere, probably)
+    # * filename defaults to Configliere::DEFAULT_CONFIG_FILE (~/.configliere, probably)
     def read handle
       filename = filename_for_handle(handle)
       begin
@@ -21,13 +21,13 @@ module Configliere
 
     # save to disk.
     # * file is in YAML format, as a hash of handle => param_hash pairs
-    # * filename defaults to ParamStore::DEFAULT_CONFIG_FILE (~/.configliere, probably)
+    # * filename defaults to Configliere::DEFAULT_CONFIG_FILE (~/.configliere, probably)
     def save! handle
       filename = filename_for_handle(handle)
       if handle.is_a?(Symbol)
-        ParamStore.merge_into_yaml_file filename, handle, self.export
+        ConfigFile.merge_into_yaml_file filename, handle, self.export
       else
-        ParamStore.write_yaml_file filename, self.export
+        ConfigFile.write_yaml_file filename, self.export
       end
     end
 
@@ -65,6 +65,6 @@ module Configliere
 
   Param.class_eval do
     # include read / save operations
-    include ParamStore
+    include ConfigFile
   end
 end

data/lib/configliere/core_ext.rb

@@ -1 +1,2 @@
+require 'configliere/core_ext/blank'
 require 'configliere/core_ext/hash'

data/lib/configliere/core_ext/blank.rb

@@ -0,0 +1,89 @@
+class Object
+  ##
+  # Returns true if the object is nil or empty (if applicable)
+  #
+  #   [].blank?         #=>  true
+  #   [1].blank?        #=>  false
+  #   [nil].blank?      #=>  false
+  #
+  # @return [TrueClass, FalseClass]
+  #
+  # @api public
+  def blank?
+    nil? || (respond_to?(:empty?) && empty?)
+  end
+end # class Object
+
+class Numeric
+  ##
+  # Numerics are never blank
+  #
+  #   0.blank?          #=>  false
+  #   1.blank?          #=>  false
+  #   6.54321.blank?    #=>  false
+  #
+  # @return [FalseClass]
+  #
+  # @api public
+  def blank?
+    false
+  end
+end # class Numeric
+
+class NilClass
+  ##
+  # Nil is always blank
+  #
+  #   nil.blank?        #=>  true
+  #
+  # @return [TrueClass]
+  #
+  # @api public
+  def blank?
+    true
+  end
+end # class NilClass
+
+class TrueClass
+  ##
+  # True is never blank.
+  #
+  #   true.blank?       #=>  false
+  #
+  # @return [FalseClass]
+  #
+  # @api public
+  def blank?
+    false
+  end
+end # class TrueClass
+
+class FalseClass
+  ##
+  # False is always blank.
+  #
+  #   false.blank?      #=>  true
+  #
+  # @return [TrueClass]
+  #
+  # @api public
+  def blank?
+    true
+  end
+end # class FalseClass
+
+class String
+  ##
+  # Strips out whitespace then tests if the string is empty.
+  #
+  #   "".blank?         #=>  true
+  #   "     ".blank?    #=>  true
+  #   " hey ho ".blank? #=>  false
+  #
+  # @return [TrueClass, FalseClass]
+  #
+  # @api public
+  def blank?
+    strip.empty?
+  end
+end # class String

data/lib/configliere/core_ext/hash.rb

@@ -4,9 +4,9 @@
 class Hash
 
   # lambda for recursive merges
-  Hash::DEEP_MERGER = proc do |key,v1,v2|
+  ::Hash::DEEP_MERGER = proc do |key,v1,v2|
     (v1.respond_to?(:merge) && v2.respond_to?(:merge)) ? v1.merge(v2.compact, &Hash::DEEP_MERGER) : (v2.nil? ? v1 : v2)
-  end
+  end unless defined?(::Hash::DEEP_MERGER)
 
   #
   # Merge hashes recursively.
@@ -76,6 +76,16 @@ class Hash
     hsh[last_key]
   end
 
+
+  #
+  # Treat hash as tree of hashes:
+  #
+  #     x = { 1 => :val, :subhash => { 1 => :val1, 2 => :val2 } }
+  #     x.deep_delete(:subhash, 1)
+  #     #=> :val
+  #     x
+  #     #=> { 1 => :val, :subhash => { 2 => :val2 } }
+  #
   def deep_delete *args
     last_key  = args.pop
     last_hsh  = args.empty? ? self : (deep_get(*args)||{})

data/lib/configliere/crypter.rb

@@ -64,7 +64,7 @@ module Configliere
 
     # Convert the encrypt_pass passphrase into the key used for encryption
     def self.encrypt_key encrypt_pass, options={}
-      raise 'Blank encryption password!' if encrypt_pass.to_s == ''
+      raise 'Blank encryption password!' if encrypt_pass.blank?
       # this provides the required 256 bits of key for the aes-256-cbc cipher
       Digest::SHA256.digest(encrypt_pass)
     end

data/lib/configliere/define.rb

@@ -13,6 +13,8 @@ module Configliere
     #
     def define param, definitions={}
       self.param_definitions[param].merge! definitions
+      self[param] = definitions[:default] if definitions.include?(:default)
+      self.environment_variables definitions[:environment], param if definitions.include?(:environment)
     end
 
     def param_definitions
@@ -20,23 +22,6 @@ module Configliere
       @param_definitions ||= Hash.new{|hsh, key| hsh[key] = {} }
     end
 
-    protected
-    # all params with a value for the definable aspect
-    #
-    # @param definable the aspect to list (:description, :type, :encrypted, etc.)
-    def params_with defineable
-      param_definitions.keys.find_all{|param| param_definitions[param][defineable] } || []
-    end
-
-    def definitions_for defineable
-      hsh = {}
-      param_definitions.each do |param, defs|
-        hsh[param] = defs[defineable] if defs[defineable]
-      end
-      hsh
-    end
-    public
-
     # performs type coercion
     def resolve!
       resolve_types!
@@ -65,7 +50,7 @@ module Configliere
 
     # All described params with their descriptions
     def descriptions
-      definitions_for(:description)
+      definitions_for(:description).reject{|param, desc| param_definitions[param][:hide_help] }
     end
 
     # List of params that have descriptions
@@ -86,33 +71,38 @@ module Configliere
       param_definitions[param][:type]
     end
 
-    # All described params with their descriptions
-    def types
+    # All typed params with their descriptions
+    def typed_params
       definitions_for(:type)
     end
 
     # List of params that have descriptions
-    def typed_params
+    def typed_param_names
       params_with(:type)
     end
 
+    require 'date'
+
     # Coerce all params with types defined to their proper form
     def resolve_types!
-      types.each do |param, type|
+      typed_params.each do |param, type|
         val = self[param]
         case
-        when val.nil? then val = nil
+        when val.nil?           then val = nil
         when (type == :boolean) then
-          if ['false', '0', ''].include?(val.to_s) then val = false else val = true end
-        when (val.to_s == '')   then val = nil
+          if ['false', false, 0, '0', ''].include?(val) then val = false else val = true end
+        when ((type == Array) && val.is_a?(String))
+          val = val.split(",")  rescue nil
+          # following types map blank to nil
+        when (val.blank?)       then val = nil
         when (type == Float)    then val = val.to_f
         when (type == Integer)  then val = val.to_i
+        when (type == Symbol)   then val = val.to_s.to_sym     rescue nil
+        when ((val.to_s == 'now') && (type == Date))     then val = Date.today
+        when ((val.to_s == 'now') && (type == DateTime)) then val = DateTime.now
         when (type == Date)     then val = Date.parse(val)     rescue nil
         when (type == DateTime) then val = DateTime.parse(val) rescue nil
-        when (type == Time)     then
-          require 'time'
-          val = Time.parse(val) rescue nil
-        when (type == Symbol)   then val = val.to_s.to_sym rescue nil
+        else # nothing
         end
         self[param] = val
       end
@@ -142,6 +132,28 @@ module Configliere
       raise "Missing values for #{missing.map{|s| s.to_s }.sort.join(", ")}" if (! missing.empty?)
     end
 
+    # all params with a value for the definable aspect
+    #
+    # @param definable the aspect to list (:description, :type, :encrypted, etc.)
+    def params_with defineable
+      param_definitions.keys.find_all{|param| param_definitions[param][defineable] } || []
+    end
+
+    # all params without a value for the definable aspect
+    #
+    # @param definable the aspect to reject (:description, :type, :encrypted, etc.)
+    def params_without defineable
+      param_definitions.keys.reject{|param| param_definitions[param].include?(defineable) } || []
+    end
+
+    def definitions_for defineable
+      hsh = {}
+      param_definitions.each do |param, defs|
+        hsh[param] = defs[defineable] if defs[defineable]
+      end
+      hsh
+    end
+  public
   end
 
   Param.class_eval do

data/lib/configliere/encrypted.rb

@@ -1,26 +1,10 @@
-Configliere.use :param_store, :define, :crypter
+Configliere.use :config_file, :define, :crypter
 
 module Configliere
   module EncryptedParam
     # The password used in encrypting params during serialization
     attr_accessor :encrypt_pass
 
-  protected
-
-    # @example
-    #   Settings.defaults :username=>"mysql_username", :password=>"mysql_password"
-    #   Settings.define :password, :encrypted => true
-    #   Settings.exportable
-    #     #=> {:username => 'mysql_username', :password=>"\345?r`\222\021"\210\312\331\256\356\351\037\367\326" }
-    def export
-      hsh = super()
-      encrypted_params.each do |param|
-        val = hsh.deep_delete(*dotted_to_deep_keys(param)) or next
-        hsh.deep_set( *(dotted_to_encrypted_keys(param) | [encrypted(val)]) )
-      end
-      hsh
-    end
-
     # decrypts any encrypted params
     # then calls the next step in the resolve! chain.
     def resolve!
@@ -38,6 +22,22 @@ module Configliere
       end
     end
 
+  protected
+
+    # @example
+    #   Settings.defaults :username=>"mysql_username", :password=>"mysql_password"
+    #   Settings.define :password, :encrypted => true
+    #   Settings.exportable
+    #     #=> {:username => 'mysql_username', :password=>"\345?r`\222\021"\210\312\331\256\356\351\037\367\326" }
+    def export
+      hsh = super()
+      encrypted_params.each do |param|
+        val = hsh.deep_delete(*dotted_to_deep_keys(param)) or next
+        hsh.deep_set( *(dotted_to_encrypted_keys(param) | [encrypted(val)]) )
+      end
+      hsh
+    end
+
     # if :encrypted_pass was set as a param, remove it from the hash and set it as an attribute
     def remove_and_adopt_encrypt_pass_param_if_any!
       @encrypt_pass = self.delete(:encrypt_pass) if self[:encrypt_pass]
@@ -61,12 +61,12 @@ module Configliere
     end
 
     def decrypted val
-      return val if val.to_s == ''
+      return val if val.blank?
       Configliere::Crypter.decrypt(val, encrypt_pass)
     end
 
-    def encrypted(val)
-      return if ( !val )
+    def encrypted val
+      return unless val
       Configliere::Crypter.encrypt(val, encrypt_pass)
     end
   end

data/lib/configliere/environment.rb

@@ -10,24 +10,25 @@ module Configliere
         case env
         when Hash
           env.each do |env, param|
-            adopt_environment_variable! env, param
+            adopt_environment_variable! env.to_s, param
           end
         else
           param = env.to_s.downcase.to_sym
-          adopt_environment_variable! env, param
+          adopt_environment_variable! env.to_s, param
         end
       end
     end
 
+    def params_from_environment
+      definitions_for(:environment)
+    end
+
+  protected
     def adopt_environment_variable! env, param
-      define param, :environment => env
+      param_definitions[param][:environment] ||= env
       val = ENV[env]
       self[param] = val if val
     end
-
-    def params_from_environment
-      definitions_for(:environment)
-    end
   end
 
   Param.class_eval do

data/lib/configliere/param.rb

@@ -75,7 +75,9 @@ module Configliere
     end
 
     def use *args
+      hsh = args.pop if args.last.is_a?(Hash)
       Configliere.use *args
+      defaults(hsh) unless hsh.nil?
     end
 
   protected

data/spec/configliere/{config_blocks_spec.rb → config_block_spec.rb}

@@ -1,7 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
-Configliere.use :config_blocks
+Configliere.use :config_block
 
-describe "Configliere::ConfigBlocks" do
+describe "Configliere::ConfigBlock" do
   before do
     @config = Configliere::Param.new :normal_param => 'normal'
   end
@@ -14,7 +14,7 @@ describe "Configliere::ConfigBlocks" do
       @config.resolve!
     end
     it 'resolves blocks last' do
-      Configliere.use :config_blocks, :define, :encrypted
+      Configliere.use :config_block, :define, :encrypted
       @config.should_receive(:resolve_types!).ordered
       @config.should_receive(:resolve_finally_blocks!).ordered
       @config.resolve!

data/spec/configliere/{param_store_spec.rb → config_file_spec.rb}

@@ -1,7 +1,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
-Configliere.use :param_store
+Configliere.use :config_file
 
-describe "Configliere::ParamStore" do
+describe "Configliere::ConfigFile" do
   before do
     @config = Configliere.new :my_param => 'val'
   end
@@ -40,7 +40,7 @@ describe "Configliere::ParamStore" do
   describe 'saves to a config file' do
     describe 'successfully' do
       it 'saves a symbol name to the default config file' do
-        Configliere::ParamStore.should_receive(:merge_into_yaml_file).
+        Configliere::ConfigFile.should_receive(:merge_into_yaml_file).
           with(Configliere::DEFAULT_CONFIG_FILE, :my_settings, { :my_param => 'val'})
         @config.save! :my_settings
       end
@@ -61,7 +61,7 @@ describe "Configliere::ParamStore" do
       mock_dump = 'mock_dump'
       YAML.should_receive(:dump).with({ :my_settings => { :my_param => 'new_val'}, :other_settings => { :that_param => 'other_val'}}).and_return(mock_dump)
       fake_file.should_receive(:<<).with(mock_dump)
-      Configliere::ParamStore.merge_into_yaml_file '/fake/path.yaml', :my_settings, :my_param => 'new_val'
+      Configliere::ConfigFile.merge_into_yaml_file '/fake/path.yaml', :my_settings, :my_param => 'new_val'
     end
   end
 

data/spec/configliere/define_spec.rb

@@ -46,24 +46,35 @@ describe "Configliere::Define" do
   require 'date'; require 'time'
   describe 'type coercion' do
     [
-      [:boolean, '0', false],  [:boolean, 0, false], [:boolean, '',  false], [:boolean, [], false], [:boolean, nil, nil],
+      [:boolean, '0', false],  [:boolean, 0, false], [:boolean, '',  false], [:boolean, [],     true], [:boolean, nil, nil],
       [:boolean, '1', true],   [:boolean, 1, true],  [:boolean, '5', true],  [:boolean, 'true', true],
       [Integer, '5', 5],       [Integer, 5,   5],    [Integer, nil, nil],    [Integer, '', nil],
       [Integer, '5', 5],       [Integer, 5,   5],    [Integer, nil, nil],    [Integer, '', nil],
       [Float,   '5.2', 5.2],   [Float,   5.2, 5.2],  [Float, nil, nil],      [Float, '', nil],
       [Symbol,   'foo', :foo], [Symbol, :foo, :foo], [Symbol, nil, nil],     [Symbol, '', nil],
-      [Date,    '1985-11-05',           Date.parse('1985-11-05')],               [Date, nil, nil], [Date, '', nil],
-      [DateTime, '1985-11-05 11:00:00', DateTime.parse('1985-11-05 11:00:00')],  [DateTime, nil, nil], [DateTime, '', nil],
-      [Time,     '1985-11-05 11:00:00', Time.parse('1985-11-05 11:00:00')],      [Time, nil, nil], [Time, '', nil],
+      [Date,     '1985-11-05',           Date.parse('1985-11-05')],               [Date, nil, nil],     [Date, '', nil],     [Date, 'blah', nil],
+      [DateTime, '1985-11-05 11:00:00', DateTime.parse('1985-11-05 11:00:00')],  [DateTime, nil, nil], [DateTime, '', nil], [DateTime, 'blah', nil],
+      [Array,  ['this', 'that', 'thother'], ['this', 'that', 'thother']],
+      [Array,  'this,that,thother',         ['this', 'that', 'thother']],
+      [Array,  'alone',                     ['alone'] ],
+      [Array,  '',                          []        ],
+      [Array,  nil,                         nil       ],
     ].each do |type, orig, desired|
       it "for #{type} converts #{orig.inspect} to #{desired.inspect}" do
         @config.define :param, :type => type
         @config[:param] = orig ; @config.resolve! ; @config[:param].should == desired
       end
     end
+    it 'converts :now to the current moment' do
+      @config.define :param, :type => DateTime
+      @config[:param] = 'now' ; @config.resolve! ; @config[:param].should be_close(DateTime.now, 4)
+      @config[:param] = :now  ; @config.resolve! ; @config[:param].should be_close(DateTime.now, 4)
+      @config.define :param, :type => Date
+      @config[:param] = :now  ; @config.resolve! ; @config[:param].should be_close(Date.today, 4)
+      @config[:param] = 'now' ; @config.resolve! ; @config[:param].should be_close(Date.today, 4)
+    end
   end
 
-
   describe 'defining requireds' do
     before do
       @config.define :param_1, :required => true
@@ -76,20 +87,19 @@ describe "Configliere::Define" do
       @config.required_params.should include(:param_2)
     end
     it 'counts false values as required' do
-      p [@config]
       @config.defaults :param_1 => true, :param_2 => false
       @config.validate!.should == true
     end
     it 'counts nil-but-set values as missing' do
       @config.defaults :param_1 => true, :param_2 => nil
-      lambda{ @config.validate! }.should raise_error "Missing values for param_2"
+      lambda{ @config.validate! }.should raise_error("Missing values for param_2")
     end
     it 'counts never-set values as missing' do
-      lambda{ @config.validate! }.should raise_error "Missing values for param_1, param_2"
+      lambda{ @config.validate! }.should raise_error("Missing values for param_1, param_2")
     end
     it 'lists all missing values when it raises' do
       Configliere.use :define
-      lambda{ p @config.validate! }.should raise_error "Missing values for param_1, param_2"
+      lambda{ @config.validate! }.should raise_error("Missing values for param_1, param_2")
     end
   end
 end

data/spec/configliere/encrypted_spec.rb

@@ -54,7 +54,7 @@ describe "Configliere::Encrypted" do
     end
     it 'encrypts' do
       Configliere::Crypter.should_receive(:encrypt).and_return(@encrypted_str)
-      Configliere::ParamStore.should_receive(:write_yaml_file).with('/fake/file', :normal_param=>"normal", :encrypted_secret => @encrypted_str)
+      Configliere::ConfigFile.should_receive(:write_yaml_file).with('/fake/file', :normal_param=>"normal", :encrypted_secret => @encrypted_str)
       @config.save! '/fake/file'
     end
     it 'decrypts' do

data/spec/configliere/param_spec.rb

@@ -35,7 +35,8 @@ describe "Configliere::Param" do
       @config['moon.cheese.smell'].should be_nil
       @config['moon.non.existent.interim.values'].should be_nil
       @config['moon.non'].should be_nil
-      lambda{ @config['hat.cat'] }.should raise_error(NoMethodError, 'undefined method `[]\' for :cat:Symbol')
+      if (RUBY_VERSION >= '1.9') then lambda{ @config['hat.cat'] }.should raise_error(TypeError)
+      else                            lambda{ @config['hat.cat'] }.should raise_error(NoMethodError, 'undefined method `[]\' for :cat:Symbol') end
       @config.should == hsh # shouldn't change from reading
     end
   end

data/spec/spec_helper.rb

@@ -1,9 +1,6 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
-require 'tempfile'
-# module Configliere ; DEFAULT_FILE = Tempfile.new("configliere_spec-") ;DEFAULT_FILE.close(false) ; DEFAULT_CONFIG_FILE = DEFAULT_FILE.path ; end
-
 require 'configliere'
 require 'spec'
 require 'spec/autorun'
@@ -11,6 +8,3 @@ require 'spec/autorun'
 Spec::Runner.configure do |config|
 
 end
-
-# Configliere::DEFAULT_FILE.close!
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configliere
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - mrflip
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-06 00:00:00 -06:00
+date: 2010-01-08 00:00:00 -06:00
 default_executable: configliere
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,49 +32,8 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-- !ruby/object:Gem::Dependency 
-  name: highline
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
-- !ruby/object:Gem::Dependency 
-  name: yaml
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
-- !ruby/object:Gem::Dependency 
-  name: openssl
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
 description: " 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.\n\n   \"\" So, Consigliere of mine, I think you should tell your Don what everyone knows. \"\" -- Don Corleone\n\n\
-  Configliere's wise counsel takes care of these problems. Design goals:\n\n\
-  * *Don't go outside the family*. Requires almost no external resources and almost no code in your script.\n\
-  * *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.\n\
-  * *Be willing to sit down with the Five Families*. Takes settings from (at your option):\n\
-  ** Pre-defined defaults from constants\n\
-  ** Simple config files\n\
-  ** Environment variables\n\
-  ** Commandline options\n\
-  ** Ruby block called when all other options are in place\n\
-  * *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.\n\
-  * *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.\n\n\
-  fuhgeddaboudit.\n"
+  Configliere manage 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.\n"
 email: flip@infochimps.org
 executables: 
 - configliere
@@ -101,23 +60,24 @@ files:
 - lib/configliere/commandline.rb
 - lib/configliere/commandline/commands.rb
 - lib/configliere/commandline/options.rb
-- lib/configliere/config_blocks.rb
+- lib/configliere/config_block.rb
+- lib/configliere/config_file.rb
 - lib/configliere/core_ext.rb
+- lib/configliere/core_ext/blank.rb
 - lib/configliere/core_ext/hash.rb
 - lib/configliere/crypter.rb
 - lib/configliere/define.rb
 - lib/configliere/encrypted.rb
 - lib/configliere/environment.rb
 - lib/configliere/param.rb
-- lib/configliere/param_store.rb
 - spec/configliere/commandline_spec.rb
-- spec/configliere/config_blocks_spec.rb
+- spec/configliere/config_block_spec.rb
+- spec/configliere/config_file_spec.rb
 - spec/configliere/crypter_spec.rb
 - spec/configliere/define_spec.rb
 - spec/configliere/encrypted_spec.rb
 - spec/configliere/environment_spec.rb
 - spec/configliere/param_spec.rb
-- spec/configliere/param_store_spec.rb
 - spec/configliere_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -151,13 +111,13 @@ specification_version: 3
 summary: Wise, discreet configuration management
 test_files: 
 - spec/configliere/commandline_spec.rb
-- spec/configliere/config_blocks_spec.rb
+- spec/configliere/config_block_spec.rb
+- spec/configliere/config_file_spec.rb
 - spec/configliere/crypter_spec.rb
 - spec/configliere/define_spec.rb
 - spec/configliere/encrypted_spec.rb
 - spec/configliere/environment_spec.rb
 - spec/configliere/param_spec.rb
-- spec/configliere/param_store_spec.rb
 - spec/configliere_spec.rb
 - spec/spec_helper.rb
 - examples/commandline_script.rb