iron-settings 1.0.0

data/lib/iron/settings/cursor.rb

@@ -0,0 +1,170 @@
+class Settings
+  
+  # Cursors handle navigating the settings hierarchy built by our Builder class, allowing
+  # getting and setting entry values and inspecting the hierarchy itself.
+  class Cursor < DslBuilder
+    
+    # Start up our cursor bound to a given group in the settings hierarchy, with
+    # the value store holding the values for the current context.
+    def initialize(group, values, context = nil)
+      @group = group
+      @values = values
+      @context = context
+    end
+    
+    # Provides access to the root of the hierarchy, generally not useful
+    # during operations... :-)
+    def root
+      @group.root
+    end
+    
+    # Returns all entry keys at the cursor's current position, and optionally
+    # including all child keys.  If the cursor is at a sub-group node, keys
+    # will be relative to that node.
+    def entry_keys(include_all = true)
+      keys = @group.entries(include_all).collect {|e| e.key }
+      unless @group.key.blank?
+        keys.collect! {|k| k.gsub(@group.key + '.', '') }
+      end
+      keys
+    end
+    
+    # Returns all group keys
+    def group_keys(include_all = false)
+      keys = @group.entries(include_all).collect {|e| e.key }
+      unless @group.key.blank?
+        keys.collect! {|k| k.gsub(@group.key + '.', '') }
+      end
+      keys
+    end
+    
+    # Finds the item (group or entry) in the hierarchy matching the provided
+    # relative key.  Raises a RuntimeError on unknown keys.
+    def find_item(key)
+      item = @group
+      key = key.to_s
+      parts = key.split(/\./)
+      until parts.empty?
+        item_key = parts.shift
+        item = item.find_item(item_key)
+        raise RuntimeError.new("Unknown settings group or entry '#{item_key}' in settings path #{[@group.key,key].list_join('.')}") if item.nil?
+      end
+      item
+    end
+    
+    # Return Settings::Entry items for entries at this cursor level and optionally below it
+    def find_entries(include_all = true)
+      @group.entries(include_all)
+    end
+    
+    # Array-like access to the entry value at the specified key
+    def [](key, &block)
+      item = find_item(key)
+      if item.group?
+        # Got asked for another group, so create a new cursor and do the right thing(tm)
+        cursor = Settings::Cursor.new(item, @values)
+        DslProxy::exec(cursor, &block) if block
+        cursor
+      else
+        item_value(item)
+      end
+    end
+    
+    # Array-like setter for entry values using the specified key
+    def []=(key, val)
+      item = find_item(key)
+      if item
+        @values.set_value(item.key, Settings.parse(val, item.type))
+      end
+      val
+    end
+    
+    # Look for the next item from our current group pointer,
+    # returning a new cursor if the item is a sub-group, or the value
+    # of the requested entry if the item is a leaf in the
+    # hierarchy tree.
+    def method_missing(method, *args, &block)
+      method = method.to_s
+      query = method.ends_with?('?')
+      assignment = method.ends_with?('=')
+      method.gsub!(/[=\?]+/,'')
+      
+      # Look up the item
+      item = @group.find_item(method)
+      if item.nil?
+        # Unknown item name, whoops.
+        raise RuntimeError.new("Unknown settings group or entry '#{method}' for settings path #{@group.key}")
+        
+      elsif item.group?
+        if query
+          # Yes, this group exists
+          return true
+        else
+          # Got asked for another group, so create a new cursor and do the right thing(tm)
+          cursor = Settings::Cursor.new(item, @values)
+          DslProxy::exec(cursor, &block) if block
+          return cursor
+        end
+        
+      elsif item.entry?
+        if query
+          # Return true if the given item has a (non-default) value
+          return item_has_value?(item)
+        else
+          if args.empty?
+            # No args means return the current value (or default if none)
+            return item_value(item)
+          else
+            # With args, we set the current value of the item (if it parses correctly)
+            val = Settings.parse(args.first, item.type)
+            @values.set_value(item.key, val)
+            return args.first
+          end
+        end
+      end
+    end
+    
+    # Counterpart to #method_missing
+    def respond_to_missing?(method, include_private = false)
+      method = method.to_s.gsub(/[=\?]+/,'')
+      item = @group.find_item(method)
+      return !item.nil?
+    end
+
+    # When true, has non-default value set for the given entry
+    def item_has_value?(item)
+      return false if item.group?
+      @values.has_value?(item.key)
+    end
+
+    # Calculates the value of the given entry item given the current value store
+    # and item default value.
+    def item_value(item)
+      return item_default_value(item) unless item_has_value?(item)
+      val = @values.get_value(item.key)
+      Settings.restore(val, item.type)
+    end
+
+    # Calculates the default value for an entry, handling callable defaults.
+    def item_default_value(item)
+      return nil if item.group? || item.default.nil?
+      if item.default.respond_to?(:call)
+        # Callable default, call in context of a root cursor, yielding our context (generally a
+        # model instance) to the block.
+        val = DslProxy.exec(Cursor.new(root, @values), @context, &(item.default))
+        val = Settings.parse(val, item.type)
+      else
+        val = item.default
+      end
+      Settings.restore(val, item.type)
+    end
+    
+    def eval_in_context(text) # :nodoc:
+      proc = Proc.new {}
+      binding = proc.binding
+      eval(text, binding)
+    end
+    
+  end
+  
+end

data/lib/iron/settings/db_store.rb

@@ -0,0 +1,57 @@
+class Settings # :nodoc:
+  
+  # Implements database-backed value storage for dynamic settings.  This value store is appropriate for both
+  # class-level and instance-level settings storage.  This store takes no special options on creation, however
+  # it is critical that the proper :reload option be set for your use-case.  
+  #
+  # For class-level settings, the proper option (and default) will often be to use a 
+  # synchronization file by specifying :reload => '<some path>' during 
+  # initialization.  This will cause the value store to touch the given file on saving changes, and
+  # reload values when the timestamp on the file is newer than the last reload.
+  #
+  # For example, in Rails (with long-running, multi-instance operations), this will allow you to have
+  # your settings loaded once on load, then once per instance when changes are saved to the database.
+  #
+  # For instance-level settings, the proper value is often :reload => false, as the values will
+  # be loaded on initilization of the instance, then thrown away with the instance.  This will be 
+  # ideal for Models in Rails, for example.  If you have long-running instances that need reloads,
+  # you can use a shared timestamp as above, causing *all* instances to reload when any instance
+  # changes (feasible for a small number of instances or when settings do not change frequently), or
+  # you can set a timeout in seconds using :reload => <num seconds> to cause instances to reload
+  # after that time has elapsed.
+  class DBStore < Settings::ValueStore
+
+    def initialize(root, context, options = {})
+      options = {
+        :reload => false
+      }.merge(options)
+      @context = context
+
+      # Let our base class at it
+      super(root, options)
+    end
+
+    def load
+      super
+      
+      # Load up the values from DB, store in internal values hash by full key
+      Settings::DBValue.for_context(@context).each do |val|
+        @values[val.full_key] = val.value
+      end
+    end
+
+    def save
+      # Clear any old settings
+      Settings::DBValue.for_context(@context).delete_all
+      
+      # Create new settings
+      @values.each_pair do |key, val|
+        Settings::DBValue.create(context: @context, full_key: key, value: val)
+      end
+      
+      super
+    end
+    
+  end
+  
+end

data/lib/iron/settings/db_value.rb

@@ -0,0 +1,33 @@
+# Stores a given setting entry's value in the database
+class Settings::DBValue < ActiveRecord::Base
+
+  # Use a non-standard table name
+  self.table_name = 'settings_values'
+
+  # Scopes for our values
+  scope :for_context, lambda {|context| 
+    if context.is_a?(Module)
+      klass = context
+      id = nil
+    else
+      klass = context.class
+      id = context.id
+    end
+    where(:context_type => klass.to_s, :context_id => id) 
+  }
+  
+  # We serialize our values...
+  serialize :value
+  
+  # Set our context
+  def context=(context)
+    if context.is_a?(ActiveRecord::Base)
+      self.context_type = context.class.name
+      self.context_id = context.id
+    else
+      self.context_type = context.to_s
+      self.context_id = nil
+    end
+  end
+
+end

data/lib/iron/settings/entry.rb

@@ -0,0 +1,26 @@
+class Settings
+
+  # Represents a leaf in our structure, has a value
+  class Entry < Settings::Node
+  
+    attr_accessor :type, :default
+  
+    def initialize(parent, type, name, default)
+      super(parent, name)
+
+      @type = type
+      @default = default.respond_to?(:call) ? default : Settings.parse(default, type)
+    end
+  
+    def entry?
+      true
+    end
+  
+    def default_value(root_cursor, context = nil)
+      return nil if @default.nil?
+      @default.respond_to?(:call) ? Settings.parse(@default.call(context), @type) : DslProxy.exec(root_cursor, @default, context)
+    end
+  
+  end
+  
+end

data/lib/iron/settings/group.rb

@@ -0,0 +1,102 @@
+class Settings
+  
+  # Groups contain a set of items - other groups and entries - that
+  # can be traversed by the Cursor to read out or set values.
+  class Group < Settings::Node
+  
+    # Create and set up a new group with the given name
+    # and optional parent
+    def initialize(parent, name = nil)
+      super
+      @nodes = {}
+    end
+    
+    def nodes
+      @nodes
+    end
+
+    def group?
+      true
+    end
+    
+    def [](key)
+      find_item(key)
+    end
+  
+    # def _add_node(item)
+    #   @nodes[item._key] = 
+  
+    # Add a group to our list of items, and define
+    # a getter to access it by name
+    def add_group(name)    
+      # Add getter for the group
+      instance_eval <<-eos
+        def #{name}
+          find_group('#{name}')
+        end
+      eos
+
+      group = Group.new(self, name)
+      @nodes[name] = group
+      group
+    end
+  
+    # Simply access a given group by name
+    def find_group(key)
+      group = @nodes[key.to_s]
+      group.is_a?(Group) ? group : nil
+    end
+  
+    def add_entry(name, type, default = nil, &block)
+      default = block unless block.nil?
+      entry = Settings::Entry.new(self, type, name, default)
+      @nodes[name] = entry
+      entry
+    end
+
+    def find_entry(name)
+      entry = @nodes[name.to_s]
+      entry.is_a?(Settings::Entry) ? entry : nil
+    end
+
+    def get_entry_val(name)
+      entry = find_entry(name)
+      return nil unless entry
+      entry.value
+    end
+  
+    def set_entry_val(name, value)
+      entry = find_entry(name)
+      return unless entry
+      entry.value = value
+    end
+    
+    def find_item(key)
+      @nodes[key.to_s]
+    end
+  
+    # Returns all child entries for this group, optionally recursing
+    # to extract sub-groups' entries as well
+    def entries(include_children = true)
+      @nodes.values.collect do |item|
+        if item.entry?
+          item
+        elsif include_children
+          item.entries(include_children)
+        else 
+          []
+        end
+      end.flatten
+    end
+    
+    # Returns all groups that are children of this group
+    def groups(include_children = false)
+      list = @nodes.values.select {|i| i.group?}
+      if include_children
+        list += list.collect {|i| i.groups}.flatten
+      end
+      list
+    end
+  
+  end
+end

data/lib/iron/settings/instance_level.rb

@@ -0,0 +1,98 @@
+class Settings
+
+  module InstanceLevel
+
+    # Will be bound to Object, provides support for defining settings structure + defaults
+    # at the class level for use in instances of that class.  Defaults to database-backed
+    # dynamic storage with a 10 second reload.  Requires that ActiveRecord be required
+    # prior to requiring this gem.
+    module ClassMethods
+
+      def instance_settings(options = {}, &block)
+        unless @settings_instance_root
+          @settings_instance_root = Settings::Root.new()
+          @options = {
+            :store => :dynamic
+          }.merge(options)
+        end
+      
+        # 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 instance level, we use
+            # a 10 second timeout by default
+            options[:reload] = 10
+          end
+        end
+
+        # Save off our options
+        @settings_instance_options = options
+      
+        # This class now need settings support at the instance level
+        include InstanceMethods
+
+        # Add our save hook if the class is an ActiveRecord model
+        if defined?(ActiveRecord) && self < ActiveRecord::Base
+          after_save :settings_save!
+        end
+      
+        # Construct a builder and do the right thing
+        builder = Settings::Builder.new(@settings_instance_root)
+        builder.define(&block) if block
+        builder
+      end
+    
+      def settings_instance_options
+        @settings_instance_options
+      end
+    
+      def settings_instance_root
+        @settings_instance_root
+      end
+    
+    end
+
+    # Set of methods that all instances with instance_settings set will share
+    module InstanceMethods
+
+      # Access settings at instance level
+      def settings(&block)
+        # Ensure we have a value store
+        unless @settings_values 
+          settings_reset!
+        end
+
+        # Set up for use, create a cursor to read/write, and we're good to go
+        @settings_values.reload_if_needed
+        cursor = Settings::Cursor.new(self.class.settings_instance_root, @settings_values, self)
+        DslProxy::exec(cursor, &block) if block
+        cursor
+      end
+  
+      def settings_save!
+        @settings_values.save if @settings_values
+      end
+  
+      # Throw out any unsaved changes
+      def settings_reset!
+        # Create our value store
+        opts = self.class.settings_instance_options
+        @settings_values = opts[:store] == :static ? 
+          Settings::StaticStore.new(self.class.settings_instance_root, opts) :
+          Settings::DBStore.new(self.class.settings_instance_root, self, opts)
+      end
+
+    end
+
+    # Install hooks
+    def self.included(base)
+      # Add our class methods
+      base.extend(ClassMethods)
+    end
+
+  end
+  
+end