shale 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26877841702bfce542b42206f519ffd1b03e2f0d3db1e70a42e37836ff0f3bff
-  data.tar.gz: 23fddba7256bc38b5d64309cf56833f47fd636ed0e9f6ec61f2a076764dad2bb
+  metadata.gz: aaa3043e612d332fab30ff87ecab722e3812e7769eba982db27c38f74c205ce1
+  data.tar.gz: bb5cdb963bce5756c48edb37d28bddc40a816901e87b4714ea512f07f8ec4c28
 SHA512:
-  metadata.gz: e98bd0bbb20fbbaf4a8bdbfb5e2f83ba5d7bae78ad66a8597a1fe28c0c13d9799bc3ade785105ea7261147f55590ff530e85c31da459fe8c9171ee5b68f02977
-  data.tar.gz: 54be0efe36f4d330c551f1bd8994a36b360ecec3696aafe12382408a0656e50a181b91ff54ec9f39758908d15fcf51eafc4810540cd1aeb00bda7b552382bc80
+  metadata.gz: ed1f1ffc88cabb5f9403ff957c02efc4565aee73b9a8a1fd2297ff13bfbb6bdf0e94664b865f8d2d812ddd66fe97d154e34982eea3318ba01c6d16b4a6922c70
+  data.tar.gz: d41392de36bcace9efee12a869f49beffba235ae09e09f33c6973159b96320e3f657a6edd4d634e53da430f8127e74fa1025fa2f5c75dad2e7568abe6a0794ce

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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/README.md

@@ -4,18 +4,20 @@ 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 Schema into 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:
 
@@ -60,11 +62,10 @@ $ gem install shale
 * [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
@@ -230,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>
@@ -588,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.
@@ -602,6 +611,7 @@ 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**
@@ -609,7 +619,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 +852,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.

data/exe/shaleb

@@ -4,12 +4,29 @@
 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 = {}
@@ -54,7 +71,12 @@ if params[:compile]
     end
   end
 
-  models = Shale::Schema.from_json(schemas, root_name: params[:root])
+  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[:output]
     dir = File.expand_path(params[:output], Dir.pwd)
@@ -94,6 +116,8 @@ else
   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])

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

data/lib/shale/adapter/nokogiri/node.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Shale
+  module Adapter
+    module Nokogiri
+      # Wrapper around Nokogiri::XML::Node API
+      #
+      # @api private
+      class Node
+        # Initialize object with Nokogiri node
+        #
+        # @param [::Nokogiri::XML::Node] node Nokogiri node
+        #
+        # @api private
+        def initialize(node)
+          @node = node
+        end
+
+        # Return namespaces defined on document
+        #
+        # @return [Hash<String, String>]
+        #
+        # @example
+        #   node.namespaces # => { 'foo' => 'http://foo.com', 'bar' => 'http://bar.com' }
+        #
+        # @api private
+        def namespaces
+          @node.namespaces.transform_keys { |e| e.sub('xmlns:', '') }
+        end
+
+        # Return name of the node in the format of
+        # namespace:name when the node is namespaced or just name when it's not
+        #
+        # @return [String]
+        #
+        # @example without namespace
+        #   node.name # => Bar
+        #
+        # @example with namespace
+        #   node.name # => http://foo:Bar
+        #
+        # @api private
+        def name
+          [@node.namespace&.href, @node.name].compact.join(':')
+        end
+
+        # Return all attributes associated with the node
+        #
+        # @return [Hash]
+        #
+        # @api private
+        def attributes
+          @node.attribute_nodes.each_with_object({}) do |node, hash|
+            name = [node.namespace&.href, node.name].compact.join(':')
+            hash[name] = node.value
+          end
+        end
+
+        # Return node's parent
+        #
+        # @return [Shale::Adapter::Nokogiri::Node, nil]
+        #
+        # @api private
+        def parent
+          if @node.respond_to?(:parent) && @node.parent && @node.parent.name != 'document'
+            self.class.new(@node.parent)
+          end
+        end
+
+        # Return node's element children
+        #
+        # @return [Array<Shale::Adapter::Nokogiri::Node>]
+        #
+        # @api private
+        def children
+          @node
+            .children
+            .to_a
+            .filter(&:element?)
+            .map { |e| self.class.new(e) }
+        end
+
+        # Return first text child of a node
+        #
+        # @return [String]
+        #
+        # @api private
+        def text
+          first = @node
+            .children
+            .to_a
+            .filter(&:text?)
+            .first
+
+          first&.text
+        end
+      end
+    end
+  end
+end

data/lib/shale/adapter/nokogiri.rb

@@ -2,6 +2,10 @@
 
 require 'nokogiri'
 
+require_relative '../error'
+require_relative 'nokogiri/document'
+require_relative 'nokogiri/node'
+
 module Shale
   module Adapter
     # Nokogiri adapter
@@ -12,7 +16,9 @@ module Shale
       #
       # @param [String] xml XML document
       #
-      # @return [::Nokogiri::XML::Document]
+      # @raise [ParseError] when XML document has errors
+      #
+      # @return [Shale::Adapter::Nokogiri::Node]
       #
       # @api private
       def self.load(xml)
@@ -20,6 +26,10 @@ module Shale
           config.noblanks
         end
 
+        unless doc.errors.empty?
+          raise ParseError, "Document is invalid: #{doc.errors}"
+        end
+
         Node.new(doc.root)
       end
 
@@ -57,156 +67,6 @@ module Shale
       def self.create_document
         Document.new
       end
-
-      # 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
-
-      # Wrapper around Nokogiri::XML::Node API
-      #
-      # @api private
-      class Node
-        # Initialize object with Nokogiri node
-        #
-        # @param [::Nokogiri::XML::Node] node Nokogiri node
-        #
-        # @api private
-        def initialize(node)
-          @node = node
-        end
-
-        # Return name of the node in the format of
-        # namespace:name when the node is namespaced or just name when it's not
-        #
-        # @return [String]
-        #
-        # @example without namespace
-        #   node.name # => Bar
-        #
-        # @example with namespace
-        #   node.name # => http://foo:Bar
-        #
-        # @api private
-        def name
-          [@node.namespace&.href, @node.name].compact.join(':')
-        end
-
-        # Return all attributes associated with the node
-        #
-        # @return [Hash]
-        #
-        # @api private
-        def attributes
-          @node.attribute_nodes.each_with_object({}) do |node, hash|
-            name = [node.namespace&.href, node.name].compact.join(':')
-            hash[name] = node.value
-          end
-        end
-
-        # Return node's element children
-        #
-        # @return [Array<Shale::Adapter::Nokogiri::Node>]
-        #
-        # @api private
-        def children
-          @node
-            .children
-            .to_a
-            .filter(&:element?)
-            .map { |e| self.class.new(e) }
-        end
-
-        # Return first text child of a node
-        #
-        # @return [String]
-        #
-        # @api private
-        def text
-          first = @node
-            .children
-            .to_a
-            .filter(&:text?)
-            .first
-
-          first&.text
-        end
-      end
     end
   end
 end

data/lib/shale/adapter/ox/document.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Shale
+  module Adapter
+    module Ox
+      # Wrapper around Ox API
+      #
+      # @api private
+      class Document
+        # Return Ox document
+        #
+        # @return [::Ox::Document]
+        #
+        # @api private
+        attr_reader :doc
+
+        # Initialize object
+        #
+        # @api private
+        def initialize
+          @doc = ::Ox::Document.new
+        end
+
+        # Create Ox element
+        #
+        # @param [String] name Name of the XML element
+        #
+        # @return [::Ox::Element]
+        #
+        # @api private
+        def create_element(name)
+          ::Ox::Element.new(name)
+        end
+
+        # Add XML namespace to document
+        #
+        # Ox doesn't support XML namespaces so this method does nothing.
+        #
+        # @param [String] prefix
+        # @param [String] namespace
+        #
+        # @api private
+        def add_namespace(prefix, namespace)
+          # :noop:
+        end
+
+        # Add attribute to Ox element
+        #
+        # @param [::Ox::Element] element Ox 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 Ox element
+        #
+        # @param [::Ox::Element] element Ox parent element
+        # @param [::Ox::Element] child Ox child element
+        #
+        # @api private
+        def add_element(element, child)
+          element << child
+        end
+
+        # Add text node to Ox element
+        #
+        # @param [::Ox::Element] element Ox element
+        # @param [String] text Text to add
+        #
+        # @api private
+        def add_text(element, text)
+          element << text
+        end
+      end
+    end
+  end
+end