active_model_serializer_plus 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 361857f5e46f0a701cf41f9d43fa7d7f404bf928
-  data.tar.gz: a59df64844aa6b4d4b7421263c8c98cb0104f69e
+  metadata.gz: 24bdcf126d5a85b91e9f44683d88da3c00f28aff
+  data.tar.gz: dcf9f939596e70496714ab6665e2f6b67591a41b
 SHA512:
-  metadata.gz: 1f4f2018d56e59590fae7c2facc0160cc7971b55bff6e78069f05a8e26ac2bdabd783e60a4a6ace40d56fb542682d49566bda9ac860c2a4325926b3507aec072
-  data.tar.gz: 13e288511f09e66054680471fa61e51bac872308ac4f46595b46b898be86706ba5cd76a90a0400f9d68618d6954384788c28aec796d24ccd6a25e36d51168edd
+  metadata.gz: 59b914a36ebfaa8349f7a31dda8605ff7449e43b78f9e240415d297f9a8d3161905803295947515eb5fc291166e386d3f5b0a018efefdfacf6c3574f1a8f21db
+  data.tar.gz: 2aefb9e4e67ed9083bf73ec03042476efd5c581aa8d6bdfefa02b2dd848e6cb3f16d398a70a234b9a7ae9dc26583bdd2af106da8a6a41c9e93b7863586313867

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.1.0
+
+* Add support for Array and Hash containers in JSON representation
+
 # 1.0.0
 
 * Initial release

data/README.md

@@ -41,12 +41,24 @@ after including all of the ActiveModel modules you need:
 include ActiveModelSerializerPlus::Assignment
 ```
 
+The `#attributes=` method this module provides will raise an `ArgumentError` with a
+descriptive message if a problem occurs.
+
 The class will need to implement the `#attribute_types` method which should return a hash
 consisting of attribute names and the name of the type/class of the attribute. You only need
 to include those attributes that are themselves a serializable class and that you want turned
 back into objects rather than being left as hashes, or attributes that aren't automatically
 converted from strings back into the correct type (eg. Date, Time, DateTime).
 
+The value can be a string, symbol or class name to specify the type. For containers (arrays or
+hashes) it is a 2-element array with the first element being the type of the container (array
+or hash) and the second element specifying the type of the elements in the container. You can
+also specify the type of the container as just `'Container'` or `:Container` and the code will
+create a container of the same type (array or hash) as occurs in the JSON. Due to the fact that
+the JSON doesn't indicate the type of elements in a container there's no straightforward way to
+have containers contain elements of different types. It's also not possible to declare a container
+whose elements are containers, elements have to be of a non-container class.
+
 This would be an example:
 
 ```ruby
@@ -61,19 +73,22 @@ class Example
     attr_accessor :time_field
     attr_accessor :string_field
     attr_accessor :object_field
+    attr_accessor :array_field
     
     def attributes
     {
         'integer_field' => nil,
         'time_field' => nil,
         'string_field' => nil,
-        'object_field' => nil
+        'object_field' => nil,
+        'array_field' => nil
     }
     
     def attribute_types
     {
         'time_field' => 'Time',
-        'object_field' => 'SomeSerializableClass'
+        'object_field' => 'SomeSerializableClass',
+        'array_field' => [ 'Array', 'Integer' ]
     }
     
     def initialize( i, t, s, o )
@@ -82,6 +97,7 @@ class Example
         time_field = t
         string_field = s
         object_field = o
+        array_field = [ 1, 2, 3, 4, 5 ]
     }
     
 end
@@ -94,8 +110,8 @@ Examples of using this class to serialize an object to a JSON string:
 
 json_string now contains:
 
-    { 'integer_field' => 5, 'time_field' => '"2015-09-26T19:04:07-07:00', 'string_field' => 'xyzzy abc',
-      'object_field' => { ... } }
+    { "integer_field" => 5, "time_field" => "2015-09-26T19:04:07-07:00", "string_field" => "xyzzy abc",
+      "object_field" => { ... }, "array_field" => [ 1, 2, 3, 4, 5 ] }
 
 And deserializing that string back to an object:
 
@@ -134,6 +150,20 @@ add_xlate('FalseClass', 'Boolean')
 which would create the parsing proc entry for `Boolean` and add the translation entries so that `TrueClass`
 and `FalseClass` act as if derived from an imaginary `Boolean` class for formatting and parsing purposes.
 
+## Adding information about new containers
+
+In `assignment.rb` there are some functions defined on the ActiveModelSerializersPlus module for adding
+new containers. The basic one is `#add_container` which takes 3 arguments: the container type
+name, a proc for iterating through elements from that kind of container and a proc for adding an item to
+that kind of container. The procs paper over the differences in containers, without that there'd need to
+be a separate bit of code for every permutation of source container in the JSON and new destination container.
+The procs for Hash-like containers are the basis for the code. The iterator proc for an Array-like container
+uses the array index as the key when calling the adder proc, and the adder proc for Array-like containers
+ignores the key and just appends the new item to the array. I don't expect a need to add containers often,
+and since most new containers will act like either Arrays or Hashes there are two convenience functions
+`#add_arraylike_container` and `#add_hashlike_container` that take just the container type name and use
+the matching standard iterator and adder procs.
+
 ## Contributing
 
 This project uses `git-flow`, where new features are developed along feature branches based off the

