shale 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5907ba25342167fa8079e683c671f83f89b51777d0b27e8d0126ba404304c2bd
-  data.tar.gz: d88f5acb763a1aaa5f3ceff194613df16377107035cf2c5528bbda593a70b6fa
+  metadata.gz: 26877841702bfce542b42206f519ffd1b03e2f0d3db1e70a42e37836ff0f3bff
+  data.tar.gz: 23fddba7256bc38b5d64309cf56833f47fd636ed0e9f6ec61f2a076764dad2bb
 SHA512:
-  metadata.gz: 967646fcc21c1735acc67ad67b467013dae4da76c2e7cfc3a863b8bc811ae3fcee73cc3a99e1344ab0ea38ef03fed181ba14286666afc6e965399c8929de045a
-  data.tar.gz: bebfbda2bb8fab102ae8b70506cd3fad3e1b178c02ed0486576d2fb26ef5a98ac45a0f62d410888e95b40d9a21ace32c76da36e2a75151ce104c4764a98b1b68
+  metadata.gz: e98bd0bbb20fbbaf4a8bdbfb5e2f83ba5d7bae78ad66a8597a1fe28c0c13d9799bc3ade785105ea7261147f55590ff530e85c31da459fe8c9171ee5b68f02977
+  data.tar.gz: 54be0efe36f4d330c551f1bd8994a36b360ecec3696aafe12382408a0656e50a181b91ff54ec9f39758908d15fcf51eafc4810540cd1aeb00bda7b552382bc80

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [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
+- Rename `id` -> `$id` and add info about supported JSON Schema dialect
+
+## [0.3.0] - 2022-04-29
+
+### Added
+- Support for XML namespaces
+- Add option to pretty print JSON and XML and to include XML declaration
+- Add support for generating JSON and XML Schema
+
+### Changed
+- Various fixes to documentation
+- Rename `hash` -> `hsh` (`hash` is used internally by Ruby)
+- Rename `Shale::Type::Base` -> `Shale::Type::Value`
+- Use ISO 8601 format for date and time in JSON, YAML and XML
+
 ## [0.2.2] - 2022-03-06
 
 ### Fixed

data/README.md

@@ -1,6 +1,17 @@
 # Shale
 
-Shale is a object mapper and serializer for JSON, YAML and XML.
+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.
+
+## Features
+
+* Convert JSON, YAML and XML to Ruby data model
+* Convert Ruby data model to JSON, YAML 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
+* Support for custom adapters
 
 ## Installation
 
@@ -24,8 +35,36 @@ Or install it yourself as:
 $ gem install shale
 ```
 
+## Contents
+
+* [Simple use case](#user-content-simple-use-case)
+* [Creating objects](#creating-objects)
+* [Converting JSON to object](#converting-json-to-object)
+* [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 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 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)
+* [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)
+
 ## Usage
 
+Documentation with interactive examples is available at [Shale website](https://www.shalerb.org)
+
 ### Simple use case
 
 ```ruby
@@ -99,6 +138,7 @@ DATA
 
 ```ruby
 person.to_json
+
 # =>
 #
 # {
@@ -137,6 +177,7 @@ DATA
 
 ```ruby
 person.to_yaml
+
 # =>
 #
 # ---
@@ -174,6 +215,7 @@ person = Person.from_hash(
 
 ```ruby
 person.to_hash
+
 # =>
 #
 # {
@@ -210,6 +252,7 @@ DATA
 
 ```ruby
 person.to_xml
+
 # =>
 #
 # <person>
@@ -229,7 +272,7 @@ 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:
 
 ```ruby
 class Person < Shale::Mapper
@@ -264,7 +307,7 @@ class Person < Shale::Mapper
   attribute :first_name, Shale::Type::String
   attribute :last_name, Shale::Type::String
 
-  hash do
+  hsh do
     map 'firstName', to: :first_name
     map 'lastName', to: :last_name
   end
@@ -273,7 +316,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
@@ -327,6 +370,72 @@ DATA
 - `map_attribute` - map element's attribute to attribute
 - `map_content` - map first text node to attribute
 
+### Using XML namespaces
+
+To map namespaced elements and attributes use `namespace` and `prefix` properties on
+`map_element` and `map_attribute`
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :age, Shale::Type::Integer
+
+  xml do
+    root 'person'
+
+    map_element 'first_name', to: :first_name, namespace: 'http://ns1.com', prefix: 'ns1'
+    map_element 'last_name', to: :last_name, namespace: 'http://ns2.com', prefix: 'ns2'
+    map_attribute 'age', to: :age, namespace: 'http://ns2.com', prefix: 'ns2'
+  end
+end
+
+person = Person.from_xml(<<~DATA)
+<person xmlns:ns1="http://ns1.com" xmlns:ns2="http://ns2.com" ns2:age="50">
+  <ns1:first_name>John</ns1:first_name>
+  <ns2:last_name>Doe</ns2:last_name>
+</person>
+DATA
+```
+
+To define default namespace for all elements use `namespace` declaration
+(this will define namespace on elements only, if you want to define namespace on an attribute
+explicitly declare it on `map_attribute`).
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :middle_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :age, Shale::Type::Integer
+  attribute :hobby, Shale::Type::String
+
+  xml do
+    root 'person'
+    namespace 'http://ns1.com', 'ns1'
+
+    map_element 'first_name', to: :first_name
+
+    # undeclare namespace on 'middle_name' element
+    map_element 'middle_name', to: :middle_name, namespace: nil, prefix: nil
+
+    # overwrite default namespace
+    map_element 'last_name', to: :last_name, namespace: 'http://ns2.com', prefix: 'ns2'
+
+    map_attribute 'age', to: :age
+    map_attribute 'hobby', to: :hobby, namespace: 'http://ns1.com', prefix: 'ns1'
+  end
+end
+
+person = Person.from_xml(<<~DATA)
+<ns1:person xmlns:ns1="http://ns1.com" xmlns:ns2="http://ns2.com" age="50" ns1:hobby="running">
+  <ns1:first_name>John</ns1:first_name>
+  <middle_name>Joe</middle_name>
+  <ns2:last_name>Doe</ns2:last_name>
+</ns1:person>
+DATA
+```
+
 ### Using methods to extract and generate data
 
 If you need full controll over extracting and generating data from/to document,
@@ -421,6 +530,36 @@ DATA
 #  @city="London">
 ```
 
+### Pretty printing and XML declaration
+
+If you need formatted output you can pass `:pretty` parameter to `#to_json` and `#to_xml`
+
+```ruby
+person.to_json(:pretty)
+
+# =>
+#
+# {
+#   "name": "John Doe",
+#   "address": {
+#     "city": "London"
+#   }
+# }
+```
+
+You can also add an XML declaration by passing `:declaration` to `#to_xml`
+
+```ruby
+person.to_xml(:pretty, :declaration)
+
+# =>
+#
+# <?xml version="1.0"?>
+# <Person>
+#   <Address city="London"/>
+# </Person>
+```
+
 ### Supported types
 
 Shale supports these types out of the box:
@@ -434,12 +573,12 @@ Shale supports these types out of the box:
 
 ### Writing your own type
 
-To add your own type extend it from `Shale::Type::Base` and implement `.cast` class method.
+To add your own type extend it from `Shale::Type::Value` and implement `.cast` class method.
 
 ```ruby
-require 'shale/type/base'
+require 'shale/type/value'
 
-class MyIntegerType < Shale::Type::Base
+class MyIntegerType < Shale::Type::Value
   def self.cast(value)
     value.to_i
   end
@@ -463,7 +602,9 @@ Shale.json_adapter = MultiJson
 Shale.yaml_adapter = MyYamlAdapter
 ```
 
-For XML, Shale provides adapters for most popular Ruby XML parsers:
+Shale provides adapters for most popular Ruby XML parsers:
+
+:warning: **Ox doesn't support XML namespaces**
 
 ```ruby
 require 'shale'
@@ -484,6 +625,223 @@ require 'shale/adapter/ox'
 Shale.xml_adapter = Shale::Adapter::Ox
 ```
 
+### Generating JSON Schema
+
+:warning: Only **[Draft 2020-12](https://json-schema.org/draft/2020-12/schema)** JSON Schema is supported
+
+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
+)
+
+# =>
+#
+# {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   "$id": "http://foo.bar/schema/person",
+#   "description": "My description",
+#   "$ref": "#/$defs/Person",
+#   "$defs": {
+#     "Address": {
+#       "type": [
+#         "object",
+#         "null"
+#       ],
+#       "properties": {
+#         "city": {
+#           "type": [
+#             "string",
+#             "null"
+#           ]
+#         }
+#       }
+#     },
+#     "Person": {
+#       "type": "object",
+#       "properties": {
+#         "name": {
+#           "type": [
+#             "string",
+#             "null"
+#           ]
+#         },
+#         "address": {
+#           "$ref": "#/$defs/Address"
+#         }
+#       }
+#     }
+#   }
+# }
+```
+
+You can also use a command line tool to do it:
+
+```
+$ shaleb -i data_model.rb -r Person -p
+```
+
+If you want to convert your own types to JSON Schema types use:
+
+```ruby
+require 'shale'
+require 'shale/schema'
+
+class MyEmailType < Shale::Type::Value
+  ...
+end
+
+class MyEmailJSONType < Shale::Schema::JSONGenerator::Base
+  def as_type
+    { 'type' => 'string', 'format' => 'email' }
+  end
+end
+
+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
+
+To generate XML Schema from your Shale data model use:
+
+```ruby
+require 'shale/schema'
+
+Shale::Schema.to_xml(Person, pretty: true)
+
+# =>
+#
+# {
+#   'schema0.xsd' => '
+#     <xs:schema
+#       elementFormDefault="qualified"
+#       attributeFormDefault="qualified"
+#       xmlns:xs="http://www.w3.org/2001/XMLSchema"
+#       xmlns:foo="http://foo.com"
+#     >
+#       <xs:import namespace="http://foo.com" schemaLocation="schema1.xsd"/>
+#       <xs:element name="person" type="Person"/>
+#       <xs:complexType name="Person">
+#         <xs:sequence>
+#           <xs:element name="name" type="xs:string" minOccurs="0"/>
+#           <xs:element ref="foo:address" minOccurs="0"/>
+#         </xs:sequence>
+#       </xs:complexType>
+#     </xs:schema>',
+#
+#   'schema1.xsd' => '
+#     <xs:schema
+#       elementFormDefault="qualified"
+#       attributeFormDefault="qualified"
+#       targetNamespace="http://foo.com"
+#       xmlns:xs="http://www.w3.org/2001/XMLSchema"
+#       xmlns:foo="http://foo.com"
+#     >
+#       <xs:element name="address" type="foo:Address"/>
+#       <xs:complexType name="Address">
+#         <xs:sequence>
+#           <xs:element name="city" type="xs:string" minOccurs="0"/>
+#         </xs:sequence>
+#       </xs:complexType>
+#     </xs:schema>'
+# }
+```
+
+You can also use a command line tool to do it:
+
+```
+$ shaleb -i data_model.rb -r Person -p -f xml
+```
+
+If you want to convert your own types to XML Schema types use:
+
+```ruby
+require 'shale'
+require 'shale/schema'
+
+class MyEmailType < Shale::Type::Value
+  ...
+end
+
+Shale::Schema::XMLGenerator.register_xml_type(MyEmailType, 'myEmailXMLType')
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kgiszczak/shale.

data/exe/shaleb

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'optparse'
+
+base_path = File.expand_path('../lib', __dir__)
+
+if File.exist?(base_path)
+  require_relative '../lib/shale/schema'
+else
+  require 'shale/schema'
+end
+
+params = {}
+
+ARGV << '-h' if ARGV.empty?
+
+OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    Usage: shaleb [options]
+    example generate schema from Shale model: shaleb -g -i data_model.rb -c MyRoot
+    example generate Shale model from schema: shaleb -c -i schema1.json,schema2.json -c MyRoot
+  BANNER
+
+  opts.on('-g', '--generate', 'generate schema from Shale model')
+  opts.on('-c', '--compile', 'compile schema into Shale model')
+  opts.on('-i INPUT', '--input', Array, 'Input file')
+  opts.on('-o OUTPUT', '--output', 'Output (defaults to STDOUT)')
+  opts.on('-r ROOT', '--root ROOT', 'Shale model class name')
+  opts.on('-f FORMAT', '--format FORMAT', 'Schema format: JSON (default), XML')
+  opts.on('-p', '--pretty', 'Pretty print generated schema')
+
+  opts.on('-v', '--version', 'Show version') do
+    puts "shaleb version #{Shale::VERSION}"
+    exit
+  end
+end.parse!(into: params)
+
+if params[:compile]
+  unless params[:input]
+    puts 'Input file is required: shaleb -c -i schema1.json,schema2.json'
+    exit
+  end
+
+  schemas = params[:input].map do |file|
+    path = File.expand_path(file, Dir.pwd)
+
+    if File.exist?(path)
+      File.read(path)
+    else
+      puts "File '#{path}' does not exist"
+      exit
+    end
+  end
+
+  models = Shale::Schema.from_json(schemas, root_name: params[:root])
+
+  if params[:output]
+    dir = File.expand_path(params[:output], Dir.pwd)
+    FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+    models.each do |name, model|
+      output_path = File.join(dir, "#{name}.rb")
+      File.write(output_path, model)
+    end
+  else
+    output = models.map do |name, model|
+      "# --- #{name}.rb ---\n#{model}\n"
+    end.join("\n")
+
+    puts output
+  end
+else
+  unless params[:input]
+    puts 'Input file is required: shaleb -i model.rb -r MyClass'
+    exit
+  end
+
+  input_path = File.expand_path(params[:input][0], Dir.pwd)
+
+  unless File.exist?(input_path)
+    puts "File '#{input_path}' does not exist"
+    exit
+  end
+
+  unless params[:root]
+    puts 'Model class is required: shaleb -i model.rb -r MyClass'
+    exit
+  end
+
+  require input_path
+
+  klass = Object.const_get(params[:root])
+
+  if params[:format] == 'xml'
+    if params[:output]
+      base_name = File.basename(params[:output], File.extname(params[:output]))
+      schemas = Shale::Schema.to_xml(klass, base_name, pretty: params[:pretty])
+
+      schemas.map do |name, xml|
+        File.write(File.expand_path(name, Dir.pwd), xml)
+      end
+    else
+      schemas = Shale::Schema.to_xml(klass, pretty: params[:pretty])
+
+      output = schemas.map do |name, xml|
+        "<!-- #{name} -->\n#{xml}\n"
+      end.join("\n")
+
+      puts output
+    end
+  else
+    schema = Shale::Schema.to_json(klass, pretty: params[:pretty])
+
+    if params[:output]
+      output_path = File.expand_path(params[:output], Dir.pwd)
+      File.write(output_path, schema)
+    else
+      puts schema
+    end
+  end
+end

data/lib/shale/adapter/json.rb

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