Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/binarylogic/settingslogic

A simple and straightforward settings solution that uses an ERB enabled YAML file and a singleton design pattern.
https://github.com/binarylogic/settingslogic

Last synced: about 1 month ago
JSON representation

A simple and straightforward settings solution that uses an ERB enabled YAML file and a singleton design pattern.

Awesome Lists containing this project

README 

        
= Settingslogic



== Project Moved: This project has been moved to https://github.com/settingslogic/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.



{Gem Version}[http://badge.fury.io/rb/settingslogic]

{Build Status}[https://travis-ci.org/settingslogic/settingslogic]

{Inline docs}[http://inch-ci.org/github/settingslogic/settingslogic]



== Helpful links



* Documentation: http://rdoc.info/projects/binarylogic/settingslogic

* Repository: http://github.com/binarylogic/settingslogic/tree/master

* Issues: http://github.com/binarylogic/settingslogic/issues



== Installation



  gem install settingslogic



== 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



I felt adding a settings file in your app was more straightforward, less tricky, and more flexible.



=== 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:



  # 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



_Note_: Certain Ruby/Bundler versions include a version of the Psych YAML parser which incorrectly handles merges (the `<<` in the example above.)

If your default settings seem to be overwriting your environment-specific settings, including the following lines in your config/boot.rb file may solve the problem:



  require 'yaml'

  YAML::ENGINE.yamler= 'syck'



=== 3. Access your settings



  >> Rails.env

  => "development"



  >> Settings.cool

  => "#"



  >> Settings.cool.saweet

  => "nested settings"



  >> Settings.neat_setting

  => 800



  >> Settings.awesome_setting

  => "Did you know 5 + 5 = 10?"



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.



=== 5. Suppressing Exceptions Conditionally



Raising exceptions for missing settings helps highlight configuration problems.  However, in a

Rails app it may make sense to suppress this in production and return nil for missing settings.

While it's useful to stop and highlight an error in development or test environments, this is

often not the right answer for production.



  class Settings < Settingslogic

    source "#{Rails.root}/config/application.yml"

    namespace Rails.env

    suppress_errors Rails.env.production?

  end



  >> Settings.non_existent_key

  => nil



== Note on Sinatra / Capistrano / Vlad



Each of these frameworks uses a +set+ convention for settings, which actually defines methods

in the global Object namespace:



  set :application, "myapp"  # does "def application" globally



This can cause collisions with Settingslogic, since those methods are global. Luckily, the

solution is to just add a call to load! in your class:



  class Settings < Settingslogic

    source "#{Rails.root}/config/application.yml"

    namespace Rails.env

    load!

  end



It's probably always safest to add load! to your class, since this guarantees settings will be

loaded at that time, rather than lazily later via method_missing.



Finally, you can reload all your settings later as well:



  Settings.reload!



This is useful if you want to support changing your settings YAML without restarting your app.



== 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].