preferable 0.1.0

data/README.markdown

@@ -0,0 +1,117 @@
+# Preferable
+
+Simple filtering for ActiveRecord. Sanitizes simple and readable query parameters -great for building APIs & HTML filters.
+
+## Installation
+
+Add this line to your Gemfile:
+
+   gem "preferable"
+
+Then, bundle:
+
+    $ bundle install
+
+Add a new migration to your project. Example:
+
+    $ rails g migration AddPreferencesToUsers
+
+    # Rails 2 & 3.0
+    class AddPreferencesToUsers < ActiveRecord::Migration
+      def self.up
+        add_column :users, :prefeences, :text
+      end
+
+      def self.down
+        remove_column :users, :prefeences, :text
+      end
+    end
+
+    # Rails >=3.1
+    class AddPreferencesToUsers < ActiveRecord::Migration
+      def change
+        add_column :users, :prefeences, :text
+      end
+    end
+
+
+## Usage Examples:
+
+Specify simple preferences, with defaults:
+
+    class User < ActiveRecord::Base
+
+      preferable do
+        integer :theme_id
+        boolean :newsletter, :default => false
+        string  :font_color, :default => "444444"
+      end
+
+    end
+
+Read and write preferences:
+
+    user = User.find(1)
+    user.preferences[:newsletter] # => false
+
+    # Set single preferences (with type casting)
+    user.preferences[:newsletter] = '1'
+    user.preferences[:newsletter] # => true
+
+    # or, bulk-set (e.g. from forms)
+    user.preferences = { :newsletter => '1' }
+
+    # Makes preferences persistent
+    user.save
+
+Specify condititions (if/unless):
+
+    class User < ActiveRecord::Base
+
+      preferable do
+        string  :font_color, :default => "444444", :if => lambda {|v| v =~ /^[A-F0-9]{6}$/ }
+      end
+
+    end
+
+    user = User.find(1)
+    user.preferences[:font_color] = 'INVALID'
+    user.preferences[:font_color] # => '444444'
+
+Store even arrays (with internal casting):
+
+    class User < ActiveRecord::Base
+
+      preferable do
+        array  :popular_words, :cast => :string
+      end
+
+    end
+
+    user = User.find(1)
+    user.preferences[:popular_words] = 'hello'
+    user.preferences[:popular_words] # => ['hello']
+
+## License
+
+    Copyright (C) 2011 Dimitrij Denissenko
+
+  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/lib/preferable/field.rb

@@ -0,0 +1,92 @@
+class Preferable::Field
+  TYPES = [:string, :integer, :float, :boolean, :date, :datetime, :array].to_set.freeze
+  TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE'].to_set
+
+  attr_reader :name, :type, :options, :default
+
+  # Create a new Field.
+  #
+  # Params:
+  #   name: The name symbol
+  #   type: The type symbol, see Preferable::Field::TYPES
+  #   options: The options hash (keys as symbols)
+  #
+  # Options:
+  #   default: The default value.
+  #   if:      Value assignment proc. Value is only assigned if true is yielded.
+  #   unless:  Value assignment proc. Value is only assigned if false is yielded.
+  #   cast:    Only relevant for :array type. Specify the type of the array contents.
+  #
+  # Examples:
+  #   Field.new :color, :string, :if => lambda {|v| v =~ /^[A-F0-9]{6}$/ }
+  #   Field.new :holidays, :array, :cast => :date
+  #   Field.new :newsletter, :boolean, :default => false
+  #   Field.new :age, :integer, :unless => &:zero?
+  #
+  def initialize(name, type, options = {})
+    raise ArgumentError, "Unknown type '#{type}', available types are: #{TYPES.map(&:to_s).join(', ')}" unless TYPES.include?(type.to_sym)
+
+    @name    = name.to_sym
+    @type    = type.to_sym
+    @options = options.dup
+    @default = type_cast @options.delete(:default)
+  end
+
+  # Returns true if a value is assignable, else false. Assumes given value is already type-casted.
+  def valid?(value)
+    result = true
+    result = options[:if].call(value) if result && options[:if]
+    result = !options[:unless].call(value) if result && options[:unless]
+    result
+  end
+
+  # Opposite of #valid?
+  def invalid?(value)
+    !valid?(value)
+  end
+
+  # Is value equal to the default. . Assumes given value is already type-casted.
+  def default?(value)
+    value == default
+  end
+
+  # Converts a value.
+  def type_cast(value, to = self.type)
+    return nil unless value
+
+    case to
+    when :string
+      value.to_s
+    when :integer
+      value.to_i
+    when :boolean
+      TRUE_VALUES.include?(value)
+    when :datetime
+      to_time(value)
+    when :date
+      to_time(value).try(:to_date)
+    when :float
+      value.to_f
+    when :array
+      Array.wrap(value).tap do |wrap|
+        wrap.map! {|item| type_cast(item, options[:cast]) } if options[:cast]
+      end
+    else
+      value
+    end
+  end
+
+  private
+
+    def to_time(value)
+      case value
+      when Time
+        value.in_time_zone
+      when Date
+        value.beginning_of_day
+      else
+        Time.zone.parse(value) rescue nil
+      end
+    end
+
+end

