decontaminate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 391a40ec6c400fea8dd7e0e0e236ccb54dd0d64c
+  data.tar.gz: ebc11740db0cd3ca3aa55dddcd6854a5b1b21d34
+SHA512:
+  metadata.gz: 5ce173bd8e3aa615abc225a2cd5dc921fbff1e7ed0509d7dd485c5670f8d398acfbdefadef498bb9a0a6ec1b1d1666f9a5557cf856d042f4f2d452bd104d981e
+  data.tar.gz: 151a004aafa09dfe7778e0d55ee5374a2d59ac6393f8ecba57e46ef27b573e64f38e780afb0afbb148f6599bd846f5954d3eee767ff234ac2b90741fef57a90b

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/decontaminate-*.gem

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+
+rvm:
+  - 2.2.2
+
+script:
+  - bundle exec rake

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright (c) 2015, Alexis King
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# Decontaminate
+
+Decontaminate is a tool for extracting information from large, potentially nested XML documents. It provides a simple Ruby DSL for selecting values from Nokogiri objects and storing the results in JSON-like Ruby hashes and arrays.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'decontaminate'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install decontaminate
+
+## Usage
+
+Decontaminate provides a DSL for creating *decontaminators*, which, when instantiated, accept XML nodes or documents and produce a hash as a result. To start, create a class that inherits from `Decontaminate::Decontaminator`:
+
+```ruby
+class MyDecontaminator < Decontaminate::Decontaminator
+end
+```
+
+If parsing an entire document, you should specify the name of the root element:
+
+```ruby
+class MyDecontaminator < Decontaminate::Decontaminator
+  self.root = 'User'
+end
+```
+
+### Scalar Values
+
+To select values from the XML document, use the `scalar` class method:
+
+```ruby
+class MyDecontaminator < Decontaminate::Decontaminator
+  self.root = 'User'
+
+  scalar 'Name'
+  scalar 'Age', type: :integer
+  scalar 'DateRegistered', key: 'registered_at'
+end
+```
+
+This might produce a result like the following:
+
+```ruby
+=> MyDecontaminator.new(xml_document).as_json
+{
+  'name' => 'Jane Smith',
+  'age' => 28,
+  'registered_at' => '2013-08-16T20:51:34.236Z'
+}
+```
+
+The first argument to `scalar` is the name of the node to extract data from. In fact, this can be any XPath string relative to the document root. By default, the resulting JSON key is inferred from the provided path, but it can also be overridden with the `key:` argument. Additionally, the type of the scalar can be specified with the `type:` argument, which defaults to `:string`.
+
+Attributes can be specified with XPath syntax by prepending an `@` sign:
+
+```ruby
+scalar '@id', type: :integer
+```
+
+### Nested Values
+
+It's also possible to specify nested or even deeply nested hashes with the `hash` class method:
+
+```ruby
+hash 'UserProfile', key: 'profile' do
+  scalar 'Description'
+
+  hash 'Specialization' do
+    scalar 'Area'
+    scalar 'Expertise', type: :float
+  end
+end
+```
+
+The `hash` method accepts a block, which works just like the class body, but all paths are scoped to the path passed to `hash`. The `key` argument is optional, just like with `scalar`.
+
+### Array Data
+
+In addition to the `scalar` and `hash` methods, there are plural forms which allow parsing and extracting data that appears many times within a single document. These are named `scalars` and `hashes`, respectively. They work much like their singular counterparts, but the provided path should match multiple elements.
+
+For example, given the following decontaminator:
+
+```ruby
+class ArticlesDecontaminator < Decontaminate::Decontaminator
+  hashes 'Articles' do
+    scalar 'Name'
+    scalars 'Tags'
+  end
+end
+```
+
+And given the following XML document:
+
+```xml
+<Articles>
+  <Article>
+    <Name>Article A</Name>
+    <Tags>
+      <Tag>News</Tag>
+      <Tag>Technology</Tag>
+    </Tags>
+  </Article>
+  <Article>
+    <Name>Article B</Name>
+    <Tags>
+      <Tag>Sports</Tag>
+      <Tag>Recreation</Tag>
+    </Tags>
+  </Article>
+</Articles>
+```
+
+The resulting object will have the following structure:
+
+```ruby
+{
+  'articles' => [
+    {
+      'name' => 'Article A',
+      'tags' => ['News', 'Technology']
+    },
+    {
+      'name' => 'Article B',
+      'tags' => ['Sports', 'Recreation']
+    }
+  ]
+}
+```
+
+There are some special things to note in the above example:
+
+  - **The name of the individual elements is inferred from the parent key.**
+
+    In both cases, the parent element was the plural form of its children (`Articles`/`Article` and `Tags`/`Tag`). Since this is common, the plural forms automatically perform this name inference.
+
+    Since this behavior is sometimes unwanted, it can be disabled by passing the path as an explicit `path:` keyword argument.
+
+    ```ruby
+    scalars path: 'Tags/TagName', key: 'tags' # Performs no name inference
+    ```
+
+  - **No `root` element was specified since the root element is a plural.**
+
+    When using name inference for a plural element at the root, specifying the root element is an error. By using the explicit `path:` form mentioned above, `root` could still be specified.
+
+    ```ruby
+    self.root = 'Articles'
+    hashes path: 'Article', key: 'articles' do; ...; end
+    ```
+
+### Flattening nested data
+
+Since source data is sometimes more nested than is desired, the `with` method is a helper for scoping decontamination directives to a given XML element without increasing the nesting depth of the resulting object. Like `hash`, it accepts an XPath and a block, but the attributes created from within the block will not be wrapped in a hash.
+
+```ruby
+with 'Some/Nested/Data' do
+  scalar 'Value'
+end
+```
+
+There is no plural form for `with` since it would, by necessity, create duplicate keys.