data/lib/active_model_serializer_plus/assignment.rb

@@ -2,6 +2,129 @@ require 'active_model_serializer_plus/translations'
 
 module ActiveModelSerializerPlus
 
+    private
+
+    # Add a new value to an array-like container. `index` will be ignored.
+    @@add_to_arraylike_proc = Proc.new { |container, index, value|
+        container << value
+    }
+    # Add a new key and it's value to a hash-like container.
+    @@add_to_hashlike_proc = Proc.new { |container, key, value|
+        container[key] = value
+    }
+
+    # Populate  a new container from an array-like value
+    @@build_from_arraylike_proc = Proc.new { |container, add_proc, obj_klass, value_container|
+        index = 0
+        value_container.each do |item|
+            obj = ActiveModelSerializerPlus.build_object(obj_klass, item)
+            add_proc.call(container, index, obj) unless obj.nil?
+            index += 1
+        end
+    }
+    # Populate a new container from a hash-like value
+    @@build_from_hashlike_proc = Proc.new { |container, add_proc, obj_klass, value_container|
+        value_container.each do |key, item|
+            obj = ActiveModelSerializerPlus.build_object(obj_klass, item)
+            add_proc.call(container, key, obj) unless obj.nil?
+        end
+    }
+
+    # Map container type names to the procs that iterate through that kind of container.
+    #
+    # You can probably treat the array-like and hash-like procs as standard procs to
+    # handle building from any container that acts like an array (iterates values, indexes are
+    # integers starting from 0) or hash (iterates keys and values).
+    # @note we need both iterator and adder procs so we can build arrays from hashes and vice-versa without
+    #   having to manually list out every permutation.
+    @@container_iterators = {
+        'Array' => @@build_from_arraylike_proc,
+        'Hash' => @@build_from_hashlike_proc
+    }
+
+    # Map container type names to the procs that add a new item to that kind of container.
+    #
+    # Again you can probably treat the array-like and hash-like procs as standard procs
+    # to add items to any container that behaves like an array or hash.
+    @@container_adders = {
+        'Array' => @@add_to_arraylike_proc,
+        'Hash' => @@add_to_hashlike_proc
+    }
+
+    public
+
+    # Look up iterator proc.
+    def self.get_container_iterator(typename)
+        @@container_iterators[typename]
+    end
+
+    # Look up adder proc.
+    def self.get_container_adder(typename)
+        @@container_adders[typename]
+    end
+
+    # Break out the logic for creating a new object of a class from a hash or string value.
+    # It's needed for both individual attributes and for each element of a
+    # container.
+    # @param [Class] obj_klass class of the object to create
+    # @param [String, Hash] value value to use to initialize the object
+    # @return [Object] newly-created object or nil
+    # @raise [ArgumentError] if the object cannot be created
+    def self.build_object(obj_klass, value)
+        obj = nil
+        if value.is_a?(Hash)
+            # If we're looking at a contained object (our value is a hash), see if we have a Proc
+            # to build the object from a hash. If we don't, fall back to creating an object and
+            # using the hash #attributes= method if possible. If all else fails just leave the value
+            obj = ActiveModelSerializerPlus.build(obj_klass.name, value)
+            if obj.nil? && obj_klass.method_defined?('attributes=')
+                obj = obj_klass.new
+                if obj.nil?
+                    raise ArgumentError, "Cannot create object of type #{obj_klass.name}."
+                end
+                obj.attributes = value
+            end
+        elsif value.is_a?(String)
+            obj = ActiveModelSerializerPlus.parse(obj_klass.name, value)
+        end
+        obj
+    end
+
+    # Add iterator and adder procs for a new kind of container.
+    # @param [String] typename type name of the container type to add
+    # @param [Proc] iterator_proc Proc to build from that type of container
+    # @param [Proc] adder_proc Proc to add an item to that type of container
+    # @return [void]
+    def self.add_container(typename, iterator_proc, adder_proc)
+        return if typename.blank? || iterator_proc.nil? || adder_proc.nil?
+        @@container_iterators[typename] = iterator_proc
+        @@container_adders[typename] = adder_proc
+        ActiveModelSerializerPlus.add_xlate(typename, 'Container')
+        return
+    end
+
+    # Add a new kind of Array-like container
+    # @param [String] typename type name of the container type to add
+    # @return [void]
+    def self.add_arraylike_container(typename)
+        return if typename.blank?
+        @@container_iterators[typename] = @@build_from_arraylike_proc
+        @@container_adders[typename] = @@add_to_arraylike_proc
+        ActiveModelSerializerPlus.add_xlate(typename, 'Container')
+        return
+    end
+
+    # Add a new kind of Hash-like container
+    # @param [String] typename type name of the container type to add
+    # @return [void]
+    def self.add_hashlike_container(typename)
+        return if typename.blank?
+        @@container_iterators[typename] = @@build_from_hashlike_proc
+        @@container_adders[typename] = @@add_to_hashlike_proc
+        ActiveModelSerializerPlus.add_xlate(typename, 'Container')
+        return
+    end
+
     # @author Todd Knarr <tknarr@silverglass.org>
     #
     # Default implementation of the <tt>#attributes=</tt> method for ActiveModel classes.
