shale 0.3.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36678c1f4afd6e0cf2d6a9a9e4b5becebf11e76404cb50dba7dc5269b5ca42cc
-  data.tar.gz: 51c6c94abafe1767c579c270e3c3cb4da2ca79a2a29a9d28ea6bfe09bc4b53fb
+  metadata.gz: 243b99a073ac189f66ae0fbfedd94a5715399de731d0e0fd1d970dad749d27a0
+  data.tar.gz: d2f57de2427574d710d6a6fe9ba35868fd162214ce8aa2092ddfb3fe1f5e7c3d
 SHA512:
-  metadata.gz: ea21dff00b6ea2663d20f9f377140250f78c29214a93f226047fe29d47680ae526652010ae268e4cf694ca1877cd8d19bfe8f0bbd767fa871fa80afaefee1c83
-  data.tar.gz: 414d45b7bcd2477bc276eee17c598efba40350e0234c32f783c73217bee65ae4260d07e8a7bcfc7f48e1f76c9af4852de1c1c109c5b807e99a945305e2de6286
+  metadata.gz: 9de1be5eccbb647f05b6573d783491f858fb56614f09c7c625e7fa922c7b89b5d38863a57defbe506d42f0b542b326e4ca61ecf308b94f7b35b4056751e0299e
+  data.tar.gz: a1e29fc097c130c55e45837af198e3cd4f7d3ad6a94b17d032eb31b8065f7ea013682836256d12127480965ed3733079e5badd7a8b0060e3bc60f00734fcc215