data/Rakefile

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

data/bin/pry

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'pry' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('pry', 'pry')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/decontaminate.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'decontaminate/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'decontaminate'
+  spec.version       = Decontaminate::VERSION
+  spec.authors       = ['Alexis King']
+  spec.email         = ['lexi.lambda@gmail.com']
+
+  spec.summary       = 'Convert XML to JSON with a DSL'
+  spec.homepage      = 'https://github.com/lexi-lambda/decontaminate'
+  spec.licenses      = ['ISC']
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 1.9'
+
+  spec.add_runtime_dependency 'activesupport', '~> 4.2'
+  spec.add_runtime_dependency 'nokogiri', '~> 1.6'
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'pry', '~> 0.10.3'
+  spec.add_development_dependency 'pry-byebug', '~> 3.2'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.3'
+  spec.add_development_dependency 'yard', '~> 0.8.7'
+end

data/lib/decontaminate/decoder/array.rb

@@ -0,0 +1,19 @@
+module Decontaminate
+  module Decoder
+    class Array
+      attr_reader :xpath, :decoder
+
+      def initialize(xpath, decoder)
+        @xpath = xpath
+        @decoder = decoder
+      end
+
+      def decode(xml_node)
+        children = xml_node.xpath xpath
+        children.map do |child|
+          decoder.decode child
+        end
+      end
+    end
+  end
+end

data/lib/decontaminate/decoder/child_node_proxy.rb

@@ -0,0 +1,17 @@
+module Decontaminate
+  module Decoder
+    class ChildNodeProxy
+      attr_reader :xpath, :decoder
+
+      def initialize(xpath, decoder)
+        @xpath = xpath
+        @decoder = decoder
+      end
+
+      def decode(xml_node)
+        child = xml_node.at_xpath xpath
+        decoder.decode child
+      end
+    end
+  end
+end

data/lib/decontaminate/decoder/hash.rb

@@ -0,0 +1,17 @@
+module Decontaminate
+  module Decoder
+    class Hash
+      attr_reader :xpath, :decontaminator
+
+      def initialize(xpath, decontaminator)
+        @xpath = xpath
+        @decontaminator = decontaminator
+      end
+
+      def decode(xml_node)
+        child = xml_node.at_xpath xpath
+        decontaminator.new(child).as_json
+      end
+    end
+  end
+end

data/lib/decontaminate/decoder/scalar.rb

@@ -0,0 +1,38 @@
+module Decontaminate
+  module Decoder
+    class Scalar
+      attr_reader :xpath, :type
+
+      def initialize(xpath, type)
+        @xpath = xpath
+        @type = type
+      end
+
+      def decode(xml_node)
+        child = xml_node.at_xpath xpath
+        text = coerce_node_to_text child
+
+        return unless text
+
+        case type
+        when :string
+          text
+        when :integer
+          text.to_i
+        when :float
+          text.to_f
+        end
+      end
+
+      private
+
+      def coerce_node_to_text(node)
+        if node.is_a?(Nokogiri::XML::Text) || node.is_a?(Nokogiri::XML::Attr)
+          node.to_s
+        else
+          node.at_xpath('text()').to_s
+        end
+      end
+    end
+  end
+end

