dynamic_configuration 0.1.6 → 0.2.0

data/README.markdown

@@ -1,4 +1,4 @@
-# dynamic_configuration: Application configuration made easy
+# dynamic_configuration
 
 Rails made great innovations in almost all areas of web application
 development, yet it surprisingly does not provide any means for
@@ -10,48 +10,168 @@ differentiate dynamic_configuration from other configuration plugins:
 
  * configuration files are very clean-looking Ruby files
 
- * the configuration is automatically reloaded in Rails development environment
+ * in Rails development environment, one doesn't have to restart the
+   server to add/remove/modify a setting
 
- * the settings are divided into groups, with each group living in a
+ * the settings are divided into groups, each group being defined in a
    separate file, making it easier to remember individual setting
    names and maintain the whole configuration
 
- * settings can be overridden locally for a given installation and
-   per-Rails-environment
+ * settings can be overridden per-Rails-environment and locally for a
+   given installation (useful for customizing the configuration
+   per-server, while keeping the core settings in Git)
 
  * throughout field- and unit- tested
 
+Developed as part of my work for http://www.tutoria.de/.
+
 ## Setup
 
 ### Rails 3 application:
 
 Add the gem to your Gemfile:
 
-    gem 'dynamic_configuration'
+```ruby
+gem 'dynamic_configuration'
+```
 
-Create a config/options directory, in it a config/options.rb file with
-the following contents:
+Create a config/options directory, then a config/options/options.rb
+file with the following contents:
 
-    DynamicConfiguration::create(:Options, File.join(Rails.root, "config/options"))
+```ruby
+DynamicConfiguration::create(:Options, File.join(Rails.root, "config/options"))
+```
 
 Require config/options/options.rb somewhere in your
 config/application.rb, like this:
 
-    module SomeApplication
-      class Application < Rails::Application
-        require "config/options/options"
+```ruby
+module SomeApplication
+  class Application < Rails::Application
+    require "config/options/options"
         
-        # ..., rest of the config
-      end
-    end
+    # ..., rest of the config
+  end
+end
+```
 
 ### Ruby application:
 
-Create a directory where you want to store the options, e. g.
-options/, and put the following before your application initialization
-code:
-
-    DynamicConfiguration::create(:Options, "/path/to/options")
+Create a subdirectory of your project directory where you want to
+store the options, e. g. options/, and put the following before your
+application initialization code:
 
+```ruby
+DynamicConfiguration::create(:Options, "options/")
+```
 
 ## Usage
+
+### Basics
+
+You create a settings group by creating a file somewhere in the
+options directory, to see how it works, create options/main.rb and
+define a single setting in it:
+
+```ruby
+# config/options/main.rb
+a_string "sample value"
+```
+
+This will make Options.main.a_string evaluate to "sample value"
+anywhere in your application:
+
+```ruby
+Options.main.a_string
+=> "sample value"
+```
+
+The name of the group of options is set to be the same as the base
+name of the file, so if you create emails.rb, the settings will be
+accessible as Options.emails.whatever_you_define etc.
+
+The value of each settings can be any kind of Ruby object, so the
+following is a valid config file:
+
+```ruby
+# config/options/main.rb
+a_string "Some string"
+
+an_array [1, 2, 3]
+
+a_fancy_string_array(%w{
+string1
+string2
+})
+```
+
+Which you can use in other places of your application like this:
+
+```ruby
+Options.main.a_string
+=> "Some string"
+Options.main.an_array
+=> [1, 2, 3]
+Options.main.a_fancy_string_array
+=> ["string1", "string2"]
+```
+
+Note that hash map values have to be wrapped in parenthesis, since
+defining a setting works under the hood as a Ruby method call, so it
+has to have the syntax of one.
+
+### Overriding settings per Rails environment ###
+
+To overwrite the settings for a given Rails environment, just create a
+subdirectory of the options directory named after the name of the
+environment, for example config/options/test/. Then create a file
+corresponding to the group of settings of which one or more you want
+to override. For example, if config/options/main.rb looks like above,
+and you create config/options/test/main.rb looking like this:
+
+```ruby
+# config/options/test/main.rb
+a_string "Test"
+```
+
+Then Options.main.a_string will evaluate to "Test" in the test
+environment, while all the other Options.main settings will evaluate
+to their values defined in config/options/main.rb.
+
+### Overriding settings locally ###
+
+This is mostly meant for applications that are stored in a version
+control system and on which multiple persons work. One can keep the
+core settings in config/options, and also create a
+config/options/local directory, that can be svn ignore'd or added to
+.gitignore. If then someone wants to override some setting just on a
+particular server or just on his local development environment, he/she
+can create a file corresponding to the group of settings of which one
+or more he/she wants to override, for example
+config/options/local/main.rb:
+
+```ruby
+# config/options/local/main.rb
+an_array [4, 5, 6]
+```
+
+Then, Options.main.an_array will evaluate to [4, 5, 6] regardless of
+Rails environment and other Options.main settings will be evaluated
+according to their per-Rails-environment definitions if present, or
+according to their global definitions in config/options/main.rb
+otherwise.
+
+## Robustness ##
+
+dynamic_configuration overwrites method_missing in the context of the
+configuration files to enable the syntax it provides. It doesn't do
+anything to method_missing globally, nor does it do any other "magic"
+that could affect any piece of your application other then the
+configuration files themselves.
+
+All the settings are frozen as soon as they are defined, so you won't
+accidentally modify them. If you try to access a settings group that
+wasn't defined, you will get an
+DynamicConfiguration::MissingGroupException, if you try to access a
+setting that isn't defined of a group that _is_ defined, you will get
+a DynamicConfiguration::MissingGroupException.

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.2.0

data/dynamic_configuration.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dynamic_configuration}
-  s.version = "0.1.6"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Jarosław Rzeszótko}]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamic_configuration
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: builder
-  requirement: &81569210 !ruby/object:Gem::Requirement
+  requirement: &76717450 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *81569210
+  version_requirements: *76717450
 description: Flexible configuration library for Ruby and Rails applications.
 email: jrzeszotko@gmail.com
 executables: []