@@ -21,42 +144,99 @@ module ActiveModelSerializerPlus
         # The default <tt>#attributes=</tt> method which assigns a hash to the object's attributes.
         # @param [Hash] hash the hash of attribute names and values
         # @return [self] self
-        # @raise [ArgumentError] if a value from the @attribute_types hash can't be converted to a Class
+        # @raise [ArgumentError] if any error occurs
         def attributes=(hash)
             hash.each do |key, value|
                 # Check #attribute_types for what type this item should be, and if we have an entry
                 # convert it to an actual Class object we can use.
-                klass = nil
-                v = nil
-                v = self.attribute_types[key] if self.respond_to?(:attribute_types) && self.attribute_types.is_a?(Hash)
-                begin
-                    klass = ActiveModelSerializerPlus.to_class(v) unless v.nil?
-                rescue ArgumentError
-                    raise ArgumentError, "Type #{v.to_s} for attribute #{key.to_s} is not a valid type."
-                end
+                attr_klass = nil
+                attr_typename = nil
+
+                attr_typename = self.attribute_types[key] if self.respond_to?(:attribute_types) && self.attribute_types.is_a?(Hash)
+                if attr_typename.is_a?(Array)
+                    # Container
+
+                    container_klass = nil
+                    object_klass = nil
+
+                    if attr_typename.length != 2
+                        raise ArgumentError, "Container type specification for attribute #{key.to_s} is invalid."
+                    end
 
