saxxy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd0c6946f13251ffc9209c9762cacb8aebb5aa11
+  data.tar.gz: c2780c576c899e594286099289a3062b69be1cb9
+SHA512:
+  metadata.gz: fb7a6ebd8808db1d6265845e5b3128213abf67779edc78ef934047952933fbd21b7b387157696d2c02e4f587130300672506050443dffdb433239adfde9cdd00
+  data.tar.gz: 02c47da0ab97345dba9ddb5ced8edc1a18af56ea2a04e8848ed1637e37d038fd28b4026d60de1a54ae477a383d63afcbea54a26dff8eee0496b0e9554cfeec77

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.bin
+.rspec
+.rbenv-version
+.DS_Store
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+docs/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.2.0
+  - 1.9.3
+  - jruby-19mode

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in saxxy.gemspec
+gemspec
+
+platform :ruby do
+  gem "libxml-ruby", "~>2.8.0"
+  gem "ox"
+  gem "redcarpet"
+end
+
+gem "nokogiri"
+gem "yard"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 rubymaniac
+
+MIT License
+
+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,117 @@
+# `Saxxy` A Ruby DSL for SAX parsers [![Build Status](https://travis-ci.org/rubymaniac/saxxy.png?branch=master)](https://travis-ci.org/rubymaniac/saxxy)
+
+Saxxy is designed to be a DSL for creating SAX parsers. If anyone tells you that you are masochist 'cause you are SAX parsing HTML show her `Saxxy`.
+
+It currently supports [Nokogiri](https://github.com/sparklemotion/nokogiri), [Ox](https://github.com/ohler55/ox), [LibXML](https://github.com/xml4r/libxml-ruby) and is really easy to implement your own parser bindings. It can parse XML out of the box but HTML SAX parsing heavily depends on how the parser handles HTML. Libxml cannot handle malformed HTML at all. Ox and Nokogiri handles the parsing of HTML (even malformed) really well and thus I recommend them.
+
+
+## Dependencies
+
+`Saxxy` requires Ruby >=1.9 or JRuby with JRUBY_OPTS=--1.9
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'saxxy'
+
+Or install it independently of Bundler
+
+    $ gem install saxxy
+
+
+## Getting started
+
+### Overview
+First you must create a service object with a specified parser. It accepts a symbol (`:nokogiri`, `:libxml`, `:ox`) or a class if you made your own parser implementation. It will create a context tree (see `Saxxy::ContextTree` for more details) and will register the callbacks it will call when parsing, as soon as you provide a block. E.g.
+
+```ruby
+require "saxxy/parsers/nokogiri"
+
+service = Saxxy::Service.new(:nokogiri) do
+  under("div", class: /cool$/) do
+    on(/span|div/, rel: "foo") do |inner_text, element, attributes|
+      puts "Under a #{element} found some text: " + inner_text
+    end
+
+    under("table", class: "main") do
+      under("tr", class: "header") do
+        on("td") do |inner_text, element, attributes|
+          puts "Found some other text in a table cell: " + inner_text
+        end
+      end
+    end
+  end
+end
+```
+The service provides either `parse_file`, `parse_string` or `parse_io` methods, depending on you needs. Every method accepts it's corresponding source (with the respective source type) as first argument and an optional encoding as a second argument.
+
+```ruby
+service.parse_string <<-eos
+  <html>
+    <span>
+      Hey I am in a span! <em>And I am nested in a span!</em>
+    </span>
+    <div>
+      Hey I am in a div!
+    </div>
+  </html>
+eos
+
+# => Under a span found some text: Hey I am in a span! And I am nested in a span!
+# => Under a div found some text: Hey I am in a div!
+```
+If the parser doesn't raise some funny error you should be seeing your registered callbacks getting called with the
+text, the element name and the attributes found at the matching node.
+
+
+
+### The DSL
+Saxxy uses a DSL in order to create a context tree and register callbacks. The two most significant methods for doing so is `on` and `under`. The `on` method is used to signify a specific condition and the block it accepts is the callback it will run when the condition is met on a node.
+
+The following example shows a callback that is run when the parser encounters a header element with a class that matches `/foo$/`
+
+```ruby
+on(/^h[1-6]{1}/, class: /foo$/) do |text, element, attributes|
+  p "Element name is: #{element} and the inner text is: #{text}".
+end
+```
+There is now the case where you want to restrict the range of the `on` call only, say, to headers inside a div element with a class footer. To do that you nest the `on` in an `under` call which is used for restricting callbacks' range. E.g.
+
+```ruby
+under("div", class: "footer") do
+  on(/^h[1-6]{1}/, class: /foo$/) do |text, element, attributes|
+    p "Element name is: #{element} and the inner text is: #{text}".
+  end
+end
+```
+
+## Documentation
+You can find the documentation [here](http://rdoc.info/github/rubymaniac/saxxy/frames).
+
+## TODO
+1. Add support for a clean DSL for easily constructing highly nested contexts
+2. Switch to a lazy evaluated context tree
+3. Add more integration tests
+
+## Known Issues
+### Nokogiri
+No issues
+
+### Ox
+No issues
+
+### Libxml
+1. Does not handle the malformed HTML (raises exceptions)
+2. Triggers twice the callbacks on the nodes
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/c6bbeb377f74da9f3e282fa2fbf4b6a3 "githalytics.com")](http://githalytics.com/rubymaniac/saxxy)

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+desc "Open an irb session preloaded with this gem"
+task :console do
+  sh "irb -rubygems -I lib -r saxxy.rb"
+end

data/lib/saxxy.rb

@@ -0,0 +1,2 @@
+require "saxxy/utils/helpers"
+require "saxxy/service"

data/lib/saxxy/activatable.rb

@@ -0,0 +1,160 @@
+module Saxxy
+
+  ##
+  # @author rubymaniac
+  #
+  # Activatable contains all the logic for handling the
+  # activation of an object, whether this is a Context or an Event
+  # or any object that needs to be activated / deactivated multiple times.
+  #
+  # Any Activatable object needs to possess an activation_rule
+  # (assuming automatic activation if activation_rule is nil) in
+  # order to use this to activate / deactivate the object. Everytime
+  # the activation_rule matches an opening node the object gets activated
+  # (by incrementing the internal @deactivation_level) and can be
+  # activated many times. Everytime the activation_rule matches a
+  # closing node the object gets deactivated (by decrementing the internal
+  # @deactivation_level variable) and can be deactivated many times.
+  #
+  # An Activatable object is considered inactive when it's @deactivation_level
+  # equals DLEVEL_MIN i.e. when it has been deactivated as many times as it
+  # has been activated.
+  #
+  # @!attribute [r] activation_rule
+  #   @return [NodeRule] this objects' activation_rule
+  ##
+  module Activatable
+
+    # The lowest integer the deactivation level can reach before the object
+    # is considered inactive.
+    #
+    DLEVEL_MIN = -1
+
+    # Sets an attribute reader to the receiver for the
+    # activation rule.
+    #
+    def self.included(receiver)
+      receiver.send(:attr_reader, :activation_rule)
+    end
+
+    # Initiates the activatable by setting the activation_rule to the
+    # argument, setting the deactivation_level to DLEVEL_MIN and it's
+    # state to inactive
+    #
+    # @param rule [NodeRule] an instance of NodeRule or nil to
+    #   declare that this object is automatically active.
+    #
+    # @return [Symbol] its state (active or inactive)
+    #
+    def initialize_activatable(rule)
+      @activation_rule = rule
+      @deactivation_level = DLEVEL_MIN
+      switch_to(rule ? :inactive : :active)
+    end
+
+    # Sets the callback to run when this object gets deactivated
+    #
+    # @param block [Proc] the code to be executed upon deactivation
+    #
+    # @return self
+    #
+    def on_deactivation(&block)
+      @deactivation_callback = block
+      self
+    end
+
+    # Sets the callback to run when this object gets activated
+    #
+    # @param block [Proc] the code to be executed upon activation
+    #
+    # @return self
+    #
+    def on_activation(&block)
+      @activation_callback = block
+      self
+    end
+
+    # Activates the object on an opening node if it is inactive and can be
+    # activated on the node or it increments the @deactivation_level
+    # if the activation_rule matches the element_name
+    #
+    # @param element_name [String] the nodes' element name
+    # @param attributes [Hash<String, String>] the nodes' attributes
+    #
+    # @return self
+    #
+    def activate_on(element_name, attributes)
+      if is(:inactive) && can_be_activated_on(element_name, attributes)
+        activate!
+      elsif is(:active) && rule_matches_element_name(element_name)
+        increment_level
+      end
+      self
+    end
+
+    # Deactivates the object on a closing node. If the object is inactive
+    # it does nothing, otherwise it decrements the @deactivation_level if
+    # the activation_rule matches the element_name and deactivates the object
+    # if the @deactivation_level is DLEVEL_MIN.
+    #
+    # @param element_name [String] the nodes' element name
+    #
+    # @return self
+    #
+    def deactivate_on(element_name)
+      return unless is(:active)
+      decrement_level if rule_matches_element_name(element_name)
+      deactivate! if closed?
+      self
+    end
+
+    private
+    def activate!
+      run_activation_callback
+      increment_level
+      switch_to(:active)
+    end
+
+    def deactivate!
+      run_deactivation_callback
+      switch_to(:inactive)
+    end
+
+    def is(mode)
+      @mode == mode
+    end
+
+    def switch_to(mode)
+      @mode = mode
+    end
+
+    def closed?
+      @deactivation_level == DLEVEL_MIN
+    end
+
+    def increment_level
+      @deactivation_level += 1
+    end
+
+    def decrement_level
+      @deactivation_level -= 1
+    end
+
+    def run_activation_callback
+      @activation_callback.call(self) if @activation_callback
+    end
+
+    def run_deactivation_callback
+      @deactivation_callback.call(self) if @deactivation_callback
+    end
+
+    def rule_matches_element_name(element_name)
+      activation_rule.nil? || activation_rule.match_element_name(element_name)
+    end
+
+    def can_be_activated_on(element_name, attributes)
+      (activation_rule.nil? || activation_rule.matches(element_name, attributes)) && closed?
+    end
+  end
+
+end

data/lib/saxxy/callbacks/libxml.rb

@@ -0,0 +1,26 @@
+require "libxml"
+require "saxxy/callbacks/sax"
+
+
+module Saxxy
+  module Callbacks
+
+    class Libxml
+      include LibXML::XML::SaxParser::Callbacks
+      include SAX
+
+      def on_start_element_ns(name, attributes, prefix, uri, namespaces)
+        on_start_element(name, attributes)
+      end
+
+      def on_end_element_ns(name, prefix, uri)
+        on_end_element(name)
+      end
+
+      def on_error(error)
+      end
+    end
+
+  end
+end
+

data/lib/saxxy/callbacks/nokogiri.rb

@@ -0,0 +1,30 @@
+require "nokogiri"
+require "saxxy/callbacks/sax"
+
+
+module Saxxy
+  module Callbacks
+
+    class Nokogiri < Nokogiri::XML::SAX::Document
+      include SAX
+
+      def start_element(name, attrs)
+        on_start_element(name, Hash[attrs])
+      end
+
+      def characters(string)
+        on_characters(string)
+      end
+
+      def end_element(name)
+        on_end_element(name)
+      end
+
+      def end_document
+        on_end_document
+      end
+    end
+
+  end
+end
+

data/lib/saxxy/callbacks/ox.rb

@@ -0,0 +1,66 @@
+require "ox"
+require "saxxy/callbacks/sax"
+
+
+module Saxxy
+  module Callbacks
+
+    class Ox < ::Ox::Sax
+      include SAX
+
+      def initialize(context)
+        super(context)
+        reset_state!
+      end
+
+      def start_element(name)
+        on_start_element_after_attr_parsing
+        reset_state!
+        set_name(name)
+      end
+
+      def attr(name, value)
+        push_attr(name, value)
+      end
+
+      def text(string)
+        on_start_element_after_attr_parsing
+        on_characters(string)
+        unset_name
+      end
+
+      def end_element(name)
+        on_start_element_after_attr_parsing
+        on_end_element(name.to_s)
+        reset_state!
+      end
+
+      private
+      def reset_state!
+        @__state = { attrs: {} }
+      end
+
+      def unset_name
+        @__state.delete(:name)
+      end
+
+      def set_name(name)
+        @__state[:name] = name.to_s
+      end
+
+      def push_attr(name, value)
+        @__state[:attrs].merge!(name.to_s => value)
+      end
+
+      def on_start_element_after_attr_parsing
+        on_start_element(@__state[:name], @__state[:attrs]) if start_element_found?
+      end
+
+      def start_element_found?
+        !@__state[:name].nil?
+      end
+    end
+
+  end
+end
+