activemodel 3.0.0.beta

data/CHANGELOG

@@ -0,0 +1,13 @@
+*Edge*
+
+* Change the ActiveModel::Base.include_root_in_json default to true for Rails 3 [DHH]
+
+* Add validates_format_of :without => /regexp/ option. #430 [Elliot Winkler, Peer Allan]
+
+  Example :
+
+      validates_format_of :subdomain, :without => /www|admin|mail/
+
+* Introduce validates_with to encapsulate attribute validations in a class.  #2630 [Jeff Dean]
+
+* Extracted from Active Record and Active Resource.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2004-2010 David Heinemeier Hansson
+
+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

@@ -0,0 +1,216 @@
+= Active Model - defined interfaces for Rails
+ 
+Prior to Rails 3.0, if a plugin or gem developer wanted to be able to have
+an object interact with Action Pack helpers, it was required to either
+copy chunks of code from Rails, or monkey patch entire helpers to make them
+handle objects that did not look like Active Record.  This generated code
+duplication and fragile applications that broke on upgrades.
+ 
+Active Model is a solution for this problem.
+ 
+Active Model provides a known set of interfaces that your objects can implement
+to then present a common interface to the Action Pack helpers.  You can include
+functionality from the following modules:
+ 
+* Adding attribute magic to your objects
+ 
+    Add prefixes and suffixes to defined attribute methods...
+    
+    class Person
+      include ActiveModel::AttributeMethods
+      
+      attribute_method_prefix 'clear_'
+      define_attribute_methods [:name, :age]
+      
+      attr_accessor :name, :age
+    
+      def clear_attribute(attr)
+        send("#{attr}=", nil)
+      end
+    end
+    
+    ...gives you clear_name, clear_age.
+  
+  {Learn more}[link:classes/ActiveModel/AttributeMethods.html]
+  
+* Adding callbacks to your objects
+ 
+    class Person
+      extend ActiveModel::Callbacks
+      define_model_callbacks :create
+    
+      def create
+        _run_create_callbacks do
+          # Your create action methods here
+        end
+      end
+    end
+    
+    ...gives you before_create, around_create and after_create class methods that
+    wrap your create method.
+   
+  {Learn more}[link:classes/ActiveModel/CallBacks.html]
+ 
+* For classes that already look like an Active Record object
+ 
+    class Person
+      include ActiveModel::Conversion
+    end
+    
+    ...returns the class itself when sent :to_model
+ 
+   {Learn more}[link:classes/ActiveModel/Conversion.html]
+ 
+* Tracking changes in your object
+ 
+    Provides all the value tracking features implemented by ActiveRecord...
+    
+    person = Person.new
+    person.name # => nil
+    person.changed? # => false
+    person.name = 'bob'
+    person.changed? # => true
+    person.changed # => ['name']
+    person.changes # => { 'name' => [nil, 'bob'] }
+    person.name = 'robert'
+    person.save
+    person.previous_changes # => {'name' => ['bob, 'robert']}
+ 
+  {Learn more}[link:classes/ActiveModel/Dirty.html]
+ 
+* Adding +errors+ support to your object
+ 
+    Provides the error messages to allow your object to interact with Action Pack
+    helpers seamlessly...
+    
+    class Person
+ 
+      def initialize
+        @errors = ActiveModel::Errors.new(self)
+      end
+ 
+      attr_accessor :name
+      attr_reader   :errors
+ 
+      def validate!
+        errors.add(:name, "can not be nil") if name == nil
+      end
+ 
+      def ErrorsPerson.human_attribute_name(attr, options = {})
+        "Name"
+      end
+ 
+    end
+    
+    ... gives you...
+    
+    person.errors.full_messages
+    # => ["Name Can not be nil"]
+    person.errors.full_messages
+    # => ["Name Can not be nil"]
+ 
+  {Learn more}[link:classes/ActiveModel/Errors.html]
+ 
+* Testing the compliance of your object
+ 
+    Use ActiveModel::Lint to test the compliance of your object to the
+    basic ActiveModel API...
+    
+  {Learn more}[link:classes/ActiveModel/Lint/Tests.html]
+ 
+* Providing a human face to your object
+ 
+    ActiveModel::Naming provides your model with the model_name convention
+    and a human_name attribute...
+    
+    class NamedPerson
+      extend ActiveModel::Naming
+    end
+    
+    ...gives you...
+    
+    NamedPerson.model_name        #=> "NamedPerson"
+    NamedPerson.model_name.human  #=> "Named person"
+ 
+  {Learn more}[link:classes/ActiveModel/Naming.html]
+ 
+* Adding observer support to your objects
+ 
+    ActiveModel::Observers allows your object to implement the Observer
+    pattern in a Rails App and take advantage of all the standard observer
+    functions.
+  
+  {Learn more}[link:classes/ActiveModel/Observer.html]
+ 
+* Making your object serializable
+ 
+    ActiveModel::Serialization provides a standard interface for your object
+    to provide to_json or to_xml serialization...
+    
+    s = SerialPerson.new
+    s.serializable_hash   # => {"name"=>nil}
+    s.to_json             # => "{\"name\":null}"
+    s.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+  
+  {Learn more}[link:classes/ActiveModel/Serialization.html]
+    
+ 
+* Turning your object into a finite State Machine
+ 
+    ActiveModel::StateMachine provides a clean way to include all the methods
+    you need to transform your object into a finite State Machine...
+ 
+    light = TrafficLight.new
+    light.current_state       #=> :red
+    light.change_color!       #=> true
+    light.current_state       #=> :green
+ 
+  {Learn more}[link:classes/ActiveModel/StateMachine.html]
+ 
+* Integrating with Rail's internationalization (i18n) handling through
+  ActiveModel::Translations...
+ 
+    class Person
+      extend ActiveModel::Translation
+    end
+  
+  {Learn more}[link:classes/ActiveModel/Translation.html]
+ 
+* Providing a full Validation stack for your objects...
+ 
+   class Person
+     include ActiveModel::Validations
+ 
+     attr_accessor :first_name, :last_name
+ 
+     validates_each :first_name, :last_name do |record, attr, value|
+       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
+     end
+   end
+ 
+   person = Person.new(:first_name => 'zoolander')
+   person.valid?          #=> false
+ 
+  {Learn more}[link:classes/ActiveModel/Validations.html]
+  
+* Make custom validators
+ 
+   class Person
+     include ActiveModel::Validations
+     validates_with HasNameValidator
+     attr_accessor :name
+   end
+   
+   class HasNameValidator < ActiveModel::Validator
+     def validate(record)
+      record.errors[:name] = "must exist" if record.name.blank?
+     end
+   end
+  
+   p = ValidatorPerson.new
+   p.valid?                  #=>  false
+   p.errors.full_messages    #=> ["Name must exist"]
+   p.name = "Bob"
+   p.valid?                  #=>  true
+ 
+  {Learn more}[link:classes/ActiveModel/Validator.html]

