lukeredpath-simpleconfig 1.0 → 1.0.1

data/README.textile

@@ -0,0 +1,158 @@
+Simple Config is a plugin designed to make application-wide configuration settings easy to set and access in an object-oriented fashion.
+
+Rails already provides a way of configuring the framework on a per-environment basis but other than global variables/constants set in each environment file or environment.rb, there isn't a built-in way of providing application-specific settings.
+
+One simple solution is to simply put all of your app configuration into a YAML file and load this somewhere in your environment, but here at Reevoo we wanted something a little bit more flexible that we could use across all of our applications and Simple Config is what we came up with.
+
+h2. Getting started
+
+The plugin comes with a rake task to get you up and running quickly, so start by running that.
+
+  $ rake simple_config:setup
+
+This will create a config/settings folder and a blank settings file for each of the main Rails environments. It will also create a copy of the SimpleConfig initializer  in config/initializers/configuration.rb[1].
+
+Now, if you open up the configuration.rb initializer, you will see something like this:
+
+<pre><code class="ruby">
+SimpleConfig.for :application do
+
+  # your app configuration here
+  
+  load File.join(RAILS_ROOT, 'config', "settings", "#{RAILS_ENV}.rb"), :if_exists? => true
+  load File.join(RAILS_ROOT, 'config', "settings", "local.rb"),        :if_exists? => true
+  
+end
+</code></pre>
+
+This is where you can set any configuration variables that are required across all Rails environments. The <code>load</code> method works just like Ruby's built-in load method, except the contents of the file it loads are evaluated within the context of the <code>SimpleConfig.for</code> block. The <code>:if_exists?</code> flag, when set to true, means that the file will only be loaded if it exists, otherwise it will simply be ignored.
+
+Variables can be overwritten, and are defined in the order that they are loaded, so you can set up default values in the above file and override them in the environment files.
+
+As well as loading a settings file for your current Rails environment, a file called "local.rb" is loaded which is designed as a place for you to override variables specific to your own development environment -- you can just keep a copy of this locally without having to check it into your version control system[2].
+
+h2. Variables
+
+h3. Setting Variables
+
+Setting variables is simple and will be familiar to anybody who has used Capistrano. Whether in your main <code>SimpleConfig.for</code> block in configuration.rb, or one of your external settings files, use the <code>set</code> method:
+
+<pre><code class="ruby">
+SimpleConfig.for :application do
+  set :my_variable, 'hello world'
+end
+</code></pre>
+
+SimpleConfig also supports a form of namespacing that allows you to group logical sets of variables together:
+
+<pre><code class="ruby">
+SimpleConfig.for :application do
+  group :awesome_stuff do
+    set :my_variable, 'hello world'
+  end
+end
+</code></pre>
+
+Both the <code>set</code> and <code>load</code> methods are available within <code>group</code> blocks and files loaded inside groups will be evaluated in the context of that group.
+
+Whilst I'd recommend not nesting your groups more than one-level, there is no limit on how deep they can be nested.
+
+h3. Unsetting variables
+
+Sometimes you might want to completely delete a variable from the collection. Simply setting its value to nil doesn't work because <code>nil</code> might be a valid value.
+You can delete a variable using the <code>unset</code> method.
+
+<pre><code class="ruby">
+SimpleConfig.for :application do
+  set :my_variable, 'hello world'
+  
+  ...
+  
+  unset :my_variable
+end
+</code></pre>
+
+For instance, this is useful to remove global settings at environment level instead of overwriting the default value with a nonsense-one.
+<code>unset</code> returns the value of the variable just in case you need to use it elsewhere.
+
+h3. Does a specific variable exist?
+
+I don't know but you can check it yourself using <code>exists?</code> method.
+
+<pre><code class="ruby">
+config = SimpleConfig.for :application do
+  set :my_variable, 'hello world'
+end
+
+# write some nice code 
+config.exists? :my_variable     # => true
+config.exists? :your_variable   # => false
+</code></pre>
+
+h2. Accessing your configuration
+
+SimpleConfig allows you set as many separate configurations as you like using the <code>SimpleConfig.for</code> method, which takes a symbol representing the configuration name, although most people will just create a single "application" config as above. To access this config from anywhere in your application, you can also use <code>SimpleConfig.for</code> method without a block, which always returns the named configuration object.
+
+It is worth pointing out that <code>SimpleConfig.for</code> provides an almost singleton-style access to a particular named config. Calling <code>SimpleConfig.for</code> with a block a second time for a particular named configuration will simply extend the existing configuration, not overwrite it.
+
+Once you have a reference to your configuration object, you can access variables using method access. Given the above example, <code>:my_variable</code> would be accessed in the following way:
+
+<pre><code class="ruby">
+config = SimpleConfig.for(:application)
+config.my_variable # => "hello world"
+</code></pre>
+
+Accessing grouped variables works as you would expect:
+
+<pre><code class="ruby">
+config = SimpleConfig.for(:application)
+config.awesome_stuff.my_variable # => "hello world"
+</code></pre>
+
+h2. Using your configuration in your Rails app
+
+The plugin provides a convenient mixin for your <code>ApplicationController</code> to make configuration access as simple as possible. Assuming a configuration called "application" (as in the above examples), it defines a <code>config</code> method which can be used in any of your controllers. It also defines this as a method as a view helper using the Rails <code>helper_method</code> macro so you can access configuration data in your views. 
+
+Note - there is no direct way of accessing your configuration variables in your models other than making a direct call to <code>SimpleConfig.for</code>. I'd recommend designing your models in such a way that configuration data can be passed into them at runtime as method arguments by your controller to avoid coupling your model to SimpleConfig.
+
+To use the mixin, simply include it in your <code>ApplicationController</code>:
+
+<pre><code class="ruby">
+class ApplicationController < ActionController::Base
+  include SimpleConfig::ControllerMixin
+end
+</code></pre>
+
+Then in your controllers:
+
+<pre><code class="ruby">
+class MyController < ApplicationController
+  def index
+    render :text => config.my_config_variable
+  end
+end
+</code></pre>
+
+The mixin provides also a class-level <code>config</code> method to access the configuration when you don't have a controller instance available.
+
+<pre><code class="ruby">
+class MyController < ApplicationController
+  protect_from_forgery :secret => config.secret_token
+
+  def index
+    render :text => config.my_config_variable
+  end
+end
+</code></pre>
+
+
+fn1(footnote). SimpleConfig was designed with Rails 2.0 in mind but it has been tested with Rails 1.2. To use the Rails-style initializers that SimpleConfig takes advantage of in Rails 1.2, simply add this to the bottom of your environment.rb file:
+
+<pre><code class="ruby">
+# backported Rails 2.x initializer folder functionality
+Dir[File.join(RAILS_ROOT, 'config', 'initializers', '*.rb')].each do |initializer|
+  load initializer
+end
+</code></pre>
+
+fn2(footnote). In fact, I recommend you make sure your version control system ignores this file otherwise you risk checking in a file that will override values in production! If you are using Subversion, simply add local.rb to the svn:ignore property for the config/settings folder.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the simpleconfig plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the simpleconfig plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Simpleconfig'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/rails_compatibility.rb

@@ -0,0 +1,7 @@
+unless Rails.respond_to?(:env)
+  Rails.instance_eval do
+    def env
+      RAILS_ENV
+    end
+  end
+end

data/lib/simple_config/utilities.rb

@@ -20,8 +20,8 @@ module SimpleConfig
       end
 
       def to_uri(uri_options = {})
-        options = uri_options.except(:host, :port)
-        URI::Generic.build(options.reverse_merge(:host => name, :port => port, :scheme => default_uri_scheme))
+        [:host, :port].each { |opt| uri_options.delete(opt) }
+        URI::Generic.build({:host => name, :port => port, :scheme => default_uri_scheme}.merge(uri_options))
       end
 
       def url_for_path(path)

data/lib/simple_config.rb

@@ -1,5 +1,14 @@
 require 'yaml'
 
+unless defined?(Rails)
+  class Object
+    def returning(object, &block)
+      yield object if block_given?
+      object
+    end
+  end
+end
+
 module SimpleConfig
   
   class << self
@@ -92,7 +101,7 @@ module SimpleConfig
     end
     
     def load(external_config_file, options={})
-      options.reverse_merge!(:if_exists? => false)
+      options = {:if_exists? => false}.merge(options)
       
       if options[:if_exists?]
         return unless File.exist?(external_config_file)

data/rails/init.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), *%w[.. lib])
+
+require 'rails_compatibility' 
+require 'simple_config'
+require 'controller_mixin'

data/tasks/simple_config.rake

@@ -0,0 +1,22 @@
+require 'fileutils'
+
+namespace :simple_config do
+  include FileUtils
+  
+  task :setup do
+    raise "This task should be run from within a Rails application." unless File.exist?('config')
+    raise "Already found config/settings. Have you already run this task?." if File.exist?('config/settings')
+    
+    mkdir('config/settings')
+    mkdir("config/initializers") unless File.exist?("config/initializers")
+    
+    Dir["config/environments/*.rb"].each do |f|
+      env = File.basename(f, ".rb")
+      touch("config/settings/#{env}.rb")
+    end
+    
+    cp(File.join(File.dirname(__FILE__), *%w[.. templates configuration.rb]), 
+        "config/initializers/configuration.rb")
+  end  
+  
+end

data/templates/configuration.rb

@@ -0,0 +1,8 @@
+SimpleConfig.for :application do
+
+  # your app configuration here
+  
+  load File.join(RAILS_ROOT, 'config', "settings", "#{RAILS_ENV}.rb"), :if_exists? => true
+  load File.join(RAILS_ROOT, 'config', "settings", "local.rb"),        :if_exists? => true
+  
+end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: lukeredpath-simpleconfig
 version: !ruby/object:Gem::Version 
-  version: "1.0"
+  version: 1.0.1
 platform: ruby
 authors: 
 - Luke Redpath
-autorequire: 
+autorequire: simple_config
 bindir: bin
 cert_chain: []
 
@@ -25,6 +25,12 @@ files:
 - lib/simple_config.rb
 - lib/controller_mixin.rb
 - lib/simple_config/utilities.rb
+- lib/rails_compatibility.rb
+- rails/init.rb
+- Rakefile
+- README.textile
+- tasks/simple_config.rake
+- templates/configuration.rb
 has_rdoc: false
 homepage: http://github.com/lukeredpath/simpleconfig
 post_install_message: