Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 164 lines (109 sloc) 5.538 kB
fdcf143 @binarylogic Renamed library from settingasm to settingslogic
authored
1 = Settingslogic
8007ac0 @binarylogic Initial commit
authored
2
c62bad5 @cofiem Added note about project changes and new repo.
cofiem authored
3 == Project Moved: This project has been moved to https://github.com/settingslogic/settingslogic
4
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
5 Settingslogic is a simple configuration / settings solution that uses an ERB enabled YAML file. It has been great for
6 our apps, maybe you will enjoy it too. Settingslogic works with Rails, Sinatra, or any Ruby project.
8007ac0 @binarylogic Initial commit
authored
7
21cd181 @cofiem added travis, docs, gem version badges
cofiem authored
8 {<img src="https://badge.fury.io/rb/settingslogic.svg" alt="Gem Version" />}[http://badge.fury.io/rb/settingslogic]
9 {<img src="https://travis-ci.org/settingslogic/settingslogic.svg" alt="Build Status" />}[https://travis-ci.org/settingslogic/settingslogic]
10 {<img src="http://inch-ci.org/github/settingslogic/settingslogic.png?branch=master" alt="Inline docs" />}[http://inch-ci.org/github/settingslogic/settingslogic]
11
502a3da @binarylogic updated readme
authored
12 == Helpful links
13
e01a30f @edgurgel Fix list of Helpful links
edgurgel authored
14 * <b>Documentation:</b> http://rdoc.info/projects/binarylogic/settingslogic
15 * <b>Repository:</b> http://github.com/binarylogic/settingslogic/tree/master
7fa2812 @binarylogic Update readme, switch from lighthouse to github
authored
16 * <b>Issues:</b> http://github.com/binarylogic/settingslogic/issues
502a3da @binarylogic updated readme
authored
17
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
18 == Installation
9008e05 @binarylogic Added installation into readme
authored
19
08792a6 @binarylogic get with the times
authored
20 gem install settingslogic
9008e05 @binarylogic Added installation into readme
authored
21
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
22 == Usage
9008e05 @binarylogic Added installation into readme
authored
23
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
24 === 1. Define your class
8007ac0 @binarylogic Initial commit
authored
25
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
26 Instead of defining a Settings constant for you, that task is left to you. Simply create a class in your application
27 that looks like:
471adcb @binarylogic Complete rewrite, see changelog / readme
authored
28
29 class Settings < Settingslogic
30 source "#{Rails.root}/config/application.yml"
31 namespace Rails.env
32 end
33
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
34 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
35 this file in a rails app is app/models/settings.rb
471adcb @binarylogic Complete rewrite, see changelog / readme
authored
36
37 I felt adding a settings file in your app was more straightforward, less tricky, and more flexible.
38
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
39 === 2. Create your settings
471adcb @binarylogic Complete rewrite, see changelog / readme
authored
40
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
41 Notice above we specified an absolute path to our settings file called "application.yml". This is just a typical YAML file.
4954925 readme doc clarifications
Nate Wiger authored
42 Also notice above that we specified a namespace for our environment. A namespace is just an optional string that corresponds
43 to a key in the YAML file.
44
45 Using a namespace allows us to change our configuration depending on our environment:
8007ac0 @binarylogic Initial commit
authored
46
ca9fd0d @stevegraham Rails.root is not app/
stevegraham authored
47 # config/application.yml
8007ac0 @binarylogic Initial commit
authored
48 defaults: &defaults
a114da8 @binarylogic Fix readme errors
authored
49 cool:
8007ac0 @binarylogic Initial commit
authored
50 saweet: nested settings
51 neat_setting: 24
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
52 awesome_setting: <%= "Did you know 5 + 5 = #{5 + 5}?" %>
08792a6 @binarylogic get with the times
authored
53
8007ac0 @binarylogic Initial commit
authored
54 development:
55 <<: *defaults
56 neat_setting: 800
57
58 test:
59 <<: *defaults
60
61 production:
62 <<: *defaults
63
08792a6 @binarylogic get with the times
authored
64 _Note_: Certain Ruby/Bundler versions include a version of the Psych YAML parser which incorrectly handles merges (the `<<` in the example above.)
9aba028 @dleavitt Added a note about YAML merges and Psych. Your library is hardly the …
dleavitt authored
65 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:
66
67 require 'yaml'
68 YAML::ENGINE.yamler= 'syck'
69
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
70 === 3. Access your settings
71
72 >> Rails.env
73 => "development"
8007ac0 @binarylogic Initial commit
authored
74
aee3f70 @binarylogic Change Setting to Settings
authored
75 >> Settings.cool
fdcf143 @binarylogic Renamed library from settingasm to settingslogic
authored
76 => "#<Settingslogic::Settings ... >"
08792a6 @binarylogic get with the times
authored
77
aee3f70 @binarylogic Change Setting to Settings
authored
78 >> Settings.cool.saweet
8007ac0 @binarylogic Initial commit
authored
79 => "nested settings"
08792a6 @binarylogic get with the times
authored
80
a431fb4 @binarylogic Fixed readme typos
authored
81 >> Settings.neat_setting
8007ac0 @binarylogic Initial commit
authored
82 => 800
08792a6 @binarylogic get with the times
authored
83
aee3f70 @binarylogic Change Setting to Settings
authored
84 >> Settings.awesome_setting
8007ac0 @binarylogic Initial commit
authored
85 => "Did you know 5 + 5 = 10?"
86
08792a6 @binarylogic get with the times
authored
87 You can use these settings anywhere, for example in a model:
4954925 readme doc clarifications
Nate Wiger authored
88
89 class Post < ActiveRecord::Base
677fccd readme doc clarifications #2
Nate Wiger authored
90 self.per_page = Settings.pagination.posts_per_page
4954925 readme doc clarifications
Nate Wiger authored
91 end
92
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
93 === 4. Optional / dynamic settings
94
95 Often, you will want to handle defaults in your application logic itself, to reduce the number of settings
96 you need to put in your YAML file. You can access an optional setting by using Hash notation:
97
98 >> Settings.messaging.queue_name
99 => Exception: Missing setting 'queue_name' in 'message' section in 'application.yml'
100
101 >> Settings.messaging['queue_name']
102 => nil
103
104 >> Settings.messaging['queue_name'] ||= 'user_mail'
105 => "user_mail"
106
107 >> Settings.messaging.queue_name
108 => "user_mail"
109
677fccd readme doc clarifications #2
Nate Wiger authored
110 Modifying our model example:
4954925 readme doc clarifications
Nate Wiger authored
111
112 class Post < ActiveRecord::Base
677fccd readme doc clarifications #2
Nate Wiger authored
113 self.per_page = Settings.posts['per_page'] || Settings.pagination.per_page
4954925 readme doc clarifications
Nate Wiger authored
114 end
08792a6 @binarylogic get with the times
authored
115
4954925 readme doc clarifications
Nate Wiger authored
116 This would allow you to specify a custom value for per_page just for posts, or
117 to fall back to your default value if not specified.
118
f108bda Fix numbering on example docs.
Winfield Peterson authored
119 === 5. Suppressing Exceptions Conditionally
6c1bd3d Document new suppress_errors option.
Winfield Peterson authored
120
121 Raising exceptions for missing settings helps highlight configuration problems. However, in a
122 Rails app it may make sense to suppress this in production and return nil for missing settings.
123 While it's useful to stop and highlight an error in development or test environments, this is
124 often not the right answer for production.
125
126 class Settings < Settingslogic
127 source "#{Rails.root}/config/application.yml"
128 namespace Rails.env
129 suppress_errors Rails.env.production?
130 end
131
132 >> Settings.non_existent_key
133 => nil
134
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
135 == Note on Sinatra / Capistrano / Vlad
136
4954925 readme doc clarifications
Nate Wiger authored
137 Each of these frameworks uses a +set+ convention for settings, which actually defines methods
138 in the global Object namespace:
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
139
140 set :application, "myapp" # does "def application" globally
141
4954925 readme doc clarifications
Nate Wiger authored
142 This can cause collisions with Settingslogic, since those methods are global. Luckily, the
143 solution is to just add a call to load! in your class:
08792a6 @binarylogic get with the times
authored
144
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
145 class Settings < Settingslogic
146 source "#{Rails.root}/config/application.yml"
147 namespace Rails.env
148 load!
149 end
150
4954925 readme doc clarifications
Nate Wiger authored
151 It's probably always safest to add load! to your class, since this guarantees settings will be
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
152 loaded at that time, rather than lazily later via method_missing.
153
4954925 readme doc clarifications
Nate Wiger authored
154 Finally, you can reload all your settings later as well:
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
155
156 Settings.reload!
157
158 This is useful if you want to support changing your settings YAML without restarting your app.
159
160 == Author
8007ac0 @binarylogic Initial commit
authored
161
c8da048 def keys as methods rather than using method_missing, added load!/rel…
Nate Wiger authored
162 Copyright (c) 2008-2010 {Ben Johnson}[http://github.com/binarylogic] of {Binary Logic}[http://www.binarylogic.com],
4954925 readme doc clarifications
Nate Wiger authored
163 released under the MIT license. Support for optional settings and reloading by {Nate Wiger}[http://nate.wiger.org].
Something went wrong with that request. Please try again.