shale 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c96481848145b9736af4cc830c84c04970042fdc61f7d348aa64099065319ef
+  data.tar.gz: 25739ce30a7f4e66040b5dbff394da06a5c578065af0cd0b03bd0a56c7d78cbf
+SHA512:
+  metadata.gz: f205c1407868c6469922b7553f9aef3cdb0dc70502981d56eeef5b08703c793213f63c2a898568f372bc4e9519bcbfa771eefd6cfd663746e5b4180d1738c351
+  data.tar.gz: 95d7e2c6f88d7d5099c1ff62345509e83faee23a3bdd16e77d8eea05fb061e0eeb76fabbba5dc50d7c15ea675d2d1430570a2ac4134416c3d03d905d4ef59528

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2021-11-30
+
+First public release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,392 @@
+# Shale
+
+Shale is a object mapper and serializer for JSON, YAML and XML.
+
+## Installation
+
+Shale supports Ruby (MRI) 2.6+
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'shale'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install shale
+```
+
+## Usage
+
+### Simple use case
+
+```ruby
+require 'shale'
+
+class Address < Shale::Mapper
+  attribute :city, Shale::Type::String
+  attribute :street, Shale::Type::String
+  attribute :zip, Shale::Type::String
+end
+
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :age, Shale::Type::Date
+  attribute :married, Shale::Type::Boolean, default: -> { false }
+  attribute :hobbies, Shale::Type::String, collection: true
+  attribute :address, Address
+end
+```
+
+- `default: -> { 'value' }` - add a default value to attribute (it must be a proc that returns value)
+- `collection: true` - indicated that a attribute is a collection
+
+### Creating objects
+
+```ruby
+person = Person.new(
+  first_name: 'John',
+  last_name: 'Doe',
+  age: 50,
+  hobbies: ['Singing', 'Dancing'],
+  address: Address.new(city: 'London', street: 'Oxford Street', zip: 'E1 6AN'),
+)
+```
+
+### Converting JSON to object
+
+```ruby
+person = Person.from_json(<<~DATA)
+{
+  "first_name": "John",
+  "last_name": "Doe",
+  "age": 50,
+  "married": false,
+  "hobbies": ["Singing", "Dancing"],
+  "address": {
+    "city": "London",
+    "street": "Oxford Street",
+    "zip": "E1 6AN"
+  }
+}
+DATA
+
+# =>
+#
+# #<Person:0x00007f9bc3086d60
+#  @address=
+#   #<Address:0x00007f9bc3086748
+#    @city="London",
+#    @street="Oxford Street",
+#    @zip="E1 6AN">,
+#  @age=50,
+#  @first_name="John",
+#  @hobbies=["Singing", "Dancing"],
+#  @last_name="Doe",
+#  @married=false>
+```
+
+### Converting object to JSON
+
+```ruby
+person.to_json
+# =>
+#
+# {
+#   "first_name": "John",
+#   "last_name": "Doe",
+#   "age": 50,
+#   "married": false,
+#   "hobbies": ["Singing", "Dancing"],
+#   "address": {
+#     "city": "London",
+#     "street": "Oxford Street",
+#     "zip": "E1 6AN"
+#   }
+# }
+```
+
+### Converting YAML to object
+
+```ruby
+person = Person.from_yaml(<<~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 YAML
+
+```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 Hash to object
+
+```ruby
+person = Person.from_hash(
+  'first_name' => 'John',
+  'last_name' => 'Doe',
+  'age' => 50,
+  'married' => false,
+  'hobbies' => ['Singing', 'Dancing'],
+  'address' => {
+    'city'=>'London',
+    'street'=>'Oxford Street',
+    'zip'=>'E1 6AN'
+  },
+)
+```
+
+### Converting object to Hash
+
+```ruby
+person.to_hash
+# =>
+#
+# {
+#   "first_name"=>"John",
+#   "last_name"=>"Doe",
+#   "age"=>50,
+#   "married"=>false,
+#   "hobbies"=>["Singing", "Dancing"],
+#   "address"=>{"city"=>"London", "street"=>"Oxford Street", "zip"=>"E1 6AN"}
+# }
+ ```
+
+### Converting XML to object
+
+```ruby
+person = Person.from_xml(<<~DATA)
+<person>
+  <first_name>John</first_name>
+  <last_name>Doe</last_name>
+  <age>50</age>
+  <married>false</married>
+  <hobbies>Singing</hobbies>
+  <hobbies>Dancing</hobbies>
+  <address>
+    <city>London</city>
+    <street>Oxford Street</street>
+    <zip>E1 6AN</zip>
+  </address>
+</person>
+DATA
+```
+
+### Converting object to XML
+
+```ruby
+person.to_xml
+# =>
+#
+# <person>
+#   <first_name>John</first_name>
+#   <last_name>Doe</last_name>
+#   <age>50</age>
+#   <married>false</married>
+#   <hobbies>Singing</hobbies>
+#   <hobbies>Dancing</hobbies>
+#   <address>
+#     <city>London</city>
+#     <street>Oxford Street</street>
+#     <zip>E1 6AN</zip>
+#   </address>
+# </person>
+```
+
+### Mapping JSON keys to object attributes
+
+By default keys are named the same as attributes. To use custom key names use:
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+
+  json do
+    map 'firstName', to: :first_name
+    map 'lastName', to: :last_name
+  end
+end
+```
+
+### Mapping YAML keys to object attributes
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+
+  yaml do
+    map 'firstName', to: :first_name
+    map 'lastName', to: :last_name
+  end
+end
+```
+
+### Mapping Hash keys to object attributes
+
+```ruby
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+
+  hash do
+    map 'firstName', to: :first_name
+    map 'lastName', to: :last_name
+  end
+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:
+
+```ruby
+class Address < Shale::Mapper
+  attribute :street, Shale::Type::String
+  attribute :city, Shale::Type::String
+  attribute :zip, Shale::Type::String
+
+  xml do
+    map_content to: :street
+    map_element 'City', to: :city
+    map_element 'ZIP', to: :zip
+  end
+end
+
+class Person < Shale::Mapper
+  attribute :first_name, Shale::Type::String
+  attribute :last_name, Shale::Type::String
+  attribute :age, Shale::Type::Date
+  attribute :hobbies, Shale::Type::String, collection: true
+  attribute :address, Address
+
+  xml do
+    root 'Person'
+
+    map_attribute 'age', to: :age
+
+    map_element 'FirstName', to: :first_name
+    map_element 'LastName', to: :last_name
+    map_element 'Hobby', to: :hobbies
+    map_element 'Address', to: :address
+  end
+end
+
+person = Person.from_xml(<<~DATA)
+<Person age="50">
+  <FirstName>John</FirstName>
+  <LastName>Doe</LastName>
+  <Hobby>Singing</Hobby>
+  <Hobby>Dancing</Hobby>
+  <Address>
+    Oxford Street
+    <City>London</City>
+    <ZIP>E1 6AN</ZIP>
+  </Address>
+</person>
+DATA
+```
+
+- `root` - name of the root element
+- `map_element` - map content of element to attribute
+- `map_attribute` - map element's attribute to attribute
+- `map_content` - map first text node to attribute
+
+### Supported types
+
+Shale supports these types out of the box:
+
+- `Shale::Type::Boolean`
+- `Shale::Type::Date`
+- `Shale::Type::Float`
+- `Shale::Type::Integer`
+- `Shale::Type::String`
+- `Shale::Type::Time`
+
+### Writing your own type
+
+To add your own type extend it from `Shale::Type::Base` and implement `.cast` class method.
+
+```ruby
+require 'shale/type/base'
+
+class MyIntegerType < Shale::Type::Base
+  def self.cast(value)
+    value.to_i
+  end
+end
+```
+
+### Adapters
+
+Shale uses adapters for parsing and generating documents.
+By default Ruby's standard JSON parser is used for handing JSON documents, YAML for YAML and
+REXML for XML.
+
+You can change it by providing your own adapter. For JSON and YAML adapter must implement
+`.load` and `.dump` class methods.
+
+```ruby
+require 'shale'
+require 'multi_json'
+
+Shale.json_adapter = MultiJson
+Shale.yaml_adapter = MyYamlAdapter
+```
+
+For XML, other than REXML, Shale provides adapters for most popular Ruby XML parsers:
+
+```ruby
+require 'shale'
+
+require 'shale/adapter/nokogiri'
+Shale.xml_adapter = Shale::Adapter::Nokogiri
+
+# or if you want to use Ox
+
+require 'shale/adapter/ox'
+Shale.xml_adapter = Shale::Adapter::Ox
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kgiszczak/shale.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/shale/adapter/json.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Shale
+  module Adapter
+    # JSON adapter
+    #
+    # @api public
+    class JSON
+      # Parse JSON into Hash
+      #
+      # @param [String] json JSON document
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def self.load(json)
+        ::JSON.parse(json)
+      end
+
+      # Serialize Hash into JSON
+      #
+      # @param [Hash] obj Hash object
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.dump(obj)
+        ::JSON.generate(obj)
+      end
+    end
+  end
+end

data/lib/shale/adapter/nokogiri.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Shale
+  module Adapter
+    # Nokogiri adapter
+    #
+    # @api public
+    module Nokogiri
+      # Parse XML into Nokogiri document
+      #
+      # @param [String] xml XML document
+      #
+      # @return [::Nokogiri::XML::Document]
+      #
+      # @api private
+      def self.load(xml)
+        doc = ::Nokogiri::XML::Document.parse(xml) do |config|
+          config.noblanks
+        end
+
+        Node.new(doc.root)
+      end
+
+      # Serialize Nokogiri document into XML
+      #
+      # @param [::Nokogiri::XML::Document] doc Nokogiri document
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.dump(doc)
+        doc.to_xml
+      end
+
+      # Create Shale::Adapter::Nokogiri::Document instance
+      #
+      # @api private
+      def self.create_document
+        Document.new
+      end
+
+      # Wrapper around Nokogiri API
+      #
+      # @api private
+      class Document
+        # Return Nokogiri document
+        #
+        # @return [::Nokogiri::XML::Document]
+        #
+        # @api private
+        attr_reader :doc
+
+        # Initialize object
+        #
+        # @api private
+        def initialize
+          @doc = ::Nokogiri::XML::Document.new
+        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 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 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 [String]
+        #
+        # @example without namespace
+        #   node.name # => Bar
+        #
+        # @example with namespace
+        #   node.name # => foo:Bar
+        #
+        # @api private
+        def name
+          [@node.namespace&.prefix, @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&.prefix, 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