data/lib/preferable/model.rb

@@ -0,0 +1,55 @@
+# Includable module, for ActiveRecord::Base
+module Preferable::Model
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :_preferable
+  end
+
+  module ClassMethods
+
+    # Preferable definition for a model. Example:
+    #
+    #   class User < ActiveRecord::Base
+    #
+    #     preferable do
+    #       integer :theme_id
+    #       boolean :accessible, :default => false
+    #       string  :font_color, :default => "444444", :if => lambda {|value| value =~ /^[A-F0-9]{6}$/ }
+    #     end
+    #
+    #   end
+    #
+    def preferable(&block)
+      unless _preferable
+        self._preferable = Preferable::Schema.new
+        serialize :preferences, Preferable::Set
+        include PreferableMethods
+      end
+      self._preferable.instance_eval(&block) if block
+      self._preferable
+    end
+
+  end
+
+  module PreferableMethods
+
+    # Accessor to preferences. Examples:
+    #
+    #   user = User.find(1)
+    #   user.preferences[:theme_id] # => 8
+    #   user.preferences[:theme_id] = 3
+    #
+    def preferences
+      value = read_attribute(:preferences)
+      value.is_a?(Preferable::Set) ? value : write_attribute(:preferences, Preferable::Set.new(self.class.name))
+    end
+
+    # Preferences writer. Updates existing preferences (doesn't replace them!)
+    def preferences=(hash)
+      preferences.set(hash) if hash.is_a?(Hash)
+      preferences
+    end
+
+  end
+end

data/lib/preferable/schema.rb

@@ -0,0 +1,20 @@
+require 'set'
+
+class Preferable::Schema < Hash
+
+  def initialize
+    super
+  end
+
+  def field(name, type, options = {})
+    item = Preferable::Field.new(name, type, options)
+    self[item.name] = item
+  end
+
+  Preferable::Field::TYPES.each do |sym|
+    define_method sym do |name, options|
+      field name, sym, options
+    end
+  end
+
+end

data/lib/preferable/set.rb

@@ -0,0 +1,46 @@
+class Preferable::Set < Hash
+  MODEL_KEY = "_".freeze
+  PRIVATE   = [:rehash, :fetch, :store, :shift, :delete, :delete_if, :keep_if].to_set
+
+  # Make destructive methods private
+  (public_instance_methods - Hash.superclass.public_instance_methods).each do |m|
+    PRIVATE.include?(m.to_sym) || m.to_s.ends_with?('!')
+  end
+
+  def initialize(model_name)
+    super()
+    store MODEL_KEY, "::#{model_name}"
+  end
+
+  def model
+    @model ||= fetch(MODEL_KEY).constantize
+  end
+
+  def [](name)
+    field = find_field(name)
+    super(field.name) || field.default if field
+  end
+
+  def []=(name, value)
+    field = find_field(name) || return
+    value = field.type_cast(value)
+
+    if value.nil? || field.invalid?(value) || field.default?(value)
+      delete field.name
+    else
+      super field.name, value
+    end
+  end
+
+  def set(pairs)
+    pairs.each {|k, v| self[k] = v }
+    self
+  end
+
+  private
+
+    def find_field(name)
+      model.preferable[name.to_sym]
+    end
+
+end

data/lib/preferable.rb

@@ -0,0 +1,13 @@
+require "active_support/core_ext"
+require "active_record"
+
+module Preferable
+  autoload :Model,  "preferable/model"
+  autoload :Schema, "preferable/schema"
+  autoload :Field,  "preferable/field"
+  autoload :Set,    "preferable/set"
+end
+
+ActiveRecord::Base.class_eval do
+  include ::Preferable::Model
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification 
+name: preferable
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Dimitrij Denissenko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-07 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: abstract
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !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: *id002
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id003 !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: *id003
+description: Great for storing user preferences
+email: dimitrij@blacksquaremedia.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- lib/preferable/field.rb
+- lib/preferable/set.rb
+- lib/preferable/schema.rb
+- lib/preferable/model.rb
+- lib/preferable.rb
+has_rdoc: true
+homepage: https://github.com/bsm/preferable
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Simple preferences store for ActiveRecord
+test_files: []
+