shale 0.8.0 → 1.0.0

data/lib/shale/type/complex.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../error'
+require_relative '../mapping/delegates'
 require_relative '../mapping/group/dict_grouping'
 require_relative '../mapping/group/xml_grouping'
 require_relative 'value'
@@ -13,11 +14,11 @@ module Shale
     # @api private
     class Complex < Value
       class << self
-        %i[hash json yaml toml].each do |format|
+        %i[hash json yaml toml csv].each do |format|
           class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
             # Convert Hash to Object using Hash/JSON/YAML/TOML mapping
             #
-            # @param [Hash] hash Hash to convert
+            # @param [Hash, Array] hash Hash to convert
             # @param [Array<Symbol>] only
             # @param [Array<Symbol>] except
             # @param [any] context
@@ -26,6 +27,18 @@ module Shale
             #
             # @api public
             def of_#{format}(hash, only: nil, except: nil, context: nil)
+              #{
+                if format != :toml
+                  <<~CODE
+                    if hash.is_a?(Array)
+                      return hash.map do |item|
+                        of_#{format}(item, only: only, except: except, context: context)
+                      end
+                    end
+                  CODE
+                end
+              }
+
               instance = model.new
 
               attributes
@@ -35,6 +48,7 @@ module Shale
 
               mapping_keys = #{format}_mapping.keys
               grouping = Shale::Mapping::Group::DictGrouping.new
+              delegates = Shale::Mapping::Delegates.new
 
               only = to_partial_render_attributes(only)
               except = to_partial_render_attributes(except)
@@ -54,7 +68,8 @@ module Shale
                     mapper.send(mapping.method_from, instance, value)
                   end
                 else
-                  attribute = attributes[mapping.attribute]
+                  receiver_attributes = get_receiver_attributes(mapping)
+                  attribute = receiver_attributes[mapping.attribute]
                   next unless attribute
 
                   if only
@@ -67,20 +82,22 @@ module Shale
                     next if except.key?(attribute.name) && attribute_except.nil?
                   end
 
+                  casted_value = nil
+
                   if value.nil?
-                    instance.send(attribute.setter, nil)
+                    casted_value = nil
                   elsif attribute.collection?
-                    [*value].each do |val|
-                      if val
+                    casted_value = (value.is_a?(Array) ? value : [value]).map do |val|
+                      unless val.nil?
                         val = attribute.type.of_#{format}(
                           val,
                           only: attribute_only,
                           except: attribute_except,
                           context: context
                         )
-                      end
 
-                      instance.send(attribute.name) << attribute.type.cast(val)
+                        attribute.type.cast(val)
+                      end
                     end
                   else
                     val = attribute.type.of_#{format}(
@@ -89,11 +106,23 @@ module Shale
                       except: attribute_except,
                       context: context
                     )
-                    instance.send(attribute.setter, attribute.type.cast(val))
+
+                    casted_value = attribute.type.cast(val)
+                  end
+
+                  if mapping.receiver
+                    delegates.add(attributes[mapping.receiver], attribute.setter, casted_value)
+                  else
+                    instance.send(attribute.setter, casted_value)
                   end
                 end
               end
 
+              delegates.each do |delegate|
+                receiver = get_receiver(instance, delegate.receiver_attribute)
+                receiver.send(delegate.setter, delegate.value)
+              end
+
               grouping.each do |group|
                 mapper = new
 
@@ -109,7 +138,7 @@ module Shale
 
             # Convert Object to Hash using Hash/JSON/YAML/TOML mapping
             #
-            # @param [any] instance Object to convert
+            # @param [any, Array<any>] instance Object to convert
             # @param [Array<Symbol>] only
             # @param [Array<Symbol>] except
             # @param [any] context
@@ -120,6 +149,18 @@ module Shale
             #
             # @api public
             def as_#{format}(instance, only: nil, except: nil, context: nil)
+              #{
+                if format != :toml
+                  <<~CODE
+                    if instance.is_a?(Array)
+                      return instance.map do |item|
+                        as_#{format}(item, only: only, except: except, context: context)
+                      end
+                    end
+                  CODE
+                end
+              }
+
               unless instance.is_a?(model)
                 msg = "argument is a '\#{instance.class}' but should be a '\#{model}'"
                 raise IncorrectModelError, msg
