= Configr

* Overview
* Installation
* Usage
* Usage (within frameworks)
* Contributors

== Overview

Configr aims to provide a more Ruby-like interface to configuring and reading a set of configuration values. The idea evolved from using a standard hash as a configuration store into a more elegant way to declare and read values from within a hash.

== Installation

The project is hosted on rubygems.org. Getting it is simple:

  gem install <gem name>

== Usage

There are a variety of ways in which you can use Configr:

* Standalone block
* From inline YAML
* From a YAML file
* A mixture of YAML and block configuration

The following examples can also be found and run in examples/all.rb.

=== Standalone Block

  configuration = Configr::Configuration.configure do |config|
    config.example_one = "One"
    config.example_two = "Two"
  end
  
  puts configuration.example_one
  puts configuration.example_two

Conceptually you could continue to nest configuration blocks as far as you wish. They exist to enable you to seperate your configuration values into contexts. Take for example a set of email configuration values:

  Configr::Configuration.configure do |config|
    config.email.from_address  = "hello@example.com"
    config.email.from_name     = "My Company"
    config.email.reply_address = "reply@example.com"
  end

=== From an inline YAML string

  yaml = <<YAML

  example_one: "Hello"
  example_two: "It loads from YAML too!"
  
  YAML
  
  configuration = Configr::Configuration.configure(yaml)

  puts configuration.example_one
  puts configuration.example_two

=== From a YAML file

  configuration = Configr::Configuration.configure("/path/to/file.yml")
  
  puts configuration.value_one
  puts configuration.value_two

=== A mixture of any of the above

  yaml = <<YAML

  example_three: "Oooooo"
  example_four: "It loads from YAML too!"

  YAML
  
  configuration = Configr::Configuration.configure(yaml) do |config|
    config.example_one = "One"
    config.example_two = "Two"
  end

  puts configuration.example_one
  puts configuration.example_two
  puts configuration.example_three
  puts configuration.example_four

== Usage (within frameworks)

Configr is intended to be framework agnostic, but it's easy to get it going within Rails/Sinatra/Hot New Framework app.

=== Rails

You can use Configr within Rails quite easily. I don't really plan to provide any "out of the box" way to hook Configr into Rails but it's quite easy to implement:

  # In config/configuration.rb
  Config = Configr::Configuration.configure(Rails.root.join("config", "environments", "#{Rails.env}.yml")) do |config|
    config.my.configuration.value = "value"
  end
  
  # In config/initializers/configuration.rb
  require Rails.root.join("config", "configuration.rb")
  
  # Anywhere in your Rails app
  Config.my.configuration.value

By requiring a different YAML file based on the environment it is easy to override global values with environment specific values.

=== Sinatra

A quick and dirty solution would be to pop it in a configure block:

  configure do
    Config = Configr::Configuration.configure(File.join("#{environment}.yml")) do |config|
      config.something = "value"
    end
  end

Again, by requiring a different YAML file based on the environment it is easy to override global values with environment specific values.

== Contributors

* Thomas Williams for the concept of nested configuration blocks.

== 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 me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Josh Nesbitt <josh@josh-nesbitt.net>. See LICENSE for details.