configliere 0.0.2 → 0.0.3

data/.document

@@ -1,6 +1,4 @@
-README.rdoc
+README.textile
 lib/**/*.rb
 bin/*
-features/**/*.feature
 LICENSE
-examples/*.rb

data/CHANGELOG.textile

@@ -0,0 +1,19 @@
+Note that while the version # is still in the 0.0.x range, the interface may change arbitrarily while we figure out the best simplest convenientest powerfullest way to arrange things
+
+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
+    Settings.define :happy_param, :default => 'yay'
+    Settings.happy_param
+    #=> "yay" 
+</pre>
+
+* Note that you *must* use symbols as keys (except for dotted notation for deep keys). See the README.
+* You must now call @#use_environment@ as @Settings.use_environment :param => 'ENV_VAR'@. (The param is used as the key everywhere else, made this consistent).
+* die takes an error code as option
+* Added example scripts for encrypted and config_block scripts
+* The directory path to a config_file will now be created automatically

data/README.textile

@@ -1,12 +1,12 @@
 h1. Configliere
 
-Configliere provides wise, lightweight configuration management for ruby programs.
+Configliere provides discreet configuration for ruby scripts.
 
 bq. So, Consigliere of mine, I think you should tell your Don what everyone knows. -- Don Corleone
 
 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 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.
+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.
 
 h3. Example
 
@@ -18,7 +18,7 @@ Here's a simple example, using params from a config file and the command line. A
     :sprats:
       :jack:  lean</pre>
 
-A simple script:
+(Note that all simple keys should be symbols, with an exception described below.) A simple script:
 
 <pre>
     #/usr/bin/env ruby
@@ -26,7 +26,7 @@ A simple script:
     
     Settings.use(:commandline, :config_file, 
       :dish => 'spoon', :cow => 'moon')
-    Settings.read 'my_script.yaml'
+    Settings.read 'my_script.yaml'  # reads ~/.configliere/my_script.yaml
     Settings.resolve!
 
     p Settings</pre>
@@ -37,6 +37,8 @@ Output:
     ./simple_script.rb --sprats.wife=fat --spider=drainspout
     {:spider=>"drainspout", :cat=>"hat", :sprats=>{:wife=>"fat", :jack=>"lean"}, :cow=>"moon"}  </pre>
 
+For an extensive usage in production, see the "wukong gem.":http://github.com/mrflip/wukong
+
 h3. Design goals:
 
 * *Don't go outside the family*. Requires almost no external resources and almost no code in your script.
@@ -77,19 +79,49 @@ Retrieve them as:
 
 <pre>
     # hash keys       
-    Config[:dest_time]                 #=> '1955-11-05'
+    Settings[:dest_time]                 #=> '1955-11-05'
     # deep keys
-    Config[:delorean][:power_source]   #=> 'plutonium'
-    Config[:delorean][:missing]        #=> nil
-    Config[:delorean][:missing][:fail] #=> raises an error
+    Settings[:delorean][:power_source]   #=> 'plutonium'
+    Settings[:delorean][:missing]        #=> nil
+    Settings[: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
+    Settings['delorean.power_source']    #=> 'plutonium'
+    Settings['delorean.missing']         #=> nil
+    Settings['delorean.missing.fail']    #=> nil
     # method-like (no deep keys tho)
     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>
@@ -128,7 +160,7 @@ When you read directly from a file you should leave off the top-level settings g
       :roads_needed:    ~
 </pre>
 
-You can save defaults with
+Save defaults by inserting a line like:
 
 <pre>
     Settings.save(:time_machine)            # merges into ~/.configliere.yaml, under :time_machine
@@ -139,10 +171,12 @@ You can save defaults with
 h2. Environment Variables
 
 <pre>
-    Settings.use_environment 'DEST_TIME', 'TM_PASS' => 'password', 'POWER_SOURCE' => 'delorean.power_source'
+    Settings.use_environment 'DEST_TIME', :password => 'TM_PASS', 'delorean.power_source' => 'POWER_SOURCE'
 </pre>
 
-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.
+As usual, dotted keys set the corresponeding nested key (@'delorean.power_source'@ sets @Settings[:delorean][:power_source]@). You can alternatively set up environment variables with @define 'delorean.power_source', :environment => 'POWER_SOURCE'@ - see below.
+
+**NOTE**: The interface to #use_environment has changed since v0.2. You must now call it as @Settings.use_environment :param => 'ENV_VAR'@, (since everywhere else the param is used as the key).
 
 h2. Command-line parameters
 
@@ -155,7 +189,7 @@ h2. Command-line parameters
 
 Interpretation of command-line parameters:
 * *name-val params*: @--param=val@ sets @Configliere[:param]@ to val.
-* *boolean params*: @--param@ sets @Configliere[:param]@ to be true. --param='' sets @Configliere[:param]@ to be nil. 
+* *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. 

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/configliere.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{configliere}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["mrflip"]
-  s.date = %q{2010-01-08}
+  s.date = %q{2010-01-15}
   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.
 
@@ -26,6 +26,7 @@ Configliere manage settings from many sources: static constants, simple config f
   s.files = [
     ".document",
      ".gitignore",
+     "CHANGELOG.textile",
      "LICENSE",
      "README.textile",
      "Rakefile",
@@ -34,18 +35,19 @@ Configliere manage settings from many sources: static constants, simple config f
      "configliere.gemspec",
      "examples/commandline_script.rb",
      "examples/commandline_script.yaml",
+     "examples/config_block.rb",
+     "examples/encrypted_script.rb",
      "examples/foo.yaml",
      "examples/simple_script.rb",
      "examples/simple_script.yaml",
      "lib/configliere.rb",
      "lib/configliere/commandline.rb",
-     "lib/configliere/commandline/commands.rb",
-     "lib/configliere/commandline/options.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/core_ext/sash.rb",
      "lib/configliere/crypter.rb",
      "lib/configliere/define.rb",
      "lib/configliere/encrypted.rb",
@@ -54,6 +56,8 @@ Configliere manage settings from many sources: static constants, simple config f
      "spec/configliere/commandline_spec.rb",
      "spec/configliere/config_block_spec.rb",
      "spec/configliere/config_file_spec.rb",
+     "spec/configliere/core_ext/hash_spec.rb",
+     "spec/configliere/core_ext/sash_spec.rb",
      "spec/configliere/crypter_spec.rb",
      "spec/configliere/define_spec.rb",
      "spec/configliere/encrypted_spec.rb",
@@ -72,6 +76,8 @@ Configliere manage settings from many sources: static constants, simple config f
     "spec/configliere/commandline_spec.rb",
      "spec/configliere/config_block_spec.rb",
      "spec/configliere/config_file_spec.rb",
+     "spec/configliere/core_ext/hash_spec.rb",
+     "spec/configliere/core_ext/sash_spec.rb",
      "spec/configliere/crypter_spec.rb",
      "spec/configliere/define_spec.rb",
      "spec/configliere/encrypted_spec.rb",
@@ -80,6 +86,8 @@ Configliere manage settings from many sources: static constants, simple config f
      "spec/configliere_spec.rb",
      "spec/spec_helper.rb",
      "examples/commandline_script.rb",
+     "examples/config_block.rb",
+     "examples/encrypted_script.rb",
      "examples/simple_script.rb"
   ]
 

data/examples/config_block.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require 'configliere'
+
+Settings :passenger => 'einstein', :dest_time => '1955-11-05', 'delorean.power_source' => :plutonium
+Settings.finally do |c|
+  p [self, 'finally', c[:passenger], c.passenger]
+  # Einstein the dog should only be sent one minute into the future.
+  dest_time = (Time.now + 60) if c.passenger == 'einstein'
+end
+Settings.resolve!
+p Settings

data/examples/encrypted_script.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+require 'configliere'
+
+DUMP_FILENAME = '/tmp/encrypted_script.yml'
+Settings.use :config_file, :define, :encrypt_pass => 'password1'
+Settings.define :password, :encrypted => true
+
+Settings :password => 'plaintext'
+Settings.resolve!
+p ["saved version will have encrypted password (see #{DUMP_FILENAME}).", Settings.send(:export)]
+p ['live version still has password in plaintext', Settings]
+Settings.save!(DUMP_FILENAME)
+
+Settings[:password] = 'before read'
+Settings.read('/tmp/encrypted_script.yml')
+Settings.resolve!
+p ["value is decrypted on resolve.", Settings]

data/lib/configliere/commandline.rb

@@ -7,6 +7,14 @@ module Configliere
   module Commandline
     attr_accessor :rest
 
+    # Processing to reconcile all options
+    #
+    # Configliere::Commandline's resolve!:
+    # * processes all commandline params
+    # * if the --help param was given, prints out a usage statement (using
+    #   any +:description+ set with #define) and then exits
+    # * lastly, calls the next method in the resolve! chain.
+    #
     def resolve!
       process_argv!
       dump_help_if_requested
@@ -34,9 +42,10 @@ module Configliere
           break
         when arg =~ /\A--([\w\-\.]+)(?:=(.*))?\z/
           param, val = [$1, $2]
-          param.gsub!(/\-/, '.')
-          if    val == nil then val = true     # --flag    option on its own means 'set that option'
-          elsif val == ''  then val = nil  end # --flag='' the explicit empty string means nil
+          param.gsub!(/\-/, '.')                        # translate --scoped-flag to --scoped.flag
+          param = param.to_sym unless (param =~ /\./)   # symbolize non-scoped keys
+          if    val == nil then val = true              # --flag    option on its own means 'set that option'
+          elsif val == ''  then val = nil end           # --flag='' the explicit empty string means nil
           self[param] = val
         else
           self.rest << arg
@@ -59,10 +68,13 @@ module Configliere
     end
 
     # die with a warning
-    def die str
+    #
+    # @param str [String] the string to dump out before exiting
+    # @param exit_code [Integer] UNIX exit code to set, default -1
+    def die str, exit_code=-1
       puts help
       warn "\n****\n#{str}\n****"
-      exit -1
+      exit exit_code
     end
 
     # Retrieve the given param, or prompt for it
@@ -80,6 +92,11 @@ module Configliere
       help_str.join("\n")
     end
 
+    def dump_help extra_msg=nil
+      $stderr.puts help
+      $stderr.puts "\n\n"+extra_msg unless extra_msg.blank?
+    end
+
     # Usage line
     def usage
       %Q{usage: #{File.basename($0)} [...--param=val...]}
@@ -90,7 +107,7 @@ module Configliere
     # Ouput the help string if requested
     def dump_help_if_requested
       return unless self[:help]
-      $stderr.puts help
+      dump_help
       exit
     end
   end

data/lib/configliere/config_block.rb

@@ -1,25 +1,36 @@
 Configliere.use :define
 module Configliere
+  #
+  # ConfigBlock lets you use pure ruby to change and define settings.  Call
+  # +#finally+ with a block of code to be run after all other settings are in
+  # place.
+  #
+  #     Settings.finally{|c| c.your_mom[:college] = 'went' unless (! c.mom_jokes_allowed) }
+  #
   module ConfigBlock
-    # Config blocks to be executed at end of resolution (just before validation)
-    attr_accessor :final_blocks
-    def final_blocks
-      @final_blocks ||= []
-    end
-
-    # @param param the setting to describe. Either a simple symbol or a dotted param string.
-    # @param definitions the defineables to set (:description, :type, :encrypted, etc.)
+    #
+    # @param &block each +finally+ block is called once, in the order it was
+    #   defined, when the resolve! method is invoked. +config_block+ resolution
+    #   is guaranteed to run last in the resolve chain, right before validation.
     #
     # @example
-    #   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.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
+    #   # ...
+    #   # after rest of setup:
+    #   Settings.resolve!
     #
     def finally &block
       self.final_blocks << block
     end
 
-    # calls superclass resolution
+    # Processing to reconcile all options
+    #
+    # The resolve! for config_block is made to run last of all in the +resolve!+
+    # chain, and runs each +finally+ block in the order it was defined.
     def resolve!
       begin ; super() ; rescue NoMethodError ; nil ; end
       resolve_finally_blocks!
@@ -27,12 +38,17 @@ module Configliere
     end
 
   protected
+    # Config blocks to be executed at end of resolution (just before validation)
+    attr_accessor :final_blocks
+    def final_blocks
+      @final_blocks ||= []
+    end
+    # call each +finally+ config block in the order it was defined
     def resolve_finally_blocks!
       final_blocks.each do |block|
         block.call(self)
       end
     end
-
   end
 
   Param.class_eval do

data/lib/configliere/config_file.rb

@@ -1,4 +1,5 @@
 require 'yaml'
+require 'fileutils'
 module Configliere
   #
   # ConfigFile -- load configuration from a simple YAML file
@@ -36,10 +37,11 @@ module Configliere
     # form suitable for serialization to disk
     # (e.g. the encryption done in configliere/encrypted)
     def export
-      to_hash
+      super.to_hash
     end
 
     def self.write_yaml_file filename, hsh
+      FileUtils.mkdir_p(File.dirname(filename))
       File.open(filename, 'w'){|f| f << YAML.dump(hsh) }
     end
 

data/lib/configliere/core_ext/hash.rb

@@ -33,7 +33,8 @@ class Hash
   end
 
   def deep_merge! hsh2
-    merge! hsh2, &Hash::DEEP_MERGER
+    update hsh2, &Hash::DEEP_MERGER
+    self
   end
 
   #
@@ -50,7 +51,8 @@ class Hash
     val      = args.pop
     last_key = args.pop
     # dig down to last subtree (building out if necessary)
-    hsh = args.empty? ? self : args.inject(self){|hsh, key| hsh[key] ||= {} }
+    hsh = self
+    args.each{|key| hsh = (hsh[key] ||= self.class.new) }
     # set leaf value
     hsh[last_key] = val
   end

data/lib/configliere/core_ext/sash.rb

@@ -0,0 +1,169 @@
+require 'configliere/core_ext/hash'
+
+#
+# Hash with indifferent access
+#
+# Adapted from extlib/lib/mash.rb
+#
+class Sash < ::Hash
+
+  # @param constructor<Object>
+  #   The default value for the mash. Defaults to an empty hash.
+  #
+  # @details [Alternatives]
+  #   If constructor is a Hash, a new mash will be created based on the keys of
+  #   the hash and no default value will be set.
+  def initialize(constructor = {})
+    if constructor.is_a?(Hash)
+      super()
+      update(constructor) unless constructor.empty?
+    else
+      super(constructor)
+    end
+  end 
+
+  alias_method :regular_writer, :[]=    unless method_defined?(:regular_writer)
+  alias_method :regular_update, :update unless method_defined?(:regular_update)
+
+  # @param key<Object> The key to set.
+  # @param value<Object>
+  #   The value to set the key to.
+  #
+  # @see Mash#convert_key
+  # @see Mash#convert_value
+  def []=(key, value)
+    regular_writer(convert_key(key), convert_value(value))
+  end
+
+  alias_method :merge!, :update
+
+  # @param key<Object> The key to check for. This will be run through convert_key.
+  #
+  # @return [Boolean] True if the key exists in the mash.
+  def key?(key)
+    super(convert_key(key))
+  end
+
+  # def include? def has_key? def member?
+  alias_method :include?, :key?
+  alias_method :has_key?, :key?
+  alias_method :member?,  :key?
+
+  # @param key<Object> The key to fetch. This will be run through convert_key.
+  # @param *extras<Array> Default value.
+  #
+  # @return [Object] The value at key or the default value.
+  def fetch(key, *extras)
+    super(convert_key(key), *extras)
+  end
+
+  # @param *indices<Array>
+  #   The keys to retrieve values for. These will be run through +convert_key+.
+  #
+  # @return [Array] The values at each of the provided keys
+  def values_at(*indices)
+    indices.collect{|key| self[convert_key(key)]}
+  end
+
+  # @param hash<Hash> The hash to merge with the mash.
+  #
+  # @return [Mash] A new mash with the hash values merged in.
+  def merge(hash, &block)
+    self.dup.update(hash, &block)
+  end
+
+  # @param key<Object>
+  #   The key to delete from the mash.\
+  def delete(key)
+    super(convert_key(key))
+  end
+
+  # @return [Hash] The mash as a Hash with string keys.
+  def to_hash
+    Hash.new(default).merge(self)
+  end
+
+  # @param key<Object> The default value for the mash. Defaults to nil.
+  #
+  # @details [Alternatives]
+  #   If key is a Symbol and it is a key in the mash, then the default value will
+  #   be set to the value matching the key.
+  def default(key = nil)
+    if key.is_a?(String) && include?(key = key.to_sym)
+      self[key]
+    else
+      super(key)
+    end
+  end
+
+  # @param other_hash<Hash>
+  #   A hash to update values in the mash with. The keys and the values will be
+  #   converted to Mash format.
+  #
+  # @return [Mash] The updated mash.
+  def update(other_hash, &block)
+    sash = self.class.new
+    other_hash.each_pair do |key, value|
+      val = convert_value(value)
+      sash[convert_key(key)] = val
+    end
+    regular_update(sash, &block)
+  end
+
+  # Used to provide the same interface as Hash.
+  #
+  # @return [Sash] This sash unchanged.
+  def symbolize_keys!; self end
+
+  # @return [Hash] The sash as a Hash with stringified keys.
+  def stringify_keys
+    h = Hash.new(default)
+    each { |key, val| h[key.to_sym] = val }
+    h
+  end
+
+protected
+  # @param key<Object> The key to convert.
+  #
+  # @param [Object]
+  #   The converted key. If the key was a string, it will be converted to a
+  #   symbol.
+  #
+  # @api private
+  def convert_key(key)
+    key.is_a?(String) ? key.to_sym : key
+  end
+
+  # @param value<Object> The value to convert.
+  #
+  # @return [Object]
+  #   The converted value. A Hash or an Array of hashes, will be converted to
+  #   their Mash equivalents.
+  #
+  # @api private
+  def convert_value(value)
+    if value.class == Hash
+      value.to_sash
+    elsif value.is_a?(Array)
+      value.collect { |e| convert_value(e) }
+    else
+      value
+    end
+  end
+end
+
+
+class ::Hash
+
+  # Convert to Sash. This class has semantics of ActiveSupport's
+  # HashWithIndifferentAccess and we only have it so that people can write
+  # params[:key] instead of params['key'].
+  #
+  # @return [Mash] This hash as a Mash for string or symbol key access.
+  def to_sash
+    hash = Sash.new(self)
+    hash.default = default
+    hash
+  end
+  
+end