awesome_xml 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6e0fdacdca25fa723e63830f68a8b2c250c4b1df
+  data.tar.gz: f49a9d5503da9076d8608e98168267ebf572a304
+SHA512:
+  metadata.gz: 1acd280ece6c36b3aa553e5b12901a8df5bf566363a7c4b0854bf285d23c0b817b74800c57255b885c4742b68b473fa3c53afa6ca78d815f9aef57ee734ac162
+  data.tar.gz: bf932106ae5e58ff57922688405c50074fd6e7640b3fa1f8ccc1066ad9abd2cc1e0fac1b17aa93affdabd483763ade2b0dd3248d76ace5d7308d8b7b05379bc7

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 fromAtoB
+
+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,498 @@
+# AwesomeXML
+
+AwesomeXML is an XML mapping library that lets your Ruby classes parse arbitrary data from XML documents into a hash.
+The hash can be structured completely freely. The parsing itself is based on [Nokogiri](https://github.com/sparklemotion/nokogiri).
+The concept is very similar to that of [happymapper](https://github.com/dam5s/happymapper).
+
+## Include it
+
+Include `AwesomeXML` in any class you want to have all the capabilities this gem provides to you.
+
+```ruby
+class MyDocument
+  include AwesomeXML
+end
+```
+
+## Feed it
+
+Your class will now have a `.parse` class method which takes in a single argument containing a string
+representing an XML document. It returns an instance of your class. Like this:
+
+```ruby
+my_document = MyDocument.parse('<document><title>This is a document.</title></document>')
+=> #<MyDocument:0x007fc57d239520 @xml=#<Nokogiri::XML::Document:0x3fe2be91ca54 name="document" children=[#<Nokogiri::XML::Element:0x3fe2be91c70c name="document" children=[#<Nokogiri::XML::Element:0x3fe2be91c52c name="title" children=[#<Nokogiri::XML::Text:0x3fe2be91c34c "This is a document.">]>]>]>, @parent_node=nil>
+```
+
+## Create your first awesome node
+
+Let's say you have this XML document and you want to parse the content of the `<title></title>` tag.
+
+```xml
+<document>
+  <title>This is a document.</title>
+</document>
+```
+
+The `AwesomeXML` module defines several class methods on your class that that help you with that.
+The most basic one is the `.node` method.
+Its arguments are
+  - a symbol, which will be the name of your node.
+  - the type which the parser will assume the parsed value has
+  - an options hash (optional)
+
+The type can either be a native type given in the form of a symbol (currently supported are `:text`,
+`:integer`, `:float`, `:duration` and `:date_time`), or a custom class. You can also pass in a string containing
+a class name in case the class constant is not yet defined at the time you run the `.node` method.
+More about that later.
+
+Let's try it!
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node :title, :text
+end
+```
+
+Notice we needed to set a context node `'document'` so the `title` node could be found. `.set_context` takes an XPath
+and sets the current node for the whole class. There's a few other ways you can achievement the same thing as above.
+For example by passing in an explicit XPath.
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  node :title, :text, xpath: 'document/title'
+end
+```
+
+If you don't pass an XPath (like in the very first example), the default is assumed, which is `"./#{name_of_you_node}"`.
+Or, if you don't want to set the context node for the whole class, you can use `.with_context`, which takes a block:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  with_context 'document' do
+    node :title, :text
+  end
+end
+```
+
+All of these make a few things possible. Firstly, after calling `MyDocument.parse(xml_string)`, you can access
+an attribute reader method with the name of your node (`title`). It contains the value parsed from your XML document.
+
+```ruby
+my_document.title
+=> "This is a document."
+```
+
+Secondly, it changes the result of the `#to_hash` method of your class. More about that later.
+
+## Attributes, elements and `self`
+
+Let's say your XML document has important data hidden in the attributes of tags:
+
+```xml
+<document title='This is a document.'/>
+```
+
+One way to do it is to pass the option `attribute: true` to your node:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node :title, :text, attribute: true
+end
+```
+
+This is the same as passing an explicit XPath `"./@#{name_of_you_node}"`.
+Instead of just `true`, you can pass in a symbol (or string) to the `:attribute` option that will then be used to
+build the XPath to your node, instead of using the node name. Use this whenever you want your nodes
+to be named differently than in the XML document.
+
+This is also true for the other two types of nodes: elements and `self`. By default, `AwesomeXML` will look for
+elements, so passing the option `element: true` will do nothing. But you can use the option like `:attribute`, in
+that you can pass something else than `true` to tell the parser to look for an element with a different name.
+
+The last type of node is `self`. Pass in `self: true` if you want to access the content of the current context
+node itself. This is equivalent to passing in `xpath: '.'`. Changing the option value will do nothing.
+
+## Method nodes
+
+If you want, you can define your node in a method. Like this:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node :title, :text
+  method_node :reversed_title
+
+  def reversed_title
+    title.reverse
+  end
+end
+```
+
+You might say, ok, that's useless. I don't need to have the node define my `#reversed_title` method for me,
+I'm doing that myself already! And you would be correct. There's one side effect, though, related to
+the following awesome method that is provided to you:
+
+## `#to_hash`
+
+Including `AwesomeXML` will define the method `#to_hash` on your class. It traverses all the nodes
+you defined in your class (including the ones declared with `.method_node`) and returns values in a hash
+that follows the structure you defined. Let's take the example from the section above. Then, `#to_hash`
+would do the following:
+
+```ruby
+my_document.to_hash
+=> {:title=>"This is a document.", :reversed_title=>".tnemucod a si sihT"}
+```
+
+Let's step it up a little.
+
+## Child nodes
+
+Let's say you have a slightly more complicated XML document. Baby steps.
+
+```xml
+<document>
+  <title>This is a document.</title>
+  <item ref='123'>
+    <owner>John Doe</owner>
+  </item>
+</document>
+```
+
+If you want your parsed hash to look like this:
+```ruby
+{ title: "This is a document.", item: { reference: 123, owner: 'John Doe' } }
+```
+You can do that by creating a node of the type of another class that also includes `AwesomeXML`.
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node :title, :text
+  node :item, 'Item'
+
+  class Item
+    include AwesomeXML
+
+    node :reference, :integer, attribute: :ref
+    node :owner, :text
+  end
+end
+```
+
+Easy! You might have noticed that the context node for the `Item` class is automatically set. No need
+to call `.set_context` except you want to override the default, of course.
+
+If you want, you can also pass in the class itself instead of a string with the class name.
+Just make sure that it is defined before you use it in your `.node` method! Like this:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  class Item
+    include AwesomeXML
+
+    node :reference, :integer, attribute: :ref
+    node :owner, :text
+  end
+
+  set_context 'document'
+  node :title, :text
+  node :item, Item
+end
+```
+
+## Array nodes
+
+What if you have more than one `<item/>`? Say your XML document looks like this:
+
+```xml
+<document>
+  <item ref='123'/>
+  <item ref='456'/>
+  <item ref='789'/>
+</document>
+```
+
+And you want your parsed hash to look like this:
+
+```ruby
+{ refs: [123, 456, 789] }
+```
+
+Fret no more, just use the option `array: true`:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/item'
+  node :refs, :integer, attribute: true, array: true
+end
+```
+
+Pretty self-explanatory, right? `AwesomeXML` even singularizes your node name automatically!
+
+Okay, you say, that's a very simple array, indeed. What if I want an array of hashes? Like so:
+```ruby
+{ items: [{ ref: 123 }, { ref: 456 }, { ref: 789 }] }
+```
+
+Just combine the two things we last learned:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node :items, 'Item', array: true
+
+  class Item
+    include AwesomeXML
+
+    node :ref, :integer, attribute: true
+  end
+end
+```
+
+Awesome, right? You've got a few more notches you can kick it up, though.
+
+## Passing blocks
+
+That's right, you can pass blocks. It's actually very simple. All `*_node` methods (except `.method_node`
+and `.constant_node`) define instance methods that yield their result to the block you specify. This lets you
+do pretty much anything you want. Let's say you don't like the way the items are numbered in your XML document:
+
+```xml
+<document>
+  <item index='1'/>
+  <item index='2'/>
+  <item index='3'/>
+</document>
+```
+
+Yuck. Let's fix that:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document'
+  node(:items, :integer, array: true, xpath: './item/@index') do |values|
+    values.map { |value| value - 1 }
+  end
+end
+
+my_document.to_hash
+=> {:items=>[0, 1, 2]}
+
+```
+
+That's better. Note that array nodes yield the whole array to the block and not an `Enumerator`.
+
+There's another twist to this block passing, though. AwesomeXML also yields the instance of your class
+to the block so you can actually access other nodes inside the block! Let's see it in action.
+
+Your XML data:
+```xml
+<document>
+  <items multiplicator='100'>
+    <item value='1'/>
+    <item value='2'/>
+    <item value='3'/>
+  </items>
+</document>
+```
+
+Your `AwesomeXML` class:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/items'
+  node :multiplicator, :integer, attribute: true
+  node(:item_values, :integer, array: :true, xpath: './item/@value') do |values, instance|
+    values.map { |value| value * instance.multiplicator }
+  end
+end
+
+my_document.to_hash
+=> {:multiplicator=>100, :item_values=>[100, 200, 300]}
+```
+
+## Overwriting attribute readers
+
+You can achieve the same effect as passing blocks by redefining the attribute accessors that `AwesomeXML`
+usually defines for you. Arguably, this is the more elegant method, although you might prefer the block
+syntax's brevity for more simple operations.
+
+Let's see how the example from above would look in this style:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/items'
+  node :multiplicator, :integer, attribute: true
+  node :item_values, :integer, array: :true, xpath: './item/@value'
+
+  def item_values
+    @item_values.map { |value| value * multiplicator }
+  end
+end
+```
+
+## `#parent_node`
+
+This method is available on all class instances including the `AwesomeXML` module. It returns the
+instance of the class it was initialized from. Let's see how that can be useful. Let's again use
+the XML document from the above two examples.
+
+```xml
+<document>
+  <items multiplicator='100'>
+    <item value='1'/>
+    <item value='2'/>
+    <item value='3'/>
+  </items>
+</document>
+```
+
+This time, you want each `<item/>` to be represented by its own hash. Like this:
+```ruby
+my_document.to_hash
+=> {:items=>[{:value=>100}, {:value=>200}, {:value=>300}]}
+```
+
+There's (at least) two ways to do this. You can either define the `multiplicator` node on your child class:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/items'
+  node :items, 'Item', array: true
+
+  class Item
+    include AwesomeXML
+
+    node :multiplicator, :integer, xpath: '../@multiplicator', private: true
+    node :value, :integer, attribute: true
+
+    def value
+      @value * multiplicator
+    end
+  end
+end
+```
+
+Or, alternatively, you can use `#parent_node`:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/items'
+  node :multiplicator, :integer, attribute: true, private: true
+  node :items, 'Item', array: true
+
+  class Item
+    include AwesomeXML
+
+    node :value, :integer, attribute: true
+
+    def value
+      @value * parent_node.multiplicator
+    end
+  end
+end
+```
+
+Both are perfectly acceptable. The latter is slightly more efficient because the `multiplicator` node
+will only be parsed once instead of once per `item`. You may have noticed that we used a new option:
+`:private`. I'll explain it in the next section.
+
+## More options
+
+### `:private`
+
+The `:private` option removes your node from the ones being evaluated in `#to_hash`. This is
+helpful if you want to parse something that is not meant to end up in the parsed schema. Let's revisit the example
+from above.
+
+```xml
+<document>
+  <items multiplicator='100'>
+    <item value='1'/>
+    <item value='2'/>
+    <item value='3'/>
+  </items>
+</document>
+```
+
+Now let's try and remove the `multiplicator` from your parsed hash. Like so:
+
+```ruby
+class MyDocument
+  include AwesomeXML
+
+  set_context 'document/items'
+  node :multiplicator, :integer, attribute: true, private: true
+  node :item_values, :integer, array: :true, xpath: './item/@value'
+
+  def item_values
+    @item_values.map { |value| value * multiplicator }
+  end
+end
+```
+
+```ruby
+my_document.to_hash
+=> {:item_values=>[100, 200, 300]}
+```
+
+Awesome.
+
+### `:default` and `:default_empty`
+
+Using these options, you can control what happens in case the tag or attribute you wanted to parse is empty
+or doesn't even exist. For the former, use `:default_empty`, for the latter, use `:default`.
+
+## More node types
+
+Let's talk about duration nodes. As you may remember, `:duration` is of the native types for `.node`.
+They return `ActiveSupport::Duration` objects, which interact freely with each other and with `Time` and
+`DateTime` objects.
+The special thing about them is that they take a *mandatory* `:format` option. There, you can specify the
+format in which the duration you want to parse is available. The format is given in the form of a duration
+format string with an easy syntax. Basically, you emulate the format of the given duration string and
+replace the numbers with instructions how to treat them. The syntax is `"{#{unit}#{parse_length}}"`.
+The `unit` can be one of `D`, `H`, `M`, or `S` (or their lowercase variants), representing days, hours, minutes, and seconds.
+The `parse_length` tells the parser how many digits to look for, and can be any integer.
+
+For example, let's say you want to parse a duration string that looks like `'1234'`, where the first two
+digits stand for minutes and the last two for seconds. To parse this correctly, use the format string
+`'{M2}{S2}'`. Easy enough.
+
+What, though, if the number of digits vary? Maybe your duration string sometimes looks like `'12m34'`,
+but when the numbers are single digit, it looks like `'2m1'`. In this case, just don't specify a
+`parse_length`. Everything up to the following character (or the end of the duration string) will be
+treated as going into the parsed value. The format string that would parse you the correct duration
+would be `'{M}m{S}'`.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/awesome_xml/class_methods.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# A collection of class methods that will be available on classes that include `AwesomeXML`.
+module AwesomeXML
+  module ClassMethods
+    attr_reader :context, :nodes, :public_nodes
+    private :nodes, :public_nodes
+
+    # Takes in a string representing an XML document. Initializes an instance of the class
+    # the module was included in and calls `#parse` on it. See there for more info.
+    def parse(xml)
+      new(xml).parse
+    end
+
+    # Takes in a string representing an XPath and assigns it to the class variable `@@context`.
+    # This sets the current context node for all nodes defined below it in the class this
+    # module is included in.
+    def set_context(xpath)
+      @context ||= xpath
+    end
+
+    # Works just like `set_context`, but sets the current context node only for nodes defined
+    # inside the block passed to this method.
+    def with_context(xpath, &block)
+      @local_context = xpath
+      yield
+      @local_context = nil
+    end
+
+    # Defines a method on your class returning a constant.
+    def constant_node(name, value, options = {})
+      attr_reader name.to_sym
+      define_method("parse_#{name}".to_sym) do
+        instance_variable_set("@#{name}", value)
+      end
+      register(name, options[:private])
+    end
+
+    # Does not actually define a method, but registers the node name
+    # in the `@nodes` attribute.
+    def method_node(name)
+      define_method("parse_#{name}".to_sym) {}
+      register(name, false)
+    end
+
+    # Defines a method on your class returning a parsed value 
+    def node(name, type, options = {}, &block)
+      attr_reader name.to_sym
+      options[:local_context] = @local_context
+      xpath = NodeXPath.new(name, options).xpath
+      define_method("parse_#{name}".to_sym) do
+        evaluate_args = [xpath, AwesomeXML::Type.for(type, self.class.name), options]
+        instance_variable_set(
+          "@#{name}",
+          evaluate_nodes(*evaluate_args, &block)
+        )
+      end
+      register(name, options[:private])
+    end
+
+    # Returns an array of symbols containing all method names defined by node builder methods
+    # in your class.
+    def nodes
+      @nodes ||= []
+    end
+
+    # Returns an array of symbols containing all method names defined by node builder methods
+    # in your class. Does not list nodes built with option `:private`.
+    def public_nodes
+      @public_nodes ||= []
+    end
+
+  private
+
+    def register(node_name, privateness)
+      @nodes ||= []
+      @nodes << node_name.to_sym
+      @public_nodes ||= []
+      @public_nodes << node_name.to_sym unless privateness
+    end
+  end
+end

data/lib/awesome_xml/duration/chunk_parser.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# A class that lets you parse a string according to the rules of a
+# specified duration format chunk.
+module AwesomeXML
+  class Duration
+    class ChunkParser
+      attr_reader :duration_string_chunk, :format_chunk, :duration
+      private :duration_string_chunk, :format_chunk
+
+      # Parses a string given as `duration_string_chunk` according to the rules of the passed in
+      # `format_chunk`. The latter being either a `AwesomeXML::Duration::Format::StaticChunk`
+      # or a `AwesomeXML::Duration::Format::DynamicChunk`. Saves the resulting duration
+      # in the attribute `duration`.
+      def initialize(duration_string_chunk, format_chunk)
+        @duration_string_chunk = duration_string_chunk
+        @format_chunk = format_chunk
+        parse
+      end
+
+    private
+
+      def parse
+        if format_chunk.dynamic?
+          @duration = number.public_send(format_chunk.unit)
+        else
+          fail format_mismatch unless duration_string_chunk == format_chunk.to_s
+          @duration = 0.seconds
+        end
+      end
+
+      def number
+        fail format_mismatch unless valid_number?
+        duration_string_chunk.to_i
+      end
+
+      def valid_number?
+        duration_string_chunk =~ /^[0-9]*$/
+      end
+
+      def format_mismatch
+        FormatMismatch.new(duration_string_chunk, format_chunk.to_s)
+      end
+
+      class FormatMismatch < StandardError
+        def initialize(timestamp, format_string)
+          super("Duration string '#{timestamp}' does not conform to given format '#{format_string}'.")
+        end
+      end
+    end
+  end
+end

data/lib/awesome_xml/duration/format/dynamic_chunk.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# A class that holds an array of characters and represents a dynamic
+# component of a format string. Has a `unit`, a `parse_length` or a `delimiter`.
+# See `AwesomeXML::Duration::Format` for more info.
+module AwesomeXML
+  class Duration
+    class Format
+      class DynamicChunk
+        UNITS = { 'D' => :days, 'H' => :hours, 'M' => :minutes, 'S' => :seconds}
+
+        attr_accessor :format_chars, :delimiter
+
+        def initialize
+          @format_chars = []
+        end
+
+        # Returns the defining characters joint into a string.
+        def to_s
+          [format_chars, delimiter].join
+        end
+
+        # Counterpart of the same method of `AwesomeXML::Duration::Format::DynamicChunk`.
+        # Used to differentiate between instances of these two classes.
+        def dynamic?
+          true
+        end
+
+        # Takes the first character of `format_chars` and interprets as a duration unit.
+        def unit
+          fail InvalidDurationUnit.new(parsed_unit) unless valid_unit?
+          @unit ||= UNITS[parsed_unit]
+        end
+
+        # Takes the characters following the first character of `format_chars` and interprets
+        # them as an integer representing the number of characters to parse when given to the
+        # `AweseomXML::Duration::ChunkParser` together with a piece of duration string.
+        # When the `format_chars` only contain a single character, this will be 0.
+        def parse_length
+          fail InvalidParseLength.new(parsed_parse_length) unless valid_parse_length?
+          @parse_length ||= parsed_parse_length.to_i
+        end
+
+      private
+
+        def valid_unit?
+          %w(D H M S).include?(parsed_unit)
+        end
+
+        def parsed_unit
+          format_chars[0].upcase
+        end
+
+        def valid_parse_length?
+          parsed_parse_length =~ /^[0-9]*$/ || parsed_parse_length.nil?
+        end
+
+        def parsed_parse_length
+          @parsed_parse_length ||= format_chars.drop(1).join
+        end
+
+        class InvalidDurationUnit < StandardError
+          def initialize(parsed_unit)
+            super("Parsed unknown duration unit: '#{parsed_unit}'. Please choose from [D, H, M, S].")
+          end
+        end
+
+        class InvalidParseLength < StandardError
+          def initialize(parsed_parse_length)
+            super("Couldn't parse '#{parsed_parse_length}' into an integer.")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/awesome_xml/duration/format/static_chunk.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# A class that holds an array of characters and represents a static
+# component of a format string. See `AwesomeXML::Duration::Format` for more info.
+module AwesomeXML
+  class Duration
+    class Format
+      class StaticChunk
+        attr_accessor :format_chars
+
+        def initialize
+          @format_chars = []
+        end
+
+        # Returns the defining characters joint into a string.
+        def to_s
+          format_chars.join
+        end
+
+        # Returns the number of the defining characters.
+        def parse_length
+          format_chars.length
+        end
+
+        # Counterpart of the same method of `AwesomeXML::Duration::Format::DynamicChunk`.
+        # Used to differentiate between instances of these two classes.
+        def dynamic?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/awesome_xml/duration/format.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# A representation of a user defined duration format.
+module AwesomeXML
+  class Duration
+    class Format
+      attr_reader :format_string, :chunks
+      private :format_string
+
+      # Returns an `AwesomeXML::Duration::Format` instance representing a user defined
+      # duration format specified by the passed in `format_string`. Splits the format
+      # string into chunks that are each one of either `AwesomeXML::Duration::Format::StaticChunk`
+      # or `AwesomeXML::Duration::Format::DynamicChunk` and saves them in the attribute `chunks`.
+      # The latter class mentioned is used for a section of the format string inside curly
+      # brackets. For more information about the syntax of the format string, read the README.
+      def initialize(format_string)
+        @format_string = format_string
+        @chunks = []
+        compile
+      end
+
+    private
+
+      def compile
+        format_string.chars.each(&method(:process))
+        @chunks = chunks&.compact
+      end
+
+      def process(character)
+        case character
+        when '{'
+          chunks.append(DynamicChunk.new)
+        when '}'
+          chunks.append(nil)
+        else
+          if chunks.last.nil? 
+            if chunks[-2].is_a?(DynamicChunk)
+              chunks[-2].delimiter = character
+            end
+            chunks.tap(&:pop).append(StaticChunk.new)
+          end
+
+          chunks.last.format_chars.append(character)
+        end
+      end
+    end
+  end
+end

data/lib/awesome_xml/native_type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# This module is shared by all native type classes of `AwesomeXML`. It defines the
+# interface for types that the `AwesomeXML::NodeEvaluator` expects.
+module AwesomeXML
+  module NativeType
+    attr_reader :string, :options
+    private :string, :options
+
+    # Native type instances are initialized with a `Nokogiri::XML` object and an options hash.
+    def initialize(node, options = {})
+      @string = node&.text
+      @options = options
+    end
+
+    # This method returns the parsed value of the given node (obtained by calling `#text` on it) according
+    # to the implementation of the private method `#parse_value` defined in every native type class.
+    def evaluate
+      @value ||= with_defaults { parse_value }
+    end
+
+  private
+
+    def with_defaults(&block)
+      return options[:default] if string.nil?
+      return options[:default_empty] if options.has_key?(:default_empty) && string.empty?
+      return default_empty if string.empty?
+      yield
+    end
+
+    def default_empty
+      nil
+    end
+  end
+end

data/lib/awesome_xml/node_evaluator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# This class is responsible for parsing a specific value from an XML document given all the
+# necessary information.
+module AwesomeXML
+  class NodeEvaluator
+    attr_reader :xml, :xpath, :type_class, :options
+    private :xml, :xpath, :type_class, :options
+
+    # Initialize an instance of this class with a Nokogiri::XML object, a string representing
+    # an XPath to the value(s) you want to parse, a type class (see `AwesomeXML::Type` for more
+    # info), and an options hash.
+    def initialize(xml, xpath, type_class, options)
+      @xml = xml
+      @xpath = xpath
+      @type_class = type_class
+      @options = options
+    end
+
+    # Parses one or several nodes, depending on the `options[:array]` setting, according to the
+    # type passed in in the form of a class that handles the conversion.
+    def call
+      if options[:array]
+        all_nodes.map { |node| type_class.new(node, options).evaluate }
+      else
+        type_class.new(first_node, options).evaluate
+      end
+    end
+
+  private
+
+    def all_nodes
+      xml_in_context&.xpath(xpath)
+    end
+
+    def first_node
+      xml_in_context&.at_xpath(xpath)
+    end
+
+    def xml_in_context
+      options[:local_context] ? xml&.xpath(options[:local_context]) : xml
+    end
+  end
+end

data/lib/awesome_xml/node_xpath.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# This class's responsibility is to build an XPath from specified options.
+module AwesomeXML
+  class NodeXPath
+    attr_reader :node_name, :specific_xpath, :element_option, :attribute_option, :self_option, :array
+    private :node_name, :specific_xpath, :element_option, :attribute_option, :self_option, :array
+
+    # Initialize this class by providing the name of the `AwesomeXML` node and an options hash.
+    # For more information on how the options work, please refer to the README.
+    def initialize(node_name, options)
+      @node_name = node_name
+      @specific_xpath = options[:xpath]
+      @element_option = options[:element]
+      @attribute_option = options[:attribute]
+      @self_option = options[:self]
+      @look_for = options[:look_for]
+      @array = options[:array]
+    end
+
+    # Returns a String representing an XPath built from the options passed in at initialization time.
+    def xpath
+      specific_xpath || xpath_by_tag_type
+    end
+
+  private
+
+    def xpath_by_tag_type
+      if attribute_option
+        "./@#{tag_name(attribute_option)}"
+      elsif self_option
+        "."
+      else
+        "./#{tag_name(element_option)}"
+      end
+    end
+
+    def node_name_singular
+      array ? node_name.to_s.singularize.to_sym : node_name
+    end
+
+    def tag_name(option)
+      (option if option != true) || node_name_singular
+    end
+  end
+end

data/lib/awesome_xml/type.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# This class converts types passed in as arguments to `.node` method calls to a
+# type class. Either native or user-defined.
+module AwesomeXML
+  module Type
+    NATIVE_TYPE_CLASSES = {
+      text: AwesomeXML::Text,
+      integer: AwesomeXML::Integer,
+      float: AwesomeXML::Float,
+      duration: AwesomeXML::Duration,
+      date_time: AwesomeXML::DateTime
+    }.freeze
+
+    # Takes a type (Symbol, String or Class) passed in from a `.node` method call and the
+    # name of the class it was called in. The latter is needed to correctly assign the namespace
+    # if the type is given in String form. Returns a class, either one of the native `AwesomeXML`
+    # types or a user-defined class. Raises an exception if `type` is given as a Symbol, but
+    # does not represent one of the native types.
+    def self.for(type, class_name)
+      case type
+      when Symbol
+        NATIVE_TYPE_CLASSES[type] || fail(UnknownNodeType.new(type))
+      when String
+        [class_name, type].join('::').constantize
+      when Class
+        type
+      end
+    end
+
+    # An excception of this type is raised if `type` is given as a Symbol to `.for`, but does not
+    # represent one of the native `AwesomeXML` types.
+    class UnknownNodeType < StandardError
+      def initialize(type)
+        super("Cannot create node with unknown node type '#{type}'.")
+      end
+    end
+  end
+end

data/lib/awesome_xml/types/date_time.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# A class that knows how to parse a point in time given a timestamp and a format string.
+module AwesomeXML
+  class DateTime
+    include AwesomeXML::NativeType
+
+  private
+
+    def parse_value
+      fail NoFormatProvided if options[:format].nil?
+      ::DateTime.strptime(string, options[:format])
+    end
+
+    class NoFormatProvided < StandardError
+      def initialize
+        super('Please provide a format option to date_time nodes.')
+      end
+    end
+  end
+end

data/lib/awesome_xml/types/duration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# A class that knows how to parse a duration given a duration string and a format string.
+module AwesomeXML
+  class Duration
+    include AwesomeXML::NativeType
+
+  private
+
+    def parse_value
+      fail NoFormatProvided if options[:format].nil?
+      string_chunks.zip(format_chunks).map do |string_chunk, format_chunk|
+        AwesomeXML::Duration::ChunkParser.new(string_chunk, format_chunk).duration
+      end.reduce(:+) || 0.seconds
+    end
+
+    def string_chunks
+      @string_chunks ||= chunk_string
+    end
+
+    def chunk_string
+      result = []
+      format_chunks.reduce(string.chars) do |chopped_string, format_chunk|
+        if format_chunk.parse_length.zero?
+          parse_length = chopped_string.find_index(format_chunk.delimiter) || chopped_string.length
+        else
+          parse_length = format_chunk.parse_length
+        end
+        result.append(chopped_string.first(parse_length).join)
+        chopped_string.drop(parse_length)
+      end
+      result
+    end
+
+    def format_chunks
+      @format_chunks ||= AwesomeXML::Duration::Format.new(options[:format]).chunks
+    end
+
+    def split_at_character(string, character)
+      return string unless string.chars.include?(character)
+      split_after(string, string.chars.find_index(character) - 1)
+    end
+
+    def split_after(string, after_position)
+      [string.chars.first(after_position), string.chars.drop(after_position)].map(&:join)
+    end
+
+    class NoFormatProvided < StandardError
+      def initialize
+        super('Please provide a format option to duration nodes.')
+      end
+    end
+  end
+end

data/lib/awesome_xml/types/float.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# A class that knows how to parse a Float from a String.
+module AwesomeXML
+  class Float
+    include AwesomeXML::NativeType
+
+  private
+
+    def parse_value
+      string.to_f
+    end
+  end
+end

data/lib/awesome_xml/types/integer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# A class that knows how to parse an Integer from a String.
+module AwesomeXML
+  class Integer
+    include AwesomeXML::NativeType
+
+  private
+
+    def parse_value
+      string.to_i
+    end
+  end
+end

data/lib/awesome_xml/types/text.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# A class that knows how to parse a String from a String. Shockingly, it doesn't do much.
+module AwesomeXML
+  class Text
+    include AwesomeXML::NativeType
+
+  private
+
+    def parse_value
+      string
+    end
+
+    def default_empty
+      ''
+    end
+  end
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: awesome_xml
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Felix Lublasser
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.41'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.41'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Have XML data that you want to bend to your willand conform to your schema?
+  This gem is for you.
+email:
+- felix.lublasser@fromatob.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/awesome_xml/class_methods.rb
+- lib/awesome_xml/duration/chunk_parser.rb
+- lib/awesome_xml/duration/format.rb
+- lib/awesome_xml/duration/format/dynamic_chunk.rb
+- lib/awesome_xml/duration/format/static_chunk.rb
+- lib/awesome_xml/native_type.rb
+- lib/awesome_xml/node_evaluator.rb
+- lib/awesome_xml/node_xpath.rb
+- lib/awesome_xml/type.rb
+- lib/awesome_xml/types/date_time.rb
+- lib/awesome_xml/types/duration.rb
+- lib/awesome_xml/types/float.rb
+- lib/awesome_xml/types/integer.rb
+- lib/awesome_xml/types/text.rb
+homepage: https://github.com/fromAtoB/awesome_xml
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Parse data from XML documents into arbitrary ruby hashes.
+test_files: []