iron-settings 1.0.0

data/lib/iron/settings/node.rb

@@ -0,0 +1,46 @@
+class Settings
+  
+  # Base class for groups and entries - provides our structure
+  class Node
+    
+    # Used to separate node names in a full key
+    NODE_SEPARATOR = '.'.freeze
+
+    # All nodes have these items...
+    attr_accessor :root, :parent, :name, :key
+    
+    def initialize(parent, name = nil)
+      # Validate name
+      unless parent.nil? || name.match(/[a-z0-9_]+/)
+        raise ArgumentError.new("Invalid settings key name '#{name}' - may only contain a-z, 0-9 and _ characters")
+      end
+      
+      @parent = parent
+      @name = name
+
+      if @parent.nil?
+        # We are the root!
+        @root = self
+        @key = nil
+      else
+        # Normal node, chain ourselves
+        @root = parent.root
+        if parent.key.blank?
+          @key = name
+        else
+          @key = [@parent.key, name].join(NODE_SEPARATOR)
+        end
+      end
+    end
+
+    def group?
+      false
+    end
+
+    def entry?
+      false
+    end
+    
+  end
+  
+end

data/lib/iron/settings/root.rb

@@ -0,0 +1,15 @@
+
+class Settings
+
+  # Root of a settings definition tree - contains a set of groups and entries
+  class Root < Settings::Group
+  
+    # Construct ourselves
+    def initialize
+      # We're a group...
+      super(nil, '')
+    end
+  
+  end
+
+end

data/lib/iron/settings/static_store.rb

@@ -0,0 +1,85 @@
+class Settings
+  
+  # Provides in-memory static (aka file and code-based) settings, suitable for class-level settings 
+  # for gems, frameworks, command-line tools, etc.
+  class StaticStore < Settings::ValueStore
+
+    attr_accessor :paths
+
+    def initialize(root, options = {})
+      file = options.delete(:file)
+      files = options.delete(:files)
+      @secure = !(options.delete(:secure) === false)
+      @ignore_missing = !(options.delete(:ignore_missing) === false)
+      super(root, options)
+      
+      @paths = []
+      @paths << file if file
+      @paths += files || []
+      
+      @modified_time = @paths.convert_to_hash(nil)
+    end
+
+    # True on our reload settings matching (see ValueStore#need_reload?), or if
+    # any of our settings files have been modified since our last load.
+    def need_reload?
+      return true if super
+      @modified_time.any? do |path, time| 
+        File.exist?(path) && File.mtime(path) != time 
+      end
+    end
+    
+    # We don't support saving our current state, hence "static" :-)
+    def read_only?
+      true
+    end
+
+    # Load our values from the file(s) specified during creation, in order,
+    # respecting the :secure option to only load safe settings files
+    # if so specified.
+    def load
+      super
+      @paths.each {|p| load_file(p) }
+    end
+
+    # Loads a single settings file, verifying its existence, ownership/security, etc.
+    # 
+    def load_file(path)
+      # Ensure we have the file, if so required
+      raise RuntimeError.new("Missing settings file #{path} - this file is required") unless @ignore_missing || File.exists?(path)
+
+      # Read in the settings file
+      verify_file_security(path)
+      text = File.read(path) rescue ''
+      return if text.blank?
+      
+      # Create a cursor, and eval the file's contents in the cursor's context
+      cursor = Settings::Cursor.new(@root, self)
+      cursor.eval_in_context(text)
+
+      # Remember our modified time for future checking
+      @modified_time[path] = File.mtime(path)
+    end
+    
+    def save_file(path)
+      @modified_time[path] = File.mtime(path)
+      raise 'Unimplemented!'
+    end
+    
+    # Implements :secure test for settings files.  Verifies that the specified file is:
+    #
+    # * Owned by the same user ID that is running the current process
+    # * Not world-writable
+    #
+    def verify_file_security(path)
+      # Not requiring security?  File doesn't exist?  Then everything is fine...
+      return unless (File.exists?(path) && @secure)
+      
+      stat = File::Stat.new(path)
+      raise RuntimeError.new("Cannot load settings file #{path} - file must be owned by the user this program is running as (UID #{Process.uid})") unless stat.owned?
+      raise RuntimeError.new("Cannot load settings file #{path} - file cannot be world-writable") if stat.world_writable?
+    end
+    
+  end
+  
+end

data/lib/iron/settings/value_store.rb