-                unless klass.nil?
-                    if value.is_a?(Hash)
-                        # If we're looking at a contained object (our value is a hash), see if we have a Proc
-                        # to build the object from a hash. If we don't, fall back to creating an object and
-                        # using the hash #attributes= method if possible. If all else fails just leave the value
-                        v = ActiveModelSerializerPlus.build(klass.name, value)
-                        if v.nil? && klass.method_defined?('attributes=')
-                            v = klass.new
-                            v.attributes = value
+                    # Sort out the type of container. First make sure the container type name translates to 'Container'.
+                    # If the type name actually is 'Container', take the type of the container from the type of the
+                    # original value. If it's an actual type name, convert it to a Class object. Raise exceptions if
+                    # any problems are encountered.
+                    container_typename = attr_typename[0]
+                    if container_typename == 'Container'
+                        container_klass = value.class
+                    else
+                        xlated_container_typename = ActiveModelSerializerPlus.type_name_xlate(container_typename)
+                        if xlated_container_typename != 'Container'
+                            raise ArgumentError, "Container type #{container_typename} for attribute #{key.to_s} is not a container."
                         end
+                        begin
+                            container_klass = ActiveModelSerializerPlus.to_class(container_typename)
+                        rescue ArgumentError
+                            raise ArgumentError, "Container type #{container_typename} for attribute #{key.to_s} is not a valid type."
+                        end
+                    end
+
+                    # Sort out the type of objects in the container. Convert the object type name to a Class object
+                    # and raise an exception if it can't be converted.
+                    object_typename = attr_typename[1]
+                    begin
+                        object_klass = ActiveModelSerializerPlus.to_class(object_typename)
+                    rescue ArgumentError
+                        raise ArgumentError, "Object type #{object_typename} for attribute #{key.to_s} is not a valid type."
+                    end
+
+                    container = container_klass.new
+                    if container.nil?
+                        raise ArgumentError, "Cannot create container of type #{container_klass.name}."
+                    end
+                    adder_proc = ActiveModelSerializerPlus.get_container_adder(container_klass.name)
+                    iterator_proc = ActiveModelSerializerPlus.get_container_iterator(value.class.name)
+                    if adder_proc.nil? || iterator_proc.nil?
+                        msg = ''
+                        if iterator_proc.nil?
+                            msg << "iterate through #{value.class.name}"
+                        end
+                        if adder_proc.nil?
+                            if msg.length == 0
+                                msg << ', '
+                            end
+                            msg << "add to #{container_klass.name}"
+                        end
+                        raise ArgumentError, "Cannot #{msg}."
+                    end
+                    # Build the new container by iterating through the value container and adding each item to
+                    # the new container, using the procs we looked up.
+                    iterator_proc.call(container, adder_proc, object_klass, value)
+
+                    self.send("#{key}=", container)
+
+                else
+                    # Object
+
+                    unless attr_typename.nil?
+                        begin
+                            attr_klass = ActiveModelSerializerPlus.to_class(attr_typename)
+                        rescue ArgumentError
+                            raise ArgumentError, "Type #{attr_typename.to_s} for attribute #{key.to_s} is not a valid type."
+                        end
+
+                        v = ActiveModelSerializerPlus.build_object(attr_klass, value)
                         value = v unless v.nil?
-                    elsif value.is_a?(String)
-                        v = ActiveModelSerializerPlus.parse(klass.name, value)
-                        value = v if v
                     end
+
+                    self.send("#{key}=", value)
+
                 end
 
-                self.send("#{key}=", value)
+                self
             end
 
-            self
-
         end
 
     end

data/lib/active_model_serializer_plus/translations.rb

@@ -67,8 +67,6 @@ module ActiveModelSerializerPlus
 
     public
 
-    # @!scope class
-
     # Translate a type/class name to it's psuedo-parent class name if it has one.
     # @param [String] class_name the name of the class to translate
     # @return [String] the translated name

data/lib/active_model_serializer_plus/version.rb

@@ -1,6 +1,6 @@
 module ActiveModelSerializerPlus
 
     # Version number.
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
 
 end

data/test/active_model_serializer_plus/assignment_test.rb

@@ -34,6 +34,81 @@ class ModelClass
     end
 end
 
