shale 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5907ba25342167fa8079e683c671f83f89b51777d0b27e8d0126ba404304c2bd
-  data.tar.gz: d88f5acb763a1aaa5f3ceff194613df16377107035cf2c5528bbda593a70b6fa
+  metadata.gz: f9396e5fcba6ff4e1f1566abe356270ef9ddbd8ce9171063f011feeb36d234e7
+  data.tar.gz: 4495b40dca3e01b6ba908dfc6b7831aea3f1e2865423de59ced69db33ba633b8
 SHA512:
-  metadata.gz: 967646fcc21c1735acc67ad67b467013dae4da76c2e7cfc3a863b8bc811ae3fcee73cc3a99e1344ab0ea38ef03fed181ba14286666afc6e965399c8929de045a
-  data.tar.gz: bebfbda2bb8fab102ae8b70506cd3fad3e1b178c02ed0486576d2fb26ef5a98ac45a0f62d410888e95b40d9a21ace32c76da36e2a75151ce104c4764a98b1b68
+  metadata.gz: 404737157189f2312b4e189d095899588495c8f80cf52f9bd5935358b2ec8bedbd98b0d7676c44641383109701d62377d3086b36342950d6fd657dbbba2d06b9
+  data.tar.gz: '04818bdcac0290dfd96fbb0ebb1364350a444a9fc0533992d2cdf3bc3443e8afb4f00021346c66610400ddce12b4848c8bbed5c0bfb3835d40438c2b5acc1a6b'

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [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

@@ -24,8 +24,35 @@ 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)
+* [Generating XML Schema](#generating-xml-schema)
+
 ## Usage
 
+Documentation with interactive examples is available at [Shale website](https://www.shalerb.org)
+
 ### Simple use case
 
 ```ruby
@@ -264,7 +291,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
@@ -327,6 +354,74 @@ DATA
 - `map_attribute` - map element's attribute to attribute
 - `map_content` - map first text node to attribute
 
+### 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`
+
+```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 only on elements, 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 +516,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 +559,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 +588,7 @@ 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:
 
 ```ruby
 require 'shale'
@@ -484,6 +609,146 @@ require 'shale/adapter/ox'
 Shale.xml_adapter = Shale::Adapter::Ox
 ```
 
+### Generating JSON Schema
+
+To generate JSON Schema from you Shale data model use:
+
+```ruby
+require 'shale/schema'
+
+Shale::Schema.to_json(Person, id: 'My ID', description: 'My description', pretty: true)
+
+# =>
+#
+# {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   "id": "My ID",
+#   "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 -c 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::JSON::Base
+  def as_type
+    { 'type' => 'string', 'format' => 'email' }
+  end
+end
+
+Shale::Schema::JSON.register_json_type(MyEmailType, MyEmailJSONType)
+```
+
+### Generating XML Schema
+
+To generate XML Schema from you 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 -c 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::XML.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,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+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 = "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.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)
+
+input_path = File.expand_path(params[:input], Dir.pwd)
+
+unless File.exist?(input_path)
+  puts "File '#{input_path}' does not exist"
+  exit
+end
+
+unless params[:class]
+  puts 'Model class is required'
+  exit
+end
+
+require input_path
+
+klass = Object.const_get(params[:class])
+
+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

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

data/lib/shale/adapter/nokogiri.rb

@@ -26,12 +26,29 @@ module Shale
       # Serialize Nokogiri document into XML
       #
       # @param [::Nokogiri::XML::Document] doc Nokogiri document
+      # @param [Array<Symbol>] options
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc)
-        doc.to_xml
+      def self.dump(doc, *options)
+        save_with = ::Nokogiri::XML::Node::SaveOptions::AS_XML
+
+        if options.include?(:pretty)
+          save_with |= ::Nokogiri::XML::Node::SaveOptions::FORMAT
+        end
+
+        unless options.include?(:declaration)
+          save_with |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
+        end
+
+        result = doc.to_xml(save_with: save_with)
+
+        unless options.include?(:pretty)
+          result = result.sub(/\n/, '')
+        end
+
+        result
       end
 
       # Create Shale::Adapter::Nokogiri::Document instance
@@ -45,18 +62,27 @@ module Shale
       #
       # @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
-        attr_reader :doc
+        def doc
+          if @doc.root
+            @namespaces.each do |prefix, namespace|
+              @doc.root.add_namespace(prefix, namespace)
+            end
+          end
 
-        # Initialize object
-        #
-        # @api private
-        def initialize
-          @doc = ::Nokogiri::XML::Document.new
+          @doc
         end
 
         # Create Nokogiri element
@@ -70,6 +96,16 @@ module Shale
           ::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
@@ -115,7 +151,7 @@ module Shale
           @node = node
         end
 
-        # Return fully qualified name of the node in the format of
+        # 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]
@@ -124,11 +160,11 @@ module Shale
         #   node.name # => Bar
         #
         # @example with namespace
-        #   node.name # => foo:Bar
+        #   node.name # => http://foo:Bar
         #
         # @api private
         def name
-          [@node.namespace&.prefix, @node.name].compact.join(':')
+          [@node.namespace&.href, @node.name].compact.join(':')
         end
 
         # Return all attributes associated with the node
@@ -138,7 +174,7 @@ module Shale
         # @api private
         def attributes
           @node.attribute_nodes.each_with_object({}) do |node, hash|
-            name = [node.namespace&.prefix, node.name].compact.join(':')
+            name = [node.namespace&.href, node.name].compact.join(':')
             hash[name] = node.value
           end
         end

data/lib/shale/adapter/ox.rb

@@ -22,12 +22,24 @@ module Shale
       # Serialize Ox document into XML
       #
       # @param [::Ox::Document, ::Ox::Element] doc Ox document
+      # @param [Array<Symbol>] options
       #
       # @return [String]
       #
       # @api private
-      def self.dump(doc)
-        ::Ox.dump(doc)
+      def self.dump(doc, *options)
+        opts = { indent: -1, with_xml: false }
+
+        if options.include?(:pretty)
+          opts[:indent] = 2
+        end
+
+        if options.include?(:declaration)
+          doc[:version] = '1.0'
+          opts[:with_xml] = true
+        end
+
+        ::Ox.dump(doc, opts).sub(/\A\n/, '')
       end
 
       # Create Shale::Adapter::Ox::Document instance
@@ -66,6 +78,18 @@ module Shale
           ::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
@@ -111,8 +135,8 @@ module Shale
           @node = node
         end
 
-        # Return fully qualified name of the node in the format of
-        # namespace:name when the node is namespaced or just name when it's not
+        # Return name of the node in the format of
+        # prefix:name when the node is namespaced or just name when it's not
         #
         # @return [String]
         #