Yet another hash/struct-like configuration object for Ruby

License: MIT

Language: Ruby

confstruct Build Status Dependency Status

Confstruct is yet another configuration gem. Definable and configurable by hash, struct, or block, confstruct aims to provide the flexibility to do things your way, while keeping things simple and intuitive.


First, either create an empty ConfStruct::Configuration object:

config = Confstruct::Configuration.new

Or with some default values:

config = Confstruct::Configuration.new({ 
  :project => 'confstruct', 
  :github => { 
    :url => 'http://www.github.com/mbklein/confstruct',
    :branch => 'master'

The above can also be done in block form:

config = Confstruct::Configuration.new do 
  project 'confstruct'
  github do
    url 'http://www.github.com/mbklein/confstruct'
    branch 'master'

There are many ways to access and configure the resulting config object...

As a struct...

config.project = 'other-project'
config.github.url = 'http://www.github.com/somefork/other-project'
config.github.branch = 'pre-1.0'

As a block...

config.configure do
  project 'other-project'
  github.url 'http://www.github.com/somefork/other-project'
  github.branch 'pre-1.0'

As a hash...

config[:github][:url] = 'http://www.github.com/somefork/other-project'

Or even as a crazy struct/hash hybrid...

config.github[:url] = 'http://www.github.com/somefork/other-project'
config[:github].branch = 'pre-1.0'

Each sub-hash/struct is a configuration object in its own right, and can be treated as such. (Note the ability to leave the configure method off the inner call.)

config.configure do
  project 'other-project'
  github do
    url 'http://www.github.com/somefork/other-project'
    branch 'pre-1.0'

You can even

config.project = 'other-project'
config.github = { :url => 'http://www.github.com/somefork/other-project', :branch => 'pre-1.0' }

The configure method will even perform a deep merge for you if you pass it a hash or hash-like object (anything that responds to each_pair)

config.configure({:project => 'other-project', :github => {:url => 'http://www.github.com/somefork/other-project', :branch => 'pre-1.0'}})

Because it's "hashes all the way down," you can store your defaults and/or configurations in YAML files, or in Ruby scripts if you need to evaluate expressions at config-time.

However you do it, the resulting configuration object can be accessed either as a hash or a struct:

 => "other-project" 
 => "other-project" 
 => {:url=>"http://www.github.com/somefork/other-project", :branch=>"pre-1.0"}
 => "http://www.github.com/somefork/other-project" 
 => "http://www.github.com/somefork/other-project" 
 => {:url=>"http://www.github.com/somefork/other-project", :branch=>"pre-1.0"}

Other Features

Deferred evaluation

Any configuration value of class Confstruct::Deferred will be evaluated on access, allowing you to define read-only, dynamic configuration attributes

config.app_name = "iWidgetCloud"
config.msgs.welcome = Confstruct::Deferred.new {|c| "Welcome to #{c.app_name}!"}    
 => "Welcome to iWidgetCloud!"
config.app_name = "Enterprisey-Webscale"
 => "Enterprisey-Webscale" 
 => "Welcome to Enterprisey-Webscale"

As a convenience, Confstruct.deferred(&block) and Confstruct::HashWithStructAccess#deferred!(&block) will create a Confstruct::Deferred for you, making the following two assignments equivalent to the above:

config.welcome_msg = Confstruct.deferred { |c| "Welcome to #{c.app_name}!" }
config do
  welcome_msg deferred! { |c| RestClient::Resource.new(c.url) }

Push/Pop configurations

push! and pop! methods allow you to temporarily override some or all of your configuration values. This can be useful in spec tests where you need to change values but don't want to worry about messing up tests that depend on the same global configuration object.

 => "http://www.github.com/mbklein/confstruct"
config.push! { github.url 'http://www.github.com/somefork/other-project' }
 => {:project=>"confstruct", :github=>{:branch=>"master", :url=>"http://www.github.com/somefork/other-project"}} 
 => "http://www.github.com/somefork/other-project"
 => {:project=>"confstruct", :github=>{:branch=>"master", :url=>"http://www.github.com/mbklein/confstruct"}} 
 => "http://www.github.com/mbklein/confstruct"


lookup! can be used to look up down a hieararchy without raising on missing values; and/or to look up with default value.

config = Confstruct::Configuration.new do 
  project 'confstruct'
  github do
    url 'http://www.github.com/mbklein/confstruct'
    branch 'master'
=> "http://www.github.com/mbklein/confstruct"
=> nil # no raising
=> nil
config.lookup!("github.not_there", "default_value")
=> "default_value"


The pattern add_$key! can be used to add to or create an array.

config = Confstruct::Configuration.new
config.add_color! "green"
=> ["green"]
=> {:color=>["green"]}
config.add_color! "red"
=> ["green", "red"]


  • Confstruct will attempt to use ordered hashes internally when available.
    • In Ruby 1.9 and above, this is automatic.
    • In Rubies earlier than 1.9, Confstruct will try to require and use ActiveSupport::OrderedHash, falling back to a regular Hash if necessary. The class/instance method ordered? can be used to determine if the hash is ordered or not.
  • In order to support struct access, all hash keys are converted to symbols, and are accessible both as strings and symbols (like a HashWithIndifferentAccess). In other words, config['foo'] and config[:foo] refer to the same value.

Release History

  • v0.1.0 - Initial release
  • v0.2.0 - Add fallback value to HashWithStructAccess#lookup!, native support for Rails I18n.
  • v0.2.1 - Initialize properly from a nested hash with string (non-symbol) keys
  • v0.2.2 - Fix ArgumentError on #respond_to?(sym, true)
  • v0.2.3 - Don't evaluate Deferreds during #inspect
  • v0.2.4 - Fix deferreds under Ruby 1.9.x
  • v0.2.5 - #14 #configure loses nested hashes somehow
  • v0.2.6 - Fix test scoping issue under Ruby 2.1.0+
  • v0.2.7 - Remove ActiveSupport for Ruby >= 1.9
  • v1.0.0 - [YANKED] Refactor to use Hashie instead of reinventing all the Hash access stuff
  • v1.0.1 - Switch back to symbolized keys internally

Contributing to confstruct

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


confstruct is released under the MIT License.

Project Statistics

Sourcerank 9
Repository Size 329 KB
Stars 200
Forks 7
Watchers 2
Open issues 12
Dependencies 7
Contributors 5
Tags 12
Last updated
Last pushed

Top Contributors See all

Michael B. Klein Jonathan Rochkind Chris Beer Bill Dueber Steve Richert

Packages Referencing this Repo

A simple, hash/struct-based configuration object
Latest release 1.0.2 - Updated - 200 stars

Recent Tags See all

v1.0.2 October 26, 2015
v1.0.1 March 25, 2015
v1.0.0 March 24, 2015
v0.2.7 March 05, 2014
v0.2.6 March 04, 2014
v0.2.5 December 05, 2012
v0.2.4 August 23, 2012
v0.2.3 May 11, 2012
v0.2.2 March 01, 2012
v0.2.1 January 23, 2012
v0.2.0 November 18, 2011
v0.1.0 November 18, 2011

Interesting Forks See all

Yet another hash/struct-like configuration object for Ruby
Ruby - Updated - 3 stars - 1 forks

Something wrong with this page? Make a suggestion

Last synced: 2019-11-10 04:12:45 UTC

Login to resync this repository