+class ObjectClass
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+    include ActiveModelSerializerPlus::Assignment
+
+    attr_accessor :x
+    attr_accessor :y
+
+    def attributes
+        { 'x' => nil,
+          'y' => nil
+        }
+    end
+end
+
+class ArrayClass
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+    include ActiveModelSerializerPlus::Assignment
+
+    attr_accessor :integer_field
+    attr_accessor :array_field
+
+    def attributes
+        { 'integer_field' => nil,
+          'array_field' => nil
+        }
+    end
+
+    def attribute_types
+        { 'array_field' => [ 'Array', 'ObjectClass' ]
+        }
+    end
+end
+
+class HashClass
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+    include ActiveModelSerializerPlus::Assignment
+
+    attr_accessor :integer_field
+    attr_accessor :hash_field
+
+    def attributes
+        { 'integer_field' => nil,
+          'hash_field' => nil
+        }
+    end
+
+    def attribute_types
+        { 'hash_field' => [ 'Hash', 'ObjectClass' ]
+        }
+    end
+end
+
+class ContainerClass
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+    include ActiveModelSerializerPlus::Assignment
+
+    attr_accessor :integer_field
+    attr_accessor :container_field
+
+    def attributes
+        { 'integer_field' => nil,
+          'container_field' => nil
+        }
+    end
+
+    def attribute_types
+        { 'container_field' => [ 'Container', 'ObjectClass' ]
+        }
+    end
+end
+
 class AssignmentTest < ActiveSupport::TestCase
     include ActiveModel::Lint::Tests
 
@@ -42,6 +117,55 @@ class AssignmentTest < ActiveSupport::TestCase
         @model.a = 'xyzzy'
         @model.b = InnerClass.new
         @model.b.x = 15
+
+        @array = ArrayClass.new
+        @array.integer_field = 15
+        @array.array_field = Array.new
+        o = ObjectClass.new
+        o.x = 21
+        o.y = 22
+        @array.array_field << o
+        o = ObjectClass.new
+        o.x = 31
+        o.y = 32
+        @array.array_field << o
+        o = ObjectClass.new
+        o.x = 41
+        o.y = 42
+        @array.array_field << o
+
+        @hash = HashClass.new
+        @hash.integer_field = 16
+        @hash.hash_field = Hash.new
+        o = ObjectClass.new
+        o.x = 21
+        o.y = 22
+        @hash.hash_field['first'] = o
+        o = ObjectClass.new
+        o.x = 31
+        o.y = 32
+        @hash.hash_field['second'] = o
+        o = ObjectClass.new
+        o.x = 41
+        o.y = 42
+        @hash.hash_field['third'] = o
+
+
+        @container = ContainerClass.new
+        @container.integer_field = 17
+        @container.container_field = Hash.new
+        o = ObjectClass.new
+        o.x = 21
+        o.y = 22
+        @container.container_field['first'] = o
+        o = ObjectClass.new
+        o.x = 31
+        o.y = 32
+        @container.container_field['second'] = o
+        o = ObjectClass.new
+        o.x = 41
+        o.y = 42
+        @container.container_field['third'] = o
     end
 
     test 'deserialize ModelClass' do
@@ -61,4 +185,89 @@ class AssignmentTest < ActiveSupport::TestCase
         assert_kind_of Integer, r.b.x, 'check attribute x'
         assert_equal 15, r.b.x, 'check attribute x'
     end
