settler 1.0.3 → 1.1.0

data/README.rdoc

@@ -1,6 +1,6 @@
 = Settler
 
-Settler can be used for defining application wide settings in Rails. Settings are loaded from a YAML file and stored in the database using ActiveRecord to allow users to update settings on the fly. The YAML configuration allows you to not only specify defaults, but setting value validations as well!
+Settler can be used for defining application wide settings in Rails. Settings are loaded from a YAML file and stored in the database using ActiveRecord to allow users to update settings on the fly. The YAML configuration allows you to not only specify defaults, but setting value validations and typecasts as well! 
 
 == Requirements
 
@@ -48,19 +48,14 @@ The initial version of settler.yml contains example settings for every default R
       validations:
         presence: true
 
-In this case, 'google_analytics_key' is the key of the setting. Every nested property is either an attribute of the setting or a list of validations:
+In this case, 'google_analytics_key' is the key of the setting. Every nested property is either an attribute of the setting or a list of validations. Alt, value, editable and deletable are attributes of the Setting model. If a Setting with a given key does not exist, it is created with the attributes found. Therefore, you can consider these attributes as the default values for the setting. See the validations section for more info on validations. 
 
-* Alt, value, editable and deletable are attributes of the Setting model. If a Setting with a given key does not exist, it is created with the attributes found. Therefore, you can consider these attributes as the default values for the setting.
-* Validations are not part of every setting, but are loaded on validation of a Setting instance. They apply to the value of the setting. The following validations can be created:
-  - 'presence',  true/false.
-  - 'inclusion', followed by a YAML array (e.g. ['a','b','c']). Accepts a comma separated string as well.
-
-  Note that you can use ERB in the configuration file if you need to. For example:
+Note that you can use ERB in the configuration file if you need to. For example:
 
     google_analytics_key: 
       value: '<%= GOOGLE_ANALYTICS_KEY %>'
 
-  will evaluate the GOOGLE_ANALYTICS_KEY constant.
+will evaluate the GOOGLE_ANALYTICS_KEY constant.
 
 == Access settings
 
@@ -79,11 +74,60 @@ In this case, 'google_analytics_key' is the key of the setting. Every nested pro
     >> Settler[:google_analytics_key]
     Setting Load (0.7ms)   SELECT * FROM "settings" WHERE ("settings"."key" = 'google_analytics_key') LIMIT 1
     => "UA-xxxxx-x"
+    
+* Some named scopes for finding setting are available that may be useful as well:
+  * Setting.editable: returns all editable settings.
+  * Setting.deletable: returns all deletable settings.
+  * Setting.deleted: returns all deleted settings.
+
+== Typecasting
+
+* Setting values can be typecasted to several types. This can easily be done by adding a 'typecast' property to the settler.yml. For example:
+
+    float_value:
+      alt: A float that should be typecasted
+      value: '0.25'
+      typecast: float
+  
+  will ensure that the value returned by this setting will always be a float (0.25) instead if the string representation of a float. 
+  
+* The following 'typecasters' are available by default:
+  * integer
+  * float
+  * boolean
+
+  Note: the boolean typecaster will yield true when the value is '1','t' or 'true' (case ignored), false otherwise.
+
+* It is possible to create and use your own typecaster instead of the built in typecasters. A custom type caster should look like this:
+
+    class CustomTypecaster < Typecaster
+      def typecast(value)
+        # typecast and return value
+      end
+    end
+
+When you require this class in your application, you can easily use your typecaster by specifying its class name in the settler configuration:
+
+    custom_value:
+      alt: An integer that should be custom typecasted
+      value: 1
+      typecast: CustomTypecaster      
+    
+== Validations
+
+* Validations are not stored in every setting, but are loaded on validation of a Setting instance. They apply to the value of the setting. The following validations can be created:
+  - 'presence',  true/false.
+  - 'inclusion', followed by a YAML array (e.g. ['a','b','c']). Accepts a comma separated string as well.
+  - 'format', followed by a YAML regex (e.g. !ruby/regexp "/^UA-.{6}-.$/i"). String can be given as well, which will be converted to a regex. Note that you will not be able to pass regex modifiers in that case, therefore the YAML regex syntax is recommended.
 
 == Changing / Destroying settings
 
 * As settings are represented by a Setting ActiveRecord model, you can just update and destroy them like you would update or destroy any AR model.
 
