activemodel 3.0.pre → 3.0.0.rc

data/lib/active_model/observing.rb

@@ -1,18 +1,16 @@
-require 'observer'
 require 'singleton'
 require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/module/aliasing'
+require 'active_support/core_ext/module/remove_method'
 require 'active_support/core_ext/string/inflections'
 
 module ActiveModel
   module Observing
     extend ActiveSupport::Concern
 
-    included do
-      extend Observable
-    end
-
     module ClassMethods
+      # == Active Model Observers Activation
+      # 
       # Activates the observers assigned. Examples:
       #
       #   # Calls PersonObserver.instance
@@ -24,8 +22,9 @@ module ActiveModel
       #   # Same as above, just using explicit class references
       #   ActiveRecord::Base.observers = Cacher, GarbageCollector
       #
-      # Note: Setting this does not instantiate the observers yet. +instantiate_observers+ is
-      # called during startup, and before each development request.
+      # Note: Setting this does not instantiate the observers yet. 
+      # +instantiate_observers+ is called during startup, and before
+      # each development request.
       def observers=(*values)
         @observers = values.flatten
       end
@@ -40,6 +39,26 @@ module ActiveModel
         observers.each { |o| instantiate_observer(o) }
       end
 
+      def add_observer(observer)
+        unless observer.respond_to? :update
+          raise ArgumentError, "observer needs to respond to `update'"
+        end
+        @observer_instances ||= []
+        @observer_instances << observer
+      end
+
+      def notify_observers(*arg)
+        if defined? @observer_instances
+          for observer in @observer_instances
+            observer.update(*arg)
+          end
+        end
+      end
+
+      def count_observers
+        @observer_instances.size
+      end
+
       protected
         def instantiate_observer(observer) #:nodoc:
           # string/symbol
@@ -55,7 +74,6 @@ module ActiveModel
         # Notify observers when the observed class is subclassed.
         def inherited(subclass)
           super
-          changed
           notify_observers :observed_class_inherited, subclass
         end
     end
@@ -69,11 +87,12 @@ module ActiveModel
       #   notify_observers(:after_save)
       # end
       def notify_observers(method)
-        self.class.changed
         self.class.notify_observers(method, self)
       end
   end
 
+  # == Active Model Observers
+  #
   # Observer classes respond to lifecycle callbacks to implement trigger-like
   # behavior outside the original class. This is a great way to reduce the
   # clutter that normally comes when the model class is burdened with
@@ -102,10 +121,12 @@ module ActiveModel
   #
   # == Observing a class that can't be inferred
   #
-  # Observers will by default be mapped to the class with which they share a name. So CommentObserver will
-  # be tied to observing Comment, ProductManagerObserver to ProductManager, and so on. If you want to name your observer
-  # differently than the class you're interested in observing, you can use the Observer.observe class method which takes
-  # either the concrete class (Product) or a symbol for that class (:product):
+  # Observers will by default be mapped to the class with which they share a
+  # name. So CommentObserver will be tied to observing Comment, ProductManagerObserver
+  # to ProductManager, and so on. If you want to name your observer differently than 
+  # the class you're interested in observing, you can use the Observer.observe class 
+  # method which takes either the concrete class (Product) or a symbol for that 
+  # class (:product):
   #
   #   class AuditObserver < ActiveModel::Observer
   #     observe :account
@@ -115,7 +136,8 @@ module ActiveModel
   #     end
   #   end
   #
-  # If the audit observer needs to watch more than one kind of object, this can be specified with multiple arguments:
+  # If the audit observer needs to watch more than one kind of object, this can be 
+  # specified with multiple arguments:
   #
   #   class AuditObserver < ActiveModel::Observer
   #     observe :account, :balance
@@ -125,7 +147,8 @@ module ActiveModel
   #     end
   #   end
   #
-  # The AuditObserver will now act on both updates to Account and Balance by treating them both as records.
+  # The AuditObserver will now act on both updates to Account and Balance by treating 
+  # them both as records.
   #
   class Observer
     include Singleton
@@ -135,6 +158,7 @@ module ActiveModel
       def observe(*models)
         models.flatten!
         models.collect! { |model| model.respond_to?(:to_sym) ? model.to_s.camelize.constantize : model }
+        remove_possible_method(:observed_classes)
         define_method(:observed_classes) { models }
       end
 
