settings-tree

= 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 : http://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.

== Copyright

Copyright (c) 2011 Offirmo. See LICENSE.txt for further details.