Skip to content
A more elegant approach to creating and accessing configuration values.
Ruby
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.