active_configuration 1.0.0

data/README.md

@@ -0,0 +1,133 @@
+# ActiveConfiguration
+
+ActiveConfiguration is an engine that exposes a generic settings store to 
+ActiveRecord models. Made for very configurable applications, it allows you 
+to avoid implementing specific ways to store settings for each model that 
+needs such a configuration. If your application isn't very configurable, 
+ActiveConfiguration isn't what you want.
+
+If you had a `Category` model that only had a configurable `sort` attribute, 
+ActiveConfiguration would be overkill. Rather, you would just read and write 
+values using a specific `sort` column and restrict the allowed values using 
+something like `validates_inclusion_of`.
+
+However, if your `Category` model was more flexible in its configuration, you 
+may want a `sort` setting, a `limit` setting and multiple `price_filter` 
+settings that can be configured by your end user. Without ActiveConfiguration, 
+you would have to develop a way to store and validate these settings for this 
+specific scenario. The `sort` and `limit` settings are simple but because 
+`price_filter` can accept multiple rules, you'd have to set up an additional 
+model. Still, this isn't really an issue when you're dealing with just a single 
+configurable model. When you're dealing with many, things tend to get messy.
+
+With ActiveConfiguration, all of your settings, even for `price_filter`, can 
+be stored in a generic way. ActiveConfiguration provides a place to store 
+settings for each of your models and even handles validation when you restrict 
+the allowed values or format of an option.
+
+## Source
+
+The source for this engine is located at:
+
+	http://github.com/tsmango/active_configuration
+
+## Installation
+
+Add the following to your Gemfile:
+
+	gem 'active_configuration'
+
+Generate the migration for the `settings` table:
+
+	rails g active_configuration:install
+
+Note: The table can be changed from `settings` to something else by specifying 
+a config option in an initializer like:
+
+	# config/initializers/active_configuration.rb
+	
+	Rails.configuration.active_configuration_table_name = 'active_configuration_settings'
+
+Migrate your database:
+
+	rake db:migrate
+
+## Example Configuration
+
+	class Category < ActiveRecord::Base
+		configure do
+			option :sort do
+				default  'alphabetical'
+				restrict 'alphabetical', 'manual'
+			end
+			
+			option :limit do
+				format 'fixnum'
+			end
+			
+			option :price_filter do
+				format    'float'
+				modifiers 'eq', 'lt', 'gt', 'lte', 'gte'
+				multiple  true
+			end
+		end
+	end
+
+After installing ActiveConfiguration, the #configure block is available to 
+every ActiveRecord model. If the #configure block is defined with a valid 
+configuration, additional methods are made available on the model.
+
+## Example Usage
+
+Given we have defined the `Category` class above, instances will now have a #settings 
+method where settings can be read from and written to.
+
+	>> category = Category.create(:name => 'Vinyl Records')
+	=> #<Category id: 1, name: "Vinyl Records", created_at: "2011-08-03 15:46:11", updated_at: "2011-08-03 15:46:11">
+	
+	?> category.settings
+	=> #<ActiveConfiguration::SettingManager:0x10e7d1950 @configurable=#<Category id: 1, name: "Vinyl Records", created_at: "2011-08-03 15:46:11", updated_at: "2011-08-03 15:46:11">>
+	
+	?> category.settings[:sort]
+	=> {:value=>"alphabetical", :modifier=>nil}
+	
+	?> category.settings[:sort][:value]
+	=> "alphabetical"
+	
+	?> category.settings[:sort][:value] = 'manual'
+	=> "manual"
+	
+	?> category.settings[:price_filter]
+	=> []
+	
+	?> category.settings[:price_filter] = [{:modifier => 'gt', :value => 10.00}, {:modifier => 'lte', :value => 25.00}]
+	=> [{:value=>10.0, :modifier=>"gt"}, {:value=>25.0, :modifier=>"lte"}]
+	
+	?> category.save
+	=> true
+	
+	?> category.settings[:sort][:value]
+	=> "manual"
+	
+	?> category.settings[:price_filter]
+	=> [{:value=>10.0, :modifier=>"gt"}, {:value=>25.0, :modifier=>"lte"}]
+
+Note:
+
+Settings are only committed after a `save` of the configurable model. If any 
+validation errors should arise, the `save` on the model will return false and 
+errors will be added to the model's errors collection.
+
+## Testing Environment
+
+The spec/ directory contains a skeleton Rails 3.0.0 application for testing 
+purposes. All specs can be found in spec/spec/.
+
+To run the specs, do the following from the root of active\_configuration:
+
+	bundle install --path=vendor/bundles --binstubs
+	bin/rspec spec
+
+## License
+
+Copyright &copy; 2011 Thomas Mango, released under the MIT license.