+* The 'key' attribute is read only as it should never be changed through your application.
+
+* The 'editable', 'deletable' and 'deleted' attributes are protected from mass assignment using attr_protected.
+
 * By default, settings will only be editable or deletable iff the corresponding attribute is set to 'true'. This will be enforced before saving or destroying a record:
 
     >> Settler.google_analytics_key.destroy
@@ -128,10 +172,6 @@ In this case, 'google_analytics_key' is the key of the setting. Every nested pro
 
       Settler.raise_missing = true
 
-== To do
-
-* Add more validations, for now only 'presence' and 'inclusion' are supported.
-
 == Note on Patches/Pull Requests
  
 * Fork the project.

data/VERSION

@@ -1 +1 @@
-1.0.3
+1.1.0

data/init.rb

@@ -1,3 +1,4 @@
 require 'hash_extension'
 require 'setting'
-require 'settler'
+require 'settler'
+require 'type_casters'

data/lib/setting.rb

@@ -1,5 +1,10 @@
+require 'type_casters'
+
 # The Setting class is an AR model that encapsulates a Settler setting. The key if the setting is the only required attribute.\
 class Setting < ActiveRecord::Base  
+  attr_readonly   :key
+  attr_protected  :editable, :deletable, :deleted  
+  
   before_update :ensure_editable
   
   validates_presence_of :key  
@@ -8,6 +13,28 @@ class Setting < ActiveRecord::Base
   serialize :value
   
   default_scope :conditions => ['deleted = ? or deleted IS NULL', false]
+  named_scope :editable, :conditions => { :editable => true }
+  named_scope :deletable, :conditions => { :deletable => true }  
+  
+  # Returns the value, typecasted if a typecaster is available.
+  def value
+    typecast.present? ? typecasted_value : super
+  end
+  
+  # Reads the raw, untypecasted value.
+  def untypecasted_value
+    read_attribute(:value)
+  end
+
+  # Returns the typecasted value or the raw value if a typecaster could not be found.
+  def typecasted_value
+    typecaster.present? ? typecaster.typecast(untypecasted_value) : untypecasted_value
+  end
+  
+  # Finds the typecast for this key in the settler configuration.
+  def typecast
+    @typecast ||= Settler.typecast_for(key)
+  end
   
   # Returns all valid values for this setting, which is based on the presence of an inclusion validator.
   # Will return nil if no valid values could be determined.
@@ -38,12 +65,18 @@ class Setting < ActiveRecord::Base
     Setting.with_exclusive_scope(&block)
   end
   
+  # Deleted scope is specified as a method as it needs to be an exclusive scope
+  def self.deleted
+    Setting.without_default_scope{ Setting.all :conditions => { :deleted => true } }
+  end
+  
 protected
 
   # Performs instance validations as defined in the settler configuration.
   def setting_validations
     errors.add(:value, I18n.t(:blank, :scope => 'activerecord.errors.messages')) if validators['presence'] && ['1','true',true].include?(validators['presence']) && self.value.nil?
     errors.add(:value, I18n.t(:inclusion, :scope => 'activerecord.errors.messages')) if valid_values && !valid_values.include?(self.value)
+    errors.add(:value, I18n.t(:format, :scope => 'activerecord.errors.messages')) if validators['format'] && !(Regexp.new(validators['format']) =~ self.value)
   end
   
   # Retrieves all validators defined for this setting.
@@ -51,7 +84,12 @@ protected
     @validators ||= Settler.validations_for(self.key)
   end
   
+  # Retrieves the typecaster instance that will typecast the value of this setting.
+  def typecaster
+    @typecaster ||= Typecaster.typecaster_for(typecast)    
+  end
+  
   # Before_update filter to ensure uneditable settings cannot be updated.
-  def ensure_editable;  return false unless editable?  end  
+  def ensure_editable; return false unless editable? end  
     
 end

data/lib/settler.rb

@@ -1,6 +1,6 @@
-require "yaml"
-require "erb"
-require "hash_extension"
+require 'yaml'
+require 'erb'
+require 'hash_extension'
 
 # Settler loads and manages application wide settings and provides an interface for retrieving settings. The Settler
 # object cannot be instantiated; all functionality is available on class level.
@@ -13,9 +13,17 @@ class Settler
     # Loads the settler configuration from settler.yml and defines methods for retrieving the found settings.
     def load!    
       raise "Source settler.yml not set. Please create one and set it by using Settler.source = <file>. When using Rails, please create a settler.yml file in the config directory." unless source
+      
       self.config = YAML.load(ERB.new(File.read(source)).result).to_hash
       self.config = config[namespace] if namespace
-      self.config.each{ |key, attributes| Setting.without_default_scope { Setting.find_or_create_by_key(attributes.only(:alt, :value, :editable, :deletable).merge(:key => key)) } }
+      self.config.each do  |key, attributes| 
+        Setting.without_default_scope do 
+          Setting.find_or_create_by_key(attributes.only(:alt, :value).merge(:key => key)) do |s|
+             s.editable = attributes['editable']
+             s.deletable = attributes['deletable']
+          end
+        end 
+      end
       Setting.all.each{ |s| key = s.key; Settler.class.send(:define_method, key){ Setting.find_by_key(key) } }
     end    
     
@@ -26,9 +34,9 @@ class Settler
     end
     
     # Returns an array of all setting keys
-    def settings
+    def settings(options = {})
       Settler.load! if config.nil?
-      Setting.all.map(&:key)
+      Setting.all(:order => options[:order]).map(&:key)
     end  
     
     # Returns a list of validations to perform on a setting.
@@ -38,6 +46,12 @@ class Settler
       (setting = config[key.to_s]) ? setting['validations'] || {} : {}
     end
     
+    # Returns the typecast for a setting (if any).
+    def typecast_for(key)
+      Settler.load! if config.nil?
+      (setting = config[key.to_s]) ? setting['typecast'] || nil : nil
+    end    
+    
     # Overrides the normal method_missing to return nil for non-existant settings. The behaviour of this method
     # depends on the boolean attributes raise_missing and report_missing.
     def method_missing(name, *args, &block)

data/lib/type_casters.rb

@@ -0,0 +1,55 @@
+require 'singleton'
+
+# The TypeClaster class maintains a list of typecasters and retrieves the appropriate typecaster
+# for a given data type.
+class Typecaster
+  include Singleton
+
+  # Returns the list of available typecasters
+  def self.registered_typecasters
+    @@registered_typecasters ||= [self.instance, IntegerTypecaster.instance, FloatTypecaster.instance, BooleanTypecaster.instance]
+  end
+  
+  # Returns the first typecaster from the list of typecasters that is able to typecast the passed type.
+  def self.typecaster_for(typecast)
+    typecaster = typecast.constantize.instance rescue nil
+    typecaster.present? && typecaster.is_a?(Typecaster) ? typecaster : registered_typecasters.detect{|tc| tc.type == typecast } || self.new
+  end
+  
+  # Subclasses should implement this method and return the type of data it can typecast.
+  def type; nil end
+  
+  # Subclasses should implement this method and return the typecasted value of the passed value.
+  # By default, the untypecasted value will be returned.
+  def typecast(value)
+    value
+  end
+end
+
+# Casts a value to an integer
+class IntegerTypecaster < Typecaster
+  def type; 'integer' end
+  
+  def typecast(value)
+    value.to_i
+  end
+end
+
+# Casts a value to a float
+class FloatTypecaster < Typecaster
+  def type; 'float' end
+  
+  def typecast(value)
+    value.to_f
+  end
+end
+
+# Casts a value to a boolean. '1', 't' or 'true' (case ignored) will evaluate to 
+# true, otherwise the result will be false.
+class BooleanTypecaster < Typecaster
+  def type; 'boolean' end
+  
+  def typecast(value)
+    !(/^(1|t|true)$/i =~ value.to_s).nil?
+  end
+end

