settings-tree

Introduction

This gem offers you a convenient settings structure for parameterizing your applications.

The good things over similar gems is the ability to have deep, recursive structures and the ability to have ‘specialized’ config according to the environment.

Example :

Settings.web_app.root_url               => 'localhost:3000'

Settings.web_app.infos.company_name     => 'Acme'
Settings.web_app.infos.app_name         => 'Coffe maker'

Settings.web_app.engine.workers_count   => 3

Those settings are read from a YAML file, like this one :

# YAML private config file
# XXX Beware ! This is YAML : indention with spaces only ! XXX

####### Common / default values #######
defaults:
  root_url: localhost:3000
  public_access: true

  infos:
    company_name: 'Acme'
    app_name: 'Coffe maker'
    copyright_starting_year: 2011
    legend: 'A superb app which does ...'

  engine:
    workers_count: 3
    auto_manage_workers: true
    auto_manage_workers_redirect_output: true

####### production environment #######
production:
# nothing special

####### development environment #######
development:
  engine:
    auto_manage_workers_redirect_output: false

####### test environment #######
test:
  engine:
    workers_count: 0

The common settings reside under a root named ‘defaults’. Other roots (‘production’, ‘development’…) will be picked depending on the environment. (more about that later)

This gem has more good features, keep reading.

Ideas taken from : kpumuk.info/ruby-on-rails/flexible-application-configuration-in-ruby-on-rails/

Installation

Available as a gem in rubygems, the default gem repository :

gem 'settings-tree'

Isn’t that easy ? (Thank you jeweler for making everything so easy)

Use

You can uses several, independent ‘groups’.

Just register a settings group from a file :

Settings.register_settings_file('web_app', File.join(File.dirname(__FILE__), "config/config_web_app.yml"))

or for ruby on rails :

(put this line in an initializer in config/initializer)
Settings.register_settings_file('web_app', File.join(::Rails.root.to_s, "config/config_web_app.yml"))

Note : of course, the group name must be a valid keyword, able to be converted to a sym.

And now you can access your settings from anywhere :

Settings.web_app.infos.company_name     => 'Acme'

(considering the YAML file given previously)

You can register any number of group you want :

Settings.register_settings_file('web_game', File.join(File.dirname(__FILE__), "config/config_web_game.yml"))

example, with this file :

####### Common / default values #######
defaults:
  guild_name: 'gang'
  party_size: 4

gives :

puts Settings.web_game.guild_name   => 'gang'

It’s common to have settings that you don’t want under version control (accounts, passwords). A solution is to use a complementary file not under version control (thanks to a gitignore for example). Just use :

Settings.register_settings_file('web_app', File.join(File.dirname(__FILE__), "config/config_complement.yml"))

Since the ‘web_app’ group already exists, data will be merged, the new one taking precedence in case of conflicts. (Precedence is set according to the order of declaration.) (All the source files are memorized, this is a complement, not a replacement.)

In case you want to reload the settings, you have two functions for that :

Settings.reload_all
Settings.reload_group('web_app')

(You may need that in development mode)

Advanced use

Note : since those functions are rarely used, they don’t have ‘Settings.’ shortcuts. Don’t mind, it’s the same.

Environment

In a rails app, the environment will be taken automatically from ‘Rails.env’. If not under a rails app or if the environment is not available, you may want to set it manually :

SettingsHolder.instance.set_environment('test')

(The existing files/groups will automatically be reloaded to take that into account.)

Reset

You may also want to reset all the settings (everything will be forgotten) :

SettingsHolder.instance.reset

Debug

A convenient debug function to see all the settings and their values :

SettingsHolder.instance.debug_inspect

Contributing to settings-tree

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.