Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A super cool, simple, and feature rich configuration system for Ruby apps.

README.md

Configatron

Build Status Code Climate

Configatron makes configuring your applications and scripts incredibly easy. No longer is a there a need to use constants or global variables. Now you can use a simple and painless system to configure your life. And, because it's all Ruby, you can do any crazy thing you would like to!

One of the more important changes to V3 is that it now resembles more a Hash style interface. You can use [], fetch, each, etc...

Installation

Add this line to your application's Gemfile:

gem 'configatron'

And then execute:

$ bundle

Or install it yourself as:

$ gem install configatron --pre

Usage

Once installed you just need to require it:

require 'configatron'

Simple

configatron.email = 'me@example.com'
configatron.database.url = "postgres://localhost/foo"

Now, anywhere in your code you can do the following:

configatron.email # => "me@example.com"
configatron.database.url # => "postgres://localhost/foo"

Voila! Simple as can be.

Now you're saying, what if I want to have a 'default' set of options, but then override them later, based on other information? Simple again. Let's use our above example. We've configured our database.url option to be postgres://localhost/foo. The problem with that is that is our production database url, not our development url. Fair enough, all you have to do is redeclare it:

configatron.database.url = "postgres://localhost/foo_development"

becomes:

configatron.email # => "me@example.com"
configatron.database.url # => "postgres://localhost/foo_development"

Notice how our other configuration parameters haven't changed? Cool, eh?

Hash/YAML

You can configure Configatron from a hash as well (this is really only useful in testing or for data driven configuration, it's not recommended for actual configuration):

configatron.configure_from_hash(email: {pop: {address: 'pop.example.com', port: 110}}, smtp: {address: 'smtp.example.com'})

configatron.email.pop.address # => 'pop.example.com'
configatron.email.pop.port # => 110
# and so on...

YAML

YAML is terrible and should be driven from the face of the Earth. Because of this Configatron V3 does not support it. Sorry.

Namespaces

The question that should be on your lips is what I need to have namespaced configuration parameters. It's easy! Configatron allows you to create namespaces.

configatron.website_url = "http://www.example.com"
configatron.email.pop.address = "pop.example.com"
configatron.email.pop.port = 110
configatron.email.smtp.address = "smtp.example.com"
configatron.email.smtp.port = 25

configatron.to_h # => {:website_url=>"http://www.example.com", :email=>{:pop=>{:address=>"pop.example.com", :port=>110}, :smtp=>{:address=>"smtp.example.com", :port=>25}}}

Configatron allows you to nest namespaces to your hearts content! Just keep going, it's that easy.

Of course you can update a single parameter n levels deep as well:

configatron.email.pop.address = "pop2.example.com"

configatron.email.pop.address # => "pop2.example.com"
configatron.email.smtp.address # => "smtp.example.com"

Configatron will also let you use a block to clean up your configuration. For example the following two ways of setting values are equivalent:

configatron.email.pop.address = "pop.example.com"
configatron.email.pop.port = 110

configatron.email.pop do |pop|
  pop.address = "pop.example.com"
  pop.port = 110
end

Temp Configurations

Sometimes in testing, or other situations, you want to temporarily change some settings. You can do this with the temp method:

configatron.one = 1
configatron.letters.a = 'A'
configatron.letters.b = 'B'
configatron.temp do
  configatron.letters.b = 'bb'
  configatron.letters.c = 'c'
  configatron.one # => 1
  configatron.letters.a # => 'A'
  configatron.letters.b # => 'bb'
  configatron.letters.c # => 'c'
end
configatron.one # => 1
configatron.letters.a # => 'A'
configatron.letters.b # => 'B'
configatron.letters.c # => {}

Delayed and Dynamic Configurations

There are times when you want to refer to one configuration setting in another configuration setting. Let's look at a fairly contrived example:

configatron.memcached.servers = ['127.0.0.1:11211']
configatron.page_caching.servers = configatron.memcached.servers
configatron.object_caching.servers = configatron.memcached.servers

if Rails.env == 'production'
  configatron.memcached.servers = ['192.168.0.1:11211']
  configatron.page_caching.servers = configatron.memcached.servers
  configatron.object_caching.servers = configatron.memcached.servers
elsif Rails.env == 'staging'
  configatron.memcached.servers = ['192.168.0.2:11211']
  configatron.page_caching.servers = configatron.memcached.servers
  configatron.object_caching.servers = configatron.memcached.servers
end

Now, we could've written that slightly differently, but it helps to illustrate the point. With Configatron you can create Delayed and Dynamic settings.

Delayed

With Delayed settings execution of the setting doesn't happen until the first time it is executed.

configatron.memcached.servers = ['127.0.0.1:11211']
configatron.page_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}
configatron.object_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}

