active_model_serializer_plus 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 361857f5e46f0a701cf41f9d43fa7d7f404bf928
+  data.tar.gz: a59df64844aa6b4d4b7421263c8c98cb0104f69e
+SHA512:
+  metadata.gz: 1f4f2018d56e59590fae7c2facc0160cc7971b55bff6e78069f05a8e26ac2bdabd783e60a4a6ace40d56fb542682d49566bda9ac860c2a4325926b3507aec072
+  data.tar.gz: 13e288511f09e66054680471fa61e51bac872308ac4f46595b46b898be86706ba5cd76a90a0400f9d68618d6954384788c28aec796d24ccd6a25e36d51168edd

data/.yardopts

@@ -0,0 +1,3 @@
+-
+LICENSE.md
+CHANGELOG.md

data/Appraisals

@@ -0,0 +1,3 @@
+appraise "rails-4.2" do
+  gem "rails", "4.2.4"
+end

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 1.0.0
+
+* Initial release
+
+# 0.9.0
+
+* Final development version with complete tests
+
+# 0.1.0
+
+* Initial development version

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Todd Knarr
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# @author Todd Knarr <tknarr@silverglass.org>
+
+# ActiveModelSerializerPlus
+
+Enhances the standard ActiveModel::Serializers::JSON and ActiveModel::Serializers::Xml
+modules by adding a default `#attributes=` method that implements the normal loop used to
+assign values to attributes. The loop makes use of the `#attribute_types` hash to convert
+sub-hashes to objects of the right class and to parse strings into values of the right
+type (eg. to insure a string containing a time value is converted into a Time object).
+This allows for automatic deserialization of serialized objects without needing to write
+code for it.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_model_serializer_plus'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_model_serializer_plus
+
+## Usage
+
+Add the gem's module to your source file:
+
+```ruby
+require 'active_model_serializer_plus`
+```
+
+Then in the class you need to serialize/deserialize you include the Assignment module
+after including all of the ActiveModel modules you need:
+
+```ruby
+include ActiveModelSerializerPlus::Assignment
+```
+
+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).
+
+This would be an example:
+
+```ruby
+require 'active_model_serializer_plus'
+
+class Example
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+    include ActiveModelSerializerPlus::Assignment
+    
+    attr_accessor :integer_field
+    attr_accessor :time_field
+    attr_accessor :string_field
+    attr_accessor :object_field
+    
+    def attributes
+    {
+        'integer_field' => nil,
+        'time_field' => nil,
+        'string_field' => nil,
+        'object_field' => nil
+    }
+    
+    def attribute_types
+    {
+        'time_field' => 'Time',
+        'object_field' => 'SomeSerializableClass'
+    }
+    
+    def initialize( i, t, s, o )
+    {
+        integer_field = i
+        time_field = t
+        string_field = s
+        object_field = o
+    }
+    
+end
+```
+
+Examples of using this class to serialize an object to a JSON string:
+
+    obj = Example.new( 5, Time.now, 'xyzzy abc', SomeSerializableClass.new )
+    json_string = obj.to_json
+
+json_string now contains:
+
+    { 'integer_field' => 5, 'time_field' => '"2015-09-26T19:04:07-07:00', 'string_field' => 'xyzzy abc',
+      'object_field' => { ... } }
+
+And deserializing that string back to an object:
+
+    new_obj = Example.new.from_json( json_string )
+
+new_obj should now be identical to obj, including having time_field being a Time object and
+object_field being a SomeSerializableClass object initialized from the hash in 'object_field'.
+
+For ActiveModel classes the types could have been included in the `#attributes` hash, but that would
+conflict with the use of `#attributes` in ActiveRecord classes and could cause confusion.
+
+## Adding information about new types
+
+In the `translations.rb` file there are some functions defined on the ActiveModelSerializerPlus module
+itself. The ones you'll probably find useful are `#add_xlate` and `#add_type` which add information about
+a type to the hashes that control formatting and parsing. You'll need to read the documentation on the hashes
+themselves for details, but the short form is that `#add_type` takes the name of a type/class, a Proc that
+takes and object and formats it into a string, a Proc that takes a string and parses it and initializes an
+object from it, and a Proc that takes a deserialized hash and constructs an object from it. `#add_xlate`
+takes the name of a type and the name of it's pseudo-parent class and adds an entry to the type name
+translation table. The lookup routines check for a translation first and see if Procs exist for the
+translated name (the pseudo-parent type). Most of the time you'd omit any new translations and let the
+lookup routines walk up the normal class inheritance chain to find the correct formatting and parsing Procs.
+You'd only fill in translations if you had classes that can be treated as derived from a common class but
+that don't actually derive from any common class. `TrueClass` and `FalseClass` are a good example. They don't
+need a formatting class because they already serialize as `true` and `false` which is convenient, but you'll\
+find a parsing Proc for the pseudo-class `Boolean` that correctly parses both of those strings back to true and
+false values. To set this up you'd do:
+
+```ruby
+add_type('Boolean', nil, Proc.new { |boolean| %w(1 true).include?(boolean.to_s.strip.downcase) }, nil)
+add_xlate('TrueClass', 'Boolean')
+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.
+
+## Contributing
+
+This project uses `git-flow`, where new features are developed along feature branches based off the
+`develop` branch rather than `master`. Avoid naming your branches `master`, `develop`, `hotfix-`* or `release-`*
+as those conflict with standard branches for hotfixes and releases. You should fork and branch off of the
+`develop` branch instead of `master`, and merge back to `develop` before creating your pull request.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler/gem_tasks'
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+    t.options += ['--title', "Active Model Serializer Plus #{ActiveModelSerializerPlus::VERSION} Documentation"]
+end

data/active_model_serializer_plus.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_model_serializer_plus/version'
+
+Gem::Specification.new do |spec|
+    spec.name = 'active_model_serializer_plus'
+    spec.version = ActiveModelSerializerPlus::VERSION
+    spec.date = Time.now.strftime('%Y-%m-%d')
+    spec.author = 'Todd Knarr'
+    spec.email = 'tknarr@silverglass.org'
+    spec.summary = %q{Enhanced serialization/deserialization support for ActiveModel classes.}
+    spec.description = %q{Adds methods for automatic deserialization from standard JSON and XML, and a variant implementation of serialization/deserialization for XML.}
+    spec.homepage = 'https://github.com/tknarr/active_model_serializer_plus'
+    spec.license = 'MIT'
+
+    spec.files = Dir.glob('lib/**/*.rb').select { |path| File.file?(path) } +
+        [  __FILE__ ]
+    spec.test_files = Dir.glob('test/**/*').select { |path| File.file?(path) && !File.fnmatch('*.{log,sqlite3}', path, File::FNM_EXTGLOB) } +
+        Dir.glob('gemfiles/*.gemfile') + [ 'Rakefile', 'Appraisals' ]
+    spec.extra_rdoc_files = [ 'README.md', 'CHANGELOG.md', 'LICENSE.md', '.yardopts' ]
+    spec.require_paths = ['lib']
+
+    spec.add_dependency 'rails', '~> 4.2'
+    spec.add_dependency 'activemodel', '~> 4.2'
+
+    # Development
+    spec.add_development_dependency 'bundler', '~> 1.7'
+    spec.add_development_dependency 'rake', '~> 10.0'
+    spec.add_development_dependency 'yard', '~> 0'
+
+    # Testing
+    spec.add_development_dependency 'minitest', '~> 5'
+    spec.add_development_dependency 'appraisal', '~> 2'
+    spec.add_development_dependency 'sqlite3', '~> 1'
+end

data/gemfiles/rails_4.2.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.2.4"
+
+gemspec :path => "../"

data/lib/active_model_serializer_plus.rb

@@ -0,0 +1,4 @@
+require 'active_model_serializer_plus/version'
+require 'active_model_serializer_plus/translations'
+require 'active_model_serializer_plus/assignment'
+require 'active_model_serializer_plus/railtie' if defined?(Rails)

data/lib/active_model_serializer_plus/assignment.rb

@@ -0,0 +1,64 @@
+require 'active_model_serializer_plus/translations'
+
+module ActiveModelSerializerPlus
+
+    # @author Todd Knarr <tknarr@silverglass.org>
+    #
+    # Default implementation of the <tt>#attributes=</tt> method for ActiveModel classes.
+    #
+    # This is the base of the JSON and Xml modules. It supplies a standard <tt>#attributes=</tt> method to
+    # classes that follows the basic pattern of the custom one you'd normally write and adds the ability
+    # to pick up object type information from the <tt>#attributes_types</tt> hash to convert the hash values of
+    # contained objects into actual objects. This mostly eliminates the need to write custom <tt>#attributes=</tt>
+    # methods for each class with code to check attribute names and initialize objects from child hashes.
+    #
+    # The standard ActiveModel/ActiveRecord serialization/deserialization has some flaws, for instance it
+    # will serialize classes as contained hashes whether or not they have an <tt>#attributes=</tt> method available
+    # to deserialize them. We work around that by having building Procs which can do the correct thing in
+    # many cases.
+    module Assignment
+
+        # 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
+        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
+
+                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
+                        end
+                        value = v unless v.nil?
+                    elsif value.is_a?(String)
+                        v = ActiveModelSerializerPlus.parse(klass.name, value)
+                        value = v if v
+                    end
+                end
+
+                self.send("#{key}=", value)
+            end
+
+            self
+
+        end
+
+    end
+
+end

data/lib/active_model_serializer_plus/railtie.rb

@@ -0,0 +1,7 @@
+module ActiveModelSerializerPlus
+
+    # Railtie class needed for Rails integration.
+    class Railtie < Rails::Railtie
+    end
+
+end

data/lib/active_model_serializer_plus/translations.rb

@@ -0,0 +1,218 @@
+# @author Todd Knarr <tknarr@silverglass.org>
+#
+# Top-level namespace for the ActiveModelSerializerPlus extensions.
+#
+# The methods and module variables here aren't commonly used directly by applications, they're
+# mainly for internal use by the Assignment, JSON and Xml namespaces. You'll want to become familiar
+# with the contents if you want to extend the set of types/classes handled automatically during
+# serialization and deserialization.
+#
+# Currently the formatting-related functionality is unused. It's included for use in a planned
+# XML serialization/deserialization extension.
+module ActiveModelSerializerPlus
+
+    private
+
+    # Pseudo-parent-class names for classes that can be handled by a common
+    # Proc even though they don't derive from a common parent class. That includes
+    # container classes, although we don't do anything with them yet.
+    @@type_name_xlate = {
+        'TrueClass' => 'Boolean',
+        'FalseClass' => 'Boolean',
+        'Hash' => 'Container',
+        'Array' => 'Container'
+    }
+
+    # If a class is listed here use the Proc to format it into a string, otherwise just use to_s
+    @@formatting = {
+        'Date' => Proc.new { |date| date.xmlschema },
+        'DateTime' => Proc.new { |datetime| datetime.xmlschema },
+        'Time' => Proc.new { |time| time.xmlschema }
+    }
+
+    # If a class is listed here, use the Proc to parse a string into an object of the right class
+    @@parsing = {
+        'Symbol' => Proc.new { |symbol| symbol.to_sym },
+        'Time' => Proc.new { |time| Time.xmlschema(time) rescue ::Time.parse(time) },
+        'Date' => Proc.new { |date| Date.xmlschema(date) rescue ::Date.parse(date) },
+        'DateTime' => Proc.new { |datetime| DateTime.xmlschema(datetime) rescue ::DateTime.parse(datetime) },
+        'Integer' => Proc.new { |integer| integer.to_i },
+        'Float' => Proc.new { |float| float.to_f },
+        'BigDecimal' => Proc.new { |number| BigDecimal(number) },
+        'Boolean' => Proc.new { |boolean| %w(1 true).include?(boolean.to_s.strip.downcase) }
+    }
+
+    # If a class is listed here, use the Proc to build it from a Hash, otherwise use the
+    # standard hash initialization method.
+    #
+    # This is used to deal with really unpleasant cases where a class is serialized as a hash but
+    # can't be constructed from a hash or the values in the hash and we can't for whatever reason
+    # insert a new method into the class to do the job.
+    @@building = {
+        'IPAddr' => Proc.new { |addr_hash|
+            fam = addr_hash['family']
+            addr = addr_hash['addr']
+            mask = addr_hash['mask_addr']
+            # Kludgy. IPAddr has no way to build from the hash or it's contents so we depend
+            # on #new accepting an integer address parameter correctly.
+            result = IPAddr.new(addr, fam)
+            # Kludgy. All we have is the integer netmask but we need either the prefix length as an
+            # integer or the netmask as a string of octets. So we use the same #new behavior as above
+            # to take the netmask integer value and convert it to a netmask string through an IPAddr
+            # object.
+            netmask = IPAddr.new(mask,fam).to_s
+            result.mask(netmask)
+        }
+    }
+
+    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
+    def self.type_name_xlate(class_name)
+        @@type_name_xlate[class_name]
+    end
+
+    # Format a value into a string using the defined formatting Proc for <tt>value</tt>'s class.
+    # @note If no formatting Proc is defined, <tt>#to_s</tt> is used instead.
+    # @note Checks all parent classes of <tt>value</tt> for Procs.
+    # @param [Object] value the value to format
+    # @return [String] the value formatted into a string
+    def self.format(value)
+        # Check the translation table first for a pseudo-parent, and if we found one check
+        # for it's proc. Then start with the value's class name and work up through it's
+        # parent classes until we find a proc for one. If we can't find a proc, just use
+        # the #to_s method.
+        p = nil
+        n = @@type_name_xlate[value.class.name]
+        p = @@formatting[n] unless n.nil?
+        if p.nil?
+            b = value.class
+            until b.nil? do
+                p = @@formatting[b.name]
+                break unless p.nil?
+                b = b.superclass
+            end
+        end
+        p ? p.call(value) : value.to_s
+    end
+
+    # Parse a string value into an object of the named type if a parsing Proc is defined.
+    # @note Checks all parent classes of <tt>class_name</tt> for Procs.
+    # @param [String] class_name name of the class of object being created from the value
+    # @param [String] value the string containing the formatted value to be parsed
+    # @return [Object] the new object, or nil if no parsing Proc for <tt>class_name</tt> is defined
+    def self.parse(class_name, value)
+        # Check for a proc for the type name given, and if we find one use it. Otherwise
+        # try to convert that name to a class. If we can, start with it and work up through
+        # it's parent classes checking for a proc for each. If we can't find a proc, return
+        # nil.
+        p = nil
+        xlt = @@type_name_xlate[class_name] || class_name
+        p = @@parsing[xlt] unless xlt.nil?
+        if p.nil?
+            klass = nil
+            begin
+                klass = class_name.constantize
+            rescue NameError
+                klass = nil
+            end
+            until klass.nil?
+                p = @@parsing[klass.name]
+                break unless p.nil?
+                klass = klass.superclass
+            end
+        end
+        p ? p.call(value.to_s) : nil
+    end
+
+    # Build an object of the named type from a hash if a building Proc is defined.
+    # @param [String] class_name name of the class of object being built from the hash
+    # @param [Hash] hash hash containing the attribute names and values from which the object is to be built
+    # @return [Object] the new object, or nil if no building Proc for <tt>class_name</tt> is defined
+    def self.build(class_name, hash)
+        p = nil
+        xlt = @@type_name_xlate[class_name] || class_name
+        p = @@building[xlt] unless xlt.nil?
+        p ? p.call(hash) : nil
+    end
+
+    # Add a new type translation.
+    # Translations are used to create pseudo-parent classes in cases where several classes can use common
+    # Procs for formatting, parsing and/or building but don't share a common parent class, eg. TrueClass
+    # and FalseClass which can both use the Boolean formatting and parsing Procs.
+    # @param [String] type_name name of the specific type
+    # @param [String] parent_type_name name of the pseudo-parent type
+    # @return [void] no return value
+    def self.add_xlate( type_name, parent_type_name )
+        return if type_name.blank?
+        @@type_name_xlate[type_name] = parent_type_name unless parent_type_name.blank?
+        return
+    end
+
+    # Add information about a new type to the formatting/parsing/building hashes.
+    # <tt>type_name</tt> is required, all others are optional and should be specified as <tt>nil</tt>
+    # if not being defined.
+    # @param [String] type_name name of the type to add
+    # @param [Proc] formatting_proc Proc to add to format an object's value into a string
+    # @param [Proc] parsing_proc Proc to add to parse a string value and create an object from it
+    # @param [Proc] building_proc Proc to add to create an object from a hash of attribute names and values
+    # @return [void] no return value
+    def self.add_type(type_name, formatting_proc = nil, parsing_proc = nil, building_proc = nil)
+        return if type_name.blank?
+        @@formatting[type_name] = formatting_proc unless formatting_proc.nil?
+        @@parsing[type_name] = parsing_proc unless parsing_proc.nil?
+        @@building[type_name] = building_proc unless building_proc.nil?
+        return
+    end
+
+    # Helper method to convert a type/class name into an actual class.
+    # @param [Class, Symbol, String] class_name name to convert into a Class object
+    # @return [Class] Class object for the named class
+    # @raise [ArgumentError] if <tt>class_name</tt> is not of an acceptable type
+    # @raise [NameError] if <tt>class_name</tt> is a Class that doesn't exist
+    def self.to_class(class_name)
+        klass = nil
+        if class_name.is_a?(Class)
+            klass = class_name
+        elsif class_name.is_a?(String)
+            begin
+                klass = class_name.constantize unless class_name.blank?
+            rescue NameError
+                raise ArgumentError, "Type #{class_name} is invalid"
+            end
+        elsif class_name.is_a?(Symbol)
+            begin
+                klass = class_name.to_s.constantize
+            rescue NameError
+                raise ArgumentError, "Type #{class_name.to_s} is invalid"
+            end
+        else
+            raise ArgumentError, "Type #{class_name.to_s} is invalid"
+        end
+        klass
+    end
+
+    # Helper method to convert a representation of a class or class name into a string containing the class name.
+    # @param [Class, Symbol, String] class_name the Class whose name you need or a symbol or string representing a class name
+    # @return [String] the class name represented by <tt>class_name</tt> converted to a string
+    # @raise [ArgumentError] if <tt>class_name</tt> is not of an acceptable type
+    # @raise [NameError] if <tt>class_name</tt> is a Class that doesn't exist
+    def self.to_classname(class_name)
+        klassname = nil
+        if class_name.is_a?(Class)
+            klassname = class_name.name
+        elsif class_name.is_a?(String)
+            klassname = class_name
+        elsif class_name.is_a?(Symbol)
+            klassname = class_name.to_s
+        else
+            raise ArgumentError, "Argument type #{class_name.class.name} is not Class, String or Symbol"
+        end
+        klassname
+    end
+
+end