@@ -144,7 +168,7 @@ module ActiveModel
       #
       #   class AuditObserver < ActiveModel::Observer
       #     def self.observed_classes
-      #       [AccountObserver, BalanceObserver]
+      #       [Account, Balance]
       #     end
       #   end
       def observed_classes

data/lib/active_model/railtie.rb

@@ -0,0 +1,2 @@
+require "active_model"
+require "rails"

data/lib/active_model/serialization.rb

@@ -2,6 +2,65 @@ require 'active_support/core_ext/hash/except'
 require 'active_support/core_ext/hash/slice'
 
 module ActiveModel
+  # == Active Model Serialization
+  # 
+  # Provides a basic serialization to a serializable_hash for your object.
+  # 
+  # A minimal implementation could be:
+  #   
+  #   class Person
+  #   
+  #     include ActiveModel::Serialization
+  #   
+  #     attr_accessor :name
+  #   
+  #     def attributes
+  #       @attributes ||= {'name' => 'nil'}
+  #     end
+  #   
+  #   end
+  # 
+  # Which would provide you with:
+  # 
+  #   person = Person.new
+  #   person.serializable_hash   # => {"name"=>nil}
+  #   person.name = "Bob"
+  #   person.serializable_hash   # => {"name"=>"Bob"}
+  #
+  # You need to declare some sort of attributes hash which contains the attributes
+  # you want to serialize and their current value.
+  # 
+  # Most of the time though, you will want to include the JSON or XML 
+  # serializations.  Both of these modules automatically include the 
+  # ActiveModel::Serialization module, so there is no need to explicitly
+  # include it.
+  # 
+  # So a minimal implementation including XML and JSON would be:
+  #   
+  #   class Person
+  #   
+  #     include ActiveModel::Serializers::JSON
+  #     include ActiveModel::Serializers::Xml
+  #   
+  #     attr_accessor :name
+  #   
+  #     def attributes
+  #       @attributes ||= {'name' => 'nil'}
+  #     end
+  #   
+  #   end
+  # 
+  # Which would provide you with:
+  # 
+  #   person = Person.new
+  #   person.serializable_hash   # => {"name"=>nil}
+  #   person.to_json             # => "{\"name\":null}"
+  #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+  # 
+  #   person.name = "Bob"
+  #   person.serializable_hash   # => {"name"=>"Bob"}
+  #   person.to_json             # => "{\"name\":\"Bob\"}"
+  #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
   module Serialization
     def serializable_hash(options = nil)
       options ||= {}

data/lib/active_model/serializers/json.rb

@@ -1,7 +1,8 @@
 require 'active_support/json'
-require 'active_support/core_ext/class/attribute_accessors'
+require 'active_support/core_ext/class/attribute'
 
 module ActiveModel
+  # == Active Model JSON Serializer
   module Serializers
     module JSON
       extend ActiveSupport::Concern
@@ -10,19 +11,18 @@ module ActiveModel
       included do
         extend ActiveModel::Naming
 
-        cattr_accessor :include_root_in_json, :instance_writer => false
+        class_attribute :include_root_in_json
+        self.include_root_in_json = true
       end
 
-      # Returns a JSON string representing the model. Some configuration is
-      # available through +options+.
+      # Returns a JSON string representing the model. Some configuration can be
+      # passed through +options+.
       #
-      # The option <tt>ActiveRecord::Base.include_root_in_json</tt> controls the
-      # top-level behavior of to_json. In a new Rails application, it is set to 
-      # <tt>true</tt> in initializers/new_rails_defaults.rb. When it is <tt>true</tt>,
-      # to_json will emit a single root node named after the object's type. For example:
+      # The option <tt>ActiveModel::Base.include_root_in_json</tt> controls the
+      # top-level behavior of <tt>to_json</tt>. It is <tt>true</tt> by default. When it is <tt>true</tt>,
+      # <tt>to_json</tt> will emit a single root node named after the object's type. For example:
       #
       #   konata = User.find(1)
-      #   ActiveRecord::Base.include_root_in_json = true
       #   konata.to_json
       #   # => { "user": {"id": 1, "name": "Konata Izumi", "age": 16,
       #                   "created_at": "2006/08/01", "awesome": true} }
@@ -81,7 +81,11 @@ module ActiveModel
       #                    "title": "So I was thinking"}]}
       def encode_json(encoder)
         hash = serializable_hash(encoder.options)