data/lib/active_model.rb

@@ -0,0 +1,61 @@
+#--
+# Copyright (c) 2004-2010 David Heinemeier Hansson
+#
+# 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.
+#++
+
+activesupport_path = File.expand_path('../../../activesupport/lib', __FILE__)
+$:.unshift(activesupport_path) if File.directory?(activesupport_path) && !$:.include?(activesupport_path)
+require 'active_support'
+
+
+module ActiveModel
+  extend ActiveSupport::Autoload
+
+  autoload :AttributeMethods
+  autoload :BlockValidator, 'active_model/validator'
+  autoload :Callbacks
+  autoload :Conversion
+  autoload :DeprecatedErrorMethods
+  autoload :Dirty
+  autoload :EachValidator, 'active_model/validator'
+  autoload :Errors
+  autoload :Lint
+  autoload :Name, 'active_model/naming'
+  autoload :Naming
+  autoload :Observer, 'active_model/observing'
+  autoload :Observing
+  autoload :Serialization
+  autoload :TestCase
+  autoload :Translation
+  autoload :VERSION
+  autoload :Validations
+  autoload :Validator
+
+  module Serializers
+    extend ActiveSupport::Autoload
+
+    autoload :JSON
+    autoload :Xml
+  end
+end
+
+require 'active_support/i18n'
+I18n.load_path << File.dirname(__FILE__) + '/active_model/locale/en.yml'

