Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Load configuration settings from ENV, dotfiles, and gems

branch: master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rvmrc
Octocat-spinner-32 Gemfile
Octocat-spinner-32 Gemfile.lock
Octocat-spinner-32 LICENSE.txt
Octocat-spinner-32 Rakefile
Octocat-spinner-32 constellation.gemspec


Constellation is a powerful configuration system. It's great for API client libraries and applications and anywhere else you need to let your users set some configuration parameters.

Putting Settings In

Ruby Parameters

Start by creating a class and calling Constellation.enhance:

class MyConfiguration
  Constellation.enhance self

With just this, you have a basic Hash configuration. The only way to set properties is to pass them in Ruby:

config = => 'bar') # => "bar"


To add support for ENV hash configuration, set env_params:

class MyConfiguration
  self.env_params = { :foo => 'MY_FOO' }

ENV['MY_FOO'] = 'bar' # => "bar"

Configuration Files

To add support for config files, set config_file to a path. The Constellation will look up a config file in that location relative to two places ("base paths"):

  • the current working directory (Dir.pwd)
  • the user's home directory (ENV['HOME'])
class MyConfiguration
  self.config_file = 'my/config.yml'

If ./my/config.yml contains the following

foo: bar

then will return "bar".

From Gems

If you set config_file to a path and set load_from_gems to true, then Constellation will add all of the loaded gem directories to the list of base paths.

class MyConfiguration
  self.config_file = 'my/config.yml'
  self.load_from_gems = true

Order of Precedence

Constellation will load parameters in the order listed above. Given

class MyConfiguration
  self.env_params = { :foo => 'MY_FOO' }
  self.config_file = 'my/config.yml'
  self.load_from_gems = true

Constellation will first look in a Hash passed in, then in ENV, then in ./my/config.yml, then in ~/my/config.yml, then in GEM_PATH/my/config.yml for each loaded gem.

File Parsers

Constellation will do the right thing if config_file ends with .yml, .yaml, or .json. If it's a different format, you'll have to tell Constellation how to parse it by redefining parse_config_file:

class MyConfiguration
  self.config_file = '.myrc'

  def parse_config_file(contents)
    contents.split("\n").inject({}) do |result, line|
      k, v = line.split(/:\s*/)
      result[k] = v

Getting Settings Out

Given a Constellation configuration object

c = => 'bar')

you can get the settings out in a few ways.

Keys are available as methods:     # => "bar"

Keys are available via [] as Strings or Symbols:

c['foo']  # => "bar"
c[:foo]   # => "bar"

to_hash will return all of the settings, with String keys:

c.to_hash # => { "foo" => "bar" }

(If you have loaded activesupport, to_hash will return a HashWithIndifferentAccess.)

The enumerable methods are available: { |k,v| k + ':' + v } # => [ "foo:bar" ]
Something went wrong with that request. Please try again.