@@ -143,7 +184,14 @@ module Shale
                     mapper.send(mapping.method_to, instance, hash)
                   end
                 else
-                  attribute = attributes[mapping.attribute]
+                  if mapping.receiver
+                    receiver = instance.send(mapping.receiver)
+                  else
+                    receiver = instance
+                  end
+
+                  receiver_attributes = get_receiver_attributes(mapping)
+                  attribute = receiver_attributes[mapping.attribute]
                   next unless attribute
 
                   if only
@@ -156,7 +204,7 @@ module Shale
                     next if except.key?(attribute.name) && attribute_except.nil?
                   end
 
-                  value = instance.send(attribute.name)
+                  value = receiver.send(attribute.name) if receiver
 
                   if value.nil?
                     hash[mapping.name] = nil if mapping.render_nil?
@@ -312,6 +360,65 @@ module Shale
           )
         end
 
+        # Convert CSV to Object
+        #
+        # @param [String] csv CSV to convert
+        # @param [Array<Symbol>] only
+        # @param [Array<Symbol>] except
+        # @param [any] context
+        # @param [true, false] headers
+        # @param [Hash] csv_options
+        #
+        # @return [model instance]
+        #
+        # @api public
+        def from_csv(csv, only: nil, except: nil, context: nil, headers: false, **csv_options)
+          data = Shale.csv_adapter.load(csv, **csv_options.merge(headers: csv_mapping.keys.keys))
+
+          data.shift if headers
+
+          of_csv(
+            data,
+            only: only,
+            except: except,
+            context: context
+          )
+        end
+
+        # Convert Object to CSV
+        #
+        # @param [model instance] instance Object to convert
+        # @param [Array<Symbol>] only
+        # @param [Array<Symbol>] except
+        # @param [any] context
+        # @param [true, false] headers
+        # @param [Hash] csv_options
+        #
+        # @return [String]
+        #
+        # @api public
+        def to_csv(instance, only: nil, except: nil, context: nil, headers: false, **csv_options)
+          data = as_csv([*instance], only: only, except: except, context: context)
+
+          cols = csv_mapping.keys.values
+
+          if only
+            cols = cols.select { |e| only.include?(e.attribute) }
+          end
+
+          if except
+            cols = cols.reject { |e| except.include?(e.attribute) }
+          end
+
+          cols = cols.map(&:name)
+
+          if headers
+            data.prepend(cols.to_h { |e| [e, e] })
+          end
+
+          Shale.csv_adapter.dump(data, **csv_options.merge(headers: cols))
+        end
+
         # Convert XML document to Object
         #
         # @param [Shale::Adapter::<XML adapter>::Node] element
@@ -331,6 +438,7 @@ module Shale
             .each { |attr| instance.send(attr.setter, attr.default.call) }
 
           grouping = Shale::Mapping::Group::XmlGrouping.new
+          delegates = Shale::Mapping::Delegates.new
 
           only = to_partial_render_attributes(only)
           except = to_partial_render_attributes(except)
@@ -350,16 +458,29 @@ module Shale
                 mapper.send(mapping.method_from, instance, value)
               end
             else
-              attribute = attributes[mapping.attribute]
+              receiver_attributes = get_receiver_attributes(mapping)
+              attribute = receiver_attributes[mapping.attribute]
               next unless attribute
 
               next if only && !only.key?(attribute.name)
               next if except&.key?(attribute.name)
 
+              casted_value = attribute.type.cast(value)
+
               if attribute.collection?
-                instance.send(attribute.name) << attribute.type.cast(value)
+                if mapping.receiver
+                  delegates.add_collection(
+                    attributes[mapping.receiver],
+                    attribute.setter,
+                    casted_value
+                  )
+                else
+                  instance.send(attribute.name) << casted_value
+                end
+              elsif mapping.receiver
+                delegates.add(attributes[mapping.receiver], attribute.setter, casted_value)
               else
-                instance.send(attribute.setter, attribute.type.cast(value))
+                instance.send(attribute.setter, casted_value)
               end
             end
           end
