configliere 0.0.1

data/.document

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

data/.gitignore

@@ -0,0 +1,38 @@
+## OS
+.DS_Store
+Icon?
+nohup.out
+
+## EDITORS
+*.tmproj
+tmtags
+*~
+\#*
+.\#*
+*.swp
+REVISION
+TAGS*
+*_flymake.*
+.project
+.settings
+
+## COMPILED
+a.out
+*.o
+*.pyc
+*.so
+
+## OTHER SCM
+.bzr
+.hg
+.svn
+
+## PROJECT::GENERAL
+coverage
+rdoc
+doc
+pkg
+.yardoc
+*private*
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 mrflip
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,196 @@
+h1. Configliere
+
+Configliere provides wise, lightweight configuration management for ruby programs.
+
+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 is a no-fuss library for flexibly managing your configuration settings. 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.
+
+h2. Settings structure
+
+Configliere settings are just a plain old normal hash. 
+
+You can define static defaults in your module
+
+    Settings.defaults({
+      :dest_time => '1955-11-05',
+      :fluxcapacitor => {
+        :speed => 88,
+        },
+      :delorean => {
+        :power_source => 'plutonium',
+        :roads_needed => true,
+        },
+      :username => 'marty',
+      :password => '',
+    })
+    
+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 
+    Configliere.use :all                  # all of them
+
+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)
+
+    # Settings for version II.
+    :time_machine:
+      :dest_time:        2015-11-05
+      :delorean:
+        :power_source:    Mr. Fusion
+        :roads_needed:    ~
+
+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.
+
+    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
+
+When you read directly from a file you should leave off the top-level settings group:
+    
+    # Settings for version II.
+    :dest_time:         2015-11-05
+    :delorean:
+      :power_source:    Mr. Fusion
+      :roads_needed:    ~
+
+You can save defaults with
+
+    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
+    
+h2. Environment Variables
+
+    Settings.use_environment 'DEST_TIME', 'TM_PASS' => 'password', 'POWER_SOURCE' => 'delorean.power_source'
+
+As usual, dotted keys set the corresponeding nested key ('delorean.power_source' sets Config[:delorean][:power_source])
+
+h2. Command-line parameters
+
+    # 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
+
+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. 
+* *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. 
+* *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.
+
+h2. Fancy Parameters
+
+You don't have to pre-define parameters, but you can:
+
+    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
+
+* *: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.
+
+h3. Required Parameters
+
+Any required parameter found to be nil raises an error (listing all missing params). (Make sure to call Settings.resolve! in your script.)
+
+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
+
+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.
+
+h2. Ruby Block
+
+    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
+    #
+    Settings.resolve!    # the finally blocks will be called in order
+
+Configliere 'finally' blocks are called after everything but required parameter    
+
+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. 
+
+    module MyProject
+      cattr_accessor :config
+      self.config = Configliere.new({
+        :helicity => 'homotopic',
+        :froebenius_matrix => 'unitary',
+        })
+    end
+    pr = proj.new
+    pr.config   #=> {:helicity => 'homotopic', :froebenius_matrix => 'unitary' }
+
+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.
+
+h2. Project info
+
+h3. Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send a pull request to github.com/mrflip
+* Drop a line to the mailing list for infochimps open-source projects, infochimps-code@googlegroups.com
+
+h3. Copyright
+
+Copyright (c) 2010 mrflip. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,91 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "configliere"
+    gem.summary = %Q{Wise, discreet configuration management}
+    gem.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.
+} #'
+    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 is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+begin
+  require 'reek/adapters/rake_task'
+  Reek::RakeTask.new do |t|
+    t.fail_on_error = true
+    t.verbose = false
+    t.source_files = 'lib/**/*.rb'
+  end
+rescue LoadError
+  task :reek do
+    abort "Reek is not available. In order to run reek, you must: sudo gem install reek"
+  end
+end
+
+begin
+  require 'roodi'
+  require 'roodi_task'
+  RoodiTask.new do |t|
+    t.verbose = false
+  end
+rescue LoadError
+  task :roodi do
+    abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
+  end
+end
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/bin/configliere

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+require 'rubygems' ; $: << File.dirname(__FILE__)+'/../lib'
+require 'configliere'
+require 'configliere/client'
+require 'configliere/client/commands'
+Log = Logger.new(STDERR) unless defined?(Log)
+
+class ConfigliereScript < Configliere::CommandClient
+  def usage
+    %Q{Client for the configliere gem: manipulate configuration and passwords for automated scripts
+
+usage: #{File.basename($0)} command handle [...--option=val...]
+where
+  command:             One of: #{COMMANDS.keys[0..-2].join(', ')} or #{COMMANDS.keys.last}
+  handle:              Name of the configliere group (within the configliere_file) or path to a configliere YAML file.
+
+Configuration taken from #{configliere_file} by default.}
+    end
+
+  def process_options! *args
+    super *args
+    self.command = options[:_rest].shift.to_sym rescue nil
+    self.handle  = options[:_rest].shift.to_sym rescue nil
+  end
+
+
+    # ===========================================================================
+    #
+    # Commands
+    #
+
+    COMMANDS[:fix] = "encrypt the param"
+    def fix
+      Log.info "Fixing stored info for #{handle}"
+      store.fix!(handle, option_or_ask(:key))
+    end
+    COMMANDS[:encrypt] = "synonym for fix. Params are stored encrypted by default"
+    def encrypt() fix end
+
+    COMMANDS[:decrypt] = "Store the param as decrypted back into the file. Can be undone with 'fix'."
+    def decrypt
+      Log.info "Storing info for #{handle} in **DECRYPTED** form."
+      param = get(handle)
+      store.put_decrypted!(handle, param)
+    end
+
+    COMMANDS[:list] = "Show all params in the configliere file."
+    def list
+      puts "List of param names: #{store.handles.inspect}"
+    end
+
+    COMMANDS[:delete] = "Permanently deletes the param"
+    def delete
+      Log.info "Permanently deleting stored info for #{handle}. O, I die, Horatio."
+      store.delete! handle, options[:key]
+    end
+
+    COMMANDS[:set] = "sets values using remaining arguments from the command line. eg #{File.basename($0)} set my_program --username=bob --password=frank"
+    def set
+      param = get(handle)
+      param.merge! external_options
+      store.put handle, param
+      store.save!
+      Log.info "Stored configuration for #{handle}: #{param}"
+    end
+
+    COMMANDS[:change_key] = "set a new key and/or new key options. Specify the old key as usual with --key='...' and the new one with --new_key='...'"
+    def change_key
+      param = get(handle)
+      new_key = option_or_ask(:new_key)
+      new_hsh = param.to_decrypted
+      new_param = Configliere::Param.new(new_key, new_hsh)
+      store.put! handle, new_param
+      Log.info "Changed param key for #{handle}: #{new_param}"
+    end
+
+    COMMANDS[:show] = "print the decrypted information"
+    def show
+      param = get(handle)
+      puts "Stored info for #{handle}:\n  #{param.to_s}"
+    end
+
+end
+
+ConfigliereScript.new.run

data/configliere.gemspec

@@ -0,0 +1,123 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{configliere}
+  s.version = "0.0.1"
+
+  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.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.
+}
+  s.email = %q{flip@infochimps.org}
+  s.executables = ["configliere"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "bin/configliere",
+     "configliere.gemspec",
+     "examples/commandline_script.rb",
+     "examples/commandline_script.yaml",
+     "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_blocks.rb",
+     "lib/configliere/core_ext.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/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"
+  ]
+  s.homepage = %q{http://github.com/mrflip/configliere}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Wise, discreet configuration management}
+  s.test_files = [
+    "spec/configliere/commandline_spec.rb",
+     "spec/configliere/config_blocks_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",
+     "examples/simple_script.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    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
+