shale 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243b99a073ac189f66ae0fbfedd94a5715399de731d0e0fd1d970dad749d27a0
-  data.tar.gz: d2f57de2427574d710d6a6fe9ba35868fd162214ce8aa2092ddfb3fe1f5e7c3d
+  metadata.gz: 76c0022b3d2d42be143362c84c6697628781acdce7694fb9bc0f305d3f854964
+  data.tar.gz: 0b0b1b060eab81ebfae80afa3c31c809280b66ebd77e413c5908c4bbd09a081a
 SHA512:
-  metadata.gz: 9de1be5eccbb647f05b6573d783491f858fb56614f09c7c625e7fa922c7b89b5d38863a57defbe506d42f0b542b326e4ca61ecf308b94f7b35b4056751e0299e
-  data.tar.gz: a1e29fc097c130c55e45837af198e3cd4f7d3ad6a94b17d032eb31b8065f7ea013682836256d12127480965ed3733079e5badd7a8b0060e3bc60f00734fcc215
+  metadata.gz: 43bc9188d1f07c5c367a8ed94e2a3da6b878a7b7b86773d7898697abbd3937d4de6ae0471f9362c72e8a6be2cc5e5100a5206b2f2cc7155ff2ff8784953ef702
+  data.tar.gz: 0e610703cc73809a78007785962d9a322e515b88ab143a55adfeaa1a0da5961f14d8768a3dec4ad797070bbab165c238123702cbc671f522f86e2934968ff78b

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [0.8.0] - 2022-08-30
+
+### Added
+- Allow to group mappings using `group` block
+- Bring back Ruby 2.6 support
+
+### Changed
+- Use anonymous module for attributes definition.
+  It allows to override accessors and `super` works as expected.
+
+## [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

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

