shale 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243b99a073ac189f66ae0fbfedd94a5715399de731d0e0fd1d970dad749d27a0
-  data.tar.gz: d2f57de2427574d710d6a6fe9ba35868fd162214ce8aa2092ddfb3fe1f5e7c3d
+  metadata.gz: 5f3c860cf358f78476f8f22a86006694c3d9fd6cb554c945d7364bbf8bb70815
+  data.tar.gz: 5eba158f49fdcfb3012f2e4dcf804fdc4c8fe1e0c37e8e3dbb37972aa469c8bb
 SHA512:
-  metadata.gz: 9de1be5eccbb647f05b6573d783491f858fb56614f09c7c625e7fa922c7b89b5d38863a57defbe506d42f0b542b326e4ca61ecf308b94f7b35b4056751e0299e
-  data.tar.gz: a1e29fc097c130c55e45837af198e3cd4f7d3ad6a94b17d032eb31b8065f7ea013682836256d12127480965ed3733079e5badd7a8b0060e3bc60f00734fcc215
+  metadata.gz: b002a6837137fa024788e50b2b408ebd7d80f1fd73c7bf1182a2d0b0ab784a07cbda08147af703c4ded76efcb086958049c3d82573e5f885d1b1745f9312eb0c
+  data.tar.gz: e66ba2657a540ad6e9cebd98cf4a61a9ae4b31c0fc6ba1e8085493cc727eda48e2cb87515d399a2524cac8bb4d92932f57dd548afa2ba1d8fb5b97bb5c8ef1a7

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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,7 +12,7 @@ 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
@@ -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,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)
 
 # =>
 #
@@ -666,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)
 
 # =>
 #
@@ -726,7 +864,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 +919,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/mapping/descriptor/dict.rb

@@ -40,17 +40,28 @@ module Shale
         # @param [String] name
         # @param [Symbol, nil] attribute
         # @param [Hash, nil] methods
+        # @param [true, false] render_nil
         #
         # @api private
-        def initialize(name:, attribute:, methods:)
+        def initialize(name:, attribute:, methods:, render_nil:)
           @name = name
           @attribute = attribute
+          @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

@@ -30,10 +30,11 @@ module Shale
         # @param [Hash, nil] methods
         # @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:, namespace:, cdata:, render_nil:)
+          super(name: name, attribute: attribute, methods: methods, render_nil: render_nil)
           @namespace = namespace
           @cdata = cdata
         end

data/lib/shale/mapping/dict.rb

@@ -30,13 +30,19 @@ module Shale
       # @param [String] key Document's key
       # @param [Symbol, nil] to Object's attribute
       # @param [Hash, nil] using
+      # @param [true, false] render_nil
       #
       # @raise [IncorrectMappingArgumentsError] when arguments are incorrect
       #
       # @api private
-      def map(key, to: nil, using: nil)
+      def map(key, to: nil, using: nil, render_nil: false)
         Validator.validate_arguments(key, to, using)
-        @keys[key] = Descriptor::Dict.new(name: key, attribute: to, methods: using)
+        @keys[key] = Descriptor::Dict.new(
+          name: key,
+          attribute: to,
+          methods: using,
+          render_nil: render_nil
+        )
       end
 
       # Set the "finalized" instance variable to true

data/lib/shale/mapping/xml.rb

@@ -83,7 +83,8 @@ module Shale
         using: nil,
         namespace: :undefined,
         prefix: :undefined,
-        cdata: false
+        cdata: false,
+        render_nil: false
       )
         Validator.validate_arguments(element, to, using)
         Validator.validate_namespace(element, namespace, prefix)
@@ -103,7 +104,8 @@ module Shale
           attribute: to,
           methods: using,
           namespace: Descriptor::XmlNamespace.new(nsp, pfx),
-          cdata: cdata
+          cdata: cdata,
+          render_nil: render_nil
         )
       end
 
@@ -118,7 +120,14 @@ module Shale
       # @raise [IncorrectMappingArgumentsError] when arguments are incorrect
       #
       # @api private
-      def map_attribute(attribute, to: nil, using: nil, namespace: nil, prefix: nil)
+      def map_attribute(
+        attribute,
+        to: nil,
+        using: nil,
+        namespace: nil,
+        prefix: nil,
+        render_nil: false
+      )
         Validator.validate_arguments(attribute, to, using)
         Validator.validate_namespace(attribute, namespace, prefix)
 
@@ -129,7 +138,8 @@ module Shale
           attribute: to,
           methods: using,
           namespace: Descriptor::XmlNamespace.new(namespace, prefix),
-          cdata: false
+          cdata: false,
+          render_nil: render_nil
         )
       end
 
@@ -146,7 +156,8 @@ module Shale
           attribute: to,
           methods: using,
           namespace: nil,
-          cdata: cdata
+          cdata: cdata,
+          render_nil: false
         )
       end
 

data/lib/shale/schema/json_generator.rb

@@ -124,9 +124,7 @@ module Shale
       # @api public
       def to_schema(klass, id: nil, title: nil, description: nil, pretty: false)
         schema = as_schema(klass, id: id, title: title, description: description)
-        options = pretty ? :pretty : nil
-
-        Shale.json_adapter.dump(schema, options)
+        Shale.json_adapter.dump(schema, pretty: pretty)
       end
 
       private

data/lib/shale/schema/xml_generator/import.rb

@@ -35,8 +35,8 @@ module Shale
         def as_xml(doc)
           import = doc.create_element('xs:import')
 
-          doc.add_attribute(import, 'namespace', @namespace)
-          doc.add_attribute(import, 'schemaLocation', @location)
+          doc.add_attribute(import, 'namespace', @namespace) if @namespace
+          doc.add_attribute(import, 'schemaLocation', @location) if @location
 
           import
         end

data/lib/shale/schema/xml_generator.rb

@@ -222,13 +222,11 @@ module Shale
       def to_schemas(klass, base_name = nil, pretty: false, declaration: false)
         schemas = as_schemas(klass, base_name)
 
-        options = [
-          pretty ? :pretty : nil,
-          declaration ? :declaration : nil,
-        ]
-
         schemas.to_h do |schema|
-          [schema.name, Shale.xml_adapter.dump(schema.as_xml, *options)]
+          [
+            schema.name,
+            Shale.xml_adapter.dump(schema.as_xml, pretty: pretty, declaration: declaration),
+          ]
         end
       end