georgepalmer-couch_foo 0.7.4 → 0.7.7

data/README.rdoc

@@ -18,7 +18,7 @@ are a few minor differences to the way CouchDB works.  In particular:
 * The price of index updating is paid when next accessing the index rather than the point of insertion.  This can be more efficient or less depending on your application.  It may make sense to use an external process to do the updating for you - see CouchFoo#find for more on this
 * On that note, occasional compacting of CouchDB is required to recover space from old versions of documents.  This can be kicked off in several ways (see quick start guide)
 
-It is recommend that you read the quick start and performance sections in the rdoc for a full overview of differences and points to be aware of when developing.
+It is recommend that you read the quick start and performance sections in the rdoc for a full overview of differences and points to be aware of when developing.  The Changelog file shows the differences between gem versions and should be checked when upgrading gem versions.
 
 
 == Getting started

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 7
-:patch: 4
+:patch: 7

data/lib/couch_foo.rb

@@ -20,7 +20,8 @@ require 'couch_foo/associations'
 #require 'active_record/association_preload'
 #require 'active_record/aggregations'
 require 'couch_foo/timestamp'
-require 'active_record/calculations'
+require 'couch_foo/calculations'
+require 'couch_foo/serialization'
 require 'couch_foo/attribute_methods'
 require 'couch_foo/dirty'
 
@@ -40,4 +41,5 @@ CouchFoo::Base.class_eval do
 #  include ActiveRecord::Aggregations
   include CouchFoo::Reflection
   include CouchFoo::Calculations
+  include CouchFoo::Serialization
 end

data/lib/couch_foo/attribute_methods.rb

@@ -11,6 +11,7 @@ module CouchFoo
     end
     
     module ClassMethods
+
       # Declares a method available for all attributes with the given suffix.
       # Uses +method_missing+ and <tt>respond_to?</tt> to rewrite the method
       #

data/lib/couch_foo/base.rb

@@ -32,6 +32,12 @@ module CouchFoo
   class DocumentConflict < CouchFooError
   end
   
+  # The types that are permitted for properties.  At the moment this is just used
+  # to determine whether a .to_xml call should be made on the type during
+  # serialization but I imagine it will be used to enforce type checking as well
+  # at a later date
+  AVAILABLE_TYPES = [String, Integer, Float, DateTime, Time, Date, TrueClass, Boolean]
+
   # Simple class encapsulating a property
   class Property
     attr_accessor :name, :type, :default
@@ -1027,7 +1033,7 @@ module CouchFoo
         define_attr_method :inheritance_column, value, &block
       end
       alias :inheritance_column= :set_inheritance_column
-      
+
       # Set a property for the document.  These can be passed a type and options hash.  If no type
       # is passed a #to_json method is called on the ruby object and the result stored in the 
       # database.  When it is retrieved from the database a class.from_json(json) method is called

data/lib/couch_foo/serialization.rb

@@ -0,0 +1,98 @@
+module CouchFoo #:nodoc:
+  module Serialization
+    class Serializer #:nodoc:
+      attr_reader :options
+
+      def initialize(record, options = {})
+        @record, @options = record, options.dup
+      end
+
+      # To replicate the behavior in CouchFoo#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 = @record.attribute_names
+
+        if options[:only]
+          options.delete(:except)
+          attribute_names = attribute_names & Array(options[:only]).collect { |n| n.to_s }
+        else
+          options[:except] = Array(options[:except]) | Array(@record.class.inheritance_column)
+          attribute_names = attribute_names - options[:except].collect { |n| n.to_s }
+        end
+
+        attribute_names
+      end
+
+      def serializable_method_names
+        Array(options[:methods]).inject([]) do |method_attributes, name|
+          method_attributes << name if @record.respond_to?(name.to_s)
+          method_attributes
+        end
+      end
+
+      def serializable_names
+        serializable_attribute_names + serializable_method_names
+      end
+
+      # Add associations specified via the <tt>:includes</tt> option.
+      # Expects a block that takes as arguments:
+      #   +association+ - name of the association
+      #   +records+     - the association record(s) to be serialized
+      #   +opts+        - options for the association records
+      def add_includes(&block)
+        if include_associations = options.delete(:include)
+          base_only_or_except = { :except => options[:except],
+                                  :only => options[:only] }
+
+          include_has_options = include_associations.is_a?(Hash)
+          associations = include_has_options ? include_associations.keys : Array(include_associations)
+
+          for association in associations
+            records = case @record.class.reflect_on_association(association).macro
+            when :has_many, :has_and_belongs_to_many
+              @record.send(association).to_a
+            when :has_one, :belongs_to
+              @record.send(association)
+            end
+
+            unless records.nil?
+              association_options = include_has_options ? include_associations[association] : base_only_or_except
+              opts = options.merge(association_options)
+              yield(association, records, opts)
+            end
+          end
+
+          options[:include] = include_associations
+        end
+      end
+
+      def serializable_record
+        returning(serializable_record = {}) do
+          serializable_names.each { |name| serializable_record[name] = @record.send(:read_attribute_before_type_cast, name) }
+          add_includes do |association, records, opts|
+            if records.is_a?(Enumerable)
+              serializable_record[association] = records.collect { |r| self.class.new(r, opts).serializable_record }
+            else
+              serializable_record[association] = self.class.new(records, opts).serializable_record
+            end
+          end
+        end
+      end
+
+      def serialize
+        # overwrite to implement
+      end
+
+      def to_s(&block)
+        serialize(&block)
+      end
+    end
+  end
+end
+
+require 'couch_foo/serializers/xml_serializer'
+require 'couch_foo/serializers/json_serializer'