data/lib/active_model/attribute_methods.rb

@@ -0,0 +1,391 @@
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/class/inheritable_attributes'
+
+module ActiveModel
+  class MissingAttributeError < NoMethodError
+  end
+
+  # <tt>ActiveModel::AttributeMethods</tt> provides a way to add prefixes and suffixes
+  # to your methods as well as handling the creation of Active Record like class methods
+  # such as +table_name+.
+  # 
+  # The requirements to implement ActiveModel::AttributeMethods are:
+  #
+  # * <tt>include ActiveModel::AttributeMethods</tt> in your object
+  # * Call each Attribute Method module method you want to add, such as 
+  #   attribute_method_suffix or attribute_method_prefix
+  # * Call <tt>define_attribute_methods</tt> after the other methods are
+  #   called.
+  # * Define the various generic +_attribute+ methods that you have declared
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #   
+  #     include ActiveModel::AttributeMethods
+  #     
+  #     attribute_method_affix  :prefix => 'reset_', :suffix => '_to_default!'
+  #     attribute_method_suffix '_contrived?'
+  #     attribute_method_prefix 'clear_'
+  #     define_attribute_methods ['name']
+  #     
+  #     attr_accessor :name
+  #     
+  #     private
+  #     
+  #     def attribute_contrived?(attr)
+  #       true
+  #     end
+  #     
+  #     def clear_attribute(attr)
+  #       send("#{attr}=", nil)
+  #     end
+  #     
+  #     def reset_attribute_to_default!(attr)
+  #       send("#{attr}=", "Default Name")
+  #     end
+  #   
+  #   end
+  # 
+  module AttributeMethods
+    extend ActiveSupport::Concern
+
+    # Declare and check for suffixed attribute methods.
+    module ClassMethods
+      # Defines an "attribute" method (like +inheritance_column+ or
+      # +table_name+). A new (class) method will be created with the
+      # given name. If a value is specified, the new method will
+      # return that value (as a string). Otherwise, the given block
+      # will be used to compute the value of the method.
+      #
+      # The original method will be aliased, with the new name being
+      # prefixed with "original_". This allows the new method to
+      # access the original value.
+      #
+      # Example:
+      #
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      # 
+      #     cattr_accessor :primary_key
+      #     cattr_accessor :inheritance_column
+      #     
+      #     define_attr_method :primary_key, "sysid"
+      #     define_attr_method( :inheritance_column ) do
+      #       original_inheritance_column + "_id"
+      #     end
+      # 
+      #   end
+      # 
+      # Provivdes you with:
+      # 
+      #   AttributePerson.primary_key
+      #   # => "sysid"
+      #   AttributePerson.inheritance_column = 'address'
+      #   AttributePerson.inheritance_column
+      #   # => 'address_id'
+      def define_attr_method(name, value=nil, &block)
+        sing = metaclass
+        sing.send :alias_method, "original_#{name}", name
+        if block_given?
+          sing.send :define_method, name, &block
+        else
+          # use eval instead of a block to work around a memory leak in dev
+          # mode in fcgi
+          sing.class_eval "def #{name}; #{value.to_s.inspect}; end"
+        end
+      end
+
+      # Declares a method available for all attributes with the given prefix.
+      # Uses +method_missing+ and <tt>respond_to?</tt> to rewrite the method.
+      #
+      #   #{prefix}#{attr}(*args, &block)
+      #
+      # to
+      #
+      #   #{prefix}attribute(#{attr}, *args, &block)
+      #
+      # An <tt>#{prefix}attribute</tt> instance method must exist and accept at least
+      # the +attr+ argument.
+      #
+      # For example:
+      #
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
+      #     attribute_method_prefix 'clear_'
+      #     define_attribute_methods [:name]
+      #
+      #     private
+      # 
+      #     def clear_attribute(attr)
+      #       send("#{attr}=", nil)
+      #     end
+      #   end
+      #
+      #   person = Person.new
+      #   person.name = "Bob"
+      #   person.name          # => "Bob"
+      #   person.clear_name
+      #   person.name          # => nil
+      def attribute_method_prefix(*prefixes)
+        attribute_method_matchers.concat(prefixes.map { |prefix| AttributeMethodMatcher.new :prefix => prefix })
+        undefine_attribute_methods
+      end
+
+      # Declares a method available for all attributes with the given suffix.
+      # Uses +method_missing+ and <tt>respond_to?</tt> to rewrite the method.
+      #
+      #   #{attr}#{suffix}(*args, &block)
+      #
+      # to
+      #
+      #   attribute#{suffix}(#{attr}, *args, &block)
+      #
+      # An <tt>attribute#{suffix}</tt> instance method must exist and accept at least
+      # the +attr+ argument.
+      #
+      # For example:
+      #
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
+      #     attribute_method_suffix '_short?'
+      #     define_attribute_methods [:name]
+      #
+      #     private
+      # 
+      #     def attribute_short?(attr)
+      #       send(attr).length < 5
+      #     end
+      #   end
+      #
+      #   person = Person.new
+      #   person.name = "Bob"
+      #   person.name          # => "Bob"
+      #   person.name_short?   # => true
+      def attribute_method_suffix(*suffixes)
+        attribute_method_matchers.concat(suffixes.map { |suffix| AttributeMethodMatcher.new :suffix => suffix })
+        undefine_attribute_methods
+      end
+
+      # Declares a method available for all attributes with the given prefix
+      # and suffix. Uses +method_missing+ and <tt>respond_to?</tt> to rewrite
+      # the method.
+      #
+      #   #{prefix}#{attr}#{suffix}(*args, &block)
+      #
+      # to
+      #
+      #   #{prefix}attribute#{suffix}(#{attr}, *args, &block)
+      #
+      # An <tt>#{prefix}attribute#{suffix}</tt> instance method must exist and
+      # accept at least the +attr+ argument.
+      #
+      # For example:
+      #
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
+      #     attribute_method_affix :prefix => 'reset_', :suffix => '_to_default!'
+      #     define_attribute_methods [:name]
+      #
+      #     private
+      # 
+      #     def reset_attribute_to_default!(attr)
+      #       ...
+      #     end
+      #   end
+      #
+      #   person = Person.new
+      #   person.name                         # => 'Gem'
+      #   person.reset_name_to_default!
+      #   person.name                         # => 'Gemma'
+      def attribute_method_affix(*affixes)
+        attribute_method_matchers.concat(affixes.map { |affix| AttributeMethodMatcher.new :prefix => affix[:prefix], :suffix => affix[:suffix] })
+        undefine_attribute_methods
+      end
+
+      def alias_attribute(new_name, old_name)
+        attribute_method_matchers.each do |matcher|
+          module_eval <<-STR, __FILE__, __LINE__+1
+            def #{matcher.method_name(new_name)}(*args)
+              send(:#{matcher.method_name(old_name)}, *args)
+            end
+          STR
+        end
+      end
+
+      # Declares a the attributes that should be prefixed and suffixed by 
+      # ActiveModel::AttributeMethods.
+      # 
+      # To use, pass in an array of attribute names (as strings or symbols),
+      # be sure to declare +define_attribute_methods+ after you define any
+      # prefix, suffix or affix methods, or they will not hook in.
+      # 
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name, :age, :address
+      #     attribute_method_prefix 'clear_'
+      #
+      #     # Call to define_attribute_methods must appear after the
+      #     # attribute_method_prefix, attribute_method_suffix or
+      #     # attribute_method_affix declares.
+      #     define_attribute_methods [:name, :age, :address]
+      #
+      #     private
+      # 
+      #     def clear_attribute(attr)
+      #       ...
+      #     end
+      #   end
+      def define_attribute_methods(attr_names)
+        return if attribute_methods_generated?
+        attr_names.each do |attr_name|
+          attribute_method_matchers.each do |matcher|
+            unless instance_method_already_implemented?(matcher.method_name(attr_name))
+              generate_method = "define_method_#{matcher.prefix}attribute#{matcher.suffix}"
+
+              if respond_to?(generate_method)
+                send(generate_method, attr_name)
+              else
+                generated_attribute_methods.module_eval <<-STR, __FILE__, __LINE__+1
+                  def #{matcher.method_name(attr_name)}(*args)
+                    send(:#{matcher.method_missing_target}, '#{attr_name}', *args)
+                  end
+                STR
+              end
+            end
+          end
+        end
+        @attribute_methods_generated = true
+      end
+
+      # Removes all the preiously dynamically defined methods from the class
+      def undefine_attribute_methods
+        generated_attribute_methods.module_eval do
+          instance_methods.each { |m| undef_method(m) }
+        end
+        @attribute_methods_generated = nil
+      end
+
+      # Returns true if the attribute methods defined have been generated.
+      def generated_attribute_methods #:nodoc:
+        @generated_attribute_methods ||= begin
+          mod = Module.new
+          include mod
+          mod
+        end
+      end
+
+      def attribute_methods_generated?
+        @attribute_methods_generated ||= nil
+      end
+
+      protected
+        def instance_method_already_implemented?(method_name)
+          method_defined?(method_name)
+        end
+
+      private
+        class AttributeMethodMatcher
+          attr_reader :prefix, :suffix
+
+          AttributeMethodMatch = Struct.new(:target, :attr_name)
+
+          def initialize(options = {})
+            options.symbolize_keys!
+            @prefix, @suffix = options[:prefix] || '', options[:suffix] || ''
+            @regex = /^(#{Regexp.escape(@prefix)})(.+?)(#{Regexp.escape(@suffix)})$/
+          end
+
+          def match(method_name)
+            if matchdata = @regex.match(method_name)
+              AttributeMethodMatch.new(method_missing_target, matchdata[2])
+            else
+              nil
+            end
+          end
+
+          def method_name(attr_name)
+            "#{prefix}#{attr_name}#{suffix}"
+          end
+
+          def method_missing_target
+            :"#{prefix}attribute#{suffix}"
+          end
+        end
+
+        def attribute_method_matchers #:nodoc:
+          read_inheritable_attribute(:attribute_method_matchers) || write_inheritable_attribute(:attribute_method_matchers, [])
+        end
+    end
+
+    # Allows access to the object attributes, which are held in the <tt>@attributes</tt> hash, as though they
+    # were first-class methods. So a Person class with a name attribute can use Person#name and
+    # Person#name= and never directly use the attributes hash -- except for multiple assigns with
+    # ActiveRecord#attributes=. A Milestone class can also ask Milestone#completed? to test that
+    # the completed attribute is not +nil+ or 0.
+    #
+    # It's also possible to instantiate related objects, so a Client class belonging to the clients
+    # table with a +master_id+ foreign key can instantiate master through Client#master.
+    def method_missing(method_id, *args, &block)
+      method_name = method_id.to_s
+      if match = match_attribute_method?(method_name)
+        guard_private_attribute_method!(method_name, args)
+        return __send__(match.target, match.attr_name, *args, &block)
+      end
+      super
+    end
+
+    # A Person object with a name attribute can ask <tt>person.respond_to?(:name)</tt>,
+    # <tt>person.respond_to?(:name=)</tt>, and <tt>person.respond_to?(:name?)</tt>
+    # which will all return +true+.
+    alias :respond_to_without_attributes? :respond_to?
+    def respond_to?(method, include_private_methods = false)
+      if super
+        return true
+      elsif !include_private_methods && super(method, true)
+        # If we're here then we haven't found among non-private methods
+        # but found among all methods. Which means that given method is private.
+        return false
+      elsif match_attribute_method?(method.to_s)
+        return true
+      end
+      super
+    end
+
+    protected
+      def attribute_method?(attr_name)
+        attributes.include?(attr_name)
+      end
+
+    private
+      # Returns a struct representing the matching attribute method.
+      # The struct's attributes are prefix, base and suffix.
+      def match_attribute_method?(method_name)
+        self.class.send(:attribute_method_matchers).each do |method|
+          if (match = method.match(method_name)) && attribute_method?(match.attr_name)
+            return match
+          end
+        end
+        nil
+      end
+
+      # prevent method_missing from calling private methods with #send
+      def guard_private_attribute_method!(method_name, args)
+        if self.class.private_method_defined?(method_name)
+          raise NoMethodError.new("Attempt to call private method", method_name, args)
+        end
+      end
+
+      def missing_attribute(attr_name, stack)
+        raise ActiveModel::MissingAttributeError, "missing attribute: #{attr_name}", stack
+      end
+  end
+end