flexparser 1.0.2

data/README.md

@@ -0,0 +1,200 @@
+# Flexparser
+`Flexparser` provides an easy to use DSL for flexible, robust xml parsers.  The goal of eflexparser is to be able to write **One Parser to parse them all**. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flexparser', path: 'vendor/gems/' # Or whereever you have eflexparser stored
+```
+
+Since this gem is private, it can only be vendored into a project right now. 
+
+**BEWARE:** Since i started working on this gem, another gem by the name of `flexparser` has been published to rubygems. So calling `gem install flexparser` will in fact install the wrong gem.
+
+## Usage
+#### Basics:
+
+Including the `Flexparser` module in any Class turns it into a parser. 
+Lets start simple:
+```ruby
+class WebParser
+  include Flexparser
+
+  property 'url'
+end
+```
+Now this class is able to parse xml similar to this:
+```xml
+<url>www.my-page.com</url>
+```
+Now your parser can do this:
+```ruby
+# Assuming the xml variable holds the xml code mentioned above
+website = WebParser.parse xml
+webite.url #=> 'www.my-page.com'
+```
+
+#### Collections
+A `node` command will only return the first value it finds. When you have multiple nodes that interest you, you can get a `collection` of them.
+```ruby
+books = '
+		<work author="H.P. Lovecraft">
+                 <story>The Call of Cthulhu</story>
+                 <story>Dagon</story>
+                 <story>The Nameless City</story>
+                 </work>
+                '
+                 
+class LovecraftParser
+  include Flexparser
+
+  property 'story', collection: true
+end
+
+work = LovecraftParser.parse books
+work.story #=> ['The Call of Cthulhu', 'Dagon', 'The Nameless City']
+```
+
+#### Nested Parsers
+Sometimes you want more than to just xtract a String. This way you can make your parser return complex Objects and nest parsers as deep as you like.
+```ruby
+library = "
+<book>
+  <author>J. R. R. Tolkien</author>
+  <title>The Hobbit</title>
+</book>
+<book>
+  <author>Suzanne Collins</author>
+  <title>The Hunger Games</title>
+</book>"
+
+class LibraryParser
+  include Flexparser
+  
+  property 'book', collection: true do
+    attr_accessor :isbn
+    property 'author'
+    property 'title'
+  end
+end
+
+lib = LibraryParser.parse library
+lib.book.second.authro #=> 'Suzanne Collins'
+lib.book.first.title #=> 'The Hobbit'
+lib.book.first.isbn = '9780582186552'
+lib.book.first.isbn #=> '9780582186552'
+```
+With nested parsers, anonymous classes are defined inside an existing parser. Therefore you can define methods all you like (should the need arise).
+
+#### Tag Definitions
+You might not always know (or it might not always be the same), what the information you are looking for is called. If that is the case, you can define multiple tags for the same property. Here are a few examples:
+```ruby
+class UniParser
+  include Flexparser
+  
+  # Creates accessors called 'url' and 'url=' but will look for nodes with the name url, link and website. Will return the first thing it finds.
+  property %w[url link website]
+  
+  # Creates a property called main_header and will look for message and title
+  property %w[message title], name: 'main_header'
+  
+  # This will define a property called width and will look for an attribute of the same name
+  property '@width'
+  
+  # This will define a property called `image_url` that will look for a node called 'image' and extract its 'url' attribute
+  property 'image/@url'
+  
+  # This will look for a tag called encoded with the namespace content
+  property 'content:encoded'
+  
+  # Here we define a transformation to make the parser return an integer
+  property 'height', transform: :to_i
+  
+  # An alternative to the transformation is a type. The type must have a #parse method that receives a string
+  property 'url', type: URI
+  
+  # A little bit of everything
+  property %w[image picture @img media:image], name: 'visual', type: URI, collection: true
+end
+```
+### Configuration
+You can configure Flexparser by using a block (for example in an initializer) like so:
+```ruby
+Flexparser.configure do |config|
+  config.option = value
+end
+```
+At time of writing there are two Options:
+
+####  `explicit_property_naming` 
+**Default: ** `true`
+If this is `true` you need to specify a `:name` for your `property` everytime there is more than one tag in your tag-list.
+Example: 
+```ruby
+# Bad!
+property %w[url link website]
+    
+# Good!
+property %w[url link website], name: 'website'
+    
+# Don't care! Unambiguous!
+property 'url'
+property ['width']
+```
+#### `retry_without_namespaces`
+**Default:** `true`
+If true, `Flexparser` will add a second set of xpaths to the list of tags you specified, that will ignore namespaces completely.
+Example: 
+```ruby
+Flexparser.configure { |c| c.retry_without_namespaces = false }
+class SomeParser
+  property 'inventory'
+end
+
+xml = "<inventory xmlns="www.my-inventory.com">james</inventory>"
+
+# The inventory can't be found because it is namespaced.
+SomeParser.parse(xml).inventory #=> nil :(
+
+Flexparser.configure { |c| c.retry_without_namespaces = true }
+class SomeBetterParser
+  property 'inventory'
+end
+
+xml = "<inventory xmlns="www.my-inventory.com">james</inventory>"
+
+# The inventory can be found because we don't care.
+SomeParser.parse(xml).inventory #=> 'james'
+```
+The Xpath used here adheres to xpath version 1.X.X and uses the name property `.//[name()='inventory']`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### How it works (in a nutshell)
+The `Flexparser` module defines certain class methods. Most importantly `property` works in similar ways.
+`property` takes a `String` or an array of strings as well as some options. The `property` method instantiates a `TagParser` and adds it to the `@tags` property of the class that is including `Flexparser` (we'll call it MainClass from here on out), which holds an array of all the `TagParser`s and `CollectionParser`s . It also defines accessors for the *name* of the property the `property` parser should extract. 
+
+The Parsers use an instance of `Flexparser::XPaths` to handle the array of tags that they are passed.
+When everything is setup (i.e. the class is loaded), you can call `::parse` on your MainClass and pass it an XML string.  At this point the MainClass instantiates itself and the `TagParser`s and `CollectionParser`s extract a value from the xml, that is then assigned to the newly created MainClass instance.
+
+#### Defining a parser with a block
+When defining nested parsers, you would use a block. Like this:
+```ruby
+class ParserClass
+  include Flexparser
+  
+  property 'story', collection: true do
+    property 'author'
+    property 'title'
+  end
+end
+```
+When passing a block to a parser definition, a new class is created that basically looks like this:
+```ruby
+Class.new { include Flexparser }
+```
+The block is then `class_eval`ed on this anonymous class. Thats gives you a lot of flexibility in definen your parsers. 

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'flexparser'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/flexparser.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'flexparser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'flexparser'
+  spec.version       = Flexparser::VERSION
+  spec.authors       = ['Paul Martensen']
+  spec.email         = ['paul.martensen@gmx.de']
+  spec.licenses      = ['GPL-3.0']
+  spec.homepage      = 'https://github.com/lokalportal/flexparser'
+  spec.summary       = 'A xml-parser dsl'
+  spec.description   = 'A flexible and robust parser-dsl.'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'nokogiri', '~> 1.7'
+  spec.add_dependency 'xpath', '~> 2.1'
+  spec.add_development_dependency 'guard', '~> 2.14'
+  spec.add_development_dependency 'guard-minitest', '~> 2.4'
+  spec.add_development_dependency 'pry-byebug', '~> 3.4'
+  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+end

data/lib/flexparser.rb

@@ -0,0 +1,37 @@
+require 'xpath'
+require 'nokogiri'
+require 'forwardable'
+
+require 'flexparser/version'
+require 'flexparser/errors'
+require 'flexparser/configuration'
+require 'flexparser/fragment'
+require 'flexparser/xpaths'
+require 'flexparser/empty_fragment'
+require 'flexparser/fragment_builder'
+require 'flexparser/tag_parser'
+require 'flexparser/collection_parser'
+require 'flexparser/class_methods'
+require 'flexparser/anonymous_parser'
+
+#
+# Main module that, when included, provides
+# the including class access to the property building
+# structure.
+#
+module Flexparser
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+end

data/lib/flexparser/anonymous_parser.rb

@@ -0,0 +1,20 @@
+module Flexparser
+  #
+  # A semi-anonymous class used for building the node
+  # structure.
+  #
+  class AnonymousParser
+    extend ClassMethods
+
+    def to_s
+      return super if self.class.parsers.empty?
+      to_h.to_s
+    end
+
+    def to_h
+      self.class.parsers.each_with_object({}) do |parser, hash|
+        hash[parser.name.to_sym] = public_send(parser.name)
+      end
+    end
+  end
+end

data/lib/flexparser/class_methods.rb

@@ -0,0 +1,94 @@
+module Flexparser
+  #
+  # The ClassMethods defined on the including base.
+  #
+  module ClassMethods
+    #
+    # Applies the previously set up property-structure to the given xml
+    # and returns Instances of the including Class.
+    #
+    def parse(xml, _options = {})
+      return if parsers.empty?
+      @doc = FragmentBuilder.build(xml)
+      new.tap do |instance|
+        parsers.each do |parser|
+          instance.public_send("#{parser.name}=", parser.parse(@doc))
+        end
+      end
+    end
+
+    # no-doc
+    def parsers
+      @parsers ||= []
+    end
+
+    protected
+
+    #
+    # Defines a TagParser belonging to the including class.
+    # This Tag parser is used in #parse to parse a piece of xml.
+    # @param [Array<String>] tags The list of tags the parser rattles through.
+    # @option opts [String] :name the name this property should have.
+    #   Overrides the naming derived from the `tags` list.
+    # @option opts [Symbol] :transform a method that will be sent to the
+    #   resulting value to transofrm it. Like `:to_i` or `:to_sym`.
+    # @option opts [Class] :type a class that implements `::parse` to
+    #   return an instance of itself, parsed from the resulting value.
+    # @option opts [Boolean] :required if true, raises an
+    #   `Flexparser::RequiredMissingError` if the resulting value is `nil`.
+    #
+    def property(tags, collection: false, **opts, &block)
+      check_ambiguous_naming!(tags, opts)
+      parser_klass = collection ? CollectionParser : TagParser
+      add_parser(parser_klass, tags, opts, &block)
+    end
+
+    #
+    # Adds a parser with a given class and options to the list
+    # of parsers this class holds.
+    # @see self#property
+    # @param klass [Flexparser::TagParser] either a collection or a single
+    #   {TagParser}
+    #
+    def add_parser(klass, tags, **opts, &block)
+      tags = Array(tags).flatten
+      define_accessors(opts[:name] || tags.first)
+      opts[:sub_parser] = new_parser(&block) if block_given?
+      parsers << klass.new(tags, opts)
+    end
+
+    #
+    # Creates a new anonymous Parser class
+    #   based on {Flexparser::AnonymousParser}.
+    # @param block [Block] The block that holds the classes parser,
+    #   methods and so on.
+    #
+    def new_parser(&block)
+      klass = Class.new(AnonymousParser)
+      klass.instance_eval(&block)
+      klass
+    end
+
+    #
+    # Defines accesors with a given name after sanitizing that name.
+    # @param name [String] the name the accessors shoudl have.
+    #   Will most likely be a tag.
+    #
+    def define_accessors(name)
+      attr_accessor name.to_s.sub(/^@/, '').gsub(/([[:punct:]]|-)+/, '_')
+    end
+
+    #
+    # Raises an error if the name of a parser is ambiguous and the options
+    #   forbid it from beeing so.
+    #
+    def check_ambiguous_naming!(tags, opts)
+      return unless Flexparser.configuration.explicit_property_naming &&
+                    opts[:name].nil? &&
+                    tags.respond_to?(:each) && tags.length > 1
+      raise(AmbiguousNamingError,
+            "You need to specify a name for the property (#{tags})
+            with the :name option.")
+    end
+  end
+end

data/lib/flexparser/collection_parser.rb

@@ -0,0 +1,27 @@
+module Flexparser
+  #
+  # A Parser similar to the TagParser but intendet for a collection
+  # of propertys.
+  # @param sub_parser [Wrench] all CollectionParsers need a subparser to
+  #   deal with the content of the nodes parsed. This should ideally be
+  #   a class that includes Spigots::Wrench and can parse the fragment it
+  #   is dealt.
+  #
+  class CollectionParser < TagParser
+    def parse(doc)
+      content(doc).map do |n|
+        next sub_parser.parse(n) if sub_parser
+        next type.parse(n.text) if type
+        n.text
+      end
+    end
+
+    protected
+
+    def content(doc)
+      content = doc.xpath(xpaths.valid_paths(doc).reduce(&:union).to_s)
+      return content unless content.empty?
+      options[:required] ? raise_required_error(doc) : content
+    end
+  end
+end