@@ -0,0 +1,88 @@
+class Settings
+  
+  # Base class for our value stores.  Derived classes manage loading and saving
+  # values in the value hash.
+  class ValueStore
+    
+    def initialize(root, options = {})
+      @root = root
+      @options = options
+      @loaded_on = nil
+      @reload = options.delete(:reload) || false
+      @values = {}
+    end
+    
+    def need_reload?
+      # Always reload at first chance, ie LOAD, duh
+      return true if @loaded_on.nil?
+      
+      # Do the right thing
+      case @reload
+      when true then
+        # Always reload each time #settings creates a new cursor
+        true
+        
+      when false then
+        # Never reload
+        false
+        
+      when Proc then
+        # Custom reload handler, reload on returning true
+        @reload.call === true
+        
+      when Fixnum then
+        # Reload after N seconds
+        Time.now > @loaded_on + @reload.to_i
+        
+      when String then
+        # Reload if file is modified
+        mod_time = File.mtime(@reload) rescue nil
+        mod_time.nil? || @loaded_on < mod_time
+        
+      else
+        # Non-standard reload setting, must be handled in kids
+        nil
+      end
+    end
+    
+    def reload_if_needed
+      load if need_reload?
+    end
+    
+    def load
+      @loaded_on = Time.now
+      @values = {}
+    end
+    
+    def save
+      # No saving for me, thanks
+      return if read_only?
+      
+      # Update our timestamp on our cache reload file, if any
+      if @reload.is_a?(String)
+        FileUtils.touch(@reload)
+      end
+      
+      # Remember when we were loaded for future use
+      @loaded_on = Time.now
+    end
+    
+    def has_value?(key)
+      @values.has_key?(key)
+    end
+    
+    def get_value(key)
+      @values[key]
+    end
+    
+    def set_value(key, value)
+      @values[key] = value
+    end
+    
+    def read_only?
+      false
+    end
+    
+  end
+  
+end

data/lib/tasks/settings.rake

@@ -0,0 +1,65 @@
+namespace :settings do
+  
+  desc "Install components required for integration of the iron-settings gem with your Rails app"
+  task :install => :environment do
+    spec = Gem::Specification.find_by_name("iron-settings")
+    gem_root = spec.gem_dir
+    
+    # Our destination directory
+    dir = File.join(Rails.root, 'db/migrate')
+    
+    # Our source migration files
+    src = File.join(gem_root, 'db/settings_migration.rb')
+    filename = Time.now.strftime('%Y%m%d%H%M%S') + '_' + File.basename(src)
+    dest = File.join(dir, filename)
+    
+    puts ''
+    puts "Installing settings migration(s) into #{dir} as:"
+    puts "  #{filename}"
+    puts ''
+    
+    if Dir.glob(File.join(dir, '*_' + File.basename(src))).empty?
+      FileUtils.cp(src, dest)
+      if File.exist?(dest)
+        puts "Migration installed successfully, please remember to run rake db:migrate to complete the installation"
+      else
+        puts "ERROR: migration file not created"
+        puts ''
+        puts "You may need to manually install the migration located here:"
+        puts "  #{src}"
+      end
+    else
+      puts "Migration already installed - skipping!"
+    end
+    
+    puts ''
+  end
+  
+  desc "Display all possible settings and their current values"
+  task :list => :environment do
+    Settings.classes.each do |klass|
+      puts "\n#{klass.name} Settings"
+      puts "----------------"
+      settings = klass.settings
+      groups = [settings.root]
+      until groups.empty?
+        # Get the next group to work on
+        group = groups.shift
+        
+        # Run each entry and display its current value
+        group.entries(false).sort_by(&:key).each do |entry|
+          info = entry.key + ' = ' + settings.item_value(entry).inspect + " (#{entry.type})"
+          unless klass.settings.item_has_value?(entry)
+            info = "\e[1;30m" + info + "\e[0;9m"
+          end
+          puts info
+        end
+        
+        # Add in sub-groups for next iteration, depth-first-wise
+        groups = group.groups(false).sort_by(&:key) + groups
+      end
+    end
+    puts ""
+  end
+
+end

data/spec/samples/static-test

@@ -0,0 +1,4 @@
+# A comment
+val1 200
+val2 'dog' + 'bone'
+group1.val3 :a_symbol

data/spec/samples/static-test-2

@@ -0,0 +1 @@
+val1 205

data/spec/settings/builder_spec.rb

@@ -0,0 +1,48 @@
+describe Settings::Builder do
+  
+  before do
+    @root = Settings::Root.new
+    @builder = Settings::Builder.new(@root)
+  end
+  
+  it 'should add groups' do
+    @builder.group('bob')
+    group = @root.find_group('bob')
+    group.should be_group
+    group.key.should == 'bob'
+  end
+  
+  it 'should return a builder after adding a group' do
+    @builder.group('bob').should be_a(Settings::Builder)
+  end
+  
+  it 'should add string entries' do
+    @builder.string('foo')
+    entry = @root.find_entry('foo')
+    entry.should be_entry
+    entry.key.should == 'foo'
+    entry.type.should == :string
+  end
+  
+  it 'should support all built-in data types' do
+    Settings.data_types.each do |type|
+      @builder.should respond_to(type)
+    end
+  end
+  
+  it 'should raise an error if defaults are not parseable' do
+    expect { @builder.string('foo', 123) }.to raise_error(ArgumentError)
+  end
+  
+  it 'should allow procs as defaults' do
+    expect { @builder.string('yo', lambda { 'hi' }) }.to_not raise_error
+  end
+  
+  it 'should reject key names that are invalid' do
+    expect { @builder.int('bad.key') }.to raise_error
+    expect { @builder.int('another-baddy') }.to raise_error
+    expect { @builder.int('0isnotok') }.to raise_error
+    expect { @builder.group('key.of.badness') }.to raise_error
+  end
+  
+end