@@ -378,7 +499,8 @@ module Shale
                 mapper.send(content_mapping.method_from, instance, element)
               end
             else
-              attribute = attributes[content_mapping.attribute]
+              receiver_attributes = get_receiver_attributes(content_mapping)
+              attribute = receiver_attributes[content_mapping.attribute]
 
               if attribute
                 skip = false
@@ -388,8 +510,13 @@ module Shale
                 skip = true if except&.key?(attribute.name)
 
                 unless skip
-                  value = attribute.type.of_xml(element)
-                  instance.send(attribute.setter, attribute.type.cast(value))
+                  value = attribute.type.cast(attribute.type.of_xml(element))
+
+                  if content_mapping.receiver
+                    delegates.add(attributes[content_mapping.receiver], attribute.setter, value)
+                  else
+                    instance.send(attribute.setter, value)
+                  end
                 end
                 # rubocop:enable Metrics/BlockNesting
               end
@@ -411,7 +538,8 @@ module Shale
                 mapper.send(mapping.method_from, instance, node)
               end
             else
-              attribute = attributes[mapping.attribute]
+              receiver_attributes = get_receiver_attributes(mapping)
+              attribute = receiver_attributes[mapping.attribute]
               next unless attribute
 
               if only
@@ -431,14 +559,31 @@ module Shale
                 context: context
               )
 
+              casted_value = attribute.type.cast(value)
+
               if attribute.collection?
-                instance.send(attribute.name) << attribute.type.cast(value)
+                if mapping.receiver
+                  delegates.add_collection(
+                    attributes[mapping.receiver],
+                    attribute.setter,
+                    casted_value
+                  )
+                else
+                  instance.send(attribute.name) << casted_value
+                end
+              elsif mapping.receiver
+                delegates.add(attributes[mapping.receiver], attribute.setter, casted_value)
               else
-                instance.send(attribute.setter, attribute.type.cast(value))
+                instance.send(attribute.setter, casted_value)
               end
             end
           end
 
+          delegates.each do |delegate|
+            receiver = get_receiver(instance, delegate.receiver_attribute)
+            receiver.send(delegate.setter, delegate.value)
+          end
+
           grouping.each do |group|
             mapper = new
 
@@ -495,7 +640,8 @@ module Shale
           _cdata = nil,
           only: nil,
           except: nil,
-          context: nil
+          context: nil,
+          version: nil
         )
           unless instance.is_a?(model)
             msg = "argument is a '#{instance.class}' but should be a '#{model}'"
@@ -503,7 +649,7 @@ module Shale
           end
 
           unless doc