@@ -12,12 +12,12 @@ Documentation with interactive examples is available at [Shale website](https://
 * 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, toml-rb, 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
 
-Shale supports Ruby (MRI) 2.7+
+Shale supports Ruby (MRI) 2.6+
 
 Add this line to your application's Gemfile:
 
@@ -57,8 +57,9 @@ $ gem install shale
 * [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)
@@ -202,18 +203,23 @@ person.to_yaml
 ### Converting TOML to object
 
 To use TOML with Shale you have to set adapter you want to use.
-Shale comes with adapter for [toml-rb](https://github.com/emancu/toml-rb).
+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 toml-rb gem is installed:
+To set it, first make sure Tomlib gem is installed:
 
 ```
-$ gem install shale
+$ 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
 ```
@@ -241,18 +247,16 @@ 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
+# 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
@@ -555,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,
@@ -582,8 +632,8 @@ class Person < Shale::Mapper
     model.hobbies = value.split(',').map(&:strip)
   end
 
-  def hobbies_to_json(model)
-    model.hobbies.join(', ')
+  def hobbies_to_json(model, doc)
+    doc['hobbies'] = model.hobbies.join(', ')
   end
 
   def address_from_json(model, value)
@@ -591,8 +641,8 @@ class Person < Shale::Mapper
     model.city = value['city']
   end
 
-  def address_to_json(model)
-    { 'street' => model.street, 'city' => model.city }
+  def address_to_json(model, doc)
+    doc['address'] = { 'street' => model.street, 'city' => model.city }
   end
 
   def hobbies_from_xml(model, value)
@@ -649,12 +699,149 @@ DATA
 #  @city="London">
 ```
 
-### Pretty printing and XML declaration
+You can also pass a `context` object that will be available in extractor/generator methods:
 
-If you need formatted output you can pass `:pretty` parameter to `#to_json` and `#to_xml`
+```ruby
+class Person < Shale::Mapper
+  attribute :password, Shale::Type::String
+
+  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)
+```
+
+If you want to work on multiple elements at a time you can group them using `group` block:
 
 ```ruby
-person.to_json(:pretty)
+class Person < Shale::Mapper
+  attribute :name, Shale::Type::String
+
+  json do
+    group from: :name_from_json, to: :name_to_json do
+      map 'first_name'
+      map 'last_name'
+    end
+  end
+
+  xml do
+    group from: :name_from_xml, to: :name_to_xml do
+      map_content
+      map_element 'first_name'
+      map_attribute 'last_name'
+    end
+  end
+
+  def name_from_json(model, value)
+    model.name = "#{value['first_name']} #{value['last_name']}"
+  end
+
+  def name_to_json(model, doc)
+    doc['first_name'] = model.name.split(' ')[0]
+    doc['last_name'] = model.name.split(' ')[1]
+  end
+
+  def name_from_xml(model, value)
+    # value => { content: ..., attributes: {}, elements: {} }
+  end
+
+  def name_to_xml(model, element, doc)
+    # ...
+  end
+end
+
+Person.from_json(<<~DATA)
+{
+  "first_name": "John",
+  "last_name": "Doe"
+}
+DATA
+
+# => #<Person:0x00007f9bc3086d60 @name="John Doe">
+```
+
+### Additional options
+
+You can control which attributes to render and parse by
+using `only: []` and `except: []` parameters.
+
+```ruby
+# 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)
 
 # =>
 #
@@ -666,10 +853,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)
 
 # =>
 #
@@ -726,7 +913,7 @@ DATA
 #  @last_name="Doe",
 #  @address=#<Address:0x0000000113d7a140 @street="Oxford Street", @city="London">>
 
-PersonMapper.to_json(person, :pretty)
+PersonMapper.to_json(person, pretty: true)
 
 # =>
 #
@@ -781,12 +968,17 @@ Shale.json_adapter = MultiJson
 Shale.yaml_adapter = MyYamlAdapter
 ```
 
-To handle TOML documents you have to set TOML adapter.
-Shale provides adapter for `toml-rb` TOML parser:
+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
 ```

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.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.rb

@@ -30,19 +30,20 @@ module Shale
       # Serialize Ox document into XML
       #
       # @param [::Ox::Document, ::Ox::Element] doc Ox 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)
         opts = { indent: -1, with_xml: false }
 
-        if options.include?(:pretty)
+        if pretty
           opts[:indent] = 2
         end
 
-        if options.include?(:declaration)
+        if declaration
           doc[:version] = '1.0'
           opts[:with_xml] = true
         end

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

@@ -70,7 +70,7 @@ module Shale
         #
         # @api private
         def add_attribute(element, name, value)
-          element.add_attribute(name, value)
+          element.add_attribute(name, value || '')
         end
 
         # Add child element to REXML element

data/lib/shale/adapter/rexml.rb

@@ -31,19 +31,20 @@ module Shale
       # Serialize REXML document into XML
       #
       # @param [::REXML::Document] doc REXML document
-      # @param [Array<Symbol>] options
+      # @param [true, false] pretty
+      # @param [true, false] declaration
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc, *options)
-        if options.include?(:declaration)
+      def self.dump(doc, pretty: false, declaration: false)
+        if declaration
           doc.add(::REXML::XMLDecl.new)
         end
 
         io = StringIO.new
 
-        if options.include?(:pretty)
+        if pretty
           formatter = ::REXML::Formatters::Pretty.new
           formatter.compact = true
         else

data/lib/shale/error.rb

@@ -7,6 +7,11 @@ module Shale
     TOML Adapter is not set.
     To use Shale with TOML documents you have to install parser and set adapter.
 
+    # To use Tomlib:
+    # Make sure tomlib is installed eg. execute: gem install tomlib
+    Shale.toml_adapter = Tomlib
+
+    # To use toml-rb:
     # Make sure toml-rb is installed eg. execute: gem install toml-rb
     require 'shale/adapter/toml_rb'
     Shale.toml_adapter = Shale::Adapter::TomlRB
@@ -18,16 +23,16 @@ module Shale
     XML Adapter is not set.
     To use Shale with XML documents you have to install parser and set adapter.
 
-    To use REXML:
+    # To use REXML:
     require 'shale/adapter/rexml'
     Shale.xml_adapter = Shale::Adapter::REXML
 
-    To use Nokogiri:
+    # To use Nokogiri:
     # Make sure Nokogiri is installed eg. execute: gem install nokogiri
     require 'shale/adapter/nokogiri'
     Shale.xml_adapter = Shale::Adapter::Nokogiri
 
-    To use OX:
+    # To use OX:
     # Make sure Ox is installed eg. execute: gem install ox
     require 'shale/adapter/ox'
     Shale.xml_adapter = Shale::Adapter::Ox

data/lib/shale/mapper.rb

@@ -98,6 +98,10 @@ module Shale
       def inherited(subclass)
         super
 
+        attributes_module = Module.new
+        subclass.instance_variable_set('@attributes_module', attributes_module)
+        subclass.include(attributes_module)
+
         subclass.instance_variable_set('@model', subclass)
         subclass.instance_variable_set('@attributes', @attributes.dup)
 
@@ -171,7 +175,7 @@ module Shale
         @toml_mapping.map(name.to_s, to: name) unless @toml_mapping.finalized?
         @xml_mapping.map_element(name.to_s, to: name) unless @xml_mapping.finalized?
 
-        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+        @attributes_module.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
           attr_reader :#{name}
 
           def #{name}=(val)

data/lib/shale/mapping/descriptor/dict.rb

@@ -35,22 +35,42 @@ module Shale
         # @api private
         attr_reader :method_to
 
+        # Return group name
+        #
+        # @return [String]
+        #
+        # @api private
+        attr_reader :group
+
         # Initialize instance
         #
         # @param [String] name
         # @param [Symbol, nil] attribute
         # @param [Hash, nil] methods
+        # @param [String, nil] group
+        # @param [true, false] render_nil
         #
         # @api private
-        def initialize(name:, attribute:, methods:)
+        def initialize(name:, attribute:, methods:, group:, render_nil:)
           @name = name
           @attribute = attribute
+          @group = group
+          @render_nil = render_nil
 
           if methods
             @method_from = methods[:from]
             @method_to = methods[:to]
           end
         end
+
+        # Check render_nil
+        #
+        # @return [true, false]
+        #
+        # @api private
+        def render_nil?
+          @render_nil == true
+        end
       end
     end
   end

data/lib/shale/mapping/descriptor/xml.rb

@@ -28,12 +28,21 @@ module Shale
         # @param [String] name
         # @param [Symbol, String] attribute
         # @param [Hash, nil] methods
+        # @param [String, nil] group
         # @param [Shale::Mapping::XmlNamespace] namespace
         # @param [true, false] cdata
+        # @param [true, false] render_nil
         #
         # @api private
-        def initialize(name:, attribute:, methods:, namespace:, cdata:)
-          super(name: name, attribute: attribute, methods: methods)
+        def initialize(name:, attribute:, methods:, group:, namespace:, cdata:, render_nil:)
+          super(
+            name: name,
+            attribute: attribute,
+            methods: methods,
+            group: group,
+            render_nil: render_nil
+          )
+
           @namespace = namespace
           @cdata = cdata
         end
@@ -46,6 +55,15 @@ module Shale
         def prefixed_name
           [namespace.prefix, name].compact.join(':')
         end
+
+        # Return name with XML namespace
+        #
+        # @return [String]
+        #
+        # @api private
+        def namespaced_name
+          [namespace.name, name].compact.join(':')
+        end
       end
     end
   end