= Settingslogic

Settingslogic is a simple configuration / settings solution that uses an ERB enabled YAML file. It has been great for
our apps, maybe you will enjoy it too.  Settingslogic works with Rails, Sinatra, or any Ruby project.

So here is my question to you.....is Settingslogic a great settings solution or the greatest?

== Helpful links

*	<b>Documentation:</b> http://rdoc.info/projects/binarylogic/settingslogic
*	<b>Repository:</b> http://github.com/binarylogic/settingslogic/tree/master
* <b>Issues:</b> http://github.com/binarylogic/settingslogic/issues

== Installation

Install from rubyforge/gemcutter:

  sudo gem install settingslogic

Or as a Rails plugin:

  script/plugin install git://github.com/binarylogic/settingslogic.git

Settingslogic does not have any dependencies on Rails.  Installing as a gem is recommended.

== Usage

=== 1. Define your class

Instead of defining a Settings constant for you, that task is left to you. Simply create a class in your application
that looks like:

  class Settings < Settingslogic
    source "#{Rails.root}/config/application.yml"
    namespace Rails.env
  end

Name it Settings, name it Config, name it whatever you want. Add as many or as few as you like. A good place to put
this file in a rails app is app/models/settings.rb. Declare your namespace to Rails.env if you use per-environment
settings. These will be merged with the settings in the default namespace.


=== 2. Create your settings

Notice above we specified an absolute path to our settings file called "application.yml". This is just a typical YAML file.
Also notice above that we specified a namespace for our environment.  A namespace is just an optional string that corresponds
to a key in the YAML file.

Using a namespace allows us to change our configuration depending on our environment:

  # app/config/application.yml
  defaults: &defaults
    cool:
      saweet: nested settings
    neat_setting: 24
    awesome_setting: <%= "Did you know 5 + 5 = #{5 + 5}?" %>
  
  development:
    <<: *defaults
    neat_setting: 800

  test:
    <<: *defaults

  production:
    <<: *defaults

=== 3. Access your settings

  >> Rails.env
  => "development"

  >> Settings.cool
  => "#<Settingslogic::Settings ... >"
  
  >> Settings.cool.saweet
  => "nested settings"
  
  >> Settings.neat_setting
  => 800
  
  >> Settings.awesome_setting
  => "Did you know 5 + 5 = 10?"

  >> Settings.key_by_path "cool.saweet"
  => "nested settings"
  
You can use these settings anywhere, for example in a model:  

  class Post < ActiveRecord::Base
    self.per_page = Settings.pagination.posts_per_page
  end

=== 4. Optional / dynamic settings

Often, you will want to handle defaults in your application logic itself, to reduce the number of settings
you need to put in your YAML file.  You can access an optional setting by using Hash notation:

  >> Settings.messaging.queue_name
  => Exception: Missing setting 'queue_name' in 'message' section in 'application.yml'

  >> Settings.messaging['queue_name']
  => nil

  >> Settings.messaging['queue_name'] ||= 'user_mail'
  => "user_mail"

  >> Settings.messaging.queue_name
  => "user_mail"

Modifying our model example:

  class Post < ActiveRecord::Base
    self.per_page = Settings.posts['per_page'] || Settings.pagination.per_page
  end
  
This would allow you to specify a custom value for per_page just for posts, or
to fall back to your default value if not specified.

== Author

Copyright (c) 2008-2010 {Ben Johnson}[http://github.com/binarylogic] of {Binary Logic}[http://www.binarylogic.com],
released under the MIT license.  Support for optional settings and reloading by {Nate Wiger}[http://nate.wiger.org].