shale 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76c0022b3d2d42be143362c84c6697628781acdce7694fb9bc0f305d3f854964
-  data.tar.gz: 0b0b1b060eab81ebfae80afa3c31c809280b66ebd77e413c5908c4bbd09a081a
+  metadata.gz: 3f880bc8d984c45e7e8a05bd155c1014df237e037263c7bf68a7ae82c0e49ea4
+  data.tar.gz: ba7a2f12bed87e048dd53d43900f1c8203d90f5f89a43b3824475ddda39eb07b
 SHA512:
-  metadata.gz: 43bc9188d1f07c5c367a8ed94e2a3da6b878a7b7b86773d7898697abbd3937d4de6ae0471f9362c72e8a6be2cc5e5100a5206b2f2cc7155ff2ff8784953ef702
-  data.tar.gz: 0e610703cc73809a78007785962d9a322e515b88ab143a55adfeaa1a0da5961f14d8768a3dec4ad797070bbab165c238123702cbc671f522f86e2934968ff78b
+  metadata.gz: 54023d4f621dae53537f73e0ad79d3736d5d52e605c1a7da2c4bdb06588b348feaae9066ce00b6b3aedc9e84ea23a425884eabf987717ffda6d3c22eccc6325f
+  data.tar.gz: e82cad292dab557891cad4f210bfb4a97d2096a6d2151a5a8aef020358accb5986e527e32a141a9a2e3a01d594e9a3adb42c0f7e8d17464517731136f63289a2

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.9.0] - 2022-10-31
+
+### Added
+- Support for CSV
+- Allow to specify version and add encoding to XML declaration
+- Support for mapping/generating collections
+
 ## [0.8.0] - 2022-08-30
 
 ### Added

data/README.md

@@ -1,18 +1,18 @@
 # Shale
 
-Shale is a Ruby object mapper and serializer for JSON, YAML, TOML and XML.
-It allows you to parse JSON, YAML, TOML and XML data and convert it into Ruby data structures,
-as well as serialize data structures into JSON, YAML, TOML or XML.
+Shale is a Ruby object mapper and serializer for JSON, YAML, TOML, CSV and XML.
+It allows you to parse JSON, YAML, TOML, CSV and XML data and convert it into Ruby data structures,
+as well as serialize data structures into JSON, YAML, TOML, CSV or XML.
 
 Documentation with interactive examples is available at [Shale website](https://www.shalerb.org)
 
 ## Features
 
-* Convert JSON, YAML, TOML and XML to Ruby data model
-* Convert Ruby data model to JSON, YAML, TOML and XML
+* Convert JSON, YAML, TOML, CSV and XML to Ruby data model
+* Convert Ruby data model to JSON, YAML, TOML, CSV and XML
 * Generate JSON and XML Schema from Ruby models
 * Compile JSON and XML Schema into Ruby models
-* Out of the box support for JSON, YAML, Tomlib, toml-rb, Nokogiri, REXML and Ox parsers
+* Out of the box support for JSON, YAML, Tomlib, toml-rb, CSV, Nokogiri, REXML and Ox parsers
 * Support for custom adapters
 
 ## Installation
@@ -51,9 +51,13 @@ $ gem install shale
 * [Converting object to Hash](#converting-object-to-hash)
 * [Converting XML to object](#converting-xml-to-object)
 * [Converting object to XML](#converting-object-to-xml)
+* [Converting CSV to object](#converting-csv-to-object)
+* [Converting object to CSV](#converting-object-to-csv)
+* [Converting collections](#converting-collections)
 * [Mapping JSON keys to object attributes](#mapping-json-keys-to-object-attributes)
 * [Mapping YAML keys to object attributes](#mapping-yaml-keys-to-object-attributes)
 * [Mapping TOML keys to object attributes](#mapping-toml-keys-to-object-attributes)
+* [Mapping CSV columns to object attributes](#mapping-csv-columns-to-object-attributes)
 * [Mapping Hash keys to object attributes](#mapping-hash-keys-to-object-attributes)
 * [Mapping XML elements and attributes to object attributes](#mapping-xml-elements-and-attributes-to-object-attributes)
 * [Using XML namespaces](#using-xml-namespaces)
@@ -346,6 +350,70 @@ person.to_xml
 # </person>
 ```
 
+### Converting CSV to object
+
+CSV represents a flat data structure, so you can't map properties to complex types directly,
+but you can use methods to map properties to complex types
+(see [Using methods to extract and generate data](#using-methods-to-extract-and-generate-data)
+section).
+
+`.from_csv` method allways returns an array of records.
+
+```ruby
+people = Person.from_csv(<<~DATA)
+John,Doe,50,false
+DATA
+```
+
+### Converting object to CSV
+
+```ruby
+people[0].to_csv # or Person.to_csv(people) if you want to convert a collection
+
+# =>
+#
+# John,Doe,50,false
+```
+
+### Converting collections
+
+Shale allows converting collections for formats that support it (JSON, YAML and CSV).
+To convert Ruby array to JSON:
+
+```ruby
+person1 = Person.new(name: 'John Doe')
+person2 = Person.new(name: 'Joe Sixpack')
+
+Person.to_json([person1, person2], pretty: true)
+# or Person.to_yaml([person1, person2])
+# or Person.to_csv([person1, person2])
+
+# =>
+#
+# [
+#   { "name": "John Doe" },
+#   { "name": "Joe Sixpack" }
+# ]
+```
+
+To convert JSON array to Ruby:
+
+```ruby
+Person.from_json(<<~JSON)
+[
+  { "name": "John Doe" },
+  { "name": "Joe Sixpack" }
+]
+JSON
+
+# =>
+#
+# [
+#   #<Person:0x00000001033dbce8 @name="John Doe">,
+#   #<Person:0x00000001033db4c8 @name="Joe Sixpack">
+# ]
+```
+
 ### Mapping JSON keys to object attributes
 
 By default keys are named the same as attributes. To use custom keys use:
@@ -392,6 +460,24 @@ class Person < Shale::Mapper
 end
 ```
 
+### Mapping CSV columns to object attributes
+
+For CSV the order of mapping matters, the first argument in the `map` method is only
+used as a label in header row. So, in the example below the first column will be mapped
+to `:first_name` attribute and the second column to `:last_name`.
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+
+  csv do
+    map 'firstName', to: :first_name
+    map 'lastName', to: :last_name
+  end
+end
+```
+
 ### Mapping Hash keys to object attributes
 
 ```ruby
@@ -561,8 +647,9 @@ DATA
 
 ### Rendering nil values
 
-By default elements with `nil` value are not rendered. You can change this behavior
-by using `render_nil: true` on a mapping.
+For JSON, YAML, TOML and XML by default, elements with `nil` value are not rendered.
+You can change this behavior by using `render_nil: true` on a mapping.
+For CSV the default is to render `nil` elements.
 
 ```ruby
 class Person < Shale::Mapper
@@ -853,19 +940,52 @@ person.to_json(pretty: true)
 # }
 ```
 
-You can also add an XML declaration by passing `declaration: true` to `#to_xml`
+You can also add an XML declaration by passing `declaration: true` and `encoding: true`
+or if you want to spcify version: `declaration: '1.1'` and `encoding: 'ASCII'` to `#to_xml`
 
 ```ruby
-person.to_xml(pretty: true, declaration: true)
+person.to_xml(pretty: true, declaration: true, encoding: true)
 
 # =>
 #
-# <?xml version="1.0"?>
+# <?xml version="1.0" encoding="UTF-8"?>
 # <Person>
 #   <Address city="London"/>
 # </Person>
 ```
 
+For CSV you can pass `headers: true` to indicate that the first row contains column
+names and shouldn't be included in the returned collection. It also accepts all the options that
+[CSV parser](https://ruby-doc.org/stdlib-3.1.2/libdoc/csv/rdoc/CSV.html#class-CSV-label-Options) accepts.
+
+```ruby
+class Person
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+end
+
+people = Person.from_csv(<<~DATA, headers: true, col_sep: '|')
+  first_name|last_name
+  John|Doe
+  James|Sixpack
+DATA
+
+# =>
+#
+# [
+#   #<Person:0x0000000113d7a488 @first_name="John", @last_name="Doe">,
+#   #<Person:0x0000000113d7a488 @first_name="James", @last_name="Sixpack">
+# ]
+
+Person.to_csv(people, headers: true, col_sep: '|')
+
+# =>
+#
+# first_name|last_name
+# John|Doe
+# James|Sixpack
+```
+
 ### Using custom models
 
 By default Shale combines mapper and model into one class. If you want to use your own classes
@@ -955,10 +1075,10 @@ end
 ### Adapters
 
 Shale uses adapters for parsing and generating documents.
-By default Ruby's standard JSON, YAML parsers are used for handling JSON and YAML documents.
+By default Ruby's standard JSON, YAML, CSV parsers are used for handling JSON YAML, CSV documents.
 
-You can change it by providing your own adapter. For JSON, YAML and TOML, adapter must implement
-`.load` and `.dump` class methods.
+You can change it by providing your own adapter. For JSON, YAML, TOML and CSV adapter must
+implement `.load` and `.dump` class methods.
 
 ```ruby
 require 'shale'

data/lib/shale/adapter/csv.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'csv'
+
+module Shale
+  module Adapter
+    # CSV adapter
+    #
+    # @api public
+    class CSV
+      # Parse CSV into Array<Hash<String, any>>
+      #
+      # @param [String] csv CSV document
+      # @param [Array<String>] headers
+      # @param [Hash] options
+      #
+      # @return [Array<Hash<String, any>>]
+      #
+      # @api private
+      def self.load(csv, headers:, **options)
+        ::CSV.parse(csv, headers: headers, **options).map(&:to_h)
+      end
+
+      # Serialize Array<Hash<String, any>> into CSV
+      #
+      # @param [Array<Hash<String, any>>] obj Array<Hash<String, any>> object
+      # @param [Array<String>] headers
+      # @param [Hash] options
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.dump(obj, headers:, **options)
+        ::CSV.generate(**options) do |csv|
+          obj.each do |row|
+            values = []
+
+            headers.each do |header|
+              values << row[header] if row.key?(header)
+            end
+
+            csv << values
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shale/adapter/nokogiri/document.rb

@@ -9,9 +9,14 @@ module Shale
       class Document
         # Initialize object
         #
+        # @param [String, nil] version
+        #
         # @api private
-        def initialize
-          @doc = ::Nokogiri::XML::Document.new
+        def initialize(version = nil)
+          ver = nil
+          ver = version if version.is_a?(String)
+
+          @doc = ::Nokogiri::XML::Document.new(ver)
           @namespaces = {}
         end
 

data/lib/shale/adapter/nokogiri.rb

@@ -37,12 +37,13 @@ module Shale
       #
       # @param [::Nokogiri::XML::Document] doc Nokogiri document
       # @param [true, false] pretty
-      # @param [true, false] declaration
+      # @param [true, false, String] declaration
+      # @param [true, false, String] encoding
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc, pretty: false, declaration: false)
+      def self.dump(doc, pretty: false, declaration: false, encoding: false)
         save_with = ::Nokogiri::XML::Node::SaveOptions::AS_XML
 
         if pretty
@@ -53,6 +54,10 @@ module Shale
           save_with |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
         end
 
+        if encoding
+          doc.encoding = encoding == true ? 'UTF-8' : encoding
+        end
+
         result = doc.to_xml(save_with: save_with)
 
         unless pretty
@@ -64,9 +69,11 @@ module Shale
 
       # Create Shale::Adapter::Nokogiri::Document instance
       #
+      # @param [true, false, String, nil] declaration
+      #
       # @api private
-      def self.create_document
-        Document.new
+      def self.create_document(version = nil)
+        Document.new(version)
       end
     end
   end

data/lib/shale/adapter/ox.rb

@@ -31,12 +31,13 @@ module Shale
       #
       # @param [::Ox::Document, ::Ox::Element] doc Ox document
       # @param [true, false] pretty
-      # @param [true, false] declaration
+      # @param [true, false, String] declaration
+      # @param [true, false, String] encoding
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc, pretty: false, declaration: false)
+      def self.dump(doc, pretty: false, declaration: false, encoding: false)
         opts = { indent: -1, with_xml: false }
 
         if pretty
@@ -44,7 +45,12 @@ module Shale
         end
 
         if declaration
-          doc[:version] = '1.0'
+          doc[:version] = declaration == true ? '1.0' : declaration
+
+          if encoding
+            doc[:encoding] = encoding == true ? 'UTF-8' : encoding
+          end
+
           opts[:with_xml] = true
         end
 
@@ -54,7 +60,7 @@ module Shale
       # Create Shale::Adapter::Ox::Document instance
       #
       # @api private
-      def self.create_document
+      def self.create_document(_version = nil)
         Document.new
       end
     end

data/lib/shale/adapter/rexml.rb

@@ -32,14 +32,28 @@ module Shale
       #
       # @param [::REXML::Document] doc REXML document
       # @param [true, false] pretty
-      # @param [true, false] declaration
+      # @param [true, false, String] declaration
+      # @param [true, false, String] encoding
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc, pretty: false, declaration: false)
+      def self.dump(doc, pretty: false, declaration: false, encoding: false)
         if declaration
-          doc.add(::REXML::XMLDecl.new)
+          ver = nil
+          enc = nil
+
+          if declaration.is_a?(String)
+            ver = declaration
+          end
+
+          if encoding == true
+            enc = 'UTF-8'
+          else
+            enc = encoding || nil
+          end
+
+          doc.add(::REXML::XMLDecl.new(ver, enc))
         end
 
         io = StringIO.new
@@ -58,7 +72,7 @@ module Shale
       # Create Shale::Adapter::REXML::Document instance
       #
       # @api private
-      def self.create_document
+      def self.create_document(_version = nil)
         Document.new
       end
     end

data/lib/shale/mapper.rb

@@ -49,6 +49,7 @@ module Shale
     @json_mapping = Mapping::Dict.new
     @yaml_mapping = Mapping::Dict.new
     @toml_mapping = Mapping::Dict.new
+    @csv_mapping = Mapping::Dict.new(render_nil_default: true)
     @xml_mapping = Mapping::Xml.new
 
     class << self
@@ -87,6 +88,13 @@ module Shale
       # @api public
       attr_reader :toml_mapping
 
+      # Return CSV mapping object
+      #
+      # @return [Shale::Mapping::Dict]
+      #
+      # @api public
+      attr_reader :csv_mapping
+
       # Return XML mapping object
       #
       # @return [Shale::Mapping::XML]
@@ -109,12 +117,14 @@ module Shale
         subclass.instance_variable_set('@__json_mapping_init', @json_mapping.dup)
         subclass.instance_variable_set('@__yaml_mapping_init', @yaml_mapping.dup)
         subclass.instance_variable_set('@__toml_mapping_init', @toml_mapping.dup)
+        subclass.instance_variable_set('@__csv_mapping_init', @csv_mapping.dup)
         subclass.instance_variable_set('@__xml_mapping_init', @xml_mapping.dup)
 
         subclass.instance_variable_set('@hash_mapping', @hash_mapping.dup)
         subclass.instance_variable_set('@json_mapping', @json_mapping.dup)
         subclass.instance_variable_set('@yaml_mapping', @yaml_mapping.dup)
         subclass.instance_variable_set('@toml_mapping', @toml_mapping.dup)
+        subclass.instance_variable_set('@csv_mapping', @csv_mapping.dup)
 
         xml_mapping = @xml_mapping.dup
         xml_mapping.root(Utils.underscore(subclass.name || ''))
@@ -173,6 +183,7 @@ module Shale
         @json_mapping.map(name.to_s, to: name) unless @json_mapping.finalized?
         @yaml_mapping.map(name.to_s, to: name) unless @yaml_mapping.finalized?
         @toml_mapping.map(name.to_s, to: name) unless @toml_mapping.finalized?
+        @csv_mapping.map(name.to_s, to: name) unless @csv_mapping.finalized?
         @xml_mapping.map_element(name.to_s, to: name) unless @xml_mapping.finalized?
 
         @attributes_module.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
@@ -280,6 +291,30 @@ module Shale
         @toml_mapping.instance_eval(&block)
       end
 
+      # Define CSV mapping
+      #
+      # @param [Proc] block
+      #
+      # @example
+      #   calss Person < Shale::Mapper
+      #     attribute :first_name, Shale::Type::String
+      #     attribute :last_name, Shale::Type::String
+      #     attribute :age, Shale::Type::Integer
+      #
+      #     csv do
+      #       map 'first_name', to: :first_name
+      #       map 'last_name', to: :last_name
+      #       map 'age', to: :age
+      #     end
+      #   end
+      #
+      # @api public
+      def csv(&block)
+        @csv_mapping = @__csv_mapping_init.dup
+        @csv_mapping.finalize!
+        @csv_mapping.instance_eval(&block)
+      end
+
       # Define XML mapping
       #
       # @param [Proc] block

data/lib/shale/mapping/dict.rb

@@ -14,12 +14,12 @@ module Shale
       # @param [String] key Document's key
       # @param [Symbol, nil] to Object's attribute
       # @param [Hash, nil] using
-      # @param [true, false] render_nil
+      # @param [true, false, nil] render_nil
       #
       # @raise [IncorrectMappingArgumentsError] when arguments are incorrect
       #
       # @api private
-      def map(key, to: nil, using: nil, render_nil: false)
+      def map(key, to: nil, using: nil, render_nil: nil)
         super(key, to: to, using: using, render_nil: render_nil)
       end
 

data/lib/shale/mapping/dict_base.rb

@@ -18,10 +18,13 @@ module Shale
 
       # Initialize instance
       #
+      # @param [true, false] render_nil_default
+      #
       # @api private
-      def initialize
+      def initialize(render_nil_default: false)
         @keys = {}
         @finalized = false
+        @render_nil_default = render_nil_default
       end
 
       # Map key to attribute
@@ -30,19 +33,19 @@ module Shale
       # @param [Symbol, nil] to
       # @param [Hash, nil] using
       # @param [String, nil] group
-      # @param [true, false] render_nil
+      # @param [true, false, nil] render_nil
       #
       # @raise [IncorrectMappingArgumentsError] when arguments are incorrect
       #
       # @api private
-      def map(key, to: nil, using: nil, group: nil, render_nil: false)
+      def map(key, to: nil, using: nil, group: nil, render_nil: nil)
         Validator.validate_arguments(key, to, using)
         @keys[key] = Descriptor::Dict.new(
           name: key,
           attribute: to,
           methods: using,
           group: group,
-          render_nil: render_nil
+          render_nil: render_nil.nil? ? @render_nil_default : render_nil
         )
       end
 

data/lib/shale/type/complex.rb

@@ -13,11 +13,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 +26,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
@@ -109,7 +121,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 +132,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
@@ -312,6 +336,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
@@ -495,7 +578,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 +587,7 @@ module Shale
           end
 
           unless doc
-            doc = Shale.xml_adapter.create_document
+            doc = Shale.xml_adapter.create_document(version)
 
             element = as_xml(
               instance,
@@ -680,6 +764,7 @@ module Shale
         # @param [any] context
         # @param [true, false] pretty
         # @param [true, false] declaration
+        # @param [true, false, String] encoding
         #
         # @raise [AdapterError]
         #
@@ -692,13 +777,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
 
@@ -801,6 +888,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 +915,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/version.rb

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

data/lib/shale.rb

@@ -3,6 +3,7 @@
 require 'yaml'
 
 require_relative 'shale/mapper'
+require_relative 'shale/adapter/csv'
 require_relative 'shale/adapter/json'
 require_relative 'shale/type/boolean'
 require_relative 'shale/type/date'
@@ -15,7 +16,7 @@ require_relative 'shale/version'
 # Main library namespace
 #
 # Shale uses adapters for parsing and serializing documents.
-# For handling JSON and YAML, adapter must implement .load and .dump methods, so
+# For handling JSON, YAML, TOML and CSV, adapter must implement .load and .dump methods, so
 # e.g for handling JSON, MultiJson works out of the box.
 #
 # Adapters for XML handling are more complicated and must conform to [@see shale/adapter/rexml]
@@ -29,9 +30,11 @@ require_relative 'shale/version'
 #   Shale.json_adapter = MultiJson
 #   Shale.json_adapter # => MultiJson
 #
-# @example setting YAML adapter for handling YAML documents
-#   Shale.yaml_adapter = MultiJson
-#   Shale.yaml_adapter # => MultiJson
+# @example setting TOML adapter for handling TOML documents
+#   require 'shale/adapter/toml_rb'
+#
+#   Shale.toml_adapter = Shale::Adapter::TomlRB
+#   Shale.toml_adapter # => Shale::Adapter::TomlRB
 #
 # @example setting REXML adapter for handling XML documents
 #   Shale.xml_adapter = Shale::Adapter::REXML
@@ -86,6 +89,16 @@ module Shale
     # @api public
     attr_accessor :toml_adapter
 
+    # Set CSV adapter
+    #
+    # @param [.load, .dump] adapter
+    #
+    # @example
+    #   Shale.csv_adapter = Shale::Adapter::CSV
+    #
+    # @api public
+    attr_writer :csv_adapter
+
     # XML adapter accessor. Available adapters are Shale::Adapter::REXML,
     # Shale::Adapter::Nokogiri and Shale::Adapter::Ox
     #
@@ -126,5 +139,18 @@ module Shale
     def yaml_adapter
       @yaml_adapter || YAML
     end
+
+    # Return CSV adapter. By default CSV is used
+    #
+    # @return [.load, .dump]
+    #
+    # @example
+    #   Shale.csv_adapter
+    #   # => Shale::Adapter::CSV
+    #
+    # @api public
+    def csv_adapter
+      @csv_adapter || Adapter::CSV
+    end
   end
 end

data/shale.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors = ['Kamil Giszczak']
   spec.email = ['beerkg@gmail.com']
 
-  spec.summary = 'Ruby object mapper and serializer for XML, JSON, TOML and YAML.'
-  spec.description = 'Ruby object mapper and serializer for XML, JSON, TOML and YAML.'
+  spec.summary = 'Ruby object mapper and serializer for XML, JSON, TOML, CSV and YAML.'
+  spec.description = 'Ruby object mapper and serializer for XML, JSON, TOML, CSV and YAML.'
   spec.homepage = 'https://shalerb.org'
   spec.license = 'MIT'
 

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: shale
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kamil Giszczak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-30 00:00:00.000000000 Z
+date: 2022-10-31 00:00:00.000000000 Z
 dependencies: []
-description: Ruby object mapper and serializer for XML, JSON, TOML and YAML.
+description: Ruby object mapper and serializer for XML, JSON, TOML, CSV and YAML.
 email:
 - beerkg@gmail.com
 executables:
@@ -23,6 +23,7 @@ files:
 - README.md
 - exe/shaleb
 - lib/shale.rb
+- lib/shale/adapter/csv.rb
 - lib/shale/adapter/json.rb
 - lib/shale/adapter/nokogiri.rb
 - lib/shale/adapter/nokogiri/document.rb
@@ -126,5 +127,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Ruby object mapper and serializer for XML, JSON, TOML and YAML.
+summary: Ruby object mapper and serializer for XML, JSON, TOML, CSV and YAML.
 test_files: []