data/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [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
+- Allow to add title to JSON Schema
+- Map Shale::Type::Value to "anyType" XML Schema type
+- Map Shale::Type::Value to "any" JSON Schema type
+- Allow to generate Shale model from JSON Schema
+
+### Changed
+- Performance improvements
+- Reformat README a little bit and fix typos
+
+### Fixed
+- Fix stack overflow caused by circular dependency when generating JSON and XML schemas
+
 ## [0.3.1] - 2022-04-29
 
 ### Changed

data/README.md

@@ -1,10 +1,23 @@
 # Shale
 
-Shale is a object mapper and serializer for JSON, YAML and 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, 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, 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:
 
@@ -32,27 +45,31 @@ $ 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)
 * [Using methods to extract and generate data](#using-methods-to-extract-and-generate-data)
 * [Pretty printing and XML declaration](#pretty-printing-and-xml-declaration)
+* [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
@@ -126,6 +143,7 @@ DATA
 
 ```ruby
 person.to_json
+
 # =>
 #
 # {
@@ -164,6 +182,63 @@ DATA
 
 ```ruby
 person.to_yaml
+
+# =>
+#
+# ---
+# first_name: John
+# last_name: Doe
+# age: 50
+# married: false
+# hobbies:
+# - Singing
+# - Dancing
+# address:
+#   city: London
+#   street: Oxford Street
+#   zip: E1 6AN
+```
+
+### 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).
+For details see [Adapters](#adapters) section.
+
+To set it, first make sure toml-rb gem is installed:
+
+```
+$ gem install shale
+```
+
+then setup adapter:
+
+```ruby
+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
+
 # =>
 #
 # ---
@@ -201,6 +276,7 @@ person = Person.from_hash(
 
 ```ruby
 person.to_hash
+
 # =>
 #
 # {
@@ -215,6 +291,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>
@@ -237,6 +324,7 @@ DATA
 
 ```ruby
 person.to_xml
+
 # =>
 #
 # <person>
@@ -256,7 +344,9 @@ person.to_xml
 
 ### Mapping JSON keys to object attributes
 
-By default keys are named the same as attributes. To use custom key names use:
+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
@@ -284,6 +374,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
@@ -300,7 +404,7 @@ end
 
 ### Mapping XML elements and attributes to object attributes
 
-XML is more complcated format than JSON or YAML. To map elements, attributes and content use:
+XML is more complicated format than JSON or YAML. To map elements, attributes and content use:
 
 ```ruby
 class Address < Shale::Mapper
@@ -354,9 +458,38 @@ DATA
 - `map_attribute` - map element's attribute to attribute
 - `map_content` - map first text node to attribute
 
-### Using XML namespaces
+You can use `cdata: true` option on `map_element` and `map_content` to handle CDATA nodes:
 
-:warning: **Ox doesn't support XML namespaces**
+```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
 `map_element` and `map_attribute`
@@ -385,7 +518,7 @@ DATA
 ```
 
 To define default namespace for all elements use `namespace` declaration
-(this will define namespace only on elements, if you want to define namespace on an attribute
+(this will define namespace on elements only, if you want to define namespace on an attribute
 explicitly declare it on `map_attribute`).
 
 ```ruby
@@ -445,42 +578,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)
+    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)
+    { '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)
@@ -505,7 +638,7 @@ person = Person.from_xml(<<~DATA)
     <Street>Oxford Street</Street>
     <City>London</City>
   </Address>
-</person>
+</Person>
 DATA
 
 # =>
@@ -546,6 +679,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)
+
+# =>
+#
+# {
+#   "first_name": "John",
+#   "last_name": "Doe",
+#   "address": {
+#     "street": "Oxford Street",
+#     "city": "London"
+#   }
+# }
+```
+
 ### Supported types
 
 Shale supports these types out of the box:
@@ -574,10 +768,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
@@ -588,12 +781,25 @@ 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:
+
+```ruby
+require 'shale'
+
+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**
+
 ```ruby
 require 'shale'
 
-# REXML is used by default:
+# if you want to use REXML:
 
 require 'shale/adapter/rexml'
 Shale.xml_adapter = Shale::Adapter::REXML
@@ -611,14 +817,19 @@ Shale.xml_adapter = Shale::Adapter::Ox
 
 ### Generating JSON Schema
 
-To generate JSON Schema from you Shale data model use:
+:warning: Only **[Draft 2020-12](https://json-schema.org/draft/2020-12/schema)** JSON Schema is supported
 
-:warning: Shale only supports **[Draft 2020-12](https://json-schema.org/draft/2020-12/schema)** JSON Schema
+To generate JSON Schema from your Shale data model use:
 
 ```ruby
 require 'shale/schema'
 
-Shale::Schema.to_json(Person, id: 'http://foo.bar/schema/person', description: 'My description', pretty: true)
+Shale::Schema.to_json(
+  Person,
+  id: 'http://foo.bar/schema/person',
+  description: 'My description',
+  pretty: true
+)
 
 # =>
 #
@@ -663,7 +874,7 @@ Shale::Schema.to_json(Person, id: 'http://foo.bar/schema/person', description: '
 You can also use a command line tool to do it:
 
 ```
-$ shaleb -i data_model.rb -c Person -p
+$ shaleb -i data_model.rb -r Person -p
 ```
 
 If you want to convert your own types to JSON Schema types use:
@@ -676,13 +887,83 @@ class MyEmailType < Shale::Type::Value
   ...
 end
 
-class MyEmailJSONType < Shale::Schema::JSON::Base
+class MyEmailJSONType < Shale::Schema::JSONGenerator::Base
   def as_type
     { 'type' => 'string', 'format' => 'email' }
   end
 end
 
-Shale::Schema::JSON.register_json_type(MyEmailType, MyEmailJSONType)
+Shale::Schema::JSONGenerator.register_json_type(MyEmailType, MyEmailJSONType)
+```
+
+### Compiling JSON Schema into Shale model
+
+:warning: Only **[Draft 2020-12](https://json-schema.org/draft/2020-12/schema)** JSON Schema is supported
+
+To generate Shale data model from JSON Schema use:
+
+```ruby
+require 'shale/schema'
+
+schema = <<~SCHEMA
+{
+  "type": "object",
+  "properties": {
+    "firstName": { "type": "string" },
+    "lastName": { "type": "string" },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    }
+  }
+}
+SCHEMA
+
+Shale::Schema.from_json([schema], root_name: 'Person')
+
+# =>
+#
+# {
+#   "address" => "
+#     require 'shale'
+#
+#     class Address < Shale::Mapper
+#       attribute :street, Shale::Type::String
+#       attribute :city, Shale::Type::String
+#
+#       json do
+#         map 'street', to: :street
+#         map '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
+#
+#       json do
+#         map 'firstName', to: :first_name
+#         map 'lastName', to: :last_name
+#         map 'address', to: :address
+#       end
+#     end
+#   "
+# }
+```
+
+You can also use a command line tool to do it:
+
+```
+$ shaleb -c -i schema.json -r Person
 ```
 
 ### Generating XML Schema
@@ -735,7 +1016,7 @@ Shale::Schema.to_xml(Person, pretty: true)
 You can also use a command line tool to do it:
 
 ```
-$ shaleb -i data_model.rb -c Person -p -f xml
+$ shaleb -i data_model.rb -r Person -p -f xml
 ```
 
 If you want to convert your own types to XML Schema types use:
@@ -748,7 +1029,83 @@ class MyEmailType < Shale::Type::Value
   ...
 end
 
-Shale::Schema::XML.register_xml_type(MyEmailType, 'myEmailXMLType')
+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