+
+    test 'deserialize ArrayClass' do
+        json = @array.to_json
+        assert_kind_of String, json, 'convert model to JSON'
+
+        r = ArrayClass.new
+        r.from_json(json)
+        assert_not_nil r, 'check new object'
+        assert_kind_of ArrayClass, r, 'check new object'
+        assert_not_nil r.integer_field, 'check integer field'
+        assert_kind_of Integer, r.integer_field, 'check integer field'
+        assert_equal 15, r.integer_field, 'check integer field'
+        assert_not_nil r.array_field, 'check array field'
+        assert_kind_of Array, r.array_field, 'check array field'
+        assert_not_empty r.array_field, 'check array field length'
+        assert_equal 3, r.array_field.length, 'check array field length'
+        for i in 0..2 do
+            assert_not_nil r.array_field[i], "check array element #{i}"
+            assert_kind_of ObjectClass, r.array_field[i], "check array element #{i}"
+            assert_not_nil r.array_field[i].x, "check array element #{i} x"
+            assert_kind_of Integer, r.array_field[i].x, "check array element #{i} x"
+            assert_equal (i+2)*10+1, r.array_field[i].x, "check array element #{i} x"
+            assert_not_nil r.array_field[i].y, "check array element #{i} y"
+            assert_kind_of Integer, r.array_field[i].y, "check array element #{i} y"
+            assert_equal (i+2)*10+2, r.array_field[i].y, "check array element #{i} y"
+        end
+    end
+
+    test 'deserialize HashClass' do
+        json = @hash.to_json
+        assert_kind_of String, json, 'convert model to JSON'
+
+        r = HashClass.new
+        r.from_json(json)
+        assert_not_nil r, 'check new object'
+        assert_kind_of HashClass, r, 'check new object'
+        assert_not_nil r.integer_field, 'check integer field'
+        assert_kind_of Integer, r.integer_field, 'check integer field'
+        assert_equal 16, r.integer_field, 'check integer field'
+        assert_not_nil r.hash_field, 'check hash field'
+        assert_kind_of Hash, r.hash_field, 'check hash field'
+        assert_not_empty r.hash_field, 'check hash field length'
+        assert_equal 3, r.hash_field.length, 'check hash field length'
+        i = 0
+        ['first', 'second', 'third'].each do |idx|
+            assert_not_nil r.hash_field[idx], "check hash element #{idx}"
+            assert_kind_of ObjectClass, r.hash_field[idx], "check hash element #{idx}"
+            assert_not_nil r.hash_field[idx].x, "check hash element #{idx} x"
+            assert_kind_of Integer, r.hash_field[idx].x, "check hash element #{idx} x"
+            assert_equal (i+2)*10+1, r.hash_field[idx].x, "check hash element #{idx} x"
+            assert_not_nil r.hash_field[idx].y, "check hash element #{idx} y"
+            assert_kind_of Integer, r.hash_field[idx].y, "check hash element #{idx} y"
+            assert_equal (i+2)*10+2, r.hash_field[idx].y, "check hash element #{idx} y"
+            i += 1
+        end
+    end
+
+    test 'deserialize ContainerClass' do
+        json = @container.to_json
+        assert_kind_of String, json, 'convert model to JSON'
+
+        r = ContainerClass.new
+        r.from_json(json)
+        assert_not_nil r, 'check new object'
+        assert_kind_of ContainerClass, r, 'check new object'
+        assert_not_nil r.integer_field, 'check integer field'
+        assert_kind_of Integer, r.integer_field, 'check integer field'
+        assert_equal 17, r.integer_field, 'check integer field'
+        assert_not_nil r.container_field, 'check container field'
+        assert_kind_of Hash, r.container_field, 'check container field'
+        assert_not_empty r.container_field, 'check container field length'
+        assert_equal 3, r.container_field.length, 'check container field length'
+        i = 0
+        ['first', 'second', 'third'].each do |idx|
+            assert_not_nil r.container_field[idx], "check container element #{idx}"
+            assert_kind_of ObjectClass, r.container_field[idx], "check container element #{idx}"
+            assert_not_nil r.container_field[idx].x, "check container element #{idx} x"
+            assert_kind_of Integer, r.container_field[idx].x, "check container element #{idx} x"
+            assert_equal (i+2)*10+1, r.container_field[idx].x, "check container element #{idx} x"
+            assert_not_nil r.container_field[idx].y, "check container element #{idx} y"
+            assert_kind_of Integer, r.container_field[idx].y, "check container element #{idx} y"
+            assert_equal (i+2)*10+2, r.container_field[idx].y, "check container element #{idx} y"
+            i += 1
+        end
+    end
 end

data/test/test_helper.rb

@@ -17,4 +17,5 @@ require 'rails/test_help'
 class ActiveSupport::TestCase
 
     # Add more helper methods to be used by all tests here...
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_model_serializer_plus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Todd Knarr
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-09 00:00:00.000000000 Z
+date: 2015-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails