shale 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9396e5fcba6ff4e1f1566abe356270ef9ddbd8ce9171063f011feeb36d234e7
-  data.tar.gz: 4495b40dca3e01b6ba908dfc6b7831aea3f1e2865423de59ced69db33ba633b8
+  metadata.gz: aaa3043e612d332fab30ff87ecab722e3812e7769eba982db27c38f74c205ce1
+  data.tar.gz: bb5cdb963bce5756c48edb37d28bddc40a816901e87b4714ea512f07f8ec4c28
 SHA512:
-  metadata.gz: 404737157189f2312b4e189d095899588495c8f80cf52f9bd5935358b2ec8bedbd98b0d7676c44641383109701d62377d3086b36342950d6fd657dbbba2d06b9
-  data.tar.gz: '04818bdcac0290dfd96fbb0ebb1364350a444a9fc0533992d2cdf3bc3443e8afb4f00021346c66610400ddce12b4848c8bbed5c0bfb3835d40438c2b5acc1a6b'
+  metadata.gz: ed1f1ffc88cabb5f9403ff957c02efc4565aee73b9a8a1fd2297ff13bfbb6bdf0e94664b865f8d2d812ddd66fe97d154e34982eea3318ba01c6d16b4a6922c70
+  data.tar.gz: d41392de36bcace9efee12a869f49beffba235ae09e09f33c6973159b96320e3f657a6edd4d634e53da430f8127e74fa1025fa2f5c75dad2e7568abe6a0794ce

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [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
+- Rename `id` -> `$id` and add info about supported JSON Schema dialect
+
 ## [0.3.0] - 2022-04-29
 
 ### Added

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 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.
+
+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
+* Generate JSON and XML Schema from Ruby models
+* Compile JSON and XML Schema into Ruby models
+* Out of the box support for JSON, YAML, 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:
 
@@ -47,12 +60,12 @@ $ gem install shale
 * [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 +139,7 @@ DATA
 
 ```ruby
 person.to_json
+
 # =>
 #
 # {
@@ -164,6 +178,7 @@ DATA
 
 ```ruby
 person.to_yaml
+
 # =>
 #
 # ---
@@ -201,6 +216,7 @@ person = Person.from_hash(
 
 ```ruby
 person.to_hash
+
 # =>
 #
 # {
@@ -215,6 +231,15 @@ 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
+```
+
 ```ruby
 person = Person.from_xml(<<~DATA)
 <person>
@@ -237,6 +262,7 @@ DATA
 
 ```ruby
 person.to_xml
+
 # =>
 #
 # <person>
@@ -256,7 +282,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
@@ -300,7 +326,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
@@ -356,8 +382,6 @@ DATA
 
 ### Using XML namespaces
 
-:warning: **Ox doesn't support XML namespaces**
-
 To map namespaced elements and attributes use `namespace` and `prefix` properties on
 `map_element` and `map_attribute`
 
@@ -385,7 +409,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
@@ -574,8 +598,7 @@ 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 and 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
 `.load` and `.dump` class methods.
@@ -588,12 +611,15 @@ Shale.json_adapter = MultiJson
 Shale.yaml_adapter = MyYamlAdapter
 ```
 
+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,18 +637,25 @@ 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
+
+To generate JSON Schema from your Shale data model use:
 
 ```ruby
 require 'shale/schema'
 
-Shale::Schema.to_json(Person, id: 'My ID', description: 'My description', pretty: true)
+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": "My ID",
+#   "$id": "http://foo.bar/schema/person",
 #   "description": "My description",
 #   "$ref": "#/$defs/Person",
 #   "$defs": {
@@ -661,7 +694,7 @@ Shale::Schema.to_json(Person, id: 'My ID', description: 'My description', pretty
 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:
@@ -674,18 +707,88 @@ 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
 
-To generate XML Schema from you Shale data model use:
+To generate XML Schema from your Shale data model use:
 
 ```ruby
 require 'shale/schema'
@@ -733,7 +836,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:
@@ -746,7 +849,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

data/exe/shaleb

@@ -1,14 +1,32 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'optparse'
 
-base_path = File.expand_path('../lib', __dir__)
+def require_local_or_global(path)
+  base_path = File.expand_path('../lib', __dir__)
 
-if File.exist?(base_path)
-  require_relative '../lib/shale/schema'
-else
-  require 'shale/schema'
+  if File.exist?(base_path)
+    require_relative "../lib/#{path}"
+  else
+    require path
+  end
+end
+
+require_local_or_global('shale/schema')
+
+def load_xml_parser
+  require_local_or_global('shale/adapter/nokogiri')
+  Shale.xml_adapter = Shale::Adapter::Nokogiri
+rescue LoadError
+  begin
+    require_local_or_global('shale/adapter/rexml')
+    Shale.xml_adapter = Shale::Adapter::REXML
+  rescue LoadError
+    puts "Can't load XML parser. Make sure Nokogiri or REXML is installed on your system!"
+    exit
+  end
 end
 
 params = {}
@@ -16,11 +34,17 @@ params = {}
 ARGV << '-h' if ARGV.empty?
 
 OptionParser.new do |opts|
-  opts.banner = "Usage: shaleb [options]\nexample: shaleb -i data_model.rb -c MyRoot"
-
-  opts.on('-i INPUT', '--input', 'Input file')
-  opts.on('-o OUTPUT', '--output', 'Output file (defaults to STDOUT)')
-  opts.on('-c CLASS', '--class CLASS', 'Shale model class name')
+  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')
 
@@ -30,46 +54,94 @@ OptionParser.new do |opts|
   end
 end.parse!(into: params)
 
-input_path = File.expand_path(params[:input], Dir.pwd)
-
-unless File.exist?(input_path)
-  puts "File '#{input_path}' does not exist"
-  exit
-end
+if params[:compile]
+  unless params[:input]
+    puts 'Input file is required: shaleb -c -i schema1.json,schema2.json'
+    exit
+  end
 
-unless params[:class]
-  puts 'Model class is required'
-  exit
-end
+  schemas = params[:input].map do |file|
+    path = File.expand_path(file, Dir.pwd)
 
-require input_path
+    if File.exist?(path)
+      File.read(path)
+    else
+      puts "File '#{path}' does not exist"
+      exit
+    end
+  end
 
-klass = Object.const_get(params[:class])
+  if params[:format] == 'xml'
+    load_xml_parser
+    models = Shale::Schema.from_xml(schemas)
+  else
+    models = Shale::Schema.from_json(schemas, root_name: params[:root])
+  end
 
-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])
+    dir = File.expand_path(params[:output], Dir.pwd)
+    FileUtils.mkdir_p(dir) unless File.directory?(dir)
 
-    schemas.map do |name, xml|
-      File.write(File.expand_path(name, Dir.pwd), xml)
+    models.each do |name, model|
+      output_path = File.join(dir, "#{name}.rb")
+      File.write(output_path, model)
     end
   else
-    schemas = Shale::Schema.to_xml(klass, pretty: params[:pretty])
-
-    output = schemas.map do |name, xml|
-      "<!-- #{name} -->\n#{xml}\n"
+    output = models.map do |name, model|
+      "# --- #{name}.rb ---\n#{model}\n"
     end.join("\n")
 
     puts output
   end
 else
-  schema = Shale::Schema.to_json(klass, pretty: params[:pretty])
+  unless params[:input]
+    puts 'Input file is required: shaleb -i model.rb -r MyClass'
+    exit
+  end
 
-  if params[:output]
-    output_path = File.expand_path(params[:output], Dir.pwd)
-    File.write(output_path, schema)
+  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'
+    load_xml_parser
+
+    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
-    puts schema
+    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/nokogiri/document.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Shale
+  module Adapter
+    module Nokogiri
+      # Wrapper around Nokogiri API
+      #
+      # @api private
+      class Document
+        # Initialize object
+        #
+        # @api private
+        def initialize
+          @doc = ::Nokogiri::XML::Document.new
+          @namespaces = {}
+        end
+
+        # Return Nokogiri document
+        #
+        # @return [::Nokogiri::XML::Document]
+        #
+        # @api private
+        def doc
+          if @doc.root
+            @namespaces.each do |prefix, namespace|
+              @doc.root.add_namespace(prefix, namespace)
+            end
+          end
+
+          @doc
+        end
+
+        # Create Nokogiri element
+        #
+        # @param [String] name Name of the XML element
+        #
+        # @return [::Nokogiri::XML::Element]
+        #
+        # @api private
+        def create_element(name)
+          ::Nokogiri::XML::Element.new(name, @doc)
+        end
+
+        # Add XML namespace to document
+        #
+        # @param [String] prefix
+        # @param [String] namespace
+        #
+        # @api private
+        def add_namespace(prefix, namespace)
+          @namespaces[prefix] = namespace if prefix && namespace
+        end
+
+        # Add attribute to Nokogiri element
+        #
+        # @param [::Nokogiri::XML::Element] element Nokogiri element
+        # @param [String] name Name of the XML attribute
+        # @param [String] value Value of the XML attribute
+        #
+        # @api private
+        def add_attribute(element, name, value)
+          element[name] = value
+        end
+
+        # Add child element to Nokogiri element
+        #
+        # @param [::Nokogiri::XML::Element] element Nokogiri parent element
+        # @param [::Nokogiri::XML::Element] child Nokogiri child element
+        #
+        # @api private
+        def add_element(element, child)
+          element.add_child(child)
+        end
+
+        # Add text node to Nokogiri element
+        #
+        # @param [::Nokogiri::XML::Element] element Nokogiri element
+        # @param [String] text Text to add
+        #
+        # @api private
+        def add_text(element, text)
+          element.content = text
+        end
+      end
+    end
+  end
+end