-            doc = Shale.xml_adapter.create_document
+            doc = Shale.xml_adapter.create_document(version)
 
             element = as_xml(
               instance,
@@ -542,13 +688,20 @@ module Shale
                 mapper.send(mapping.method_to, instance, element, doc)
               end
             else
-              attribute = attributes[mapping.attribute]
+              if mapping.receiver
+                receiver = instance.send(mapping.receiver)
+              else
+                receiver = instance
+              end
+
+              receiver_attributes = get_receiver_attributes(mapping)
+              attribute = receiver_attributes[mapping.attribute]
               next unless attribute
 
               next if only && !only.key?(attribute.name)
               next if except&.key?(attribute.name)
 
-              value = instance.send(attribute.name)
+              value = receiver.send(attribute.name) if receiver
 
               if mapping.render_nil? || !value.nil?
                 doc.add_namespace(mapping.namespace.prefix, mapping.namespace.name)
@@ -571,7 +724,14 @@ module Shale
                 mapper.send(content_mapping.method_to, instance, element, doc)
               end
             else
-              attribute = attributes[content_mapping.attribute]
+              if content_mapping.receiver
+                receiver = instance.send(content_mapping.receiver)
+              else
+                receiver = instance
+              end
+
+              receiver_attributes = get_receiver_attributes(content_mapping)
+              attribute = receiver_attributes[content_mapping.attribute]
 
               if attribute
                 skip = false
@@ -581,7 +741,7 @@ module Shale
                 skip = true if except&.key?(attribute.name)
 
                 unless skip
-                  value = instance.send(attribute.name)
+                  value = receiver.send(attribute.name) if receiver
 
                   if content_mapping.cdata
                     doc.create_cdata(value.to_s, element)
@@ -606,7 +766,14 @@ module Shale
                 mapper.send(mapping.method_to, instance, element, doc)
               end
             else
-              attribute = attributes[mapping.attribute]
+              if mapping.receiver
+                receiver = instance.send(mapping.receiver)
+              else
+                receiver = instance
+              end
+
+              receiver_attributes = get_receiver_attributes(mapping)
+              attribute = receiver_attributes[mapping.attribute]
               next unless attribute
 
               if only
@@ -619,7 +786,7 @@ module Shale
                 next if except.key?(attribute.name) && attribute_except.nil?
               end
 
-              value = instance.send(attribute.name)
+              value = receiver.send(attribute.name) if receiver
 
               if mapping.render_nil? || !value.nil?
                 doc.add_namespace(mapping.namespace.prefix, mapping.namespace.name)
@@ -680,6 +847,7 @@ module Shale
         # @param [any] context
         # @param [true, false] pretty
         # @param [true, false] declaration
+        # @param [true, false, String] encoding
         #
         # @raise [AdapterError]
         #
@@ -692,13 +860,15 @@ module Shale
           except: nil,
           context: nil,
           pretty: false,
-          declaration: false
+          declaration: false,
+          encoding: false
         )
           validate_xml_adapter
           Shale.xml_adapter.dump(
-            as_xml(instance, only: only, except: except, context: context),
+            as_xml(instance, only: only, except: except, context: context, version: declaration),
             pretty: pretty,
-            declaration: declaration
+            declaration: declaration,
+            encoding: encoding
           )
         end
 
@@ -740,6 +910,64 @@ module Shale
             end
           end.to_h
         end
+
+        # Get receiver attributes for given mapping
+        #
+        # @param [Shale::Mapping::Descriptor::Dict] mapping
+        #
+        # @raise [AttributeNotDefinedError]
+        # @raise [NotAShaleMapperError]
+        #
+        # @return [Hash<Symbol, Shale::Attribute>]
+        #
+        # @api private
+        def get_receiver_attributes(mapping)
+          return attributes unless mapping.receiver
+
+          receiver_attribute = attributes[mapping.receiver]
+
+          unless receiver_attribute
+            msg = "attribute '#{mapping.receiver}' is not defined on #{self} mapper"
+            raise AttributeNotDefinedError, msg
+          end
+
+          unless receiver_attribute.type < Mapper
+            msg = "attribute '#{mapping.receiver}' is not a descendant of Shale::Mapper type"
+            raise NotAShaleMapperError, msg
+          end
+
+          if receiver_attribute.collection?
+            msg = "attribute '#{mapping.receiver}' can't be a collection"
+            raise NotAShaleMapperError, msg
+          end
+
+          receiver_attribute.type.attributes
+        end
+
+        # Get receiver for given mapping
+        #
+        # @param [any] instance
+        # @param [Shale::Attribute] receiver_attribute
+        #
+        # @return [Array]
+        #
+        # @api private
+        def get_receiver(instance, receiver_attribute)
+          receiver = instance.send(receiver_attribute.name)
+
+          unless receiver
+            receiver = receiver_attribute.type.model.new
+
+            receiver_attribute.type.attributes
+              .values
+              .select { |attr| attr.default }
+              .each { |attr| receiver.send(attr.setter, attr.default.call) }
+
+            instance.send(receiver_attribute.setter, receiver)
+          end
+
+          receiver
+        end
       end
 
       # Convert Object to Hash
@@ -801,6 +1029,26 @@ module Shale
         self.class.to_toml(self, only: only, except: except, context: context)
       end
 
+      # Convert Object to CSV
+      #
+      # @param [Array<Symbol>] only
+      # @param [Array<Symbol>] except
+      # @param [any] context
+      #
+      # @return [String]
+      #
+      # @api public
+      def to_csv(only: nil, except: nil, context: nil, headers: false, **csv_options)
+        self.class.to_csv(
+          self,
+          only: only,
+          except: except,
+          context: context,
+          headers: headers,
+          **csv_options
+        )
+      end
+
       # Convert Object to XML
       #
       # @param [Array<Symbol>] only