if Rails.env == 'production'
  configatron.memcached.servers = ['192.168.0.1:11211']
elsif Rails.env == 'staging'
  configatron.memcached.servers = ['192.168.0.2:11211']
end

Execution occurs once and after that the result of that execution is returned. So in our case the first time someone calls the setting configatron.page_caching.servers it will find the configatron.memcached.servers setting and return that. After that point if the configatron.memcached.servers setting is changed, the original settings are returned by configatron.page_caching.servers.

Dynamic

Dynamic settings are very similar to Delayed settings, but with one big difference. Every time you call a Dynamic setting is executed. Take this example:

configatron.current.time = Configatron::Dynamic.new {Time.now}

Each time you call configatron.current.time it will return a new value to you. While this seems a bit useless, it is pretty useful if you have ever changing configurations.

nil

Even if parameters haven't been set, you can still call them, but you'll get a Configatron::Store object back. The Configatron::Store class, however, will respond true to .nil? or .blank? if there are no parameters configured on it.

configatron.i.dont.exist.nil? # => true
configatron.i.dont.exist.blank? # => true
configatron.i.dont.exist # => Configatron::Store

You can use .has_key? to determine if a key already exists.

configatron.i.dont.has_key?(:exist) # => false

(key)!

You can also append a ! to the end of any key. If the key exists it will return it, otherwise it will raise a Configatron::UndefinedKeyError.

configatron.a.b = 'B'
configatron.a.b # => 'B'
configatron.a.b! # => 'B'
configatron.a.b.c! # => raise Configratron::UndefinedKeyError

Kernel

The configatron "helper" method is store in the Kernel module. Some people didn't like that in the V2 of Configatron, so in V3, while that hasn't changed, you don't have to use it.

Instead of requiring configatron simply require configatron/core, but then you'll have to set up your own Configatron::Store object.

Example:

require 'configatron/core'

store = Configatron::Store.new
store.foo = 'FOO'

store.to_h #= {foo: 'FOO'}

Locking

Once you have setup all of your configurations you can call the lock! method to lock your settings and raise an error should anyone try to change settings or access an unset setting later.

Example:

configatron.foo = 'FOO'
configatron.lock!

configatron.foo # => 'FOO'

configatron.bar # => raises Configatron::UndefinedKeyError
configatron.bar = 'BAR' # => raises Configatron::LockedError

Rails

Configatron works great with Rails. Use the built-in generate to generate an initializer file and a series of environment files for you to use to configure your applications.

$ rails generate configatron:install

Configatron will read in the config/configatron/defaults.rb file first and then the environment specific file, such as config/configatron/development.rb. Settings in the environment file will merge into and replace the settings in the defaults.rb file.

Example

# config/configatron/defaults.rb
configatron.letters.a = 'A'
configatron.letters.b = 'B'
# config/configatron/development.rb
configatron.letters.b = 'BB'
configatron.letters.c = 'C'
configatron.to_h # => {:letters=>{:a=>"A", :b=>"BB", :c=>"C"}}

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Write Tests!
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request

Contributors

  • Mark Bates
  • Kurtis Rainbolt-Greene
  • Rob Sanheim
  • Jérémy Lecour
  • Greg Brockman
  • Cody Maggard
  • Jean-Denis Vauguet
  • Torsten Schönebaum
  • Simon Menke
  • Gleb Pomykalov
  • chatgris
  • Mat Brown
  • Casper Gripenberg
  • Dan Pickett
  • Artiom Diomin
  • Tim Riley
  • mattelacchiato
  • joe miller
  • Brandon Dimcheff
  • Rick Fletcher
  • Josh Nichols
Something went wrong with that request. Please try again.