flexconf 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format nested

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in flexconf.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,116 @@
+The Don't Be a Dick License
+===========================
+_version 0.3_
+
+**Project:** [FlexConf][3] (Ruby gem)
+**Author:**  Stephen Eley (<sfeley@gmail.com>)
+
+This is a proposed draft of the **Don't Be a Dick** license for open source projects.  The purpose of this license is to permit the broadest feasible scope for reuse and modification of creative work, restricted only by the requirement that one is not a dick about it.
+
+>  **NOTE:** Despite its original gender association, the word "Dick" is used herein in a _cultural_ context and not a _genital_ context.  This License has chosen to adopt the term for its linguistic force and psychological impact, and sincerely regrets any inference of sexism.  For purposes of the terms and conditions contained herein, it is understood that both men and women are equally capable of being Dicks.  
+
+>  (But they shouldn't be.)  
+
+
+1. Legal Parameters
+-------------------
+For legal purposes, the DBAD license is a strict superset of the [Apache License, Version 2.0][1] and incorporates all terms, conditions, privileges and limitations therein.  The following text is a binding part of this license for this project:
+
+> Copyright 2011 Stephen Eley
+
+> Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+>   <http://www.apache.org/licenses/LICENSE-2.0>
+
+> Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+Nothing in the following text should be construed to inhibit, contradict, or override any part of the Apache License, Version 2.0.  
+
+2. Definitions
+--------------
+The following terms and definitions shall be in effect for the rest of this document.
+
+>  **NOTE:** Singular nouns and pronouns are used throughout this License for 
+  grammatical convenience.  However, any of the terms below _may_ refer to a
+  collective work or group of people.  If this pegs your punctiliousness, you
+  are directed to mentally substitute "Person _or persons,_" "Dick _or 
+  dicks,_" etc., throughout this license.  Just don't harass us about it.
+
+### A. Project
+
+A creative work of (software | writing | visual art | music) into which significant time and energy have been invested by people who _are not you,_ and which has been released into the world for the benefit of the general public (_including you._)
+
+The **Project** may include, incorporate, derive from, or be inspired by other works.  The Author, being a Reasonable Person, has made use of such source materials only as permitted by their own licenses or applicable law.  The License you are reading applies only to those portions of the Project which are original and distinct to it.  Source materials may be covered by their own licenses or conditions, and should not be assumed to have coverage under this License.  (However, you are strongly encouraged not to be a dick about them either.)
+
+### B. Author
+
+A person who has invested significant time and energy into the Project licensed herein.  Given the Author's release of the Project to the world under a liberal license, the Author is declared a Reasonable Person (at least within this context) and inherits all attributes, freedoms, and responsibilities thereof.  No other assumptions are made about the Author, nor should you make any.
+
+### C. Reasonable Person
+
+A person who respects the time and energy that have been invested in the Project licensed herein, and acts accordingly.  A Reasonable Person is broadly characterized as one who exercises his or her privilege to use, _not_ use, redistribute, modify, improve, worsen, review, report issues upon, participate in the community of, or ignore the work _without_ placing undue demands upon the Author.  I.e., a Reasonable Person is a constituent of the majority of open source users and the population at large who are not Dicks.
+
+### D. Dick
+
+A person who _does not_ respect the time and energy that have been invested in the Project, and acts to punish such effort by giving others associated with the Project -- including, but not limited to, the Author -- a hard time.  A Dick is nearly always selfish, but not necessarily with deliberate intent; some Dicks are merely thoughtless.  The distinguishing characteristic of a Dick is that he or she places burdens upon Reasonable People, reducing their motivation to engage in open source activities.  This damping effect is a significant detriment to the Project, to open source in general, to the production of new intellectual value in the world -- and, ultimately, to the Dick himself or herself.
+
+3. Permissions
+--------------
+
+The following privileges are granted explicitly and with positive encouragement to Reasonable People.  Although the Author acknowledges that Dicks cannot practically be barred from enjoying the same privileges, they are nevertheless asked to refrain from substantial public activity related to the Project _until_ they reconsider their behavior and stop being Dicks.
+
+1. You are permitted to use the Project or any component of the Project.
+
+2. You are permitted to redistribute the Project or any component of the Project, by itself or as part of a different work, provided that you give fair and reasonable credit back to the Author.
+
+3. You are permitted to change the Project for your own needs or anyone else's.  You may keep your changes to yourself or submit them back to the Author or the community, as you see fit, provided you are not a Dick about it.
+
+4. You are permitted and encouraged to participate in any community related to the Project, or to create new communities.
+
+5. You are permitted to report issues or problems with the Project, and to request that they be addressed, so long as the request is made in a reasonable fashion.  (This privilege does _not_ oblige the Author to respond.)
+
+6. You are permitted to make money from the Project.  No recompense is owed to the Author unless by separate agreement, although sharing opportunities for mutual benefit is by no means discouraged.
+
+7. You are permitted to discuss the Project in any medium, in positive or negative spirit, so long as criticism is not libelous, excessively emotional, nor _ad hominem._  (I.e.: don't lie, don't be vicious, and keep it about the _work_ and not the _people._)
+
+8. You are permitted to ignore the Project completely and make no use of it whatsoever.  This right is irrevocable and absolute, and extended to Dicks and Reasonable People alike.
+
+4. Limitations
+--------------
+
+The following restrictions are imposed upon all persons, but with active emphasis upon Dicks.  These limitations are the inverse of the above privileges and are also tautological, as the prohibited actions are those _definitive_ of Dickhood.
+
+1. You may not impede Reasonable People from exercising their privilege to use, redistribute, change, participate in, profit from, discuss, or ignore the Project.
+
+2. You may not withhold credit from the Author for the Project, nor otherwise present the work of anyone else as your own.
+
+3. You may not hold the Author responsible for any use or abuse of the Project by you or anyone else.
+
+4. You may not troll, flame, nor dumb down any community associated with the Project.
+
+5. Barring separate agreements, you may not _demand_ any time or attention on the part of the Author nor anyone else in the community.  You may not hold the Author personally accountable for any issues or damages you discover, nor otherwise spread your own problems to other people.
+
+6. You may not attempt to _compel_ time nor money from the Author nor any other community member by any means, including but not limited to legal action, intimidation, or annoyance.  
+
+7. You may not engage in deceptive, excessive, nor _ad hominem_ (i.e. personal) attacks in the course of criticizing the Project.
+
+8. You may not impede the absolute and irrevocable privilege of the Author and other members of the community to ignore you.  
+
+5. Use of This License
+----------------------
+The Don't Be a Dick License is released under the terms of the Don't Be a Dick License. Projects released under this License must remain under the License, and only the Author may modify the terms of this License as it relates to this particular Project.
+
+If you wish to make use of the License for your own open work, you may do so without asking permission, provided said work is truly your own, truly open, and you are truly not a Dick. You may modify the terms of the License to suit your own needs, but are encouraged to annotate said changes where they differ from the original.  Modifications should not reduce the freedoms granted to Reasonable People as described in Section 3.
+
+The 'official' Web site of the Don't Be a Dick License is at [dbad-license.org][2]. Reasonable People are _invited,_ but not compelled, to visit the site and browse or add to the repository of works released under the License.
+
+
+[1]: http://apache.org/licenses/LICENSE-2.0
+[2]: http://dbad-license.org
+[3]: http://github.com/SFEley/flexconf

data/README.md

@@ -0,0 +1,203 @@
+# FlexConf #
+
+FlexConf is a simple configuration utility that does its job and gets out of
+your way. It reads settings from a hash or YAML file (`config.yml` by default)
+with optional overrides from a `*_local.yml` file and from environment
+variables. Settings can be retrieved as indifferent hash values (config['foo']
+or config[:foo]) or method calls (config.foo).
+
+Simplicity and portability are major design goals. The code is a single
+lightweight class (roughly 100 lines of code) with no external gem
+dependencies. The spec suite passes in Ruby 1.8.7, 1.9.2, 1.9.3, and current
+(October 2011) versions of JRuby and Rubunius.
+
+## Installation ##
+
+Come on kids, you know this one:
+
+    gem install flexconf
+
+Or do what the sophisticated urbanite does and use Bundler:
+
+    # In your Gemfile:
+    gem 'flexconf'
+    
+## Loading From a Hash ##
+
+This is the simplest approach for small use cases.  Just create a Ruby file
+and declare your values:
+
+    require 'flexconf'
+    
+    CONFIG = FlexConf.new {
+      my_arbitrary_username: 'joeschmoe',   # Ruby 1.9 syntax
+      my_arbitrary_password: 'blah1234',
+      
+      :another_thing => 'here',             # Classic 'hashrocket' syntax
+      'some_number'  => 24,
+      
+      nested: {
+        'mommy_bird' => 'Tweet!',
+        'baby_bird'  => 'Facebook.'
+      }
+    }
+
+This usage mode has no options and no overrides.  If you need to calculate
+or merge anything, just do it before you create the FlexConf object.
+
+All keys are converted to symbols on creation, regardless of their original
+type. Yes, that means numbers and arrays and other crazy objects too. This is
+for _configuration data;_ we're not trying to be a general-purpose hash.
+
+Values are left alone, except that nested hashes are converted into nested
+FlexConf objects. 
+
+## Loading from YAML ##
+
+This is the more flexible usage, with multiple options for scoping and 
+overrides:
+
+    require 'flexconf'
+    
+    CONFIG = FlexConf.new '../mysettings.yml',  # Core filename (include path if needed)
+        scope: :development,            # Only load values from the 'development' key
+        local: 'mysettings_local.yml',  # Merge in values from this other YAML file
+        environment: true,              # Allow overrides from environment variables
+        override: { :cache => 'Dummy' } # Also override from the provided hash
+        
+Or, if it suits your needs, you could simply take the defaults:
+
+    require 'flexconf'
+    
+    CONFIG = FlexConf.new
+    
+...which is equivalent to:
+
+    CONFIG = FlexConf.new 'config.yml', local: 'config_local.yml', environment: true
+
+As with hash loading, all keys are converted to symbols on creation and the
+object is read-only after it's created. Options are described in detail after
+the "Using It" section.
+
+## Using It ##
+
+The FlexConf object supports both the 'indifferent hash' style and the 'method
+call' style for accessing configuration values. Both are interchangeable and
+recursive:
+
+    CONFIG[:some_number]      #=> 24
+    CONFIG['some_number']     #=> 24
+    CONFIG.some_number        #=> 24
+    
+    CONFIG[:nested]['mommy_bird']   #=> 'Tweet!'
+    CONFIG['nested'][:mommy_bird]   #=> 'Tweet!'
+    CONFIG.nested.mommy_bird        #=> 'Tweet!'
+    CONFIG.nested[:baby_bird]       #=> 'Facebook.'
+
+If you've spent a little time working with [Chef](http://wiki.opscode.com),
+this level of looseness will probably seem familiar. Their attribute access
+patterns were a direct inspiration for FlexConf. (If you've spent a _lot_ of
+time working with Chef, you're probably at the sanatorium and _nothing_ seems
+familiar.)
+
+FlexConf objects are _very loosely_ duck-typed to Hashes, but are not subclasses of Hash.  They publicly support the following methods:
+
+* `[]` (your friend the accessor)
+* `has_key?`
+* `each` (returns key and value, just like Hash)
+* the Enumerable mixin
+
+FlexConf objects are _read-only_ once they're initialized. You can't change
+any values later. This is by deliberate design decision. (If you need to muck
+with your application's configuration after it's up and running, it's not
+'configuration' any more, it's mutable state and you should be paying more
+attention to it than this.)
+
+## Options ##
+
+Options that can be passed at initialization are as follows (and only work in YAML mode):
+
+### :scope ###
+
+Use this for Rails-style environments. The provided value must be a top-level
+key in the main YAML file. The key/value pairs nested beneath it will become
+top-level structures for the FlexConf configuration, and the rest of the file
+will be ignored. Note that this happens _after_ the YAML library does its
+processing, so if your file looks like:
+
+    defaults: &defaults
+      foo: 'bar'
+      yoo: 'yar'
+      something_else: 17
+      
+    test:
+      << *defaults
+      foo: 'car'
+
+...and so forth, a `:scope => :test` option will still do the right thing.
+
+Scope limiting applies _only_ to the main YAML file and occurs before any
+other options are handled. Overrides from a 'local' YAML file, environment
+variables, or a supplied hash are assumed already to be in the desired scope
+and won't be transformed.
+
+### :local ###
+
+This option addresses the common use case of supplying sensitive data
+(passwords, etc.) or user-specific development machine settings in a secondary
+YAML file that is _not_ checked into source control. The options from this
+secondary file are merged into the main configuration. There are two ways to
+use it:
+
+* `:local => 'path/somefile.yml'` looks for the given file and loads it if it
+  exists.
+
+* `:local => true` appends '_local' to the base filename of the main YAML
+  file, and loads it if it exists in the same directory. (E.g., if your
+  primary file was `/conf/amazon_settings.yml`, it would look for
+  `/conf/amazon_settings_local.yml`.)
+
+In either case, no error will be raised if the file is not found.
+
+### :override ###
+
+This option takes a hash value and merges it into the configuration _after_
+the main YAML file and `:local` file are processed. It works just like the
+"Loading From a Hash" section described above.  'Nuff said.
+
+### :environment ###
+
+This option allows values to be passed in from the command line or from external processes (your Web server, et cetera) by means of environment variables. The environment variable name is lowercased and symbolized, and nested keys can be pointed to by separating them with a double underscore (`__`).  The intended use case is something like:
+
+    $ AMAZON__ACCESS_ID=blahblah AMAZON__SECRET_KEY=yaddayadda rake deploy:thingy
+    
+If the Rake task is using a FlexConf anywhere with the `:environment` option set, then those two variables will automatically be merged into `CONFIG[:amazon][:access_id]` and `CONFIG[:amazon][:secret_key]`. As with the `:local` option, there are two ways to use it:
+
+* `:environment => ['SOME_ENV_VAR', 'ANOTHER_ENV_VAR']` merges in _only_ the
+  environment variables specified in the given array. Keys that didn't
+  previously exist are created (including nested paths). The rest of the
+  environment is ignored, and no error is raised if the variables aren't
+  actually set. This is the most secure way to use it if you can plan ahead
+  for which configuration values may need changing at runtime.
+
+* `:environment => true` scans the entire environment, but _only_ updates keys
+  that already exist (from the main YAML file or some other override). New
+  keys are not created, to prevent polluting your configuration with settings
+  like `[:home]` and `[:_]` and `[:grep_options]`. This is a useful shortcut
+  if you want your entire configuration to be alterable at runtime, but make
+  sure you don't have any top-level key names that may collide with common
+  Unix names.
+
+## Support and Such ##
+
+Documentation can be found at the [usual RDoc.info](http://rdoc.info/github/SFEley/flexconf/master) spot.
+
+If you have questions, problems, or suggestions please start by leaving an Issue here, but feel free to email me at <sfeley@gmail.com> if you don't get a timely response.  I'm sporadic about staying on top of my Github stuff, but I'm trying to get better about it.
+
+I encourage pull requests, forks, etc. There's probably more that could be done with this. (But not _much_ more, lest we lose the "simple" part.)
+
+FlexConf is licensed under the [Don't Be a Dick](http://dbad-license.org) license, v0.3. The specific license for the project can be found [here](http://github.com/SFEley/flexconf/blob/master/LICENSE.md). (In brief: do anything you want with this, so long as you aren't a dick about it.)
+
+
+
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/flexconf.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "flexconf"
+  s.version     = "0.1.0"
+  s.authors     = ["Stephen Eley"]
+  s.email       = ["sfeley@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Simple, flexible YAML- or Ruby-based configuration management}
+  s.description = <<-END
+FlexConf is a simple configuration utility that does its job and gets
+out of your way. It reads settings from a hash or YAML file ('config.yml' by default)
+but allows overrides from a '*_local.yml' file and from environment variables. 
+Settings can be read as indifferent hash values (config['foo'] or config[:foo]) 
+or method calls (config.foo) with recursive nesting (config.foo.bar). The code
+is lightweight and fast with no additional dependencies.
+END
+
+  s.rubyforge_project = "flexconf"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

data/lib/flexconf.rb

@@ -0,0 +1,187 @@
+require 'yaml'
+require 'forwardable'
+
+# A simple but flexible configuration class. 
+class FlexConf
+  extend Forwardable
+  include Enumerable
+  
+  # Loads configuration from the supplied source(s).  
+  # @overload initialize(hash)
+  #   Reads the supplied hash as the entire configuration. No options are handled; you'll
+  #   have to make sure the data you provide contains everything you intend it to.
+  #   @param [Hash] source The configuration data you want to provide.
+  # 
+  # @overload initialize(yaml_file, opts)
+  #   Loads the given YAML file and optional overrides. 
+  #   @param [String, Hash] source A YAML filename. The file must be in the current
+  #     directory or a complete path must be given.
+  #   @param [optional, Hash] opts Specifies ways in which the supplied data can be
+  #     overridden. Overrides are processed in the following order:
+  #       1. `:scope` (limit the source configuration namespace)
+  #       2. `:local` (secondary '*_local.yml' file)
+  #       3. `:override` (hash supplied in code)
+  #       4. `:environment` (environment variables)
+  #   @option opts [Hash] :override A hash which will be merged over the source 
+  #     configuration.
+  #   @option opts [String, Boolean] :local A second YAML file containing local data
+  #     (presumably outside source control). No error is raised if this file does
+  #     not exist. A value of 'true' appends `_local` to the source file's base name,
+  #     e.g. `config_local.yml`.
+  #   @option opts [Array, Boolean] :environment If given an array of environment
+  #     variable names, FlexConf will lowercase the names and then inject or override
+  #     them into the configuration. Nested values can be marked by a double underscore
+  #     (i.e. 'FOO__BAR' would set a value at [:foo][:bar]).  A value of 'true' scans
+  #     all environment variables, but will _only_ override existing values (e.g. an
+  #     existing config value at [:aws_access_key] could be overridden by the 
+  #     AWS_ACCESS_KEY environment variable.)  
+  #     (Use with caution!  Casually setting ':environment => true' if you have
+  #     configuration variables such as [:home] or [:path] could have undesired results.)
+  #   @option opts [String, Symbol] :scope Limits the configuration to the values
+  #     beneath the given top-level key in the YAML source file. Useful for 
+  #     Rails-style environment configurations ('development', 'production', etc.) 
+  #     Local, environment, and hash overrides are unaffected; they are assumed 
+  #     to be already within the intended scope.
+  #
+  # @overload initialize()
+  #   With no parameters, takes a common default case and acts as if you had run
+  #   `FlexConf.new('config.yml', :local => 'config_local.yml', :environment => true)`.
+  #   Raises an exception if 'config.yml' does not exist.
+  def initialize(source=nil, options=nil)
+    @data = {}
+    case source
+    when /.*\.yml/
+      source_data = YAML.load_file(source)
+      if options && options[:scope]
+        flexify scoped(source_data, options[:scope])
+      else
+        flexify source_data
+      end
+      handle_overrides(source, options) if options
+    when Hash
+      flexify source
+    when nil
+      if File.exists?('config.yml')
+        initialize('config.yml', :local => 'config_local.yml', :environment => true)
+      else
+        raise ArgumentError, "FlexConf can't load: no configuration was given and there is no config.yml file to default to."  
+      end
+    end
+  end
+  
+  # Returns the value for the given key, which can be a string or a symbol.  Named
+  # keys can also be accessed via method calls (i.e. `config.foo`).  Nested 
+  # configurations are returned as FlexConf objects.
+  def [](key)
+    @data[normalize_key(key)]
+  end
+  
+  # Returns true if the given configuration value exists.
+  def has_key?(key)
+    @data.has_key? normalize_key(key)
+  end
+  
+  # Calls Hash#each on the underlying data structure.
+  def_delegator(:@data, :each)
+  
+  protected
+  def_delegator(:@data, :[]=)   # Needed to merge override data
+  
+  private
+  # We're deconstructionists.  Everything is a symbol!
+  def normalize_key(key)
+    case key
+    when Symbol
+      key
+    when String
+      key.to_sym
+    else
+      key.to_s.to_sym
+    end
+  end
+  
+  # Flatten out, turning keys to symbols and hash values to FlexConfs
+  def flexify(hash)
+    hash.each do |key, value|
+      key = normalize_key(key)
+      value = FlexConf.new(value) if value.kind_of?(Hash)
+      if @data[key].is_a?(FlexConf)
+        merge(@data[key], value)
+      else
+        @data[key] = value
+      end
+    end
+  end
+  
+  # Deep merge into existing substructures
+  def merge(mine, theirs)
+    theirs.each do |key, value|
+      if mine.has_key?(key) and value.kind_of?(Hash)
+        merge(mine[key], value)
+      else
+        mine[key] = value
+      end
+    end
+  end
+  
+  def handle_overrides(source_file, options={})
+    local_override(source_file, options[:local]) if options[:local]
+    hash_override(options[:override]) if options[:override]
+    if options[:environment].respond_to?(:each)
+      env_subset = ENV.select {|k,v| options[:environment].include? k}
+      environment_override(env_subset, true)
+    elsif options[:environment] == true
+      environment_override(ENV, false)
+    end
+  end
+  
+  def local_override(source_file, local)
+    local = File.join(File.join(File.dirname(source_file), File.basename(source_file, '.yml') + '_local.yml')) if local == true
+    flexify YAML.load_file(local) if File.exists?(local)
+  end
+  
+  def hash_override(hash)
+    flexify hash
+  end
+  
+  
+  # Turn 'THIS_LONG__ENVIRONMENT__PATH' to [:this_long, :environment, :path]
+  def normalize_envvar(name)
+    name.downcase.split('__').map {|e| e.empty? ? nil : e.to_sym}
+  end
+  
+  def get_path(root, names, create_path=false)
+    this, remaining = names.first, names[1..-1]
+    if remaining.empty?
+      root
+    elsif root[this].kind_of?(FlexConf)
+      get_path(root[this], remaining, create_path)
+    elsif create_path and !root.has_key?(this)
+      root[this] = FlexConf.new({}) # Create an empty stub for the path
+      get_path(root[this], remaining, true)
+    else  # The node exists and isn't a FlexConf, or create_path is false
+      false
+    end
+  end
+  
+  # Override from a provided hash of environment variables. Create new paths
+  # or new values only if create=true.
+  def environment_override(env, create_key=false)
+    env.each do |key, value|
+      flexvar = normalize_envvar(key)  # Get an array of symbols representing the path
+      if data_path = get_path(@data, flexvar, create_key)
+        data_key = flexvar[-1]
+        data_path[data_key] = value if data_path.has_key?(data_key) or create_key
+      end
+    end
+  end
+  
+  def scoped(data, scope)
+    # This is before flattening, so we need to check both string and symbol forms
+    data[scope] || data[scope.to_s] || data[scope.to_sym]
+  end
+  
+  def method_missing(name, *args, &block)
+    self[name] or super
+  end
+end

data/spec/example/alternate.yml

@@ -0,0 +1,2 @@
+this_file: 'The alternate in example/alternate.yml'
+locally_grown: 'Yummy!'

data/spec/example/alternate_local.yml

@@ -0,0 +1 @@
+locally_grown: 'Blech!'

data/spec/example/config.yml

@@ -0,0 +1,25 @@
+# Overrides
+this_file: 'example/config.yml'
+local_file: 'none'
+
+# Basic key access
+foo: :bar     # Ordinary string key
+7: 'seven'    # Non-string key
+:boo: 'far'   # Symbol key
+
+# Name collisions
+'zoo': 'ostrich'
+:zoo: 'yak'
+
+# Nesting
+nest:
+  foo: 'barbar'
+  joo: 'lepp'
+  renest:
+    bar: 'foofoo'
+
+# Scope
+development:
+  foo: 'dev-fu'
+  boo: 'Chicken Boo'
+  yoo: 'yuh?'

data/spec/example/config_local.yml

@@ -0,0 +1,2 @@
+local_file: 'example/config_local.yml'
+yoo: 0.5

data/spec/flexconf_spec.rb

@@ -0,0 +1,250 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'flexconf'
+
+describe FlexConf do
+  before(:each) do
+    Dir.chdir(File.join(File.dirname(__FILE__), 'example'))
+    @this = FlexConf.new
+  end
+
+  describe "access" do    
+    it "can read keys as strings" do
+      @this['foo'].should == :bar
+    end
+    
+    it "can read keys as symbols" do
+      @this[:foo].should == :bar
+    end
+    
+    it "can read keys as method calls" do
+      @this.foo.should == :bar
+    end
+    
+    it "can read non-string keys" do
+      @this[7].should == 'seven'
+    end
+    
+    it "can read non-string keys as strings" do
+      @this['7'].should == 'seven'
+    end
+    
+    it "can read non-string keys as symbols" do
+      @this[:'7'].should == 'seven'
+    end
+    
+    it "can read symbol keys as strings" do
+      @this['boo'].should == 'far'
+    end
+    
+    it "can read symbol keys as symbols" do
+      @this[:boo].should == 'far'
+    end
+    
+    it "always keeps a consistent value in the event of name collisions" do
+      @this['zoo'].should == @this[:zoo]
+    end
+    
+    it "knows when it has a key" do
+      @this.has_key?('zoo').should be_true
+      @this.has_key?(:zoo).should be_true
+    end
+    
+    it "knows when it doesn't have a key" do
+      @this.has_key?(:fantastical).should be_false
+    end
+    
+    it "can be iterated" do 
+      @this.each do |key, value|
+        @this[key].should == value
+      end
+    end
+    
+    it "is enumerable" do
+      @this.count.should > 0
+    end
+  end
+  
+  describe "nesting" do
+    it "can return nested variables" do
+      @this[:nest]['foo'].should == 'barbar'
+    end
+    
+    it "can return nested variables as method chains" do
+      @this.nest.foo.should == 'barbar'
+    end
+    
+    it "can use arbitrary call styles" do
+      @this.nest[:renest].bar.should == 'foofoo'
+    end
+  end
+    
+  describe "initialization" do
+    it "can be given a hash" do
+      c = FlexConf.new 'foo' => 17
+      c['foo'].should == 17
+    end
+    
+    it "can be given a filename" do
+      c = FlexConf.new 'alternate.yml'
+      c.this_file.should == 'The alternate in example/alternate.yml'
+    end
+    
+    it "defaults to config.yml" do
+      @this['this_file'].should == 'example/config.yml'
+    end
+    
+    it "defaults to overriding from config_local.yml" do
+      @this.local_file.should == 'example/config_local.yml'
+    end
+    
+    it "complains if given no parameters and there is no config.yml" do
+      Dir.chdir('..')
+      lambda {FlexConf.new}.should raise_error(ArgumentError, /config\.yml/)
+    end
+  end
+  
+  describe "local overrides" do
+    before(:each) do
+      @this = FlexConf.new('config.yml', :local => 'alternate.yml')
+    end
+    
+    it "replaces existing values with ones from the local file" do
+      @this.this_file.should == 'The alternate in example/alternate.yml'
+    end
+    
+    it "adds new values from the local file" do
+      @this[:locally_grown].should == 'Yummy!'
+    end
+    
+    it "still leaves values not referred to alone" do
+      @this[:development].foo.should == 'dev-fu'
+    end
+    
+    it "loads the *_local.yml if :local is 'true'" do
+      c = FlexConf.new('alternate.yml', :local => true)
+      c[:locally_grown].should == 'Blech!'
+    end
+  end
+  
+  describe "hash overrides" do
+    before(:each) do
+      @this = FlexConf.new 'config.yml', :override => {
+        'foo' => 'fahrvergnugen',
+        :qoo => 'Qatar',
+        :nest => {
+          :foo => 'yep',
+          :renest => 5
+        }
+      }
+    end
+    
+    it "overrides at the top level" do
+      @this.foo.should == 'fahrvergnugen'
+    end
+    
+    it "adds new values" do
+      @this.qoo.should == 'Qatar'
+    end
+    
+    it "overrides nested values" do
+      @this.nest.foo.should == 'yep'
+    end
+    
+    it "leaves other values alone" do
+      @this.nest[:joo].should == 'lepp'
+    end
+    
+    it "can take out full blocks" do
+      @this.nest.renest.should == 5
+    end
+  end
+  
+  describe "environment variable overrides" do
+    before(:all) do
+      ENV['FOO'] = 'harrumph'
+      ENV['NEST__JOO'] = 'nipper'
+      ENV['HAPPY'] = 'go lucky'
+      ENV['ZOO'] = '97'
+      ENV['YOO'] = 'know who'
+    end
+    
+    describe "stated as an array" do
+      before(:each) do
+        @this = FlexConf.new('config.yml', :environment => %w{ZOO HAPPY NEST__JOO FRACK})
+      end
+      
+      it "overrides existing values" do
+        @this.zoo.should == '97'
+      end
+      
+      it "creates new values" do
+        @this[:happy].should == 'go lucky'
+      end
+      
+      it "overrides nested values" do
+        @this.nest.joo.should == 'nipper'
+      end
+      
+      it "does nothing with stated variables that don't exist" do
+        @this.should_not have_key(:frack)
+      end
+    end
+    
+    describe "automatically pulled with :environment => true" do
+      before(:each) do
+        @this = FlexConf.new('config.yml', :environment => true) 
+      end
+      
+      it "overrides existing values" do
+        @this.foo.should == 'harrumph'
+      end
+      
+      it "does NOT create new values" do
+        @this.should_not have_key(:happy)
+      end
+      
+      it "overrides nested values" do
+        @this[:nest][:joo].should == 'nipper'
+      end
+    end
+    
+    describe "by default" do
+      it "overrides local overrides from the environment" do
+        @this.yoo.should == 'know who'
+      end
+    end
+    
+    after(:all) do
+      ENV['FOO'] = nil
+      ENV['NEST__JOO'] = nil
+      ENV['HAPPY'] = nil
+      ENV['ZOO'] = nil
+      ENV['YOO'] = nil
+    end
+  end
+  
+  
+  describe "scope limitation" do
+    before(:each) do
+      @this = FlexConf.new('config.yml', :scope => :development)
+    end
+    
+    it "returns the values in scope" do
+      @this.foo.should == 'dev-fu'
+    end
+    
+    it "does not locally override unless explicitly told" do
+      @this.yoo.should == 'yuh?'
+    end
+    
+    it "knows nothing about out-of-scope values" do
+      lambda {@this.zoo}.should raise_error(NoMethodError)
+    end
+    
+    it "takes local overrides at the top level" do
+      c = FlexConf.new('config.yml', :scope => :development, :local => true)
+      c.yoo.should == 0.5
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: flexconf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Stephen Eley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70311136259080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70311136259080
+description: ! "FlexConf is a simple configuration utility that does its job and gets\nout
+  of your way. It reads settings from a hash or YAML file ('config.yml' by default)\nbut
+  allows overrides from a '*_local.yml' file and from environment variables. \nSettings
+  can be read as indifferent hash values (config['foo'] or config[:foo]) \nor method
+  calls (config.foo) with recursive nesting (config.foo.bar). The code\nis lightweight
+  and fast with no additional dependencies.\n"
+email:
+- sfeley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- flexconf.gemspec
+- lib/flexconf.rb
+- spec/example/alternate.yml
+- spec/example/alternate_local.yml
+- spec/example/config.yml
+- spec/example/config_local.yml
+- spec/flexconf_spec.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: flexconf
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Simple, flexible YAML- or Ruby-based configuration management
+test_files:
+- spec/example/alternate.yml
+- spec/example/alternate_local.yml
+- spec/example/config.yml
+- spec/example/config_local.yml
+- spec/flexconf_spec.rb
+has_rdoc: