modelish 0.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.yardoc/*
+doc/*
+*~
+.DS_Store

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.rvmrc

@@ -0,0 +1,3 @@
+branch_name=`git branch --no-color 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/\1/'`
+#rvm --create use 1.9.2@modelish-${branch_name}
+rvm --create use 1.8.7@modelish-${branch_name}

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in modelish.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Maeve Revels
+
+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.md

@@ -0,0 +1,95 @@
+# modelish #
+
+When a real modeling framework is too heavy, sometimes you want something just 
+a little modelish.
+
+If a Hash or OpenStruct almost suits your needs, but you need bits of 
+model-like behavior such as simple validation and typed values, modelish can 
+help.
+
+If you need persistence or anything but the most basic functionality, modelish 
+will frustrate you to no end.
+
+## Installation ##
+
+For the especially foolhardy, you can:
+
+1. Add this to your Gemfile:
+
+         gem 'modelish', :git => 'git://github.com/maeve/modelish.git'
+
+2. Execute `bundle install`
+
+## Basics ##
+
+The modelish syntax is very similar to some of the classes provided by 
+[hashie]. In fact, the initial implementation simply extended 
+[Hashie::Trash][trash] to add property types:
+
+        require 'modelish'
+
+        class Foo < Modelish::Base
+          property :my_date, :type => Date
+          property :my_float, :type => Float, :default => 0.0
+          property :my_funky_id, :type => Integer, :from => 'MyFUNKYId'
+          property :my_simple_property
+        end
+
+You can then set properties as string value and have them automatically 
+converted to the appropriate type, while respecting default values and 
+key-mappings:
+
+       f = Foo.new('MyFUNKYId' => '42', 
+                   :my_date => '2011-03-10', 
+                   :my_simple_property => 'bar')
+
+       f.my_date
+         => #<Date: 2011-03-10 (4911261/2,0,2299161)> 
+       f.my_float
+         => 0.0 
+       f.my_funky_id
+         => 42 
+       f.my_simple_property
+         => "bar" 
+
+modelish also supports defining simple property validations:
+
+        class Bar < Modelish::Base
+            property :important_field, :required => true
+            property :state, :max_length => 2
+            property :my_int, :type => Integer, :validate_type => true
+            property :another_field, :validator => lambda { |val| "val must respond to []" unless val.respond_to?(:[]) }
+        end
+
+Validations can be run using methods that return an error map (keyed on property name), raise errors, or return a boolean value to indicate validation outcome.
+
+        valid_bar = Bar.new(:important_field => 'some value', 
+                            :state => 'OR', 
+                            :my_int => 42, 
+                            :another_field => Hash.new)
+        valid_bar.valid?
+          => true
+
+        valid_bar.validate
+          => {}
+
+        valid_bar.validate!
+          => nil
+
+
+        invalid_bar = Bar.new(:state => 'a value that is too long',
+                              :my_int => 'this is not an integer',
+                              :another_field => Object.new)
+        invalid_bar.valid?
+          => false
+
+        invalid_bar.validate
+          => {:important_field=>[#<ArgumentError: important_field must not be nil or blank>], :my_int=>[#<ArgumentError: my_int must be of type Integer, but got "this is not an integer">], :another_field=>[#<ArgumentError: val must respond to []>], :state=>[#<ArgumentError: state must be less than 2 characters>]}
+
+        invalid_bar.validate!
+          ArgumentError: important_field must not be nil or blank
+                  from /Users/maeverevels/projects/modelish/lib/modelish/validations.rb:31:in `validate!'
+                  ...
+
+ [hashie]: https://github.com/intridea/hashie
+ [trash]: http://rdoc.info/github/intridea/hashie/master/Hashie/Trash

data/Rakefile

@@ -0,0 +1,17 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['README.md', 'lib/**/*.rb']
+    task.options = [
+      '--markup', 'markdown',
+    ]
+  end
+end

data/lib/modelish.rb

@@ -0,0 +1,8 @@
+$:.unshift(File.expand_path('modelish',File.dirname(__FILE__)))
+
+require 'version'
+require 'base'
+
+module Modelish
+  # Your code goes here...
+end

data/lib/modelish/base.rb

@@ -0,0 +1,44 @@
+require 'hashie'
+require 'property_types'
+require 'validations'
+
+module Modelish
+  class Base < Hashie::Trash
+    include PropertyTypes
+    include Validations
+
+    # Creates a new attribute.
+    #
+    # @param [Symbol] name the name of the property
+    # @param [Hash] options configuration for the property
+    # @option opts [Object] :default the default value for this property
+    #                                when the value has not been explicitly
+    #                                set (defaults to nil)
+    # @option opts [#to_s] :from the original key name for this attribute
+    #                            (created as write-only)
+    # @option opts [Class,Proc] :type the type of the property value. For
+    #                                 a list of accepted types, see
+    #                                 {Modelish::PropertyTypes}
+    # @options opts [true,false] :required enables validation for the property
+    #                                      value's presence; nil or blank values
+    #                                      will cause validation methods to fail
+    # @options opts [Integer] :max_length the maximum allowable length for a valid
+    #                                     property value
+    # @options opts [true,false] :validate_type enables validation for the property value's
+    #                                           type based on the :type option
+    # @options opts [Proc] :validator A block that accepts a value and validates it;
+    #                                 should return nil if validation passes, or an error
+    #                                 message or error object if validation fails.
+    #                                 See {Modelish::Validations}
+    def self.property(name, options={})
+      super
+
+      add_property_type(name, options[:type]) if options[:type]
+
+      add_validator(name) { |val| validate_required(name => val).first } if options[:required]
+      add_validator(name) { |val| validate_length(name, val, options[:max_length]) } if options[:max_length]
+      add_validator(name, &options[:validator]) if options[:validator]
+      add_validator(name) { |val| validate_type(name, val, options[:type]) } if options[:validate_type]
+    end
+  end
+end

data/lib/modelish/property_types.rb

@@ -0,0 +1,133 @@
+require 'date'
+
+module Modelish
+  # Mixes in behavior for automatically converting property types.
+  module PropertyTypes
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Adds a typed property to the model.
+      # This dynamically generates accessor/mutator methods that perform
+      # the appropriate type conversions on the property's value.
+      # 
+      # Generated methods:
+      # * +<property_name>=(new_value)+ -- sets the property value. 
+      # * +<property_name>+ -- returns the property value, converted to the configured
+      #                        type. If the value cannot be converted, no error will be
+      #                        raised, and the raw unconverted value will be returned.
+      # * +<property_name>!+ -- returns the property value, converted to the configured
+      #                         type. If the value cannot be converted, a TypeError will
+      #                         be raised.
+      # * +raw_<property_name> -- the original property value, without any type conversions.
+      # 
+      # @param [Symbol] property_name the name of the property.
+      # @param [Class, Proc] property_type the type of the property's value.
+      #                                    Valid types include:
+      #   * +Integer+
+      #   * +Float+
+      #   * +Array+
+      #   * +Date+ -- converts using Date.parse on value.to_s
+      #   * +Symbol+ -- also converts from camel case to snake case
+      #   * +String+
+      #   * any arbitrary +Class+ -- will attempt conversion by passing the raw
+      #                              value into the class's initializer
+      #   * an instance of +Proc+ -- will convert the value by executing the proc,
+      #                              passing in the raw value as an argument
+      def add_property_type(property_name, property_type=String)
+        accessor = property_name.to_sym
+        property_types[accessor] = property_type
+
+        raw_accessor = define_raw_accessor(accessor)
+        bang_accessor = define_bang_accessor(accessor)
+
+        typed_accessor = "_typed_#{accessor}".to_sym
+        typed_mutator = "#{typed_accessor}=".to_sym
+        to_safe = "_to_safe_#{accessor}".to_sym
+
+        class_eval do
+          attr_accessor typed_accessor
+          private typed_accessor, typed_mutator
+
+          define_method(to_safe) do
+            self.send(bang_accessor) rescue self.send(raw_accessor)
+          end
+          private to_safe
+
+          define_method(accessor) do
+            val = self.send(typed_accessor)
+
+            unless val || self.send(raw_accessor).nil?
+              val = self.send(to_safe)
+              self.send(typed_mutator, val)
+            end
+
+            val
+          end
+
+          define_method("#{accessor}=") do |val|
+            self.send("#{raw_accessor}=", val)
+            self.send(typed_mutator, self.send(to_safe))
+          end
+        end
+      end
+
+      def property_types
+        @property_types ||= {}
+      end
+
+      private
+      def define_raw_accessor(name)
+        accessor = name.to_sym
+        raw_accessor = "raw_#{name}".to_sym
+
+        mutator = "#{name}=".to_sym
+        raw_mutator = "raw_#{name}=".to_sym
+
+        class_eval do
+          if method_defined?(accessor) && method_defined?(mutator)
+            alias_method(raw_accessor, accessor)
+            alias_method(raw_mutator, mutator)
+          else
+            attr_accessor raw_accessor
+          end
+        end
+
+        raw_accessor
+      end
+
+      def define_bang_accessor(property_name)
+        bang_accessor = "#{property_name}!".to_sym
+        converter = value_converter(property_types[property_name.to_sym])
+
+        class_eval do
+          define_method(bang_accessor) do
+            value = self.send("raw_#{property_name}")
+            (converter && value) ? converter.call(value) : value
+          end
+        end
+
+        bang_accessor
+      end
+
+      def value_converter(property_type)
+        if property_type == Date
+          lambda { |val| Date.parse(val.to_s) }
+        elsif property_type == Symbol
+          lambda { |val| val.to_s.strip.gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2').
+                                          gsub(/([a-z\d])([A-Z])/, '\\1_\\2').
+                                          gsub(/\s+|-/,'_').downcase.to_sym }
+        elsif property_type == String
+          lambda { |val| val.to_s.strip }
+        elsif Kernel.respond_to?(property_type.to_s) 
+          lambda { |val| Kernel.send(property_type.to_s, val) }
+        elsif property_type.respond_to?(:call)
+          property_type
+        else
+          lambda { |val| property_type.new(val) }
+        end
+      end
+    end
+  end
+end