-        hash = { self.class.model_name.element => hash } if include_root_in_json
+        if include_root_in_json
+          custom_root = encoder.options && encoder.options[:root]
+          hash = { custom_root || self.class.model_name.element => hash }
+        end
+
         ActiveSupport::JSON.encode(hash)
       end
 
@@ -90,7 +94,9 @@ module ActiveModel
       end
 
       def from_json(json)
-        self.attributes = ActiveSupport::JSON.decode(json)
+        hash = ActiveSupport::JSON.decode(json)
+        hash = hash.values.first if include_root_in_json
+        self.attributes = hash
         self
       end
     end

data/lib/active_model/serializers/xml.rb

@@ -1,7 +1,11 @@
+require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/class/attribute_accessors'
+require 'active_support/core_ext/array/conversions'
 require 'active_support/core_ext/hash/conversions'
+require 'active_support/core_ext/hash/slice'
 
 module ActiveModel
+  # == Active Model XML Serializer
   module Serializers
     module Xml
       extend ActiveSupport::Concern
@@ -11,68 +15,31 @@ module ActiveModel
         class Attribute #:nodoc:
           attr_reader :name, :value, :type
 
-          def initialize(name, serializable)
+          def initialize(name, serializable, raw_value=nil)
             @name, @serializable = name, serializable
+            @value = value || @serializable.send(name)
             @type  = compute_type
-            @value = compute_value
           end
 
-          # There is a significant speed improvement if the value
-          # does not need to be escaped, as <tt>tag!</tt> escapes all values
-          # to ensure that valid XML is generated. For known binary
-          # values, it is at least an order of magnitude faster to
-          # Base64 encode binary values and directly put them in the
-          # output XML than to pass the original value or the Base64
-          # encoded value to the <tt>tag!</tt> method. It definitely makes
-          # no sense to Base64 encode the value and then give it to
-          # <tt>tag!</tt>, since that just adds additional overhead.
-          def needs_encoding?
-            ![ :binary, :date, :datetime, :boolean, :float, :integer ].include?(type)
-          end
-
-          def decorations(include_types = true)
+          def decorations
             decorations = {}
-
-            if type == :binary
-              decorations[:encoding] = 'base64'
-            end
-
-            if include_types && type != :string
-              decorations[:type] = type
-            end
-
-            if value.nil?
-              decorations[:nil] = true
-            end
-
+            decorations[:encoding] = 'base64' if type == :binary
+            decorations[:type] = type unless type == :string
+            decorations[:nil] = true if value.nil?
             decorations
           end
 
-          protected
-            def compute_type
-              value = @serializable.send(name)
-              type = Hash::XML_TYPE_NAMES[value.class.name]
-              type ||= :string if value.respond_to?(:to_str)
-              type ||= :yaml
-              type
-            end
-
-            def compute_value
-              value = @serializable.send(name)
+        protected
 
-              if formatter = Hash::XML_FORMATTING[type.to_s]
-                value ? formatter.call(value) : nil
-              else
-                value
-              end
-            end
+          def compute_type
+            type = ActiveSupport::XmlMini::TYPE_NAMES[value.class.name]
+            type ||= :string if value.respond_to?(:to_str)
+            type ||= :yaml
+            type
+          end
         end
 
         class MethodAttribute < Attribute #:nodoc:
-          protected
-            def compute_type
-              Hash::XML_TYPE_NAMES[@serializable.send(name).class.name] || :string
-            end
         end
 
         attr_reader :options
@@ -85,112 +52,88 @@ module ActiveModel
           @options[:except] = Array.wrap(@options[:except]).map { |n| n.to_s }
         end
 
-        # To replicate the behavior in ActiveRecord#attributes,
-        # <tt>:except</tt> takes precedence over <tt>:only</tt>.  If <tt>:only</tt> is not set
+        # To replicate the behavior in ActiveRecord#attributes, <tt>:except</tt> 
+        # takes precedence over <tt>:only</tt>.  If <tt>:only</tt> is not set
         # for a N level model but is set for the N+1 level models,
         # then because <tt>:except</tt> is set to a default value, the second
         # level model can have both <tt>:except</tt> and <tt>:only</tt> set.  So if
         # <tt>:only</tt> is set, always delete <tt>:except</tt>.