data/settler.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{settler}
-  s.version = "1.0.3"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Reinier de Lange"]
-  s.date = %q{2010-09-23}
+  s.date = %q{2010-09-26}
   s.description = %q{This gem is a combination of the Squeegy's rails-settings and Binarylogic's settingslogic gem, meaning it reads its configuration from a YAML file, but stores all settings in the database as well for on the fly changes.}
   s.email = %q{r.j.delange@nedforce.nl}
   s.extra_rdoc_files = [
@@ -30,7 +30,9 @@ Gem::Specification.new do |s|
      "lib/hash_extension.rb",
      "lib/setting.rb",
      "lib/settler.rb",
+     "lib/type_casters.rb",
      "settler.gemspec",
+     "test/custom_typecaster.rb",
      "test/database.yml",
      "test/helper.rb",
      "test/schema.rb",
@@ -43,7 +45,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{Settler manages global application settings in Rails}
   s.test_files = [
-    "test/helper.rb",
+    "test/custom_typecaster.rb",
+     "test/helper.rb",
      "test/schema.rb",
      "test/test_settler.rb"
   ]

data/test/custom_typecaster.rb

@@ -0,0 +1,5 @@
+class CustomTypecaster < Typecaster
+  def typecast(value)
+    'custom value'
+  end
+end

data/test/settler.yml

@@ -1,10 +1,11 @@
 settings:
   google_analytics_key:
-    alt: Google analytics key
+    alt: Google analytics key 
     value: 'UA-xxxxxx-x'
     editable: true
-    deletable: false
+    deletable: false    
     validations:
+      format: !ruby/regexp "/^UA-.{6}-.$/i" 
       presence: true
   search_algorithm:
     alt: Default search engine
@@ -13,4 +14,20 @@ settings:
     deletable: true
     validations:
       inclusion: [ 'ferret' , 'sphinx' ]
+  bool_value:
+    alt: A boolean that should be typecasted
+    value: true
+    typecast: boolean    
+  float_value:
+    alt: A float that should be typecasted
+    value: 0.25
+    typecast: float 
+  integer_value:
+    alt: An integer that should be typecasted
+    value: 3
+    typecast: integer           
+  custom_value:
+    alt: An integer that should be custom typecasted
+    value: 1
+    typecast: CustomTypecaster      
 

data/test/test_settler.rb

@@ -11,7 +11,7 @@ class TestSettler < Test::Unit::TestCase
   end
     
   def test_should_load_settings
-    assert_equal ['google_analytics_key', 'search_algorithm'], Settler.settings
+    assert_equal ["bool_value", "custom_value", "float_value", "google_analytics_key", "integer_value", "search_algorithm"], Settler.settings(:order => :key) 
   end
   
   def test_should_find_setting_value
@@ -20,7 +20,7 @@ class TestSettler < Test::Unit::TestCase
   end
   
   def test_should_get_validations_for_setting
-    assert_equal({'presence' => true}, Settler.validations_for(:google_analytics_key))
+    assert Settler.validations_for(:google_analytics_key).keys.include?('presence')
     assert_equal({"inclusion"=>["ferret", "sphinx"]}, Settler.validations_for(:search_algorithm))
   end
   
@@ -31,7 +31,7 @@ class TestSettler < Test::Unit::TestCase
   end
   
   def test_should_report_or_raise_missing    
-    Settler.report_missing = true    
+    #Settler.report_missing = true    
     Settler.raise_missing = true
     
     assert_raise RuntimeError do
@@ -61,8 +61,68 @@ class TestSettler < Test::Unit::TestCase
   
   def test_should_update_editable_setting
     editable_setting = Settler.google_analytics_key
-    assert editable_setting.update_attributes(:value => 'new_value')
-    assert_equal 'new_value', Settler[:google_analytics_key]
-  end  
+    assert editable_setting.update_attributes(:value => 'UA-xxxxxx-1')
+    assert_equal 'UA-xxxxxx-1', Settler[:google_analytics_key]
+  end
+  
+  def test_key_should_be_readonly_attribute
+    setting = Settler.google_analytics_key
+    setting.update_attribute(:key, 'new_key')
+    assert_equal 'google_analytics_key', setting.reload.key
+  end
+  
+  def test_should_not_update_protected_attributes
+    setting = Settler.google_analytics_key
+    assert setting.update_attributes(:key => 'new_key', :alt => 'new_alt', :value => 'UA-xxxxxx-1', :editable => false, :deletable => true, :deleted => true)
+    setting.reload
+    assert_equal 'google_analytics_key', setting.key
+    assert_equal 'new_alt', setting.alt         
+    assert_equal 'UA-xxxxxx-1', setting.value    
+    assert setting.editable?        
+    assert !setting.deletable?
+    assert_nil setting.deleted    
+  end
+  
+  def test_should_get_scopes
+    assert_equal [Settler.google_analytics_key], Setting.editable
+    assert_equal [Settler.search_algorithm], Setting.deletable
+
+    assert_equal [], Setting.deleted        
+    deletable_setting = Settler.search_algorithm
+    assert deletable_setting.destroy
+    assert_equal [deletable_setting], Setting.deleted    
+  end
+  
+  def test_should_typecast
+    require 'custom_typecaster'
+    assert_equal 3, Settler.integer_value.value
+    assert_equal 0.25, Settler.float_value.value
+    assert_equal true, Settler.bool_value.value        
+    assert_equal 'custom value', Settler.custom_value.value                  
+  end
+  
+  def test_boolean_typecaster
+    bool_setting = Settler.bool_value
+    assert_equal true, bool_setting.value
+    bool_setting.update_attribute(:value, false)      
+    assert_equal false, bool_setting.value    
+    bool_setting.update_attribute(:value, 'f')      
+    assert_equal false, bool_setting.value      
+    bool_setting.update_attribute(:value, 'bla')      
+    assert_equal false, bool_setting.value          
+    bool_setting.update_attribute(:value, 't')      
+    assert_equal true, bool_setting.value     
+    bool_setting.update_attribute(:value, 'true')      
+    assert_equal true, bool_setting.value  
+    bool_setting.update_attribute(:value, 'TrUe')      
+    assert_equal true, bool_setting.value    
+    bool_setting.update_attribute(:value, 'tr')      
+    assert_equal false, bool_setting.value        
+  end
+  
+  def test_should_validate_format
+    setting = Settler.google_analytics_key
+    assert !setting.update_attributes(:value => 'invalid_format')    
+  end
   
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 3
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors: 
 - Reinier de Lange
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-23 00:00:00 +02:00
+date: 2010-09-26 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -41,7 +41,9 @@ files:
 - lib/hash_extension.rb
 - lib/setting.rb
 - lib/settler.rb
+- lib/type_casters.rb
 - settler.gemspec
+- test/custom_typecaster.rb
 - test/database.yml
 - test/helper.rb
 - test/schema.rb
@@ -78,6 +80,7 @@ signing_key:
 specification_version: 3
 summary: Settler manages global application settings in Rails
 test_files: 
+- test/custom_typecaster.rb
 - test/helper.rb
 - test/schema.rb
 - test/test_settler.rb