Skip to content

stacworks/configr

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

59 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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  = "[email protected]"
  config.email.from_name     = "My Company"
  config.email.reply_address = "[email protected]"
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 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 © 2010 Josh Nesbitt <[email protected]>. See LICENSE for details.

Packages

No packages published

Languages

  • Ruby 100.0%