-        def serializable_attribute_names
-          attribute_names = @serializable.attributes.keys.sort
-
+        def attributes_hash
+          attributes = @serializable.attributes
           if options[:only].any?
-            attribute_names &= options[:only]
+            attributes.slice(*options[:only])
           elsif options[:except].any?
-            attribute_names -= options[:except]
+            attributes.except(*options[:except])
+          else
+            attributes
           end
-
-          attribute_names
         end
 
         def serializable_attributes
-          serializable_attribute_names.collect { |name| Attribute.new(name, @serializable) }
+          attributes_hash.map do |name, value|
+            self.class::Attribute.new(name, @serializable, value)
+          end
         end
 
-        def serializable_method_attributes
-          Array(options[:methods]).inject([]) do |methods, name|
-            methods << MethodAttribute.new(name.to_s, @serializable) if @serializable.respond_to?(name.to_s)
+        def serializable_methods
+          Array.wrap(options[:methods]).inject([]) do |methods, name|
+            methods << self.class::MethodAttribute.new(name.to_s, @serializable) if @serializable.respond_to?(name.to_s)
             methods
           end
         end
 
         def serialize
-          args = [root]
-
-          if options[:namespace]
-            args << {:xmlns => options[:namespace]}
-          end
+          require 'builder' unless defined? ::Builder
 
-          if options[:type]
-            args << {:type => options[:type]}
-          end
+          options[:indent]  ||= 2
+          options[:builder] ||= ::Builder::XmlMarkup.new(:indent => options[:indent])
 
-          builder.tag!(*args) do
-            add_attributes
-            procs = options.delete(:procs)
-            options[:procs] = procs
-            add_procs
-            yield builder if block_given?
-          end
-        end
+          @builder = options[:builder]
+          @builder.instruct! unless options[:skip_instruct]
 
-        private
-          def builder
-            @builder ||= begin
-              require 'builder' unless defined? ::Builder
-              options[:indent] ||= 2
-              builder = options[:builder] ||= ::Builder::XmlMarkup.new(:indent => options[:indent])
+          root = (options[:root] || @serializable.class.model_name.element).to_s
+          root = ActiveSupport::XmlMini.rename_key(root, options)
 
-              unless options[:skip_instruct]
-                builder.instruct!
-                options[:skip_instruct] = true
-              end
-
-              builder
-            end
-          end
-
-          def root
-            root = (options[:root] || @serializable.class.model_name.singular).to_s
-            reformat_name(root)
-          end
+          args = [root]
+          args << {:xmlns => options[:namespace]} if options[:namespace]
+          args << {:type => options[:type]} if options[:type] && !options[:skip_types]
 
-          def dasherize?
-            !options.has_key?(:dasherize) || options[:dasherize]
+          @builder.tag!(*args) do
+            add_attributes_and_methods
+            add_extra_behavior
+            add_procs
+            yield @builder if block_given?
           end
+        end
 
-          def camelize?
-            options.has_key?(:camelize) && options[:camelize]
-          end
+      private
 
-          def reformat_name(name)
-            name = name.camelize if camelize?
-            dasherize? ? name.dasherize : name
-          end
+        def add_extra_behavior
+        end
 
-          def add_attributes
-            (serializable_attributes + serializable_method_attributes).each do |attribute|
-              builder.tag!(
-                reformat_name(attribute.name),
-                attribute.value.to_s,
-                attribute.decorations(!options[:skip_types])
-              )
-            end
+        def add_attributes_and_methods
+          (serializable_attributes + serializable_methods).each do |attribute|
+            key = ActiveSupport::XmlMini.rename_key(attribute.name, options)
+            ActiveSupport::XmlMini.to_tag(key, attribute.value,
+              options.merge(attribute.decorations))
           end
+        end
 
-          def add_procs
-            if procs = options.delete(:procs)
-              [ *procs ].each do |proc|
-                if proc.arity > 1
-                  proc.call(options, @serializable)
-                else
-                  proc.call(options)
-                end
+        def add_procs
+          if procs = options.delete(:procs)
+            Array.wrap(procs).each do |proc|
+              if proc.arity == 1
+                proc.call(options)
+              else
+                proc.call(options, @serializable)
               end
             end
           end
+        end
       end
 
+      # Returns XML representing the model. Configuration can be
+      # passed through +options+.
       def to_xml(options = {}, &block)
         Serializer.new(self, options).serialize(&block)
       end