shale 0.4.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26877841702bfce542b42206f519ffd1b03e2f0d3db1e70a42e37836ff0f3bff
-  data.tar.gz: 23fddba7256bc38b5d64309cf56833f47fd636ed0e9f6ec61f2a076764dad2bb
+  metadata.gz: 5f3c860cf358f78476f8f22a86006694c3d9fd6cb554c945d7364bbf8bb70815
+  data.tar.gz: 5eba158f49fdcfb3012f2e4dcf804fdc4c8fe1e0c37e8e3dbb37972aa469c8bb
 SHA512:
-  metadata.gz: e98bd0bbb20fbbaf4a8bdbfb5e2f83ba5d7bae78ad66a8597a1fe28c0c13d9799bc3ade785105ea7261147f55590ff530e85c31da459fe8c9171ee5b68f02977
-  data.tar.gz: 54be0efe36f4d330c551f1bd8994a36b360ecec3696aafe12382408a0656e50a181b91ff54ec9f39758908d15fcf51eafc4810540cd1aeb00bda7b552382bc80
+  metadata.gz: b002a6837137fa024788e50b2b408ebd7d80f1fd73c7bf1182a2d0b0ab784a07cbda08147af703c4ded76efcb086958049c3d82573e5f885d1b1745f9312eb0c
+  data.tar.gz: e66ba2657a540ad6e9cebd98cf4a61a9ae4b31c0fc6ba1e8085493cc727eda48e2cb87515d399a2524cac8bb4d92932f57dd548afa2ba1d8fb5b97bb5c8ef1a7

data/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [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
+- Allow to generate Shale model from XML Schema
+
+### Changed
+- Shale doesn't defaults to REXML anymore - XML adapter needs to be set explicitly
+- Rename "JSONSchemaError" to "SchemaError"
+- Rename "Composite" type to "Complex"
+- Drop support for Ruby 2.6
+
 ## [0.4.0] - 2022-05-30
 
 ### 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,21 +1,23 @@
 # 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 Schema into Ruby models
-* Out of the box support for JSON, YAML, Nokogiri, REXML and Ox parsers
+* Compile JSON and XML Schema into Ruby models
+* 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.6+
+Shale supports Ruby (MRI) 2.7+
 
 Add this line to your application's Gemfile:
 
@@ -43,28 +45,32 @@ $ 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)
 * [Generating JSON Schema](#generating-json-schema)
 * [Compiling JSON Schema into Shale model](#compiling-json-schema-into-shale-model)
 * [Generating XML Schema](#generating-xml-schema)
+* [Compiling XML Schema into Shale model](#compiling-xml-schema-into-shale-model)
 
 ## Usage
 
-Documentation with interactive examples is available at [Shale website](https://www.shalerb.org)
-
 ### Simple use case
 
 ```ruby
@@ -194,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
@@ -230,6 +295,17 @@ person.to_hash
 
 ### Converting XML to object
 
+To use XML with Shale you have to set adapter you want to use.
+Shale comes with adapters for REXML, Nokogiri and OX parsers.
+For details see [Adapters](#adapters) section.
+
+```ruby
+require 'shale/adapter/rexml'
+Shale.xml_adapter = Shale::Adapter::REXML
+```
+
+Now you can use XML with Shale:
+
 ```ruby
 person = Person.from_xml(<<~DATA)
 <person>
@@ -274,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
@@ -300,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
@@ -370,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
@@ -436,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,
@@ -459,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)
@@ -519,7 +688,7 @@ person = Person.from_xml(<<~DATA)
     <Street>Oxford Street</Street>
     <City>London</City>
   </Address>
-</person>
+</Person>
 DATA
 
 # =>
@@ -530,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:
 
-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)
+```
+
+### 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)
 
 # =>
 #
@@ -547,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)
 
 # =>
 #
@@ -560,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:
@@ -588,10 +906,9 @@ end
 ### Adapters
 
 Shale uses adapters for parsing and generating documents.
-By default Ruby's standard JSON parser is used for handling JSON documents, YAML for YAML and
-REXML for XML.
+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
@@ -602,6 +919,22 @@ 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:
 
 :warning: **Ox doesn't support XML namespaces**
@@ -609,7 +942,7 @@ Shale provides adapters for most popular Ruby XML parsers:
 ```ruby
 require 'shale'
 
-# REXML is used by default:
+# if you want to use REXML:
 
 require 'shale/adapter/rexml'
 Shale.xml_adapter = Shale::Adapter::REXML
@@ -842,6 +1175,82 @@ end
 Shale::Schema::XMLGenerator.register_xml_type(MyEmailType, 'myEmailXMLType')
 ```
 
+### Compiling XML Schema into Shale model
+
+To generate Shale data model from XML Schema use:
+
+```ruby
+require 'shale/schema'
+
+schema = <<~SCHEMA
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Person" type="Person" />
+
+  <xs:complexType name="Person">
+    <xs:sequence>
+      <xs:element name="FirstName" type="xs:string" />
+      <xs:element name="LastName" type="xs:string" />
+      <xs:element name="Address" type="Address" />
+    </xs:sequence>
+  </xs:complexType>
+
+  <xs:complexType name="Address">
+    <xs:sequence>
+      <xs:element name="Street" type="xs:string" />
+      <xs:element name="City" type="xs:string" />
+    </xs:sequence>
+  </xs:complexType>
+</xs:schema>
+SCHEMA
+
+Shale::Schema.from_xml([schema])
+
+# =>
+#
+# {
+#   "address" => "
+#     require 'shale'
+#
+#     class Address < Shale::Mapper
+#       attribute :street, Shale::Type::String
+#       attribute :city, Shale::Type::String
+#
+#       xml do
+#         root 'Address'
+#
+#         map_element 'Street', to: :street
+#         map_element 'City', to: :city
+#       end
+#     end
+#   ",
+#   "person" => "
+#     require 'shale'
+#
+#     require_relative 'address'
+#
+#     class Person < Shale::Mapper
+#       attribute :first_name, Shale::Type::String
+#       attribute :last_name, Shale::Type::String
+#       attribute :address, Address
+#
+#       xml do
+#         root 'Person'
+#
+#         map_element 'FirstName', to: :first_name
+#         map_element 'LastName', to: :last_name
+#         map_element 'Address', to: :address
+#       end
+#     end
+#   "
+# }
+```
+
+You can also use a command line tool to do it:
+
+```
+$ shaleb -c -f xml -i schema.xml
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kgiszczak/shale.