shale 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaa3043e612d332fab30ff87ecab722e3812e7769eba982db27c38f74c205ce1
-  data.tar.gz: bb5cdb963bce5756c48edb37d28bddc40a816901e87b4714ea512f07f8ec4c28
+  metadata.gz: 468fc4f3fa1ccd796958748eea653aaa9aec0dbf223c2e5486ddba00350d79fc
+  data.tar.gz: 4b78746e97bc6fd080b8a6566be2534c3a1c05017acacabd3935f7e2ea81b097
 SHA512:
-  metadata.gz: ed1f1ffc88cabb5f9403ff957c02efc4565aee73b9a8a1fd2297ff13bfbb6bdf0e94664b865f8d2d812ddd66fe97d154e34982eea3318ba01c6d16b4a6922c70
-  data.tar.gz: d41392de36bcace9efee12a869f49beffba235ae09e09f33c6973159b96320e3f657a6edd4d634e53da430f8127e74fa1025fa2f5c75dad2e7568abe6a0794ce
+  metadata.gz: 776a30c22e95f8c85e150b64ec7df09e89aeb4e86fb2f6f0fcec67a438b13b73926c3d5419b8194f457a2f09fc8eb64bf491e8b1ea5c5d6957e1e1b5cfab9549
+  data.tar.gz: 0d236bde4f3b5aaf9b3ea5a5b8380b3861b24f5d0b310430329c68d010c368890dedbd7f6fad8649b71cd443362c8c6272ebb9c7a234998fa546ecb99e728f44

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [0.7.1] - [2022-08-12]
+
+### Fixed
+- Fix broken handling of Date and Time types
+
+## [0.7.0] - [2022-08-09]
+
+### Added
+- `only: []` and `except: []` options that allow to controll what attributes are rendered/parsed
+- `render_nil: true` option that allows to render nil values
+- Allow to pass a context object to extractor/generator methods
+
+### Changed
+- Pass whole document to methods for JSON/YAML/TOML so its behavior is consistent with XML mapping
+- Convert splat arguments to keyword arguments
+- RSpec: enable random spec execution and warnings
+
+## [0.6.0] - 2022-07-05
+
+### Added
+- Support for TOML
+- Support for CDATA nodes in XML documents
+- Support for using custom models
+
+### Fixed
+- Allow to map XML content using methods
+- Prevent adding default mapping after mapping block was declared
+
 ## [0.5.0] - 2022-06-28
 
 ### Added

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 TODO: Write your name
+Copyright (c) 2021 Kamil Giszczak
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,18 +1,18 @@
 # Shale
 