data/lib/modelish/validations.rb

@@ -0,0 +1,208 @@
+require 'date'
+
+module Modelish
+  module Validations
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Validates all properties based on configured validators.
+    #
+    # @return [Hash<Symbol,Array>] map of errors where key is the property name
+    #                              and value is the list of errors
+    # @see ClassMethods#add_validator
+    def validate
+      errors = {}
+ 
+      call_validators do |name,message|
+        errors[name] ||= []
+        errors[name] << to_error(message)
+      end
+
+      errors
+    end
+
+    # Validates all properties based on configured validators.
+    #
+    # @raise ArgumentError when any property fails validation
+    def validate!
+      call_validators do |name,message| 
+        error = to_error(message)
+        raise error if error
+      end
+      nil
+    end
+
+    def valid?
+      validate.empty?
+    end
+
+    private
+    def call_validators(&error_handler)
+      self.class.validators.each_pair do |k,v|
+        v.each do |prop_validator|
+          if msg = prop_validator.call(self.send(k))
+            error_handler.call(k, msg)
+          end
+        end
+      end
+    end
+
+    def to_error(msg)
+      msg.is_a?(StandardError) ? msg : ArgumentError.new(msg.to_s)
+    end
+
+    module ClassMethods
+      # Sets up a block containing validation logic for a given property.
+      # Each property may have 0 or more validators.
+      #
+      # @param [String,Symbol] property_name the name of the property to validate
+      # @param [#call] validator the block containing the validation logic; must return
+      #                          either an error object or a string containing the error
+      #                          message if validation fails.
+      # 
+      # @example adding a validator that only allows non-nil values
+      #     class MyModel
+      #       include Modelish::Validations
+      #       attr_accessor :foo
+      #       add_validator(:foo) { |val| val.nil? ? 'foo must not be nil': nil }
+      #     end
+      def add_validator(property_name, &validator)
+        validators[property_name.to_sym] ||= [] 
+        validators[property_name.to_sym] << validator
+
+        class_eval do
+          attr_accessor property_name.to_sym unless method_defined?(property_name.to_sym)
+        end
+      end
+
+      # A map of registered validator blocks, keyed on property_name.
+      def validators
+        @validators ||= {}
+      end
+
+      # Validates the required values, returning a list of errors when validation
+      # fails.
+      #
+      # @param [Hash] args the map of name => value pairs to validate
+      # @return [Array<ArgumentError>] a list of ArgumentErrors for validation failures.
+      def validate_required(args)
+        errors = []
+        args.each do |name, value|
+          errors << ArgumentError.new("#{name} must not be nil or blank") if value.nil? || value.to_s.strip.empty?
+        end
+        errors
+      end
+
+      # Validates the required values, raising an error when validation fails.
+      #
+      # @param [Hash] args the map of name => value pairs to validate
+      # @raise [ArgumentError] when any value in args hash is nil or empty. The name
+      #                        key will be used to construct an informative error message.
+      def validate_required!(args)
+        errors = validate_required(args)
+        raise errors.first unless errors.empty?
+      end
+
+      # Validates the required values, returning a boolean indicating validation success.
+      #
+      # @param [Hash] args the map of name => value pairs to validate
+      # @return [true,false] true when validation passes; false when validation fails
+      def validate_required?(args)
+        validate_required(args).empty?
+      end
+
+      # Validates the length of a value, raising an error to indicate validation failure.
+      #
+      # @param (see .validate_length)
+      # @raise [ArgumentError] when the value is longer than max_length
+      def validate_length!(name, value, max_length)
+        error = validate_length(name, value, max_length)
+        raise error if error
+      end
+
+      # Validates the length of a value, returning a boolean to indicate validation
+      # success.
+      #
+      # @param (see .validate_length)
+      # @return [true,false] true if value does not exceed max_length; false otherwise
+      def validate_length?(name, value, max_length)
+        validate_length(name, value, max_length).nil?
+      end
+
+      # Validates the length of a value, returning an error when validation fails.
+      #
+      # @param [Symbol,String] name the name of the property/argument to be validated
+      # @param [#length] value the value to be validated
+      # @param [#to_i] max_length the maximum allowable length
+      # @raise [ArgumentError] when the value is longer than max_length
+      def validate_length(name, value, max_length)
+        if max_length.to_i > 0 && value.to_s.length > max_length.to_i
+          ArgumentError.new("#{name} must be less than #{max_length} characters")
+        end
+      end
+
+      # Validates the type of the value, returning a boolean indicating validation
+      # outcome.
+      #
+      # @see #validate_type
+      # @param {see #validate_type}
+      # @return [true,false] true when the value is the correct type; false otherwise
+      def validate_type?(name, value, type)
+        validate_type(name, value, type).nil?
+      end
+
+      # Validates the type of the value, raising an error when the value is not
+      # of the correct type.
+      #
+      # @see #validate_type
+      # @param {see #validate_type}
+      # @raise [ArgumentError] when the value is not the correct type
+      def validate_type!(name, value, type)
+        error = validate_type(name, value, type)
+        raise error if error
+      end
+
+      # Validates the type of the value, returning an error when the value cannot
+      # be converted to the appropriate type.
+      #
+      # @param [Symbol,String] name the name of the property/argument to be validated
+      # @param [Object] value the value to be validated
+      # @param [Class,Proc] type the type of the class to be validated. Supported types include:
+      #   * +Integer+
+      #   * +Float+
+      #   * +Date+
+      #   * +Symbol+ 
+      #   * any arbitrary +Class+ -- validates based on the results of is_a?
+      # @return [ArgumentError] when validation fails
+      def validate_type(name, value, type)
+        error = nil
+
+        begin
+          if value && type
+            # Can't use a case statement because of the way === is implemented on some classes
+            if type == Integer
+              is_valid = (value.is_a?(Integer) || value.to_s =~ /^\-?\d+$/)
+            elsif type == Float
+              is_valid = (value.is_a?(Float) || value.to_s =~ /^\-?\d+\.?\d*$/)
+            elsif type == Date
+              is_valid = (value.is_a?(Date) || Date.parse(value)) 
+            elsif type == Symbol
+              is_valid = value.respond_to?(:to_sym)
+            else
+              is_valid = value.is_a?(type)
+            end
+
+            unless is_valid
+              error = ArgumentError.new("#{name} must be of type #{type}, but got #{value.inspect}")
+            end
+          end
+        rescue StandardError => e
+          error = ArgumentError.new("An error occurred validating #{name} with value #{value.inspect}: #{e.message}")
+        end
+
+        error
+      end
+    end
+  end
+end