Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A more elegant approach to creating and accessing configuration values.
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
lib
spec
.gitignore
LICENSE
Rakefile
VERSION
configr.gemspec
readme.rdoc

readme.rdoc

Configr

  • Overview

  • Installation

  • Usage

  • Usage (within frameworks)

  • Locking

  • Bugs

  • Contributors

Overview

Configr aims to provide a clean interface for 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 configr

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 a 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 separate 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

puts configuration.email.from_address
puts configuration.email.from_name
puts configuration.email.reply_address

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: "three"
example_four: "four"

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

Asserting key presence

Sometimes when using configuration values you might want to assert whether the value exists before using it. Configr allows you to do this with the #key_name? syntax:

puts configuration.example_one? # => true
puts configuration.doesnt_exist? # => false

Usage (within frameworks)

Configr is intended to be framework agnostic, but it's easy to get it going inside of Rails/Sinatra.

Rails

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

# In config/configuration.rb
yaml_file = Rails.root.join("config", "environments", "#{Rails.env}.yml")

Configuration = Configr::Configuration.configure(yaml_file) 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
Configuration.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
  Configuration = Configr::Configuration.configure("config/file.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.

A note about locking

By design a configuration value is not meant to be edited or created after the configuration block has been run (if you do you will run into a Configr::ConfigurationLocked error). In my opinion configurations such as those created by Configr are meant to be read-only during the lifetime of the application. Configr could however be altered to allow this with a simple patch should it be required.

Bugs

If you have any problems with Configr, please file an issue at github.com/joshnesbitt/configr/issues.

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 © 2010 Josh Nesbitt <josh@josh-nesbitt.net>. See LICENSE for details.

Something went wrong with that request. Please try again.