data/lib/couch_foo/serializers/json_serializer.rb

@@ -0,0 +1,81 @@
+module CouchFoo #:nodoc:
+  module Serialization
+    def self.included(base)
+      base.cattr_accessor :include_root_in_json, :instance_writer => false
+      base.extend ClassMethods
+    end
+
+    # Returns a JSON string representing the model. Some configuration is
+    # available through +options+.
+    #
+    # Without any +options+, the returned JSON string will include all
+    # the model's attributes. For example:
+    #
+    #   konata = User.find(1)
+    #   konata.to_json
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true}
+    #
+    # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
+    # included, and work similar to the +attributes+ method. For example:
+    #
+    #   konata.to_json(:only => [ :id, :name ])
+    #   # => {"id": 1, "name": "Konata Izumi"}
+    #
+    #   konata.to_json(:except => [ :id, :created_at, :age ])
+    #   # => {"name": "Konata Izumi", "awesome": true}
+    #
+    # To include any methods on the model, use <tt>:methods</tt>.
+    #
+    #   konata.to_json(:methods => :permalink)
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "permalink": "1-konata-izumi"}
+    #
+    # To include associations, use <tt>:include</tt>.
+    #
+    #   konata.to_json(:include => :posts)
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
+    #                   {"id": 2, author_id: 1, "title": "So I was thinking"}]}
+    #
+    # 2nd level and higher order associations work as well:
+    #
+    #   konata.to_json(:include => { :posts => {
+    #                                  :include => { :comments => {
+    #                                                :only => :body } },
+    #                                  :only => :title } })
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
+    #                    "title": "Welcome to the weblog"},
+    #                   {"comments": [{"body": "Don't think too hard"}],
+    #                    "title": "So I was thinking"}]}
+    def to_json(options = {})
+      if include_root_in_json
+        "{#{self.class.json_class_name}: #{JsonSerializer.new(self, options).to_s}}"
+      else
+        JsonSerializer.new(self, options).to_s
+      end
+    end
+
+    def from_json(json)
+      self.attributes = ActiveSupport::JSON.decode(json)
+      self
+    end
+
+    class JsonSerializer < CouchFoo::Serialization::Serializer #:nodoc:
+      def serialize
+        puts serializable_record.inspect
+        serializable_record.to_json
+      end
+    end
+
+    module ClassMethods
+      def json_class_name
+        @json_class_name ||= name.demodulize.underscore.inspect
+      end
+    end
+  end
+end

data/lib/couch_foo/serializers/xml_serializer.rb

@@ -0,0 +1,347 @@
+module CouchFoo #:nodoc:
+  module Serialization
+    # Builds an XML document to represent the model. Some configuration is
+    # available through +options+. However more complicated cases should
+    # override CouchFoo::Base#to_xml.  This is a necessary step if you wish
+    # to use custom types
+    #
+    # By default the generated XML document will include the processing
+    # instruction and all the object's attributes. For example:
+    #
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <topic>
+    #     <title>The First Topic</title>
+    #     <author-name>David</author-name>
+    #     <id type="integer">1</id>
+    #     <approved type="boolean">false</approved>
+    #     <replies-count type="integer">0</replies-count>
+    #     <bonus-time type="datetime">2000-01-01T08:28:00+12:00</bonus-time>
+    #     <written-on type="datetime">2003-07-16T09:28:00+1200</written-on>
+    #     <content>Have a nice day</content>
+    #     <author-email-address>david@loudthinking.com</author-email-address>
+    #     <parent-id></parent-id>
+    #     <last-read type="date">2004-04-15</last-read>
+    #   </topic>
+    #
+    # This behavior can be controlled with <tt>:only</tt>, <tt>:except</tt>,
+    # <tt>:skip_instruct</tt>, <tt>:skip_types</tt> and <tt>:dasherize</tt>.
+    # The <tt>:only</tt> and <tt>:except</tt> options are the same as for the
+    # +attributes+ method. The default is to dasherize all column names, but you
+    # can disable this setting <tt>:dasherize</tt> to +false+. To not have the
+    # column type included in the XML output set <tt>:skip_types</tt> to +true+.
+    #
+    # For instance:
+    #
+    #   topic.to_xml(:skip_instruct => true, :except => [ :id, :bonus_time, :written_on, :replies_count ])
+    #
+    #   <topic>
+    #     <title>The First Topic</title>
+    #     <author-name>David</author-name>
+    #     <approved type="boolean">false</approved>
+    #     <content>Have a nice day</content>
+    #     <author-email-address>david@loudthinking.com</author-email-address>
+    #     <parent-id></parent-id>
+    #     <last-read type="date">2004-04-15</last-read>
+    #   </topic>
+    #
+    # To include first level associations use <tt>:include</tt>:
+    #
+    #   firm.to_xml :include => [ :account, :clients ]
+    #
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <firm>
+    #     <id type="integer">1</id>
+    #     <rating type="integer">1</rating>
+    #     <name>37signals</name>
+    #     <clients type="array">
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Summit</name>
+    #       </client>
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Microsoft</name>
+    #       </client>
+    #     </clients>
+    #     <account>
+    #       <id type="integer">1</id>
+    #       <credit-limit type="integer">50</credit-limit>
+    #     </account>
+    #   </firm>
+    #
+    # To include deeper levels of associations pass a hash like this:
+    #
+    #   firm.to_xml :include => {:account => {}, :clients => {:include => :address}}
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <firm>
+    #     <id type="integer">1</id>
+    #     <rating type="integer">1</rating>
+    #     <name>37signals</name>
+    #     <clients type="array">
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Summit</name>
+    #         <address>
+    #           ...
+    #         </address>
+    #       </client>
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Microsoft</name>
+    #         <address>
+    #           ...
+    #         </address>
+    #       </client>
+    #     </clients>
+    #     <account>
+    #       <id type="integer">1</id>
+    #       <credit-limit type="integer">50</credit-limit>
+    #     </account>
+    #   </firm>
+    #
+    # To include any methods on the model being called use <tt>:methods</tt>:
+    #
+    #   firm.to_xml :methods => [ :calculated_earnings, :real_earnings ]
+    #
+    #   <firm>
+    #     # ... normal attributes as shown above ...
+    #     <calculated-earnings>100000000000000000</calculated-earnings>
+    #     <real-earnings>5</real-earnings>
+    #   </firm>
+    #
+    # To call any additional Procs use <tt>:procs</tt>. The Procs are passed a
+    # modified version of the options hash that was given to +to_xml+:
+    #
+    #   proc = Proc.new { |options| options[:builder].tag!('abc', 'def') }
+    #   firm.to_xml :procs => [ proc ]
+    #
+    #   <firm>
+    #     # ... normal attributes as shown above ...
+    #     <abc>def</abc>
+    #   </firm>
+    #
+    # Alternatively, you can yield the builder object as part of the +to_xml+ call:
+    #
+    #   firm.to_xml do |xml|
+    #     xml.creator do
+    #       xml.first_name "David"
+    #       xml.last_name "Heinemeier Hansson"
+    #     end
+    #   end
+    #
+    #   <firm>
+    #     # ... normal attributes as shown above ...
+    #     <creator>
+    #       <first_name>David</first_name>
+    #       <last_name>Heinemeier Hansson</last_name>
+    #     </creator>
+    #   </firm>
+    #
+    # As noted above, you may override +to_xml+ in your CouchFoo::Base
+    # subclasses to have complete control about what's generated. The general
+    # form of doing this is:
+    #
+    #   class IHaveMyOwnXML < CouchFoo::Base
+    #     def to_xml(options = {})
+    #       options[:indent] ||= 2
+    #       xml = options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
+    #       xml.instruct! unless options[:skip_instruct]
+    #       xml.level_one do
+    #         xml.tag!(:second_level, 'content')
+    #       end
+    #     end
+    #   end
+    def to_xml(options = {}, &block)
+      serializer = XmlSerializer.new(self, options)
+      block_given? ? serializer.to_s(&block) : serializer.to_s
+    end
+
+    def from_xml(xml)
+      self.attributes = Hash.from_xml(xml).values.first
+      self
+    end
+  end
+
+  class XmlSerializer < CouchFoo::Serialization::Serializer #:nodoc:
+    def builder
+      @builder ||= begin
+        options[:indent] ||= 2
+        builder = options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
+
+        unless options[:skip_instruct]
+          builder.instruct!
+          options[:skip_instruct] = true
+        end
+
+        builder
+      end
+    end
+
+    def root
+      root = (options[:root] || @record.class.to_s.underscore).to_s
+      dasherize? ? root.dasherize : root
+    end
+
+    def dasherize?
+      !options.has_key?(:dasherize) || options[:dasherize]
+    end
+
+    def serializable_attributes
+      serializable_attribute_names.collect { |name| Attribute.new(name, @record) }
+    end
+
+    def serializable_method_attributes
+      Array(options[:methods]).inject([]) do |method_attributes, name|
+        method_attributes << MethodAttribute.new(name.to_s, @record) if @record.respond_to?(name.to_s)
+        method_attributes
+      end
+    end
+
+    def add_attributes
+      (serializable_attributes + serializable_method_attributes).each do |attribute|
+        add_tag(attribute)
+      end
+    end
+
+    def add_procs
+      if procs = options.delete(:procs)
+        [ *procs ].each do |proc|
+          proc.call(options)
+        end
+      end
+    end
+
+    def add_tag(attribute)
+      builder.tag!(
+        dasherize? ? attribute.name.dasherize : attribute.name,
+        attribute.value.to_s,
+        attribute.decorations(!options[:skip_types])
+      )
+    end
+
+    def add_associations(association, records, opts)
+      if records.is_a?(Enumerable)
+        tag = association.to_s
+        tag = tag.dasherize if dasherize?
+        if records.empty?
+          builder.tag!(tag, :type => :array)
+        else
+          builder.tag!(tag, :type => :array) do
+            association_name = association.to_s.singularize
+            records.each do |record|
+              record.to_xml opts.merge(
+                :root => association_name,
+                :type => (record.class.to_s.underscore == association_name ? nil : record.class.name)
+              )
+            end
+          end
+        end
+      else
+        if record = @record.send(association)
+          record.to_xml(opts.merge(:root => association))
+        end
+      end
+    end
+
+    def serialize
+      args = [root]
+      if options[:namespace]
+        args << {:xmlns=>options[:namespace]}
+      end
+
+      if options[:type]
+        args << {:type=>options[:type]}
+      end
+
+      builder.tag!(*args) do
+        add_attributes
+        procs = options.delete(:procs)
+        add_includes { |association, records, opts| add_associations(association, records, opts) }
+        options[:procs] = procs
+        add_procs
+        yield builder if block_given?
+      end
+    end
+
+    class Attribute #:nodoc:
+      attr_reader :name, :value, :type
+
+      def initialize(name, record)
+        @name, @record = name, record
+
+        @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)
+        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
+      end
+
+      protected
+        def compute_type
+          type = @record.class.property_types[name.to_sym]
+
+          # Hack until get these types into properties structure
+          if name.to_sym == :_id || name.to_sym == :_rev || name.to_sym == :ruby_class
+            type = String
+          end
+
+          case type
+            when Time
+              Datetime
+            when Boolean
+              TrueClass
+            else
+              type
+          end
+        end
+
+        def compute_value
+          value = @record.send(name)
+
+          # Custom types must implement .to_xml
+          if !CouchFoo::AVAILABLE_TYPES.include?(type)
+            value.to_xml unless value.nil?
+          elsif formatter = Hash::XML_FORMATTING[type.to_s]
+            value ? formatter.call(value) : nil
+          else
+            value
+          end
+        end
+    end
+
+    class MethodAttribute < Attribute #:nodoc:
+      protected
+        def compute_type
+          Hash::XML_TYPE_NAMES[@record.send(name).class.name] || :string
+        end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: georgepalmer-couch_foo
 version: !ruby/object:Gem::Version 
-  version: 0.7.4
+  version: 0.7.7
 platform: ruby
 authors: 
 - George Palmer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-06 00:00:00 -08:00
+date: 2009-02-09 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -64,6 +64,7 @@ files:
 - lib/couch_foo
 - lib/couch_foo/database.rb
 - lib/couch_foo/dirty.rb
+- lib/couch_foo/serialization.rb
 - lib/couch_foo/associations.rb
 - lib/couch_foo/associations
 - lib/couch_foo/associations/has_one_association.rb
@@ -75,6 +76,9 @@ files:
 - lib/couch_foo/associations/has_and_belongs_to_many_association.rb
 - lib/couch_foo/observer.rb
 - lib/couch_foo/base.rb
+- lib/couch_foo/serializers
+- lib/couch_foo/serializers/xml_serializer.rb
+- lib/couch_foo/serializers/json_serializer.rb
 - lib/couch_foo/calculations.rb
 - lib/couch_foo/view_methods.rb
 - lib/couch_foo/attribute_methods.rb