rusty 0.1

data/.gitignore

@@ -0,0 +1,2 @@
+coverage
+rdoc

data/Gemfile

@@ -0,0 +1,9 @@
+gemspec
+
+group :development do
+  gem "rake"
+  gem "rdoc"
+  gem "test-unit"
+  gem "ruby-debug19"
+  gem "simplecov"
+end

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    rusty (0.1)
+      nokogiri
+
+GEM
+  specs:
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.6)
+    json (1.7.7)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    multi_json (1.6.1)
+    nokogiri (1.5.6)
+    rake (10.0.3)
+    rdoc (3.12.1)
+      json (~> 1.4)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    test-unit (2.5.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rdoc
+  ruby-debug19
+  rusty!
+  simplecov
+  test-unit

data/LICENSE.BSD

@@ -0,0 +1,26 @@
+Parts of this package are copyrighted under the terms of the modified BSD license.
+
+Copyright (c) 2011, 2012, @radiospiel.
+  
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * No names of the contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,200 @@
+# Ever wanted to parse XML, but hated all the hassle?
+
+Rusty is here to help. Lets start with a small example:
+
+    require "rusty"
+    
+    # A simple RSS parser
+    module SimpleRSS
+      extend Rusty::RuleSet
+      helper Rusty::Helpers::Text
+
+      on "*"                  do end
+      on "rss channel *"      do rss[node.name] = text(node) end
+      on "rss channel item"   do rss.items << item end
+      on "rss channel item *" do item[node.name] = text(node) end
+    end
+
+    doc = Nokogiri.XML File.read("stressfaktor.xml")
+    data = SimpleRSS.transform! doc
+    p data.rss.to_ruby
+
+Interested? Read on.
+
+## Transforming nodes
+
+Each XML and HTML document, after being parsed by Nokogiri, is represented as a tree of nodes.
+A transformation would visit all the nodes in the input document and do something with the data
+in it. A trivial 1:1 transformation would recreate the tree with the same data. This is obviously
+not what you want; what you want is probably to build a *different* tree, with some information, 
+and/or to do something else entirely.
+
+rusty is here to help you.
+
+- It let you define procedures to run on nodes, specified by CSS selectors, and
+- it provides a simple name lookup when in fact creating a data structure.
+
+And this works miracles.
+
+## Defining callbacks
+
+Rusty knows two different kind of callbacks. The `on` callback, which is run before processing a node's children, and the `after` callback, which is run once all children have been visited.
+
+    module SimpleRSS
+      extend Rusty::RuleSet
+
+      on "rss channel item"       do puts "Hu! An item node" end
+      on "rss channel item *"     do puts "A child of an item" end
+      after "rss channel item"    do puts "Now I have seen all of the item's children" end
+    end
+
+There is an additional way to define a callback, which makes some sense if you need both an "on" and an "after" callback for the same nodes, and probably want to share some information between these:
+  
+    module SimpleRSS
+      extend Rusty::RuleSet
+
+      on "rss channel item" do 
+        start = Time.now
+        callback do
+          puts "Parsing the item took #{Time.now - start} secs."
+        end
+      end
+    end
+
+## Defining callbacks
+
+Rusty knows two different kind of callbacks. The `on` callback, which is run before processing a node's children, and the `after` callback, which is run once all children have been visited.
+
+    module SimpleRSS
+      extend Rusty::RuleSet
+
+      on "rss channel item"       do puts "Hu! An item node" end
+      on "rss channel item *"     do puts "A child of an item" end
+      after "rss channel item"    do puts "Now I have seen all of the item's children" end
+    end
+
+There is an additional way to define a callback, which makes some sense if you need both an "on" and an "after" callback for the same nodes, and probably want to share some information between these:
+  
+    module SimpleRSS
+      extend Rusty::RuleSet
+
+      on "rss channel item"       do 
+        puts "Hu! An item node" 
+        callback do
+          puts "Now I have seen all of the item's children" end
+        end
+      end
+    end
+
+`after` and `callback` callbacks can coexist.
+
+## Creating output data
+
+One case to parse XML is to recreate some kind of data structure which resembles some or all of the XML's input. To support this mode of operation rusty "mirrors" input nodes with output data nodes. To further help you rusty comes with a nimble name lookup scheme in its callbacks. Whenever you use an undeclared name in a callback, rusty goes up to the parent of the document to find a node with a matching name:
+
+    module SimpleRSS
+      extend Rusty::RuleSet
+
+      on "rss" do
+        rss.item_count = 0
+        callback do
+          puts "There are #{rss.item_count} items in the input"
+        end
+      end
+      
+      on "rss channel item" do 
+        rss.count += 1
+      end
+    end
+
+What happens with the resulting data is up to you. By default rusty throws away all resulting data except what belongs to the top node of the document. In the above example SimpleRSS.transform! would return a hash 
+
+    { count => <some_number> }
+
+If you want to keep a node's data you must put it somewhere, as in the following example:
+
+    on "rss channel item"   do rss.items << item end
+
+## Node names
+
+What is a matching name? While XML documents may come with names that might make sense, HTML usually does not. After all, a `<div>` is a `<div>` no matter what.
+
+For that reason rusty matches both node names and node classes when looking up a node by name. (And yes, that means a node might have multiple names.) And as of yet node names that are not valid ruby identifiers cannot be used in the callback block.
+
+There is one special name, `document`, which refers to the top-most node.
+
+## Rusty data nodes
+
+A Rusty data node (of type Rusty::DX), is a mongrel of a `Hash`, an `Array`, and `nil`. Unless set to something - i.e. as long as being `nil` - it might turn into an Array or a Hash-like structure, depending on what you do to them.
+
+The following makes `rss` a hash:
+
+    rss.key?(:foo)
+    rss.item_count = 0 # Hash entries are automatically created
+
+while the following makes it an array
+
+    rss << 1
+    rss[5] = 25
+
+To get back a stupid ruby object use the `.to_ruby` method, i.e.
+
+    rss.to_ruby # => [ 1, nil, nil, nil, nil, 5 ]
+
+## ..or something else?
+
+Of course you are free to do whatever. After all, each callback is just a piece of ruby code.
+
+    module SimpleRSS
+      extend Rusty::RuleSet
+      helper Rusty::Helpers::Text
+      
+      on "rss channel item *"     do item[node.name] = text(node) end
+      after "rss channel item"    do puts "Found an item: #{item.to_ruby}" end
+    end
+
+## The `*` callback
+
+You will usually see a rule like this:
+    
+    on "*" do end
+
+The "*" selector has a very low weight, meaning it matches all nodes that are not matched by any other rule. This is done to prevent rusty from warning about nodes without a matching rule.
+
+During development you should not use a rule like that. Add it only after you feel confident you get all the data you need form the input.
+
+## Speeding up
+
+Especially when parsing HTML you might find a number of nodes that belong to a subtree in the document which is completely irrelevant. For example, a page like http://www.google.com/movies contains tons of UI elements, which - assuming you would be interested in theater schedules - is just irrelevant. By skipping the entire subtree you might gain some speed when parsing the input:
+
+    on "#navbar, #left_nav" do
+      skip!
+    end
+
+## Helpers and the callback scope
+
+Note that callbacks get a special scope. This scope - a Rusty::CallbackBinding - is responsible for looking up names up the node tree. The only value defined there - apart from things like `object_id`, `class`, etc. is `node`, which refers to the input node.
+
+If you need special functionality you should define helper methods and modules, as in the following example:
+
+    module SimpleRSS
+      extend Rusty::RuleSet
+      helper Rusty::Helpers::Text
+      helper do
+        def a_helper_method(*args)
+        end
+      end
+      on "rss channel item *"     do a_helper_method 1, 2, 3  end
+    end
+
+Rusty comes with the Rusty::Helpers::Text module, which provides a single helper method, `text`, which returns a node's text after cleaning it up.
+
+# That is all.
+
+Rusty does have a number of shortcomings.
+
+- It does not support namespaces,
+- it's CSS selector matching could be faster, 
+- the selector weighting could be more correct,
+
+Don't hesitate to fork away and send pull requests!

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler"
+Bundler.setup :development
+
+Dir.glob("tasks/*.rake").each do |file|
+  load file
+end
+
+task :default => :test
+
+# Add "rake release and rake install"
+Bundler::GemHelper.install_tasks
+
+task :default => [:test, :rdoc]

data/bin/watchr

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+require 'rb-fsevent'
+
+if ARGV.length < 2
+  STDERR.puts "watchr dir ruby-parameter(s)..."
+  abort
+end
+
+paths = ARGV.shift.split(",")
+$args = ARGV.dup
+
+def do_ruby
+  STDERR.puts $args.join(" ")
+  STDERR.puts "=" * 80
+  
+  system(*$args)
+end
+
+puts "Initial run"
+do_ruby
+
+fsevent = FSEvent.new
+fsevent.watch paths do |directories|
+  puts "Detected change inside: #{directories.inspect}"
+  do_ruby
+end
+fsevent.run

data/lib/rusty.rb

@@ -0,0 +1,16 @@
+# This file is part of the rusty ruby gem.
+#
+# Copyright (c) 2013 @radiospiel
+# Distributed under the terms of the modified BSD license, see LICENSE.BSD
+require "nokogiri"
+
+module Rusty; end
+
+require_relative "rusty/version"
+require_relative "rusty/nokogiri_ext"
+require_relative "rusty/dx"
+require_relative "rusty/scope"
+require_relative "rusty/helpers"
+require_relative "rusty/callback_binding"
+require_relative "rusty/selector"
+require_relative "rusty/rule_set"

data/lib/rusty/callback_binding.rb

@@ -0,0 +1,71 @@
+# This file is part of the rusty ruby gem.
+#
+# Copyright (c) 2013 @radiospiel
+# Distributed under the terms of the modified BSD license, see LICENSE.BSD
+
+# CallbackBinding objects are used to provide name lookup for callbacks. 
+# They are set up in such a way that unknown identifiers might traverse
+# up the parents of a node to find a finally matching node. This allows
+# the "top" node in the following callback to be refered by the name
+# "top", like this:
+#
+#     on "top p" { top.attribute = "p" }
+#
+class Rusty::CallbackBinding < Object #BasicObject
+  #
+  # Create a subclass with a given name and a set of helper modules.
+  def self.subclass_with_name_and_helpers(name, *helpers)
+    name = name.split("::").last
+
+    ::Class.new(self).tap do |klass|
+      const_set name, klass
+      klass.send :include, *helpers
+    end
+  end
+
+  # create an event scope which wraps a node scope.
+  def initialize(scope)
+    @scope = scope
+  end
+  
+  # -- special attributes -----------------------------------------------------
+  
+  # callback: set a callback proc which will be called after a node is 
+  # processed completely.
+  def callback(&block)
+    @callback = block if block
+    @callback
+  end
+  
+  # skip!: allow to skip completely skip children.
+  def skip!
+    @skip = true
+  end
+  
+  # Should children be skipped?
+  def skip?
+    !!@skip
+  end
+  
+  # If the missing method is an identifier and has no arguments, this method 
+  # looks in this node scope and its parent scopes for a scope with that name. 
+  # If there is no such target scope, the message is forwarded to the 
+  # node scope (which has its own set of magic, see Rusty::DX)
+  def method_missing(sym, *args, &block)
+    target = if !block && args.empty? && sym =~ /^[A-Za-z_][A-Za-z_0-9]*$/
+      up_scope!(sym.to_s)
+    end
+
+    (target || @scope).send sym, *args, &block
+  end
+  
+  private
+  
+  def up_scope!(name)
+    @scope.up! do |scope| 
+      return scope if scope.has_name?(name) 
+    end
+
+    nil
+  end
+end

data/lib/rusty/dx.rb

@@ -0,0 +1,127 @@
+# This file is part of the rusty ruby gem.
+#
+# Copyright (c) 2013 @radiospiel
+# Distributed under the terms of the modified BSD license, see LICENSE.BSD
+
+require "forwardable"
+
+# A flexible data object which may act either as a hash or an array.
+# It automatically initialises as array or hash, when used in a context
+# which requires one or the other usage.
+class Rusty::DX
+  
+  # -- set up storage ---------------------------------------------------------
+
+  # The hash storage implementation.
+  class Dict < Hash
+    DELEGATE_METHODS  = [:[], :[]=, :key?]
+    module Delegator
+      extend Forwardable
+      delegate DELEGATE_METHODS => :@storage
+    end
+
+    def initialize
+      super { |hash, key| hash[key] = Rusty::DX.new }
+    end
+  end
+
+  # The array storage implementation.
+  class List < Array
+    DELEGATE_METHODS = [:[], :[]=, :<<, :first]
+    module Delegator
+      extend Forwardable
+      delegate DELEGATE_METHODS => :@storage
+    end
+  end
+
+  def inspect
+    "<#{@storage ? @storage.inspect : "nil"}>"
+  end
+
+  private
+  
+  def __storage(klass)
+    if @storage
+      raise ArgumentError, "Cannot change type to #{klass}" unless @storage.is_a?(klass)
+      @storage
+    else
+      extend klass::Delegator
+      @storage = klass.new
+    end
+  end
+
+  ## -- test mode, convert to ruby objects ------------------------------------
+
+  public
+  
+  # Is this object in hash mode?
+  def dict?; @storage.is_a?(Dict); end
+
+  # Is this object in list mode?
+  def list?; @storage.is_a?(List); end
+
+  
+  def self.to_ruby(object)
+    object.is_a?(Rusty::DX) ? object.to_ruby : object
+  end
+  
+  # convert into a ruby object
+  def to_ruby
+    case @storage
+    when Dict
+      items = @storage.inject([]) do |ary, (k, v)| 
+        ary << k << Rusty::DX.to_ruby(v) 
+      end
+      Hash[*items]
+    when List
+      @storage.map { |v| Rusty::DX.to_ruby(v) }
+    end
+  end
+  
+  # -- method missing magic ---------------------------------------------------
+  
+  public
+  
+  # method_missing automatically sets up storage, and matches method names
+  # with hash keys (when in Dict mode)
+  #
+  # When setting up storage for this object the storage type is determined
+  # by these conditions:
+  #
+  # - identifiers, as getters (i.e. with no arguments), result in Dict storage 
+  # - identifiers, as setters (i.e. with one argument, ending in '='), result
+  #   in Dict storage
+  # - the [] and []= operators result in List storage, if the argument is
+  #   an integer, else in Dict storage.
+  # - Methods that are only implemented in the List or Dict storage determine
+  #   the storage type accordingly. These are set up automatically by evaluating
+  #   {List/Dict}::DELEGATE_METHODS. For example, you cannot push (<<) into a
+  #   Hash, nor you can't ask an array for existence of a key?
+  EXCLUSIVE_LIST_METHODS = List::DELEGATE_METHODS - Dict::DELEGATE_METHODS
+  EXCLUSIVE_DICT_METHODS = Dict::DELEGATE_METHODS - List::DELEGATE_METHODS
+  
+  def method_missing(sym, *args, &block)
+    # A number of missing methods try to initialize this object either as
+    # a hash or an array, and then forward the message to storage.
+    case sym
+    when :[], :[]=
+      raise "#{self.class.name}##{sym}: Missing argument" unless args.length >= 1
+      return __storage(args.first.is_a?(Integer) ? List : Dict).send(sym, *args)
+    when /^([_A-Za-z][_A-Za-z0-9]*)$/
+      if args.length == 0 && block.nil?
+        return __storage(Dict)[sym.to_s]
+      end
+    when /^([_A-Za-z][_A-Za-z0-9]*)=$/
+      if args.length == 1 && block.nil?
+        return __storage(Dict)[$1] = args.first
+      end
+    else
+      return __storage(List).send sym, *args, &block  if EXCLUSIVE_LIST_METHODS.include?(sym)
+      return __storage(Dict).send sym, *args, &block  if EXCLUSIVE_DICT_METHODS.include?(sym)
+    end
+
+    # -- we could not set up nor delegate to storage; run super instead
+    #    (this will raise a unknown method exception.)
+    super
+  end
+end