data/spec/settings/class_level_spec.rb

@@ -0,0 +1,46 @@
+describe Settings::ClassLevel do
+  
+  class SimpleTest
+    class_settings do
+      # General settings
+      string('key', 'changeme')
+      group('session') do
+        string('secret')
+        string('key') { '_' + key + '_session' }
+        int('timeout')
+      end
+    end
+  end
+  
+  class StaticTest 
+    class_settings(:file => SpecHelper.sample_path('static-test')) do
+      int('val1', 10)
+      string('val2')
+      group('group1') do
+        symbol('val3')
+      end
+    end
+  end
+  
+  it 'should be available in all Modules' do
+    Module.should respond_to(:class_settings)
+  end
+  
+  it 'should return a Builder instance' do
+    class Bob ; end
+    Bob.class_settings.should be_a(Settings::Builder)
+  end
+  
+  it 'should not be available at instance level' do
+    test = SimpleTest.new
+    test.respond_to?(:settings).should be_false
+  end
+  
+  # Basically an integration test
+  it 'should load values from a file' do
+    StaticTest.settings.val1.should == 200
+    StaticTest.settings.val2.should == 'dogbone'
+    StaticTest.settings.group1.val3.should == :a_symbol
+  end
+  
+end

data/spec/settings/cursor_spec.rb

@@ -0,0 +1,96 @@
+describe Settings::Cursor do
+  
+  class CursorTest
+    class_settings do
+      int('val1', 5)
+      int('val2')
+      group('top') do
+        group('middle') do
+          group('bottom') do
+            string('leaf')
+            int('lamby') { val1 + 1 }
+          end
+        end
+      end
+      string('invalid_default', lambda { 5 })
+    end
+  end
+  
+  before do
+    # Clear out temp data and reset to blank slate
+    CursorTest.class_settings_reset!
+  end
+  
+  it 'should traverse from group to group' do
+    CursorTest.settings.top?.should be_true
+    CursorTest.settings.top.middle?.should be_true
+    CursorTest.settings.top.middle.bottom?.should be_true
+  end
+  
+  it 'should test for value presence using interogator' do
+    CursorTest.settings.val2?.should be_false
+    CursorTest.settings.val2 100
+    CursorTest.settings.val2?.should be_true
+  end
+  
+  it 'should set via dsl-style and explicit setters' do
+    CursorTest.settings.val1 = 5
+    CursorTest.settings.val1.should == 5
+    CursorTest.settings.val1 10
+    CursorTest.settings.val1.should == 10
+  end
+  
+  it 'should handle block-style setters' do
+    CursorTest.settings.val1.should == 5
+    CursorTest.settings do
+      val1 6
+      val2 0
+    end
+    CursorTest.settings.val1.should == 6
+    CursorTest.settings.val2.should == 0
+  end
+  
+  it 'should raise on setting an entry to an incorrect value type' do
+    expect { CursorTest.settings.val1 = 'not an integer' }.to raise_error
+  end
+  
+  it 'should raise an error on accessing an entry with a default proc that returns the wrong data type' do
+    expect { CursorTest.settings.invalid_default }.to raise_error(ArgumentError)
+  end
+  
+  it 'should support getting values via key strings' do
+    CursorTest.settings['val1'].should == 5
+    CursorTest.settings.top.middle.bottom.leaf = 'yo'
+    CursorTest.settings['top.middle.bottom.leaf'].should == 'yo'
+  end
+  
+  it 'should support setting values via key strings' do
+    CursorTest.settings['top.middle.bottom.leaf'] = 'yo'
+    CursorTest.settings.top.middle.bottom.leaf.should == 'yo'
+  end
+
+  it 'should return a cursor on getting a group\'s value using key access' do
+    CursorTest.settings['top'].should be_a(Settings::Cursor)
+  end
+  
+  it 'should return an array of all keys' do
+    CursorTest.settings.entry_keys.should match_array([
+      'val1',
+      'val2',
+      'top.middle.bottom.lamby',
+      'top.middle.bottom.leaf',
+      'invalid_default'
+    ])
+  end
+  
+  it 'should return keys relative to its bound group' do
+    CursorTest.settings.top.middle.entry_keys.should match_array([
+      'bottom.leaf', 'bottom.lamby'
+    ])
+  end
+  
+  it 'should eval lambda defaults in the context of the root cursor' do
+    CursorTest.settings.top.middle.bottom.lamby.should == 6
+  end
+  
+end