-Shale is a Ruby object mapper and serializer for JSON, YAML and XML.
-It allows you to parse JSON, YAML and XML data and convert it into Ruby data structures,
-as well as serialize data structures into JSON, YAML or XML.
+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.
 
 Documentation with interactive examples is available at [Shale website](https://www.shalerb.org)
 
 ## Features
 
-* Convert JSON, YAML and XML to Ruby data model
-* Convert Ruby data model to JSON, YAML and XML
+* Convert JSON, YAML, TOML and XML to Ruby data model
+* Convert Ruby data model to JSON, YAML, TOML 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, Nokogiri, REXML and Ox parsers
+* Out of the box support for JSON, YAML, Tomlib, toml-rb, Nokogiri, REXML and Ox parsers
 * Support for custom adapters
 
 ## Installation
@@ -45,17 +45,22 @@ $ gem install shale
 * [Converting object to JSON](#converting-object-to-json)
 * [Converting YAML to object](#converting-yaml-to-object)
 * [Converting object to YAML](#converting-object-to-yaml)
+* [Converting TOML to object](#converting-toml-to-object)
+* [Converting object to TOML](#converting-object-to-toml)
 * [Converting Hash to object](#converting-hash-to-object)
 * [Converting object to Hash](#converting-object-to-hash)
 * [Converting XML to object](#converting-xml-to-object)
 * [Converting object to XML](#converting-object-to-xml)
 * [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 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)
+* [Rendering nil values](#rendering-nil-values)
 * [Using methods to extract and generate data](#using-methods-to-extract-and-generate-data)
-* [Pretty printing and XML declaration](#pretty-printing-and-xml-declaration)
+* [Additional options](#additional-options)
+* [Using custom models](#using-custom-models)
 * [Supported types](#supported-types)
 * [Writing your own type](#writing-your-own-type)
 * [Adapters](#adapters)
@@ -195,6 +200,65 @@ person.to_yaml
 #   zip: E1 6AN
 ```
 
+### Converting TOML to object
+
+To use TOML with Shale you have to set adapter you want to use.
+Out of the box Shale suports [Tomlib](https://github.com/kgiszczak/tomlib).
+It also comes with adapter for [toml-rb](https://github.com/emancu/toml-rb) if you prefer that.
+For details see [Adapters](#adapters) section.
+
+To set it, first make sure Tomlib gem is installed:
+
+```
+$ gem install tomlib
+```
+
+then setup adapter:
+
+```ruby
+require 'tomlib'
+Shale.toml_adapter = Tomlib
+
+# Alternatively if you'd like to use toml-rb, use:
+require 'shale/adapter/toml_rb'
+Shale.toml_adapter = Shale::Adapter::TomlRB
+```
+
+Now you can use TOML with Shale:
+
+```ruby
+person = Person.from_toml(<<~DATA)
+first_name = "John"
+last_name = "Doe"
+age = 50
+married = false
+hobbies = ["Singing", "Dancing"]
+[address]
+city = "London"
+street = "Oxford Street"
+zip = "E1 6AN"
+DATA
+```
+
+### Converting object to TOML
+
+```ruby
+person.to_toml
+
+# =>
+#
+# first_name = "John"
+# last_name = "Doe"
+# age = 50
+# married = false
+# hobbies = [ "Singing", "Dancing" ]
+#
+# [address]
+# city = "London"
+# street = "Oxford Street"
+# zip = "E1 6AN"
+```
+
 ### Converting Hash to object
 
 ```ruby
@@ -240,6 +304,8 @@ require 'shale/adapter/rexml'
 Shale.xml_adapter = Shale::Adapter::REXML
 ```
 
+Now you can use XML with Shale:
+
 ```ruby
 person = Person.from_xml(<<~DATA)
 <person>
@@ -284,6 +350,8 @@ person.to_xml
 
 By default keys are named the same as attributes. To use custom keys use:
 
+:warning: **Declaring custom mapping removes default mapping for given format!**
+
 ```ruby
 class Person < Shale::Mapper
   attribute :first_name, Shale::Type::String
@@ -310,6 +378,20 @@ class Person < Shale::Mapper
 end
 ```
 
+### Mapping TOML keys to object attributes
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+
+  toml do
+    map 'firstName', to: :first_name
+    map 'lastName', to: :last_name
+  end
+end
+```
+
 ### Mapping Hash keys to object attributes
 
 ```ruby
@@ -380,6 +462,37 @@ DATA
 - `map_attribute` - map element's attribute to attribute
 - `map_content` - map first text node to attribute
 
+You can use `cdata: true` option on `map_element` and `map_content` to handle CDATA nodes:
+
+```ruby
+class Address < Shale::Mapper
+  attribute :content, Shale::Type::String
+
+  xml do
+    map_content to: :content, cdata: true
+  end
+end
+
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :address, Address
+
+  xml do
+    root 'Person'
+
+    map_element 'FirstName', to: :first_name, cdata: true
+    map_element 'Address', to: :address
+  end
+end
+
+person = Person.from_xml(<<~DATA)
+<Person>
+  <FirstName><![CDATA[John]]></FirstName>
+  <Address><![CDATA[Oxford Street]]></Address>
+</person>
+DATA
+```
+
 ### Using XML namespaces
 
 To map namespaced elements and attributes use `namespace` and `prefix` properties on
@@ -446,6 +559,52 @@ person = Person.from_xml(<<~DATA)
 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.
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :age, Shale::Type::Integer
+
+  json do
+    map 'first_name', to: :first_name, render_nil: true
+    map 'last_name', to: :last_name, render_nil: false
+    map 'age', to: :age, render_nil: true
+  end
+
+  xml do
+    root 'person'
+
+    map_element 'first_name', to: :first_name, render_nil: true
+    map_element 'last_name', to: :last_name, render_nil: false
+    map_attribute 'age', to: :age, render_nil: true
+  end
+end
+
+person = Person.new(first_name: nil, last_name: nil, age: nil)
+
+puts person.to_json(pretty: true)
+
+# =>
+#
+# {
+#   "first_name": null,
+#   "age": "null"
+# }
+
+puts person.to_xml(pretty: true)
+
+# =>
+#
+# <person age="">
+#   <first_name/>
+# </person>
+```
+
 ### Using methods to extract and generate data
 
 If you need full controll over extracting and generating data from/to document,
@@ -469,42 +628,42 @@ class Person < Shale::Mapper
     map_element 'Address', using: { from: :address_from_xml, to: :address_to_xml }
   end
 
-  def hobbies_from_json(value)
-    self.hobbies = value.split(',').map(&:strip)
+  def hobbies_from_json(model, value)
+    model.hobbies = value.split(',').map(&:strip)
   end
 
-  def hobbies_to_json
-    hobbies.join(', ')
+  def hobbies_to_json(model, doc)
+    doc['hobbies'] = model.hobbies.join(', ')
   end
 
-  def address_from_json(value)
-    self.street = value['street']
-    self.city = value['city']
+  def address_from_json(model, value)
+    model.street = value['street']
+    model.city = value['city']
   end
 
-  def address_to_json
-    { 'street' => street, 'city' => city }
+  def address_to_json(model, doc)
+    doc['address'] = { 'street' => model.street, 'city' => model.city }
   end
 
-  def hobbies_from_xml(value)
-    self.hobbies = value.split(',').map(&:strip)
+  def hobbies_from_xml(model, value)
+    model.hobbies = value.split(',').map(&:strip)
   end
 
-  def hobbies_to_xml(element, doc)
-    doc.add_attribute(element, 'hobbies', hobbies.join(', '))
+  def hobbies_to_xml(model, element, doc)
+    doc.add_attribute(element, 'hobbies', model.hobbies.join(', '))
   end
 
-  def address_from_xml(node)
-    self.street = node.children.find { |e| e.name == 'Street' }.text
-    self.city = node.children.find { |e| e.name == 'City' }.text
+  def address_from_xml(model, node)
+    model.street = node.children.find { |e| e.name == 'Street' }.text
+    model.city = node.children.find { |e| e.name == 'City' }.text
   end
 
-  def address_to_xml(parent, doc)
+  def address_to_xml(model, parent, doc)
     street_element = doc.create_element('Street')
-    doc.add_text(street_element, street.to_s)
+    doc.add_text(street_element, model.street.to_s)
 
     city_element = doc.create_element('City')
-    doc.add_text(city_element, city.to_s)
+    doc.add_text(city_element, model.city.to_s)
 
     address_element = doc.create_element('Address')
     doc.add_element(address_element, street_element)
@@ -529,7 +688,7 @@ person = Person.from_xml(<<~DATA)
     <Street>Oxford Street</Street>
     <City>London</City>
   </Address>
-</person>
+</Person>
 DATA
 
 # =>
@@ -540,12 +699,100 @@ DATA
 #  @city="London">
 ```
 
-### Pretty printing and XML declaration
+You can also pass a `context` object that will be available in extractor/generator methods:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :password, Shale::Type::String
 
-If you need formatted output you can pass `:pretty` parameter to `#to_json` and `#to_xml`
+  json do
+    map 'password', using: { from: :password_from_json, to: :password_to_json }
+  end
+
+  def password_from_json(model, value, context)
+    if context.admin?
+      model.password = value
+    else
+      model.password = '*****'
+    end
+  end
+
+  def password_to_json(model, doc, context)
+    if context.admin?
+      doc['password'] = model.password
+    else
+      doc['password'] = '*****'
+    end
+  end
+end
+
+Person.new(password: 'secret').to_json(context: current_user)
+```
+
+### Additional options
+
+You can control which attributes to render and parse by
+using `only: []` and `except: []` parameters.
 
 ```ruby
-person.to_json(:pretty)
+# e.g. if you have this model graph:
+person = Person.new(
+  first_name: 'John'
+  last_name: 'Doe',
+  address: Address.new(city: 'London', street: 'Oxford Street')
+)
+
+# if you want to render only `first_name` and `address.city` do:
+person.to_json(only: [:first_name, address: [:city]], pretty: true)
+
+# =>
+#
+# {
+#   "first_name": "John",
+#   "address": {
+#     "city": "London"
+#   }
+# }
+
+# and if you don't need an address you can do:
+person.to_json(except: [:address], pretty: true)
+
+# =>
+#
+# {
+#   "first_name": "John",
+#   "last_name": "Doe"
+# }
+```
+
+It works the same for parsing:
+
+```ruby
+# e.g. if you want to parse only `address.city` do:
+Person.from_json(doc, only: [address: [:city]])
+
+# =>
+#
+# #<Person:0x0000000113d7a488
+#  @first_name=nil,
+#  @last_name=nil,
+#  @address=#<Address:0x0000000113d7a140 @street=nil, @city="London">>
+
+# and if you don't need an `address`:
+Person.from_json(doc, except: [:address])
+
+# =>
+#
+# #<Person:0x0000000113d7a488
+#  @first_name="John",
+#  @last_name="Doe",
+#  @address=nil>
+```
+
+If you need formatted output you can pass `pretty: true` parameter to `#to_json` and `#to_xml`
+
+```ruby
+person.to_json(pretty: true)
 
 # =>
 #
@@ -557,10 +804,10 @@ person.to_json(:pretty)
 # }
 ```
 
-You can also add an XML declaration by passing `:declaration` to `#to_xml`
+You can also add an XML declaration by passing `declaration: true` to `#to_xml`
 
 ```ruby
-person.to_xml(:pretty, :declaration)
+person.to_xml(pretty: true, declaration: true)
 
 # =>
 #
@@ -570,6 +817,67 @@ person.to_xml(:pretty, :declaration)
 # </Person>
 ```
 
+### Using custom models
+
+By default Shale combines mapper and model into one class. If you want to use your own classes
+as models you can do it by using `model` directive on the mapper:
+
+```ruby
+class Address
+  attr_accessor :street, :city
+end
+
+class Person
+  attr_accessor :first_name, :last_name, :address
+end
+
+class AddressMapper < Shale::Mapper
+  model Address
+
+  attribute :street, Shale::Type::String
+  attribute :city, Shale::Type::String
+end
+
+class PersonMapper < Shale::Mapper
+  model Person
+
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :address, AddressMapper
+end
+
+person = PersonMapper.from_json(<<~DATA)
+{
+  "first_name": "John",
+  "last_name": "Doe",
+  "address": {
+    "street": "Oxford Street",
+    "city": "London"
+  }
+}
+DATA
+
+# =>
+#
+# #<Person:0x0000000113d7a488
+#  @first_name="John",
+#  @last_name="Doe",
+#  @address=#<Address:0x0000000113d7a140 @street="Oxford Street", @city="London">>
+
+PersonMapper.to_json(person, pretty: true)
+
+# =>
+#
+# {
+#   "first_name": "John",
+#   "last_name": "Doe",
+#   "address": {
+#     "street": "Oxford Street",
+#     "city": "London"
+#   }
+# }
+```
+
 ### Supported types
 
 Shale supports these types out of the box:
@@ -598,9 +906,9 @@ end
 ### Adapters
 
 Shale uses adapters for parsing and generating documents.
-By default Ruby's standard JSON and YAML parsers are used for handling JSON and YAML documents.
+By default Ruby's standard JSON, YAML parsers are used for handling JSON and YAML documents.
 
-You can change it by providing your own adapter. For JSON and YAML, adapter must implement
+You can change it by providing your own adapter. For JSON, YAML and TOML, adapter must implement
 `.load` and `.dump` class methods.
 
 ```ruby
@@ -611,6 +919,21 @@ Shale.json_adapter = MultiJson
 Shale.yaml_adapter = MyYamlAdapter
 ```
 
+To handle TOML documents you have to set TOML adapter. Out of the box `Tomlib` is supported.
+Shale also provides adapter for `toml-rb` parser:
+
+```ruby
+require 'shale'
+
+# if you want to use Tomlib
+require 'tomlib'
+Shale.toml_adapter = Tomlib
+
+# if you want to use toml-rb
+require 'shale/adapter/toml_rb'
+Shale.toml_adapter = Shale::Adapter::TomlRB
+```
+
 To handle XML documents you have to explicitly set XML adapter.
 Shale provides adapters for most popular Ruby XML parsers:
 

data/lib/shale/adapter/json.rb

@@ -22,13 +22,13 @@ module Shale
       # Serialize Hash into JSON
       #
       # @param [Hash] obj Hash object
-      # @param [Array<Symbol>] options
+      # @param [true, false] pretty
       #
       # @return [String]
       #
       # @api private
-      def self.dump(obj, *options)
-        if options.include?(:pretty)
+      def self.dump(obj, pretty: false)
+        if pretty
           ::JSON.pretty_generate(obj)
         else
           ::JSON.generate(obj)

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

@@ -41,6 +41,16 @@ module Shale
           ::Nokogiri::XML::Element.new(name, @doc)
         end
 
+        # Create CDATA node and add it to parent
+        #
+        # @param [String] text
+        # @param [::Nokogiri::XML::Element] parent
+        #
+        # @api private
+        def create_cdata(text, parent)
+          parent.add_child(::Nokogiri::XML::CDATA.new(@doc, text))
+        end
+
         # Add XML namespace to document
         #
         # @param [String] prefix

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

@@ -89,7 +89,7 @@ module Shale
           first = @node
             .children
             .to_a
-            .filter(&:text?)
+            .filter { |e| e.text? || e.cdata? }
             .first
 
           first&.text

data/lib/shale/adapter/nokogiri.rb

@@ -36,25 +36,26 @@ module Shale
       # Serialize Nokogiri document into XML
       #
       # @param [::Nokogiri::XML::Document] doc Nokogiri document
-      # @param [Array<Symbol>] options
+      # @param [true, false] pretty
+      # @param [true, false] declaration
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc, *options)
+      def self.dump(doc, pretty: false, declaration: false)
         save_with = ::Nokogiri::XML::Node::SaveOptions::AS_XML
 
-        if options.include?(:pretty)
+        if pretty
           save_with |= ::Nokogiri::XML::Node::SaveOptions::FORMAT
         end
 
-        unless options.include?(:declaration)
+        unless declaration
           save_with |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
         end
 
         result = doc.to_xml(save_with: save_with)
 
-        unless options.include?(:pretty)
+        unless pretty
           result = result.sub(/\n/, '')
         end
 

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

@@ -32,6 +32,16 @@ module Shale
           ::Ox::Element.new(name)
         end
 
+        # Create CDATA node and add it to parent
+        #
+        # @param [String] text
+        # @param [::Ox::Element] parent
+        #
+        # @api private
+        def create_cdata(text, parent)
+          parent << ::Ox::CData.new(text)
+        end
+
         # Add XML namespace to document
         #
         # Ox doesn't support XML namespaces so this method does nothing.

data/lib/shale/adapter/ox/node.rb

@@ -80,7 +80,16 @@ module Shale
         #
         # @api private
         def text
-          @node.text
+          texts = @node.nodes.map do |e|
+            case e
+            when ::Ox::CData
+              e.value
+            when ::String
+              e
+            end
+          end
+
+          texts.compact.first
         end
       end
     end