iron-settings 1.0.0

data/.rspec

@@ -0,0 +1 @@
+--require <%= File.join(File.expand_path(File.dirname(__FILE__)), 'spec', 'spec_helper.rb') %>

data/History.txt

@@ -0,0 +1,9 @@
+== 1.0.0 / 2013-09-XX
+
+* Initial revision
+* Working class and instance level settings definition
+* Working static and db-backed value stores
+* Working user-specifiable settings data types
+* Reload support for file timestamp, timeout, and custom proc-based reload logic
+* Security checking for file ownership and world-writability on settings files
+* Working Rails integration

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Irongaze Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,133 @@
+= GEM: iron-settings
+
+Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
+
+== DESCRIPTION
+
+A set of classes to support elegant class and instance level settings, both 
+static (in files/code) and dynamic (database-backed).
+
+== SYNOPSIS
+
+Managing settings in applications is a pain.  This gem makes it less so.  You define your setting 
+structure using a simple DSL, then override it as needed in your code or via user interaction.  Great for
+gem-based tools, frameworks, etc needing elegant customization, and great for any project
+wanting to have flexible, powerful user-editable settings stored in a database.
+
+As an example, consider the User model in any given Rails-based site.  Here's how we could add
+some flexible settings:
+
+    class User < ActiveRecord::Base
+
+      # Declare our settings schema for this model with types, names and defaults.
+      # Each model instance will have its own set of values for these settings.
+      instance_settings do
+        # homepage is a string, with a default of '/dashboard'
+        string('homepage', '/dashboard')
+
+        # Groups let you bundle settings together, as well as namespace
+        # items if so desired
+        group('notification') do
+          # This setting has a dynamic default - basically a block that gets evaluated to generate
+          # a default value.  It has access to the model that owns it - in this case, we have
+          # an email notification address that defaults to the user's primary email.
+          string('email') {|user| user.email}
+          
+          # Lists (aka arrays) are also supported, of any of the supported types
+          int_list('subscriptions', [ListServe::NEWS_GROUP, ListServe::ALERTS])
+        end
+      end
+
+    end
+
+To work with these settings:
+
+    # Create a new user
+    >> @user = User.new(:email => 'info@irongaze.com')
+
+    # Default values are available immediately
+    >> puts @user.settings.homepage
+    => '/dashboard'
+
+    # Override the default value for this user
+    >> @user.settings.homepage = '/dashboard-v2'
+
+    # Update his notification frequency, drilling down into the 'notification' group
+    >> @user.settings.notification.frequency = 10
+    
+    # Settings are saved when the model that owns them is saved
+    >> @user.save!
+    
+    # Once saved, the settings are reloaded as needed
+    >> puts User.find_by_email('info@irongaze.com').settings.homepage
+    => '/dashboard-v2'
+
+Static settings work differently.  Imagine you are building a command-line tool that needs
+configuration info.  
+
+    class MyTool
+
+      # You'd first define your schema at class level, passing the file
+      # you want to use as an option on creation
+      class_settings(:file => '~/.mytool') do
+        string('api_key')
+        string('base_path', '~')
+      end
+      
+      def initialize
+        # The bound file will be loaded automatically if present on first access.
+        # Verify we have what we need - interrogative version of keys tests for the
+        # presence of a non-default value.
+        unless MyTool.settings.api_key?
+          raise "You must define your API key in your ~/.mytool settings file!"
+        end
+      end
+  
+    end
+    
+Now, your users could create a .mytool file like so:
+
+    api_key   '1234ASDF'
+    base_path '~/code'
+    
+On calling MyTool.settings, this file would be loaded and override the settings defaults.
+    
+You could set up a similar arrangement for managing settings for Gems and other reusable libraries.
+
+== LIMITATIONS
+
+Database-backed settings are not a panacea.  They duplicate functionality that could be built more 
+directly using standard model attributes.  In particular, care must be taken to avoid changing existing
+entry paths and data types, as doing so will invalidate saved values and potentially cause errors
+on loading prior values.
+
+In addition, they are not intended for storing hundreds of thousands of values!  Like any key/value
+store, they are a tool suited for certain tasks.
+
+== REQUIREMENTS
+
+Depends on the iron-extensions gem, and optionally requires ActiveRecord to support db-backed 
+dynamic settings.
+
+Requires RSpec, ActiveRecord and Sqlite3 gems to build/test.
+
+== INSTALLATION
+
+To install, simply run:
+
+    sudo gem install iron-settings
+    
+RVM users can skip the sudo:
+  
+    gem install iron-settings
+
+Then use
+
+    require 'iron/settings'
+    
+to require the library code.
+
+If you want to use db-backed settings (for example, for per-model settings), you will need to run
+the settings-creation migration.  In a Rails project, simply run the provided rake settings:install task, 
+which will copy the required migration into your app.  If you're using this in a non-Rails environment,
+you can manually run the migration in <gem_path>/db/settings_migration.rb.

data/Version.txt

@@ -0,0 +1 @@
+1.0.0

data/db/settings_migration.rb

@@ -0,0 +1,23 @@
+class SettingsMigration < ActiveRecord::Migration
+  
+  def change
+    
+    # To support db-backed settings, we need a table containing their values
+    create_table :settings_values do |t|
+      # Polymorphic ownership as "context"
+      t.string  'context_type', :null => false
+      t.integer 'context_id'
+
+      # Full key, ie App.settings.foo.bar.some_value => 'foo.bar.some_value'
+      t.string  'full_key', :null => false
+
+      # Serialized value
+      t.text    'value'
+    end
+    
+    # In cases where we have a lot of db-backed settings, an index is a must!
+    add_index :settings_values, ['context_type', 'context_id']
+    
+  end
+  
+end

data/lib/iron/rake_loader.rb

@@ -0,0 +1,6 @@
+# Defines a Railtie to inject our rake tasks into the Rails rake environment
+class SettingsRailtie < Rails::Railtie
+  rake_tasks do
+    Dir[File.join(File.dirname(__FILE__),'../tasks/*.rake')].each { |f| load f }
+  end
+end

data/lib/iron/settings.rb

@@ -0,0 +1,161 @@
+# Dependencies
+require 'tmpdir'
+require 'fileutils'
+require 'iron/extensions'
+
+# Top-level class with numerous helper methods for defining and handling
+# our supported settings data types.
+class Settings 
+
+  # Registers a new data type for use in settings entries.  Pass a symbol
+  # for the type, and a lambda that accepts an arbitrary value and either
+  # parses it into a value of the required type or raises.
+  #
+  # For example, let's say we had a project that commonly had to assign
+  # admin users (represented here by ActiveRecord models) on projects, tasks, etc.
+  # We could create a :user data type that would seamlessly allow setting
+  # and getting admin users as a native settings type:
+  #
+  #   Settings.register_type :user, 
+  #     :parse => lambda {|val| val.is_a?(AdminUser) ? val.id : raise },
+  #     :restore => lambda {|val| AdminUser.find_by_id(val) }
+  #
+  # Now we can use the user type in our settings definitions:
+  #
+  #   class Project < ActiveRecord::Base
+  #     instance_settings do
+  #       user('lead')
+  #     end
+  #   end
+  #
+  # With our settings defined, we can get and set admin users to that setting entry:
+  #
+  #   @project = Project.new(:name => 'Lazarus')
+  #   @project.settings.lead = AdminUser.find_by_email('jim@example.com')
+  #   @project.save
+  #
+  #   @project = Project.find_by_name('Lazarus')
+  #   # Will use our :restore lambda to restore the id as a full AdminUser model
+  #   @lead = @project.settings.lead
+  #   # Will print 'jim@example.com'
+  #   puts @lead.email
+  #
+  # If you do not define either the parse or restore lambdas, they will act as 
+  # pass-throughs.  Also note that you do not need to handle nil values, which
+  # will always parse to nil and restore to nil.
+  def self.register_type(type, options = {})
+    data_type_map[type] = {parse: options[:parse], restore: options[:restore]}
+  end
+  
+  # Registers initial set of built-in data types
+  def self.register_built_ins
+    register_type(:int, parse: lambda {|val| val.is_a?(Fixnum) || (val.is_a?(String) && val.integer?) ? val.to_i : raise })
+    register_type(:string, parse: lambda {|val| val.is_a?(String) ? val : raise })
+    register_type(:symbol, parse: lambda {|val| val.is_a?(Symbol) ? val : raise })
+    register_type(:bool, parse: lambda {|val| (val === true || val === false) ? val : raise })
+    register_type(:var)
+  end
+  
+  def self.data_type_map
+    @data_type_map ||= {}
+    @data_type_map
+  end
+
+  # Returns array of symbols for the supported data types for
+  # settings entries.  You can add custom types using the #register_type 
+  # method
+  def self.data_types
+    data_type_map.keys
+  end
+  
+  # Returns the proper parser for a given type and mode (either :parse or :restore)
+  def self.converter_for(type, mode)
+    if type.to_s.ends_with?('_list')
+      type = type.to_s.gsub('_list','').to_sym
+    end
+
+    hash = data_type_map[type]
+    raise ArgumentError.new("Unknown settings data type [#{type.inspect}]") if hash.nil?
+    hash[mode]
+  end
+  
+  def self.parse(val, type)
+    # Nil is always ok
+    return nil if val.nil?
+    
+    # Check for lists
+    parser = converter_for(type, :parse)
+    if type.to_s.ends_with?('_list')
+      # Gotta be an array, thanks
+      raise ArgumentError.new("Must set #{type} settings to an array of values") unless val.is_a?(Array)
+
+      # Parse 'em all
+      return val if parser.nil?
+      val.collect {|v| parser.call(v) } rescue raise ArgumentError.new("Values #{val.inspect} is not a valid #{type}")
+    else
+      # Single value
+      return val if parser.nil?
+      parser.call(val) rescue raise ArgumentError.new("Value [#{val.inspect}] is not a valid #{type}")
+    end
+  end
+
+  def self.restore(val, type)
+    # Nil restores to nil... always
+    return nil if val.nil?
+    
+    # Check for lists
+    restorer = converter_for(type, :restore)
+    if type.to_s.ends_with?('_list')
+      # Gotta be an array, thanks
+      raise ArgumentError.new("Must set #{type} settings to an array of values") unless val.is_a?(Array)
+
+      # Parse 'em all
+      return val if restorer.nil?
+      val.collect {|v| parser.call(v) } rescue raise ArgumentError.new("Unable to restore values #{val.inspect} to type #{type}")
+    else
+      # Single value
+      return val if restorer.nil?
+      restorer.call(val) rescue raise ArgumentError.new("Unable to restore value [#{val.inspect}] to type #{type}")
+    end
+  end
+
+  def self.classes
+    @classes ||= []
+  end
+
+  def self.default_timestamp_file(class_name)
+    filename = class_name.gsub(/([a-z])([A-Z])/, '\1-\2').to_dashcase + '-settings.txt'
+    defined?(Rails) ?
+      File.join(RAILS_ROOT, 'tmp', filename) :
+      File.join(Dir.tmpdir, filename)
+  end
+
+end
+
+# Register our built-in types
+Settings.register_built_ins
+
+# Include required classes
+require_relative 'settings/node'
+require_relative 'settings/group'
+require_relative 'settings/root'
+require_relative 'settings/entry'
+require_relative 'settings/builder'
+require_relative 'settings/cursor'
+require_relative 'settings/class_level'
+require_relative 'settings/instance_level'
+require_relative 'settings/value_store'
+require_relative 'settings/static_store'
+if defined?(ActiveRecord)
+  require_relative 'settings/db_value'
+  require_relative 'settings/db_store'
+end
+
+# Install our support at the correct scopes
+Module.send(:include, Settings::ClassLevel)
+Object.send(:include, Settings::InstanceLevel)
+
+# Rails support here
+if defined?(Rails)
+  require_relative 'rake_loader'
+end

data/lib/iron/settings/builder.rb

@@ -0,0 +1,72 @@
+class Settings
+  
+  # Mirror to the Cursor class, this class helps extend and expand a settings
+  # hierarchy.
+  class Builder
+  
+    def self.define(group, &block)
+      builder = self.new(group)
+      builder.define(&block)
+    end
+  
+    # Bind to a group/root
+    def initialize(group)
+      @group = group
+    end
+    
+    # Define in block mode
+    def define(&block)
+      DslProxy.exec(self, &block)
+    end
+    
+    # Create a new sub-group, yield for definition if block passed
+    def group(name, &block)
+      verify_key?(name)
+      group = @group.find_group(name)
+      unless group
+        verify_available?(name, :group)
+        group = @group.add_group(name)
+      end
+      
+      # Chain it
+      builder = self.class.new(group)
+      builder.define(&block) if block
+      builder
+    end
+    
+    def method_missing(method, *args, &block)
+      type = method.to_s
+      
+      if Settings.data_types.include?(type.gsub('_list','').to_sym)
+        type = type.to_sym
+        name = args[0]
+        default = args[1]
+        verify_key?(name)
+        verify_available?(name, :entry)
+        @group.add_entry(name, type, default, &block)
+      else
+        super
+      end
+    end
+    
+    def respond_to_missing?(method, include_private = false)
+      Settings.data_types.include?(method.to_s.gsub('_list','').to_sym)
+    end
+
+    protected
+
+    # Raise's if name already in use for the group
+    def verify_available?(name, type)
+      unless @group.find_item(name).nil?
+        raise RuntimeError.new("#{type.capitalize}'s name '#{name}' already defined for settings group: #{@group.key}")
+      end
+    end
+  
+    def verify_key?(key)
+      unless key.is_a?(String) && key.match(/^[a-z][a-z0-9_]*$/)
+        raise RuntimeError.new("Key '#{key}' is not a valid group/entry key while defining settings group #{@group.key} - must be a string with a-z, 0-9, or _ chars")
+      end
+    end
+  end
+  
+end

data/lib/iron/settings/class_level.rb

@@ -0,0 +1,122 @@
+class Settings #:nodoc:
+  
+  # Class-level settings can be either static (file/code-based) or dynamic (db-based) depending
+  # on your needs.  Static settings will work well for gem configuration, command-line tools,
+  # etc. while dynamic settings might be useful for a CMS or other web-based tool that needs
+  # to support user editing of settings values on-the-fly.
+  module ClassLevel
+
+    module ClassMethods
+    
+      # Access the class-level settings values for this class, returns
+      # a Settings::Cursor to read/write, pointed at the root of the 
+      # settings definition for this class.
+      #
+      # Optionally accepts a block
+      # for mass assignment using DSL setters, eg:
+      #
+      #    Foo.settings do
+      #      some_group.some_entry 'some value'
+      #      some_other_entry 250
+      #    end
+      def settings(&block)
+        @settings_values.reload_if_needed
+        cursor = Settings::Cursor.new(@settings_class_root, @settings_values)
+        DslProxy::exec(cursor, &block) if block
+        cursor
+      end
+    
+      # Reset state to default values only - useful in testing
+      def class_settings_reset!
+        @settings_values = @settings_class_options[:store] == :static ? 
+          Settings::StaticStore.new(@settings_class_root, @settings_class_options) :
+          Settings::DbStore.new(@settings_class_root, @settings_class_options)
+      end
+
+      # Force a settings reload (from db or file(s) depending on settings) regarless
+      # of need to reload automatically.  Useful for testing, but not generally needed in production use
+      def reload_settings
+        @settings_values.load
+      end
+
+    end
+  
+    # Define the class-level settings for a given class.  Supported options include:
+    #
+    #   :store => :static | :dynamic - how to load and (potentially) save settings values, defaults to :static
+    #
+    # Static mode options:
+    #
+    #   :file => '/path/to/file' - provides a single file to load when using the static settings store
+    #   :files => ['/path1', '/path2'] - same as :file, but allows multiple files to be loaded in order
+    #
+    # Reload timing (primarily intended for use with :db mode):
+    #
+    #   :reload => <when> - when and if to reload from file/db, with <when> as one of:
+    #      true - on every access to #settings
+    #      false - only do initial load, never reload
+    #      '/path/to/file' - file to test for modified timestamp changes, reload if file timestamp is after latest load
+    #      <num seconds> - after N seconds since last load
+    #      lambda { <true to reload> } - custom lambda to execute to check for reload, reloads on returned true value
+    #
+    # Any options passed on subsequent calls to #class_settings will be ignored.
+    #
+    # A passed block will be evaluated in the context of a Settings::Builder instance
+    # that can be used to define groups and entries.
+    #
+    # Example:
+    #
+    #    class Site
+    #      class_settings(:file => File.join(RAILS_ROOT, 'config/site-settings.rb')) do
+    #        string('name')
+    #        group('security') do
+    #          bool('force-ssl', false)
+    #          string('secret-key')
+    #        end
+    #      end
+    #    end
+    #
+    # The above would set up Site.settings.name, Site.settings.security.force_ssl, etc, with an optional settings
+    # file located at $RAILS_ROOT/config/site-settings.rb
+    def class_settings(options = {}, &block)
+      unless @settings_class_root
+        # Set up our root group and options
+        @settings_class_root = Settings::Root.new()
+        options = {
+          :store => :static
+        }.merge(options)
+        
+        # Set our default reload timing
+        if options[:reload].nil?
+          if options[:store] == :static
+            # Static settings generally don't need reloading
+            options[:reload] = false
+          else
+            # For dynamic, db-backed settings at the class level, we use
+            # file modified reload timing by default
+            options[:reload] = Settings.default_timestamp_file(self.name)
+          end
+        end
+        
+        # Save off our options
+        @settings_class_options = options
+        
+        # Add this class to the settings registry
+        Settings.classes << self
+
+        # Add in support for settings for this class
+        extend ClassMethods
+        
+        # Create our value store
+        class_settings_reset!
+      end
+    
+      # Create a builder and do the right thing based on passed args
+      builder = Settings::Builder.new(@settings_class_root)
+      builder.define(&block) if block
+      builder
+    end
+    
+  end
+  
+end