@@ -808,18 +1056,27 @@ module Shale
       # @param [any] context
       # @param [true, false] pretty
       # @param [true, false] declaration
+      # @param [true, false, String] encoding
       #
       # @return [String]
       #
       # @api public
-      def to_xml(only: nil, except: nil, context: nil, pretty: false, declaration: false)
+      def to_xml(
+        only: nil,
+        except: nil,
+        context: nil,
+        pretty: false,
+        declaration: false,
+        encoding: false
+      )
         self.class.to_xml(
           self,
           only: only,
           except: except,
           context: context,
           pretty: pretty,
-          declaration: declaration
+          declaration: declaration,
+          encoding: encoding
         )
       end
     end

data/lib/shale/type/date.rb

@@ -47,6 +47,17 @@ module Shale
         value&.iso8601
       end
 
+      # Use ISO 8601 format in CSV document
+      #
+      # @param [Date] value
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.as_csv(value, **)
+        value&.iso8601
+      end
+
       # Use ISO 8601 format in XML document
       #
       # @param [Date] value Value to convert to XML

data/lib/shale/type/time.rb

@@ -47,6 +47,17 @@ module Shale
         value&.iso8601
       end
 
+      # Use ISO 8601 format in CSV document
+      #
+      # @param [Time] value
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.as_csv(value, **)
+        value&.iso8601
+      end
+
       # Use ISO 8601 format in XML document
       #
       # @param [Time] value Value to convert to XML

data/lib/shale/type/value.rb

@@ -111,6 +111,28 @@ module Shale
           value
         end
 
+        # Extract value from CSV document
+        #
+        # @param [any] value
+        #
+        # @return [any]
+        #
+        # @api private
+        def of_csv(value, **)
+          value
+        end
+
+        # Convert value to form accepted by CSV document
+        #
+        # @param [any] value
+        #
+        # @return [any]
+        #
+        # @api private
+        def as_csv(value, **)
+          value
+        end
+
         # Extract value from XML document
         #
         # @param [Shale::Adapter::<XML adapter>::Node] value

data/lib/shale/utils.rb

@@ -5,6 +5,21 @@ module Shale
   #
   # @api private
   module Utils
+    # Upcase first letter of a string
+    #
+    # @param [String] val
+    #
+    # @example
+    #   Shale::Utils.upcase_first('fooBar')
+    #   # => 'FooBar'
+    #
+    # @api private
+    def self.upcase_first(str)
+      return '' unless str
+      return '' if str.empty?
+      str[0].upcase + str[1..-1]
+    end
+
     # Convert string to Ruby's class naming convention
     #
     # @param [String] val
@@ -15,13 +30,14 @@ module Shale
     #
     # @api private
     def self.classify(str)
-      str = str.to_s.sub(/.*\./, '')
+      # names may include a period, which will need to be stripped out
+      str = str.to_s.gsub(/\./, '')
 
-      str = str.sub(/^[a-z\d]*/) { |match| match.capitalize || match }
+      str = str.sub(/^[a-z\d]*/) { |match| upcase_first(match) || match }
 
-      str.gsub(%r{(?:_|-|(/))([a-z\d]*)}i) do
+      str.gsub('::', '/').gsub(%r{(?:_|-|(/))([a-z\d]*)}i) do
         word = Regexp.last_match(2)
-        substituted = word.capitalize || word
+        substituted = upcase_first(word) || word
         Regexp.last_match(1) ? "::#{substituted}" : substituted
       end
     end
@@ -36,6 +52,8 @@ module Shale
     #
     # @api private
     def self.snake_case(str)
+      # XML elements allow periods and hyphens
+      str = str.to_s.gsub('.', '_')
       return str.to_s unless /[A-Z-]|::/.match?(str)
       word = str.to_s.gsub('::', '/')
       word = word.gsub(/([A-Z]+)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) do

data/lib/shale/version.rb

@@ -2,5 +2,5 @@
 
 module Shale
   # @api private
-  VERSION = '0.8.0'
+  VERSION = '1.0.0'
 end