data/app/models/active_configuration/setting.rb

@@ -0,0 +1,35 @@
+module ActiveConfiguration
+
+  # Holds the details of a Setting and is attached to any model configured
+  # for use with ActiveConfiguration.
+  #
+  # Note: Settings are not meant to be created and updated directly.
+  # Rather, they should be managed through the #settings method available
+  # through the configured model. See ActiveRecord::Configuration.
+  class Setting < ActiveRecord::Base
+
+    # To avoid collisions with another Setting model that isn't from
+    # ActiveConfiguration, this model and table is namespaced.
+    set_table_name ActiveConfiguration::Config.table_name
+
+    # The model this Setting was created against.
+    belongs_to :configurable, :polymorphic => true
+
+    # Settings are looked up from their key.
+    scope :with_key, lambda { |key|
+      where(:key => key.to_s)
+    }
+
+    # Settings should be created through a configured model's
+    # #active_configuration_settings relationship.
+    attr_protected :configurable_type
+    attr_protected :configurable_id
+
+    # Settings must be related to some other model, have a key
+    # and have a value. They do not necessarily need a modifier.
+    validates_presence_of :configurable_type
+    validates_presence_of :configurable_id
+    validates_presence_of :key
+    validates_presence_of :value
+  end
+end

data/lib/active_configuration/base.rb

@@ -0,0 +1,38 @@
+require 'active_configuration/option'
+
+module ActiveConfiguration
+
+  # Holds a set of configuration details. An instance of this object is created
+  # when the #configure block is used on an ActiveRecord model. For more details
+  # see ActiveRecord::Configuration#configure.
+  class Base
+    attr_accessor :options
+
+    # Initializes an empty options hash to store ActiveConfiguration::Option
+    # instances containing configuration details.
+    def initialize
+      @options = HashWithIndifferentAccess.new
+    end
+
+    # Creates and accepts the configuration details for an Option.
+    #
+    # An example of setting an option with a block:
+    #
+    #   option :sort do
+    #     default  'alphabetical'
+    #     restrict 'alphabetical', 'manual'
+    #   end
+    #
+    # Here, the #option method is called and passed the key of :sort and then the
+    # the block that follows. The block given to #option is then evaluated against
+    # a new instance of ActiveConfiguration::Option.
+    #
+    # @param [Symbol] key the key for this option and settings against this option.
+    # @param [Proc] block what should be evaluated against the option.
+    def option(key, &block)
+      opt = Option.new(key)
+      opt.instance_eval(&block)
+      @options[key.to_sym] = opt
+    end
+  end
+end

data/lib/active_configuration/engine.rb

@@ -0,0 +1,4 @@
+module ActiveConfiguration
+  class Engine < Rails::Engine
+  end
+end

data/lib/active_configuration/error.rb

@@ -0,0 +1,3 @@
+module ActiveConfiguration
+  class Error < RuntimeError; end
+end

data/lib/active_configuration/option.rb

@@ -0,0 +1,129 @@
+require 'active_configuration/error'
+
+module ActiveConfiguration
+
+  # Holds the configuration details of a single option. An instance of this
+  # object is created when the #option block is used within a #configure block.
+  class Option
+
+    # ActiveSupport::Callbacks are included so that the #validate! method can
+    # be automaticalled called after each modification to this option.
+    include ActiveSupport::Callbacks
+
+    # There is a callback called :validate that should be watched.
+    define_callbacks :validate
+
+    # After the :validate callback, execute the #validate! method.
+    set_callback :validate, :after, :validate!
+
+    attr_accessor :key, :default_value, :allowed_format, :allowed_values, :allowed_modifiers, :allow_multiple
+
+    alias :allow_multiple? :allow_multiple
+
+    # Initializes the default values for all deatils of this options. This
+    # includes no default value, no restricted values set, no modifiers,
+    # and a 'string' format.
+    #
+    # @param [Symbol] key the key for this option and settings against this option.
+    def initialize(key)
+      @key               = key
+      @default_value     = nil
+      @allowed_format    = 'string'
+      @allowed_values    = nil
+      @allowed_modifiers = nil
+      @allow_multiple    = false
+    end
+
+    # Sets the default value for this option. This cannot be used in
+    # conjunction with the multiple options. Additionally, if a set
+    # of allowed values is set with the #restrict method, this default
+    # value must appear in that list of allowed values.
+    #
+    # @param value the value to be used as the default for this option.
+    def default(value)
+      run_callbacks :validate do
+        @default_value = (value.is_a?(Symbol) ? value.to_s : value)
+      end
+    end
+
+    # Sets a specific format that the value of this option must conform
+    # to. Allowed formats include: 'string', 'fixnum', 'float',  'boolean',
+    # 'email', 'url' or a /regular expression/.
+    #
+    # @param [String, Regexp] value the format this option must be given in.
+    def format(value)
+      run_callbacks :validate do
+        @allowed_format = (value.is_a?(Symbol) ? value.to_s : value)
+      end
+    end
+
+    # Restricts the allowed values of this option to a given list of values.
+    #
+    # Example:
+    #
+    #   restrict 'alphabetical', 'manual'
+    #
+    # @param [Array] values the allowsed values for this option.
+    def restrict(*values)
+      run_callbacks :validate do
+        @allowed_values = values.collect{|value| (value.is_a?(Symbol) ? value.to_s : value)}
+      end
+    end
+
+    # Restricts the allows modifiers of this option to a given list of modifers.
+    #
+    # Example:
+    #
+    #   modifiers 'eq', 'lt', 'gt', 'lte', 'gte'
+    #
+    # @param [Array] values the allowed modifiers for this option
+    def modifiers(*values)
+      run_callbacks :validate do
+        @allowed_modifiers = values.collect{|value| (value.is_a?(Symbol) ? value.to_s : value)}
+      end
+    end
+
+    # Whether or not this option can have multiple settings set against it.
+    #
+    # @param [TrueClass, FalseClass] value either true or false for whether
+    #   this option should allow multiple settings or not.
+    def multiple(value)
+      run_callbacks :validate do
+        @allow_multiple = value
+      end
+    end
+
+    # Validates how the specified configuration options are used with one
+    # another. If an invalid configuration is detected, such as using both
+    # the #default method and setting #multiple to true, an exception of
+    # ActiveConfiguration::Error is raised.
+    #
+    # Note: This method is automatically called after each of the
+    # configuration methods are run.
+    def validate!
+
+      # If both a default value and a list of allowed values are given,
+      # the default value must appear in the list of allowed values.
+      if !@default_value.nil? and !@allowed_values.nil? and !@allowed_values.include?(@default_value)
+        raise ActiveConfiguration::Error, "The default value '#{@default_value}' isn't present in the list of allowed values."
+      end
+
+      # If multiple is set, it must be set to either true or false.
+      if ![TrueClass, FalseClass].include?(@allow_multiple.class)
+        raise ActiveConfiguration::Error, 'The multiple option requires a boolean.'
+      end
+
+      # If a default value is given, multiple must be false.
+      if !@default_value.nil? and @allow_multiple
+        raise ActiveConfiguration::Error, 'The default value cannot be set in combination with the multiple option.'
+      end
+
+      # If a format is specified, it must be an allowed format. This
+      # includes 'string', 'fixnum', 'float', 'boolean', 'email', 'url'
+      # or a /regular exprssion.
+      if !@allowed_format.nil? and !['string', 'fixnum', 'float', 'boolean', 'email', 'url'].include?(@allowed_format) and !@allowed_format.is_a?(Regexp)
+        raise ActiveConfiguration::Error, "The format #{@allowed_format} is not supported."
+      end
+    end
+  end
+end

data/lib/active_configuration/setting_manager.rb

@@ -0,0 +1,94 @@
+require 'active_configuration/setting_proxy'
+
+module ActiveConfiguration
+
+  # Returns a SettingProxy object for any option that has been configured.
+  class SettingManager
+    attr_accessor :configurable
+    attr_accessor :settings
+
+    # Initializes this SettingManager and keeps track of what model this
+    # SettingManager is proxying settings for.
+    #
+    # @param [ActiveRecord::Base] configurable the model that hsa been
+    #   configured for use with ActiveConfiguration.
+    def initialize(configurable)
+      @configurable = configurable
+      @settings     = Hash.new
+    end
+
+    # Provides access to setting details for a setting at the given key.
+    #
+    # @param [Symbol] key the key of the requested setting.
+    #
+    # @return [Hash, Array, NilClass] the Hash or Array of Hashes for the
+    #   setting with the given key or nil if there isn't a match.
+    def [](key)
+      if @configurable.class.configuration.options.has_key?(key)
+        @settings[key] ||= SettingProxy.new(self, key)
+
+        return @settings[key].value
+      end
+
+      return nil
+    end
+
+    # Replaces the Hash or Array of Hashes for the setting with the given
+    # key with the given value.
+    #
+    # @param [Symbol] key the key of the requested setting.
+    #
+    # @return [Hash, Array, NilClass] the Hash or Array of Hashes for the
+    #   setting with the given key or nil if there isn't a match.
+    def []=(key, value)
+      if @configurable.class.configuration.options.has_key?(key)
+        @settings[key] ||= SettingProxy.new(self, key)
+        @settings[key].replace(value)
+
+        return @settings[key].value
+      end
+
+      return nil
+    end
+
+    # Writes over multiple settings at once.
+    #
+    # @param [Hash] replacement_settings the has of settings to be set.
+    def write_settings(replacement_settings = {})
+      replacement_settings.each_pair do |key, value|
+        self[key] = value
+      end
+    end
+
+    # Runs validations against all settings with pending modificaitons.
+    # Any errors are added to @configurable.errors[:settings].
+    def validate
+      settings.values.collect{|setting| setting.validate}
+    end
+
+    # Saves all settings with pending modificaitons.
+    #
+    # @return [Boolean] whether or not the save was successful.
+    def save
+      return !settings.values.collect{|setting| setting.save}.include?(false)
+    end
+
+    # Writes over multiple settings and saves all setting updates at once.
+    #
+    # @param [Hash] replacement_settings the has of settings to be set.
+    #
+    # @return [Boolean] whether or not the save was successful.
+    def update_settings(replacement_settings = {})
+      write_settings(replacement_settings)
+
+      validate
+
+      return (@configurable.errors[:settings].empty? ? save : false)
+    end
+
+    # Resets any pending setting modifications.
+    def reload
+      @settings = Hash.new
+    end
+  end
+end

data/lib/active_configuration/setting_proxy.rb

@@ -0,0 +1,202 @@
+require 'active_configuration/error'
+
+module ActiveConfiguration
+
+  # Handles the reading and writing of ActiveConfiguration::Setting objects
+  # and ensures configuration requirements are upheld.
+  class SettingProxy
+    attr_accessor :manager
+    attr_accessor :key
+    attr_accessor :value
+
+    # Initializes a new ActiveConfiguration::SettingProxy with a related
+    # SettingManager and a key for this setting. This setting's modifiers
+    # and values are cached locally as either a Hash or an Array for later
+    # access and manipulation.
+    #
+    # @param [ActiveConfiguration::SettingManager] manager the manager which
+    #   holds this SettingProxy and has access to the configurable object that
+    #   this setting will be attached to.
+    # @param [Symbol] key the key for this setting and its related option.
+    def initialize(manager, key)
+      @manager, @key = manager, key
+
+      if settings = @manager.configurable.active_configuration_settings.with_key(@key).all
+        if option.allow_multiple?
+          @value = settings.collect{|setting| {:value => coerce(setting.value), :modifier => setting.modifier}}
+
+        else
+          setting = settings.first
+
+          @value = {
+            :modifier => (setting ? setting.modifier : nil),
+            :value    => coerce(setting ? setting.value : option.default_value)
+          }
+        end
+      end
+    end
+
+    # Replaces the underlying Hash or Array with a replacement. This handles
+    # reverting to defaults when nil is given as the value.
+    #
+    # Note: Athough Hashes given may contain keys other than :modifier and
+    # :value, all other keys will be stripped out and not saved.
+    #
+    # @raise [ArgumentError] if a Hash, Array or NilClass isn't given for a
+    #   multiple option.
+    # @raise [ArgumentError] if a Hash or NilClass isn't given for a non-multiple
+    #   option.
+    #
+    # @param [Hash] value_with_modifier the Hash or Array of Hashes containing
+    #   modifier and value pairs.
+    #
+    # @return [Hash, Array] the requested change.
+    def replace(value_with_modifier)
+      if option.allow_multiple?
+        if value_with_modifier.is_a?(Hash) or value_with_modifier.is_a?(Array) or value_with_modifier.is_a?(NilClass)
+          value_with_modifier = [value_with_modifier].flatten.collect{|value_with_modifier| {:modifier => nil, :value => nil}.merge(value_with_modifier.nil? ? {} : value_with_modifier.slice(*[:modifier, :value]))}
+          value_with_modifier.delete({:modifier => nil, :value => nil})
+        else
+          raise ArgumentError, "Array expected."
+        end
+      else
+        if value_with_modifier.is_a?(Hash) or value_with_modifier.is_a?(NilClass)
+          value_with_modifier = {:modifier => nil, :value => nil}.merge(value_with_modifier.nil? ? {:value => coerce(option.default_value)} : value_with_modifier.slice(*[:modifier, :value]))
+        else
+          raise ArgumentError, "Hash expected."
+        end
+      end
+
+      return (@value = value_with_modifier)
+    end
+
+    # Checks modifiers and values on this setting for validation errors and, if
+    # found, adds those errors to this proxy's model's collection of errors.
+    def validate
+      errors = Array.new
+
+      [value].flatten.each do |value_with_modifier|
+        value    = value_with_modifier[:value]
+        modifier = value_with_modifier[:modifier]
+
+        if !option.allowed_values.nil? and !option.allowed_values.include?(value)
+          errors << "The value '#{value}' for the '#{option.key}' setting isn't present in the list of allowed values."
+        end
+
+        if !option.allowed_format.nil?
+          case option.allowed_format
+          when 'string'
+            if !value.is_a?(String)
+              errors << "The value '#{value}' for the '#{option.key}' setting is not a String."
+            end
+          when 'fixnum'
+            if !value.is_a?(Fixnum)
+              errors << "The value '#{value}' for the '#{option.key}' setting is not a Fixnum."
+            end
+          when 'float'
+            if !value.is_a?(Float) and !value.is_a?(Fixnum)
+              errors << "The value '#{value}' for the '#{option.key}' setting is not a Float."
+            end
+          when 'boolean'
+            if !value.is_a?(TrueClass) and !value.is_a?(FalseClass)
+              errors << "The value '#{value}' for the '#{option.key}' setting is not a Boolean."
+            end
+          when 'email'
+            if !value[/^[A-Z0-9_\.%\+\-\']+@(?:[A-Z0-9\-]+\.)+(?:[A-Z]{2,4}|museum|travel)$/i]
+              errors << "The value '#{value}' for the '#{option.key}' setting is not an Email Address."
+            end
+          when 'url'
+            if !value[URI.regexp]
+              errors << "The value '#{value}' for the '#{option.key}' setting is not a URL."
+            end
+          end
+
+          if option.allowed_format.is_a?(Regexp) and !value[option.allowed_format]
+            errors << "The value '#{value}' for the '#{option.key}' setting is not in the correct format."
+          end
+        end
+
+        if !modifier.nil? and !option.allowed_modifiers.nil? and !option.allowed_modifiers.include?(modifier)
+          errors << "The modifier '#{modifier}' for the '#{option.key}' setting isn't present in the list of allowed modifiers."
+        end
+      end
+
+      errors.each do |error|
+        @manager.configurable.errors.add(:settings, error)
+      end
+    end
+
+    # Saves this setting's modifiers and values.
+    #
+    # @return [Boolean] whether or not the save was successful.
+    def save
+      save_status = true
+      original_setting_ids = @manager.configurable.active_configuration_settings.with_key(@key).collect(&:id)
+      replaced_setting_ids = []
+
+      [value].flatten.each do |value_with_modifier|
+        if (setting = @manager.configurable.active_configuration_settings.create(:key => @key, :modifier => value_with_modifier[:modifier], :value => value_with_modifier[:value])).new_record?
+          save_status = false && break
+        else
+          replaced_setting_ids << setting.id
+        end
+      end
+
+      @manager.configurable.active_configuration_settings.reload
+      @manager.configurable.active_configuration_settings.with_key(@key).where(:id => (save_status ? original_setting_ids : replaced_setting_ids)).destroy_all
+
+      @manager.settings.delete(@key)
+
+      return save_status
+    end
+
+    # Returns the Hash or Array representation of the underlying stored settings 
+    # depending on whether or not this is a multiple option.
+    # 
+    # @return [Hash] the value and modifier, as a Hash, for a non-multiple
+    #   option.
+    # @return [Array] the array of hashes containing value and modifiers, like
+    #   those returned on a non-multiple options, for a multiple option.
+    def inspect
+      return @value.inspect
+    end
+
+    private
+
+    # Returns this SettingProxy's related Option based on the given key. This
+    # is necessary to ensure all configuration requirements are upheld during
+    # reads and writes.
+    #
+    # @return [ActiveConfiguration::Option] the option for this setting.
+    def option
+      return @manager.configurable.class.configuration.options[key]
+    end
+
+    # Coerces a stored String value into the expected type if an allowed format
+    # is explicitly set on this setting's option.
+    #
+    # Note: Because values are validated against given formats when updated,
+    # it is assumed that they can be properly coerced back to their intended
+    # type.
+    #
+    # @param [String] value the value stored in the database that must be coerced.
+    #
+    # @return [String, Fixnum, Float, TrueClass, FalseClass] the properly coerced
+    #   value, assuming the value should be coerced.
+    def coerce(value)
+      if !value.nil? and !option.allowed_format.nil?
+        case option.allowed_format
+        when 'fixnum'
+          value = value.to_i
+        when 'float'
+          value = value.to_f
+        when 'boolean'
+          value = true  if (value == 'true'  or value == 't')
+          value = false if (value == 'false' or value == 'f')
+        end
+      end
+
+      return value
+    end
+  end
+end

data/lib/active_configuration/table_name.rb

@@ -0,0 +1,20 @@
+module ActiveConfiguration
+
+  # Holds the configuration details of this ActiveConfiguration install.
+  class Config
+
+    # Returns the name of the table holding ActiveConfiguration::Settings. This
+    # table defaults to `settings` but can be changed with an initializer like:
+    #
+    #     Rails.configuration.active_configuration_table_name = 'active_configuration_settings'
+    #
+    # @return [String] the table name holding ActiveConfiguration::Settings.
+    def self.table_name
+      if Rails.configuration.respond_to?(:active_configuration_table_name)
+        return Rails.configuration.active_configuration_table_name
+      end
+
+      (Rails.configuration.active_configuration_table_name = 'settings')
+    end
+  end
+end

data/lib/active_configuration/version.rb

@@ -0,0 +1,10 @@
+module ActiveConfiguration
+  class Version
+    MAJOR = 1
+    MINOR = 0
+    PATCH = 0
+    BUILD = nil
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end

data/lib/active_configuration.rb

@@ -0,0 +1,7 @@
+require 'active_configuration/engine'
+require 'active_configuration/table_name'
+require 'active_record/configuration'
+
+ActiveRecord::Base.class_eval do
+  include ActiveRecord::Configuration
+end

data/lib/active_record/configuration.rb

@@ -0,0 +1,145 @@
+require 'active_configuration/base'
+require 'active_configuration/setting_manager'
+require 'active_configuration/error'
+
+module ActiveRecord
+
+  # Exposes a #configure method to all ActiveRecord classes and if configured,
+  # defines a #settings method for reading and writing settings.
+  module Configuration
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Configures the current ActiveRecord class to allow specific options.
+      # After being configured, a #settings method will be defined against
+      # all instances as well as a has_many :active_configuration_settings
+      # relationship for storing settings.
+      #
+      # Example configuration:
+      #
+      #   class Category < ActiveRecord::Base
+      #     configure do
+      #       option :sort do
+      #         default  'alphabetical'
+      #         restrict 'alphabetical', 'manual'
+      #       end
+      #
+      #       option :limit do
+      #         format 'fixnum'
+      #       end
+      #
+      #       option :price_filter do
+      #         format    'float'
+      #         modifiers 'eq', 'lt', 'gt', 'lte', 'gte'
+      #         multiple  true
+      #       end
+      #     end
+      #   end
+      #
+      # The #configure block can only contain #option blocks. Within each
+      # option block may be a number of methods such as:
+      #
+      # * default
+      #     A default value. Cannot be used in conjunction with multiple.
+      #
+      # * format -
+      #   A specific format, including: 'string', 'fixnum', 'float',
+      #   'boolean', 'email', 'url' or a /regular expression/. Defaults
+      #   to 'string'.
+      #
+      # * restrict -
+      #   An array of allowed values.
+      #
+      # * modifiers -
+      #   An array of allowed modifiers.
+      #
+      # * multiple -
+      #   Whether or not multiple Settings can be set against the single
+      #   option. Must be set to either true or false. Defaults to false.
+      #
+      #
+      # @param [Proc] block the configuration block that contains option blocks.
+      def configure(&block)
+        class_eval <<-EOV
+
+          # Includes the #settings method for reading and writing settings
+          # against any instances of this class.
+          include ActiveRecord::Configuration::InstanceMethods
+
+          # Where the actual settings are stored against the instance.
+          has_many :active_configuration_settings, :as => :configurable, :class_name => 'ActiveConfiguration::Setting'
+
+          # Validates are run on settings along with other validations.
+          validate :validate_settings
+
+          # After being saved, outstanding setting modifications are saved.
+          after_save :save_settings
+
+          # Returns the configuration details of this class.
+          def self.configuration
+            @configuration ||= ActiveConfiguration::Base.new
+          end
+        EOV
+
+        # Evaluates the configuration block given to #configure. Each
+        # option block is then evaluated and options are setup. For more
+        # details, see ActiveConfiguration::Base.
+        configuration.instance_eval(&block)
+      end
+    end
+
+    module InstanceMethods
+
+      # Returns an ActiveConfiguration::SettingManager that proxies
+      # all reads and writes of settings to ActiveConfiguration::SettingProxy
+      # objects for the specific setting requested.
+      def settings
+        @setting_manager ||= ActiveConfiguration::SettingManager.new(self)
+      end
+
+      # Writes over multiple settings at once.
+      # 
+      # @param [Hash] replacement_settings the has of settings to be set.
+      def settings=(replacement_settings = {})
+        settings.write_settings(replacement_settings)
+      end
+
+      # Runs validations against all settings with pending modificaitons.
+      # Any errors are added to #errors[:settings].
+      def validate_settings
+        settings.validate
+      end
+
+      # Saves all settings with pending modificaitons.
+      # 
+      # @return [Boolean] whether or not the save was successful.
+      def save_settings
+        settings.save
+      end
+
+      # Writes over multiple settings and saves all setting updates at once.
+      # 
+      # @param [Hash] replacement_settings the has of settings to be set.
+      # 
+      # @return [Boolean] whether or not the save was successful.
+      def update_settings(replacement_settings = {})
+        settings.update_settings(replacement_settings)
+      end
+
+      # Overrides this model's #reload method by first resetting any requested 
+      # changes to settings and then continuing to perform a standard #reload.
+      #
+      # Note: Can this be accomplished with a callback after #reload rather 
+      # than overriding the #reload method?
+      # 
+      # @param options any options that must be passed along to this methods 
+      # original #reload method.
+      def reload(options = nil)
+        settings.reload && super(options)
+      end
+    end
+  end
+end

data/lib/generators/active_configuration/install/install_generator.rb

@@ -0,0 +1,27 @@
+module ActiveConfiguration
+
+  # Generates a migration for the settings table.
+  #
+  # Example:
+  #
+  #   rails g active_configuration:install
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    def self.source_root
+      File.join(File.dirname(__FILE__), 'templates')
+    end
+
+    def self.next_migration_number(dirname)
+      if ActiveRecord::Base.timestamped_migrations
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      else
+        "%.3d" % (current_migration_number(dirname) + 1)
+      end
+    end
+
+    def create_migration_file
+      migration_template('create_active_configuration_settings.rb', 'db/migrate/create_active_configuration_settings.rb')
+    end
+  end
+end

data/lib/generators/active_configuration/install/templates/create_active_configuration_settings.rb

@@ -0,0 +1,16 @@
+class CreateActiveConfigurationSettings < ActiveRecord::Migration
+  def self.up
+    create_table ActiveConfiguration::Config.table_name do |t|
+      t.string  :configurable_type
+      t.integer :configurable_id
+      t.string  :key
+      t.string  :modifier
+      t.text    :value
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table ActiveConfiguration::Config.table_name
+  end
+end

metadata

@@ -0,0 +1,186 @@
+--- !ruby/object:Gem::Specification 
+name: active_configuration
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Thomas Mango
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-31 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: active_configuration
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec-rails
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id007
+description: |-
+  ActiveConfiguration is an engine that exposes a generic settings store to 
+                         ActiveRecord models. Made for very configurable applications, it allows you 
+                         to avoid implementing specific ways to store settings for each model that 
+                         needs such configuration. If your application isn't very configurable, 
+                         ActiveConfiguration is probably overkill.
+email: tsmango@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- app/models/active_configuration/setting.rb
+- lib/active_configuration.rb
+- lib/active_configuration/base.rb
+- lib/active_configuration/engine.rb
+- lib/active_configuration/error.rb
+- lib/active_configuration/option.rb
+- lib/active_configuration/setting_manager.rb
+- lib/active_configuration/setting_proxy.rb
+- lib/active_configuration/table_name.rb
+- lib/active_configuration/version.rb
+- lib/active_record/configuration.rb
+- lib/generators/active_configuration/install/install_generator.rb
+- lib/generators/active_configuration/install/templates/create_active_configuration_settings.rb
+- README.md
+homepage: http://github.com/tsmango/active_configuration
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: A generic settings store for Rails 3.x ActiveRecord models.
+test_files: []
+