Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Load configuration settings from ENV, dotfiles, and gems
Latest commit 7b05e49 James A. Rosen don't rely on ActiveSupport's core extensions
Use instead of {}.with_indifferent_access


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.