data/lib/decontaminate/decontaminator.rb

@@ -0,0 +1,109 @@
+require 'active_support/inflector'
+
+require_relative 'decoder/array'
+require_relative 'decoder/child_node_proxy'
+require_relative 'decoder/hash'
+require_relative 'decoder/scalar'
+
+module Decontaminate
+  # Decontaminate::Decontaminator is the base class for creating XML extraction
+  # parsers. A DSL is exposed via class methods to allow specifying how the XML
+  # should be parsed.
+  class Decontaminator
+    class << self
+      attr_accessor :root
+      attr_reader :decoders
+
+      def inherited(subclass)
+        subclass.instance_eval do
+          @root = '.'
+          @decoders = {}
+        end
+      end
+
+      def scalar(xpath, type: :string, key: infer_key(xpath))
+        add_decoder key, Decontaminate::Decoder::Scalar.new(xpath, type)
+      end
+
+      def scalars(xpath = nil, path: nil, type: :string, key: nil)
+        resolved_path = path || infer_plural_path(xpath)
+        key ||= infer_key(path || xpath)
+
+        singular = Decontaminate::Decoder::Scalar.new('.', type)
+        decoder = Decontaminate::Decoder::Array.new(resolved_path, singular)
+
+        add_decoder key, decoder
+      end
+
+      def hash(xpath, key: infer_key(xpath), &body)
+        decontaminator = Class.new(Decontaminate::Decontaminator, &body)
+        add_decoder key, Decontaminate::Decoder::Hash.new(xpath, decontaminator)
+      end
+
+      def hashes(xpath = nil, path: nil, key: nil, &body)
+        resolved_path = path || infer_plural_path(xpath)
+        key ||= infer_key(path || xpath)
+
+        decontaminator = Class.new(Decontaminate::Decontaminator, &body)
+        singular = Decontaminate::Decoder::Hash.new('.', decontaminator)
+        decoder = Decontaminate::Decoder::Array.new(resolved_path, singular)
+
+        add_decoder key, decoder
+      end
+
+      def with(xpath, &body)
+        this = self
+        decontaminator = Class.new(Decontaminate::Decontaminator)
+
+        decontaminator.instance_eval do
+          define_singleton_method :add_decoder do |key, decoder|
+            proxy = Decontaminate::Decoder::ChildNodeProxy.new(xpath, decoder)
+            this.add_decoder key, proxy
+          end
+        end
+
+        decontaminator.class_eval(&body)
+      end
+
+      def add_decoder(key, decoder)
+        fail "Decoder already registered for key #{key}" if decoders.key? key
+        decoders[key] = decoder
+      end
+
+      def infer_key(xpath)
+        xpath.delete('@').underscore
+      end
+
+      def infer_plural_path(xpath)
+        xpath + '/' + xpath.split('/').last.singularize
+      end
+    end
+
+    attr_reader :xml_node
+
+    def initialize(xml_node)
+      @xml_node = xml_node
+    end
+
+    def as_json
+      acc = {}
+
+      root_node = xml_node.at_xpath root
+      decoders.each do |key, decoder|
+        acc[key] = decoder.decode root_node
+      end
+
+      acc
+    end
+
+    private
+
+    def decoders
+      self.class.decoders
+    end
+
+    def root
+      self.class.root
+    end
+  end
+end

data/lib/decontaminate/version.rb

@@ -0,0 +1,3 @@
+module Decontaminate
+  VERSION = '0.1.0'
+end

data/lib/decontaminate.rb

@@ -0,0 +1,4 @@
+require 'decontaminate/decontaminator'
+
+module Decontaminate
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: decontaminate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexis King
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-16 00:00:00.000000000 Z
+dependencies:
+- !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.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.3
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !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.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+description: 
+email:
+- lexi.lambda@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/pry
+- bin/rake
+- bin/rspec
+- decontaminate.gemspec
+- lib/decontaminate.rb
+- lib/decontaminate/decoder/array.rb
+- lib/decontaminate/decoder/child_node_proxy.rb
+- lib/decontaminate/decoder/hash.rb
+- lib/decontaminate/decoder/scalar.rb
+- lib/decontaminate/decontaminator.rb
+- lib/decontaminate/version.rb
+homepage: https://github.com/lexi-lambda/decontaminate
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Convert XML to JSON with a DSL
+test_files: []
+has_rdoc: