machete 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+lib/machete/parser.rb
+doc/
+.yardoc
+*.rbc

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 SUSE
+
+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,88 @@
+Machete
+=======
+
+Machete is a simple tool for matching Rubinius AST nodes against patterns. You can use it if you are writing any kind of tool that processes Ruby code and needs to do some work on specific types of nodes, needs to find patterns in the code, etc.
+
+Installation
+------------
+
+You need to install [Rubinius](http://rubini.us/) first. You can then install Machete:
+
+    $ gem install machete
+
+Usage
+-----
+
+First, require the library:
+
+    require "machete"
+
+You can now use one of two methods Machete offers: `Machete.matches?` and `Machete.find`.
+
+The `Machete.matches?` method matches a Rubinus AST node against a pattern:
+
+    Machete.matches?('foo.bar'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+    # => true
+
+    Machete.matches?('42'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+    # => false
+
+(See below for pattern syntax description.)
+
+The `Machete.find` method finds all nodes in a Rubinius AST tree matching a pattern:
+
+    Machete.find('42 + 43 + 44'.to_ast, 'FixnumLiteral')
+    # => [
+    #      #<Rubinius::AST::FixnumLiteral:0x10b0 @value=44 @line=1>,
+    #      #<Rubinius::AST::FixnumLiteral:0x10b8 @value=43 @line=1>,
+    #      #<Rubinius::AST::FixnumLiteral:0x10c0 @value=42 @line=1>
+    #    ]
+
+Pattern Syntax
+--------------
+
+Rubinius AST consists of instances of classes that represent various types of nodes:
+
+    '42'.to_ast     # => #<Rubinius::AST::FixnumLiteral:0xf28 @value=42 @line=1>
+    '"abcd"'.to_ast # => #<Rubinius::AST::StringLiteral:0xf60 @line=1 @string="abcd">
+
+To match a specific node type, just use its class name in the pattern:
+
+    Machete.matches?('42'.to_ast,     'FixnumLiteral') # => true
+    Machete.matches?('"abcd"'.to_ast, 'FixnumLiteral') # => false
+
+If you want to match specific attribute of the node, specify its value inside `<...>` right after the node name:
+
+    Machete.matches?('42'.to_ast, 'FixnumLiteral<value = 42>') # => true
+    Machete.matches?('45'.to_ast, 'FixnumLiteral<value = 42>') # => false
+
+The attribute value can be an integer, string, symbol or other pattern. This means you can easily match nested nodes recursively. You can also specify multiple attributes:
+
+    Machete.matches?('foo.bar'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+    # => true
+
+    Machete.matches?('42'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+    # => false
+
+To specify multiple alternatives, use the choice operator:
+
+    Machete.matches?('42'.to_ast,     'FixnumLiteral | StringLiteral') # => true
+    Machete.matches?('"abcd"'.to_ast, 'FixnumLiteral | StringLiteral') # => true
+
+FAQ
+---
+
+**Why did you chose Rubinius AST as a base? Aren't there other tools for Ruby parsing which are not VM-specific?**
+
+There are three other tools which were considered but each has its issues:
+
+* [parse_tree](http://parsetree.rubyforge.org/) — unmaintained and unsupported for 1.9
+* [ruby_parser](http://parsetree.rubyforge.org/) — sometimes reports wrong line numbers for the nodes (this is a killer for some use cases)
+* [Ripper](http://rubyforge.org/projects/ripper/) — usable but the generated AST is too low level (the patterns would be too complex and low-level)
+
+Rubinius AST is also by far the easiest to work with.
+
+Acknowledgement
+---------------
+
+The general idea and inspiration for the pattern syntax was taken form Python's [2to3](http://docs.python.org/library/2to3.html) tool.

data/Rakefile

@@ -0,0 +1,19 @@
+require "rspec/core/rake_task"
+require "yard"
+
+desc "Generate the expression parser"
+task :parser do
+  source = "lib/machete/parser.y"
+  target = "lib/machete/parser.rb"
+  unless uptodate?(target, source)
+    system "racc -o #{target} #{source}" or exit 1
+  end
+end
+
+RSpec::Core::RakeTask.new
+task :spec => :parser
+
+YARD::Rake::YardocTask.new
+task :yard => :parser
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/machete.rb

@@ -0,0 +1,55 @@
+require File.expand_path(File.dirname(__FILE__) + "/machete/matchers")
+require File.expand_path(File.dirname(__FILE__) + "/machete/parser")
+require File.expand_path(File.dirname(__FILE__) + "/machete/version")
+
+module Machete
+  # Matches a Rubinius AST node against a pattern.
+  #
+  # @param [Rubinius::AST::Node] node node to match
+  # @param [String] pattern pattern to match the node against (see {file:README.md} for syntax description)
+  #
+  # @example Succesfull match
+  #   Machete.matches?('foo.bar'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+  #   # => true
+  #
+  # @example Failed match
+  #   Machete.matches?('42'.to_ast, 'Send<receiver = Send<receiver = Self, name = :foo>, name = :bar>')
+  #   # => false
+  #
+  # @return [Boolean] +true+ if the node matches the pattern, +false+ otherwise
+  #
+  # @raise [Matchete::Parser::SyntaxError] if the pattern is invalid
+  def self.matches?(node, pattern)
+    Parser.new.parse(pattern).matches?(node)
+  end
+
+  # Finds all nodes in a Rubinius AST matching a pattern.
+  #
+  # @param [Rubinius::AST::Node] ast tree to search
+  # @param [String] pattern pattern to match the nodes against (see {file:README.md} for syntax description)
+  #
+  # @example
+  #   Machete.find('42 + 43 + 44'.to_ast, 'FixnumLiteral')
+  #   # => [
+  #   #      #<Rubinius::AST::FixnumLiteral:0x10b0 @value=44 @line=1>,
+  #   #      #<Rubinius::AST::FixnumLiteral:0x10b8 @value=43 @line=1>,
+  #   #      #<Rubinius::AST::FixnumLiteral:0x10c0 @value=42 @line=1>
+  #   #    ]
+  #
+  # @return [Array] list of matching nodes (in unspecified order)
+  #
+  # @raise [Matchete::Parser::SyntaxError] if the pattern is invalid
+  def self.find(ast, pattern)
+    matcher = Parser.new.parse(pattern)
+
+    result = []
+    result << ast if matcher.matches?(ast)
+
+    ast.walk(true) do |dummy, node|
+      result << node if matcher.matches?(node)
+      true
+    end
+
+    result
+  end
+end

data/lib/machete/matchers.rb

@@ -0,0 +1,58 @@
+module Machete
+  # @private
+  module Matchers
+    # @private
+    class ChoiceMatcher
+      attr_reader :alternatives
+
+      def initialize(alternatives)
+        @alternatives = alternatives
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && @alternatives == other.alternatives
+      end
+
+      def matches?(node)
+        alternatives.any? { |a| a.matches?(node) }
+      end
+    end
+
+    # @private
+    class NodeMatcher
+      attr_reader :class_name, :attrs
+
+      def initialize(class_name, attrs = {})
+        @class_name, @attrs = class_name, attrs
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) &&
+          @class_name == other.class_name &&
+          @attrs == other.attrs
+      end
+
+      def matches?(node)
+        node.class == Rubinius::AST.const_get(@class_name) &&
+          attrs.all? { |name, matcher| matcher.matches?(node.send(name)) }
+      end
+    end
+
+    # @private
+    class LiteralMatcher
+      attr_reader :literal
+
+      def initialize(literal)
+        @literal = literal
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && @literal == other.literal
+      end
+
+      def matches?(node)
+        @literal == node
+      end
+    end
+  end
+end

data/lib/machete/parser.y

@@ -0,0 +1,184 @@
+class Machete::Parser
+
+token VAR_NAME
+token CLASS_NAME
+token SYMBOL
+token INTEGER
+token STRING
+
+start expression
+
+rule
+
+expression : primary
+           | expression "|" primary {
+               result = if val[0].is_a?(ChoiceMatcher)
+                 ChoiceMatcher.new(val[0].alternatives << val[2])
+               else
+                 ChoiceMatcher.new([val[0], val[2]])
+               end
+             }
+
+primary : node
+        | literal
+
+node : CLASS_NAME {
+         result = NodeMatcher.new(val[0].to_sym)
+       }
+     | CLASS_NAME "<" attrs ">" {
+         result = NodeMatcher.new(val[0].to_sym, val[2])
+       }
+
+attrs : attr
+      | attrs "," attr { result = val[0].merge(val[2]) }
+
+attr : VAR_NAME "=" expression { result = { val[0].to_sym => val[2] } }
+
+literal : SYMBOL  { result = LiteralMatcher.new(val[0][1..-1].to_sym) }
+        | INTEGER {
+            value = if val[0] =~ /^0[bB]/
+              val[0][2..-1].to_i(2)
+            elsif val[0] =~ /^0[oO]/
+              val[0][2..-1].to_i(8)
+            elsif val[0] =~ /^0[dD]/
+              val[0][2..-1].to_i(10)
+            elsif val[0] =~ /^0[xX]/
+              val[0][2..-1].to_i(16)
+            elsif val[0] =~ /^0/
+              val[0][1..-1].to_i(8)
+            else
+              val[0].to_i
+            end
+            result = LiteralMatcher.new(value)
+          }
+        | STRING {
+            quote = val[0][0..0]
+            value = if quote == "'"
+              val[0][1..-2].gsub("\\\\", "\\").gsub("\\'", "'")
+            elsif quote == '"'
+              val[0][1..-2].
+                gsub("\\\\", "\\").
+                gsub('\\"', '"').
+                gsub("\\n", "\n").
+                gsub("\\t", "\t").
+                gsub("\\r", "\r").
+                gsub("\\f", "\f").
+                gsub("\\v", "\v").
+                gsub("\\a", "\a").
+                gsub("\\e", "\e").
+                gsub("\\b", "\b").
+                gsub("\\s", "\s").
+                gsub(/\\([0-7]{1,3})/) { $1.to_i(8).chr }.
+                gsub(/\\x([0-9a-fA-F]{1,2})/) { $1.to_i(16).chr }
+            else
+              raise "Unknown quote: #{quote.inspect}."
+            end
+            result = LiteralMatcher.new(value)
+          }
+
+---- inner
+
+include Matchers
+
+class SyntaxError < StandardError; end
+
+def parse(input)
+  @input = input
+  @pos = 0
+
+  do_parse
+end
+
+private
+
+SIMPLE_TOKENS = ["|", "<", ">", ",", "="]
+
+COMPLEX_TOKENS = [
+  [:VAR_NAME,   /^[a-z_][a-zA-Z0-9_]*/],
+  [:CLASS_NAME, /^[A-Z][a-zA-Z0-9_]*/],
+  [:SYMBOL,     /^:[a-zA-Z_][a-zA-Z0-9_]*/],
+  [
+    :INTEGER,
+    /^
+      [+-]?                               # sign
+      (
+        0[bB][01]+(_[01]+)*               # binary (prefixed)
+        |
+        0[oO][0-7]+(_[0-7]+)*             # octal (prefixed)
+        |
+        0[dD]\d+(_\d+)*                   # decimal (prefixed)
+        |
+        0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)* # hexadecimal (prefixed)
+        |
+        0[0-7]*(_[0-7]+)*                 # octal (unprefixed)
+        |
+        [1-9]\d*(_\d+)*                   # decimal (unprefixed)
+      )
+    /x
+  ],
+  [
+    :STRING,
+    /^
+      (
+        '                 # sinqle-quoted string
+          (
+            \\[\\']           # escape
+            |
+            [^']              # regular character
+          )*
+        '
+        |
+        "                 # double-quoted string
+          (
+            \\                # escape
+            (
+              [\\"ntrfvaebs]    # one-character escape
+              |
+              [0-7]{1,3}        # octal number escape
+              |
+              x[0-9a-fA-F]{1,2} # hexadecimal number escape
+            )
+            |
+            [^"]              # regular character
+          )*
+        "
+      )
+    /x
+  ]
+]
+
+def next_token
+  skip_whitespace
+
+  return false if remaining_input.empty?
+
+  SIMPLE_TOKENS.each do |token|
+    if remaining_input[0...token.length] == token
+      @pos += token.length
+      return [token, token]
+    end
+  end
+
+  COMPLEX_TOKENS.each do |type, regexp|
+    if remaining_input =~ regexp
+      @pos += $&.length
+      return [type, $&]
+    end
+  end
+
+  raise SyntaxError, "Unexpected character: #{remaining_input[0..0].inspect}."
+end
+
+def skip_whitespace
+  if remaining_input =~ /^[ \t\r\n]+/
+    @pos += $&.length
+  end
+end
+
+def remaining_input
+  @input[@pos..-1]
+end
+
+def on_error(error_token_id, error_value, value_stack)
+  raise SyntaxError, "Unexpected token: #{error_value.inspect}."
+end

data/lib/machete/version.rb

@@ -0,0 +1,3 @@
+module Machete
+  VERSION = File.read(File.dirname(__FILE__) + "/../../VERSION").strip
+end

data/machete.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path(File.dirname(__FILE__) + "/lib/machete/version")
+
+Gem::Specification.new do |s|
+  s.name        = "machete"
+  s.version     = Machete::VERSION
+  s.summary     = "Simple tool for matching Rubinius AST nodes against patterns"
+  s.description = <<-EOT.split("\n").map(&:strip).join(" ")
+    Machete is a simple tool for matching Rubinius AST nodes against patterns.
+    You can use it if you are writing any kind of tool that processes Ruby code
+    and needs to do some work on specific types of nodes, needs to find patterns
+    in the code, etc.
+  EOT
+
+  s.author      = "David Majda"
+  s.email       = "dmajda@suse.de"
+  s.homepage    = "https://github.com/openSUSE/machete"
+  s.license     = "MIT"
+
+  s.files       = `git ls-files`.split("\n") + ["lib/machete/parser.rb"]
+
+  s.add_development_dependency "racc"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rdoc"
+  s.add_development_dependency "rdiscount"
+  s.add_development_dependency "yard"
+end

data/spec/machete/matchers_spec.rb

@@ -0,0 +1,186 @@
+require "spec_helper"
+
+module Machete::Matchers
+  describe ChoiceMatcher do
+    before :each do
+      @alternatives = [
+        LiteralMatcher.new(42),
+        LiteralMatcher.new(43),
+        LiteralMatcher.new(44)
+      ]
+      @matcher = ChoiceMatcher.new(@alternatives)
+    end
+
+    describe "initialize" do
+      it "sets attributes correctly" do
+        @matcher.alternatives.should == @alternatives
+      end
+    end
+
+    describe "==" do
+      it "returns true when passed the same object" do
+        @matcher.should == @matcher
+      end
+
+      it "returns true when passed a ChoiceMatcher initialized with the same parameters" do
+        @matcher.should == ChoiceMatcher.new(@alternatives)
+      end
+
+      it "returns false when passed some random object" do
+        @matcher.should_not == Object.new
+      end
+
+      it "returns false when passed a subclass of ChoiceMatcher initialized with the same parameters" do
+        class SubclassedChoiceMatcher < ChoiceMatcher
+        end
+
+        @matcher.should_not == SubclassedChoiceMatcher.new(@alternatives)
+      end
+
+      it "returns false when passed a ChoiceMatcher initialized with different parameters" do
+        @matcher.should_not == ChoiceMatcher.new([
+          LiteralMatcher.new(45),
+          LiteralMatcher.new(46),
+          LiteralMatcher.new(47)
+        ])
+      end
+    end
+
+    describe "matches?" do
+      it "matches any alternative" do
+        @matcher.matches?(42).should be_true
+        @matcher.matches?(43).should be_true
+        @matcher.matches?(44).should be_true
+      end
+
+      it "does not match a non-alternative" do
+        @matcher.matches?(45).should be_false
+      end
+    end
+  end
+
+  describe NodeMatcher do
+    before :each do
+      @attrs = {
+        :source  => LiteralMatcher.new("abcd"),
+        :options => LiteralMatcher.new(128)
+      }
+      @matcher = NodeMatcher.new(:RegexLiteral, @attrs)
+    end
+
+    describe "initializa" do
+      describe "when passed one parameter" do
+        it "sets attributes correctly" do
+          matcher = NodeMatcher.new(:RegexLiteral)
+
+          matcher.class_name.should == :RegexLiteral
+          matcher.attrs.should == {}
+        end
+      end
+
+      describe "when passed two parameters" do
+        it "sets attributes correctly" do
+          matcher = NodeMatcher.new(:RegexLiteral, @attrs)
+
+          matcher.class_name.should == :RegexLiteral
+          matcher.attrs.should == @attrs
+        end
+      end
+    end
+
+    describe "==" do
+      it "returns true when passed the same object" do
+        @matcher.should == @matcher
+      end
+
+      it "returns true when passed a NodeMatcher initialized with the same parameters" do
+        @matcher.should == NodeMatcher.new(:RegexLiteral, @attrs)
+      end
+
+      it "returns false when passed some random object" do
+        @matcher.should_not == Object.new
+      end
+
+      it "returns false when passed a subclass of NodeMatcher initialized with the same parameters" do
+        class SubclassedNodeMatcher < NodeMatcher
+        end
+
+        @matcher.should_not ==
+          SubclassedNodeMatcher.new(:RegexLiteral, @attrs)
+      end
+
+      it "returns false when passed a NodeMatcher initialized with different parameters" do
+        @matcher.should_not == NodeMatcher.new(:StringLiteral, {
+          :source  => LiteralMatcher.new("abcd"),
+          :options => LiteralMatcher.new(128)
+        })
+        @matcher.should_not == NodeMatcher.new(:RegexLiteral, {
+          :source  => LiteralMatcher.new("efgh"),
+          :options => LiteralMatcher.new(256)
+        })
+      end
+    end
+
+    describe "matches?" do
+      it "matches a node with correct class and matching attributes" do
+        @matcher.matches?(Rubinius::AST::RegexLiteral.new(0, "abcd", 128)).should be_true
+      end
+
+      it "does not match a node with incorrect class" do
+        @matcher.matches?(Rubinius::AST::StringLiteral.new(0, "abcd")).should be_false
+      end
+
+      it "does not match a node with non-matching attributes" do
+        @matcher.matches?(Rubinius::AST::RegexLiteral.new(0, "efgh", 128)).should be_false
+        @matcher.matches?(Rubinius::AST::RegexLiteral.new(0, "efgh", 256)).should be_false
+      end
+    end
+  end
+
+  describe LiteralMatcher do
+    before :each do
+      @matcher = LiteralMatcher.new(42)
+    end
+
+    describe "initialize" do
+      it "sets attributes correctly" do
+        @matcher.literal.should == 42
+      end
+    end
+
+    describe "==" do
+      it "returns true when passed the same object" do
+        @matcher.should == @matcher
+      end
+
+      it "returns true when passed a LiteralMatcher initialized with the same parameters" do
+        @matcher.should == LiteralMatcher.new(42)
+      end
+
+      it "returns false when passed some random object" do
+        @matcher.should_not == Object.new
+      end
+
+      it "returns false when passed a subclass of LiteralMatcher initialized with the same parameters" do
+        class SubclassedLiteralMatcher < LiteralMatcher
+        end
+
+        @matcher.should_not == SubclassedLiteralMatcher.new(42)
+      end
+
+      it "returns false when passed a LiteralMatcher initialized with different parameters" do
+        @matcher.should_not == LiteralMatcher.new(43)
+      end
+    end
+
+    describe "matches?" do
+      it "matches an object equivalent to the literal" do
+        @matcher.matches?(42).should be_true
+      end
+
+      it "does not match an object not equivalent to the literal" do
+        @matcher.matches?(43).should be_false
+      end
+    end
+  end
+end

data/spec/machete/parser_spec.rb

@@ -0,0 +1,262 @@
+require "spec_helper"
+
+module Machete
+  include Matchers
+
+  describe Parser do
+    RSpec::Matchers.define :be_parsed_as do |ast|
+      match do |input|
+        Parser.new.parse(input).should == ast
+      end
+    end
+
+    RSpec::Matchers.define :not_be_parsed do |message|
+      match do |input|
+        lambda {
+          Parser.new.parse(input)
+        }.should raise_exception(Parser::SyntaxError, message)
+      end
+    end
+
+    before :each do
+      @i42 = LiteralMatcher.new(42)
+      @i43 = LiteralMatcher.new(43)
+      @i44 = LiteralMatcher.new(44)
+
+      @foo = NodeMatcher.new(:Foo)
+      @foo_a = NodeMatcher.new(:Foo, :a => @i42)
+      @foo_ab = NodeMatcher.new(:Foo, :a => @i42, :b => @i43)
+
+      @ch4243 = ChoiceMatcher.new([@i42, @i43])
+      @ch424344 = ChoiceMatcher.new([@i42, @i43, @i44])
+    end
+
+    def node_matcher_with_attr(attr)
+      NodeMatcher.new(:Foo, { attr => @i42 })
+    end
+
+    # Canonical expression is "42 | 43".
+    it "parses expression" do
+      '42'.should be_parsed_as(@i42)
+      '42 | 43'.should be_parsed_as(@ch4243)
+      '42 | 43 | 44'.should be_parsed_as(@ch424344)
+    end
+
+    # Canonical primary is "42".
+    it "parses primary" do
+      'Foo<a = 42>'.should be_parsed_as(@foo_a)
+      '42'.should be_parsed_as(@i42)
+    end
+
+    # Canonical node is "Foo".
+    it "parses node" do
+      'Foo'.should be_parsed_as(@foo)
+      'Foo<a = 42, b = 43>'.should be_parsed_as(@foo_ab)
+    end
+
+    # Canonical attrs is "a = 42, b = 43".
+    it "parses attrs" do
+      'Foo<a = 42>'.should be_parsed_as(@foo_a)
+      'Foo<a = 42, b = 43>'.should be_parsed_as(@foo_ab)
+    end
+
+    # Canonical attr is "a = 42".
+    it "parses attr" do
+      'Foo<a = 42 | 43>'.should be_parsed_as(NodeMatcher.new(:Foo, :a => @ch4243))
+    end
+
+    # Canonical literal is "42".
+    it "parses literal" do
+      ':a'.should be_parsed_as(LiteralMatcher.new(:a))
+      '42'.should be_parsed_as(@i42)
+      '"abcd"'.should be_parsed_as(LiteralMatcher.new("abcd"))
+    end
+
+    # Canonical VAR_NAME is "a".
+    it "parses VAR_NAME" do
+      'Foo<a = 42>'.should be_parsed_as(node_matcher_with_attr(:a))
+      'Foo<z = 42>'.should be_parsed_as(node_matcher_with_attr(:z))
+      'Foo<_ = 42>'.should be_parsed_as(node_matcher_with_attr(:_))
+      'Foo<aa = 42>'.should be_parsed_as(node_matcher_with_attr(:aa))
+      'Foo<az = 42>'.should be_parsed_as(node_matcher_with_attr(:az))
+      'Foo<aA = 42>'.should be_parsed_as(node_matcher_with_attr(:aA))
+      'Foo<aZ = 42>'.should be_parsed_as(node_matcher_with_attr(:aZ))
+      'Foo<a0 = 42>'.should be_parsed_as(node_matcher_with_attr(:a0))
+      'Foo<a9 = 42>'.should be_parsed_as(node_matcher_with_attr(:a9))
+      'Foo<a_ = 42>'.should be_parsed_as(node_matcher_with_attr(:a_))
+      'Foo<abcd = 42>'.should be_parsed_as(node_matcher_with_attr(:abcd))
+    end
+
+    # Canonical CLASS_NAME is "A".
+    it "parses CLASS_NAME" do
+      'A'.should be_parsed_as(NodeMatcher.new(:A))
+      'Z'.should be_parsed_as(NodeMatcher.new(:Z))
+      'Aa'.should be_parsed_as(NodeMatcher.new(:Aa))
+      'Az'.should be_parsed_as(NodeMatcher.new(:Az))
+      'AA'.should be_parsed_as(NodeMatcher.new(:AA))
+      'AZ'.should be_parsed_as(NodeMatcher.new(:AZ))
+      'A0'.should be_parsed_as(NodeMatcher.new(:A0))
+      'A9'.should be_parsed_as(NodeMatcher.new(:A9))
+      'A_'.should be_parsed_as(NodeMatcher.new(:A_))
+      'Abcd'.should be_parsed_as(NodeMatcher.new(:Abcd))
+    end
+
+    # Canonical SYMBOL is ":a".
+    it "parses SYMBOL" do
+      ':a'.should be_parsed_as(LiteralMatcher.new(:a))
+      ':z'.should be_parsed_as(LiteralMatcher.new(:z))
+      ':A'.should be_parsed_as(LiteralMatcher.new(:A))
+      ':Z'.should be_parsed_as(LiteralMatcher.new(:Z))
+      ':_'.should be_parsed_as(LiteralMatcher.new(:_))
+      ':aa'.should be_parsed_as(LiteralMatcher.new(:aa))
+      ':az'.should be_parsed_as(LiteralMatcher.new(:az))
+      ':aA'.should be_parsed_as(LiteralMatcher.new(:aA))
+      ':aZ'.should be_parsed_as(LiteralMatcher.new(:aZ))
+      ':a0'.should be_parsed_as(LiteralMatcher.new(:a0))
+      ':a9'.should be_parsed_as(LiteralMatcher.new(:a9))
+      ':a_'.should be_parsed_as(LiteralMatcher.new(:a_))
+      ':abcd'.should be_parsed_as(LiteralMatcher.new(:abcd))
+    end
+
+    # Canonical INTEGER is "42".
+    it "parses INTEGER" do
+      # Sign
+      '+1'.should be_parsed_as(LiteralMatcher.new(1))
+      '-1'.should be_parsed_as(LiteralMatcher.new(-1))
+      '1'.should be_parsed_as(LiteralMatcher.new(1))
+
+      # Binary (prefixed)
+      '0b1'.should be_parsed_as(LiteralMatcher.new(0b1))
+      '0B1'.should be_parsed_as(LiteralMatcher.new(0b1))
+      '0b0'.should be_parsed_as(LiteralMatcher.new(0b0))
+      '0b1'.should be_parsed_as(LiteralMatcher.new(0b1))
+      '0b101'.should be_parsed_as(LiteralMatcher.new(0b101))
+      '0b1_0'.should be_parsed_as(LiteralMatcher.new(0b10))
+      '0b1_1'.should be_parsed_as(LiteralMatcher.new(0b11))
+      '0b1_101'.should be_parsed_as(LiteralMatcher.new(0b1101))
+      '0b1_0_1_0'.should be_parsed_as(LiteralMatcher.new(0b1010))
+
+      # Octall (prefixed)
+      '0o1'.should be_parsed_as(LiteralMatcher.new(0o1))
+      '0O1'.should be_parsed_as(LiteralMatcher.new(0o1))
+      '0o0'.should be_parsed_as(LiteralMatcher.new(0o0))
+      '0o7'.should be_parsed_as(LiteralMatcher.new(0o7))
+      '0o123'.should be_parsed_as(LiteralMatcher.new(0o123))
+      '0o1_0'.should be_parsed_as(LiteralMatcher.new(0o10))
+      '0o1_7'.should be_parsed_as(LiteralMatcher.new(0o17))
+      '0o1_123'.should be_parsed_as(LiteralMatcher.new(0o1123))
+      '0o1_2_3_4'.should be_parsed_as(LiteralMatcher.new(0o1234))
+
+      # Decimal (prefixed)
+      '0d1'.should be_parsed_as(LiteralMatcher.new(0d1))
+      '0D1'.should be_parsed_as(LiteralMatcher.new(0d1))
+      '0d0'.should be_parsed_as(LiteralMatcher.new(0d0))
+      '0d9'.should be_parsed_as(LiteralMatcher.new(0d9))
+      '0d123'.should be_parsed_as(LiteralMatcher.new(0d123))
+      '0d1_0'.should be_parsed_as(LiteralMatcher.new(0d10))
+      '0d1_9'.should be_parsed_as(LiteralMatcher.new(0d19))
+      '0d1_123'.should be_parsed_as(LiteralMatcher.new(0d1123))
+      '0d1_2_3_4'.should be_parsed_as(LiteralMatcher.new(0d1234))
+
+      # Hexadecimal (prefixed)
+      '0x1'.should be_parsed_as(LiteralMatcher.new(0x1))
+      '0X1'.should be_parsed_as(LiteralMatcher.new(0x1))
+      '0x0'.should be_parsed_as(LiteralMatcher.new(0x0))
+      '0x9'.should be_parsed_as(LiteralMatcher.new(0x9))
+      '0xa'.should be_parsed_as(LiteralMatcher.new(0xA))
+      '0xf'.should be_parsed_as(LiteralMatcher.new(0xF))
+      '0xA'.should be_parsed_as(LiteralMatcher.new(0xA))
+      '0xF'.should be_parsed_as(LiteralMatcher.new(0xF))
+      '0x123'.should be_parsed_as(LiteralMatcher.new(0x123))
+      '0x1_0'.should be_parsed_as(LiteralMatcher.new(0x10))
+      '0x1_9'.should be_parsed_as(LiteralMatcher.new(0x19))
+      '0x1_a'.should be_parsed_as(LiteralMatcher.new(0x1A))
+      '0x1_f'.should be_parsed_as(LiteralMatcher.new(0x1F))
+      '0x1_A'.should be_parsed_as(LiteralMatcher.new(0x1A))
+      '0x1_F'.should be_parsed_as(LiteralMatcher.new(0x1F))
+      '0x1_123'.should be_parsed_as(LiteralMatcher.new(0x1123))
+      '0x1_2_3_4'.should be_parsed_as(LiteralMatcher.new(0x1234))
+
+      # Octal (unprefixed)
+      '0'.should be_parsed_as(LiteralMatcher.new(0))
+      '00'.should be_parsed_as(LiteralMatcher.new(0))
+      '07'.should be_parsed_as(LiteralMatcher.new(07))
+      '0123'.should be_parsed_as(LiteralMatcher.new(0123))
+      '0_0'.should be_parsed_as(LiteralMatcher.new(0))
+      '0_7'.should be_parsed_as(LiteralMatcher.new(07))
+      '0_123'.should be_parsed_as(LiteralMatcher.new(0123))
+      '0_1_2_3'.should be_parsed_as(LiteralMatcher.new(0123))
+
+      # Decimal (unprefixed)
+      '1'.should be_parsed_as(LiteralMatcher.new(1))
+      '9'.should be_parsed_as(LiteralMatcher.new(9))
+      '10'.should be_parsed_as(LiteralMatcher.new(10))
+      '19'.should be_parsed_as(LiteralMatcher.new(19))
+      '1234'.should be_parsed_as(LiteralMatcher.new(1234))
+      '1_0'.should be_parsed_as(LiteralMatcher.new(10))
+      '1_9'.should be_parsed_as(LiteralMatcher.new(19))
+      '1_123'.should be_parsed_as(LiteralMatcher.new(1123))
+      '1_2_3_4'.should be_parsed_as(LiteralMatcher.new(1234))
+    end
+
+    # Canonical STRING is "\"abcd\"".
+    it "parses STRING" do
+      "''".should be_parsed_as(LiteralMatcher.new(""))
+      "'a'".should be_parsed_as(LiteralMatcher.new("a"))
+      "'\\\\'".should be_parsed_as(LiteralMatcher.new("\\"))
+      "'\\''".should be_parsed_as(LiteralMatcher.new("'"))
+      "'abc'".should be_parsed_as(LiteralMatcher.new("abc"))
+
+      '""'.should be_parsed_as(LiteralMatcher.new(""))
+      '"a"'.should be_parsed_as(LiteralMatcher.new("a"))
+      '"\\\\"'.should be_parsed_as(LiteralMatcher.new("\\"))
+      '"\\""'.should be_parsed_as(LiteralMatcher.new('"'))
+      '"\\n"'.should be_parsed_as(LiteralMatcher.new("\n"))
+      '"\\t"'.should be_parsed_as(LiteralMatcher.new("\t"))
+      '"\\r"'.should be_parsed_as(LiteralMatcher.new("\r"))
+      '"\\f"'.should be_parsed_as(LiteralMatcher.new("\f"))
+      '"\\v"'.should be_parsed_as(LiteralMatcher.new("\v"))
+      '"\\a"'.should be_parsed_as(LiteralMatcher.new("\a"))
+      '"\\e"'.should be_parsed_as(LiteralMatcher.new("\e"))
+      '"\\b"'.should be_parsed_as(LiteralMatcher.new("\b"))
+      '"\\s"'.should be_parsed_as(LiteralMatcher.new("\s"))
+      '"\\0"'.should be_parsed_as(LiteralMatcher.new("\0"))
+      '"\\7"'.should be_parsed_as(LiteralMatcher.new("\7"))
+      '"\\123"'.should be_parsed_as(LiteralMatcher.new("\123"))
+      '"\\x0"'.should be_parsed_as(LiteralMatcher.new("\x0"))
+      '"\\x9"'.should be_parsed_as(LiteralMatcher.new("\x9"))
+      '"\\xa"'.should be_parsed_as(LiteralMatcher.new("\xa"))
+      '"\\xf"'.should be_parsed_as(LiteralMatcher.new("\xf"))
+      '"\\xA"'.should be_parsed_as(LiteralMatcher.new("\xA"))
+      '"\\xF"'.should be_parsed_as(LiteralMatcher.new("\xF"))
+      '"\\x12"'.should be_parsed_as(LiteralMatcher.new("\x12"))
+      '"abc"'.should be_parsed_as(LiteralMatcher.new("abc"))
+    end
+
+    it "skips whitespace before tokens" do
+      '42'.should be_parsed_as(@i42)
+      ' 42'.should be_parsed_as(@i42)
+      "\t42".should be_parsed_as(@i42)
+      "\r42".should be_parsed_as(@i42)
+      "\n42".should be_parsed_as(@i42)
+      '   42'.should be_parsed_as(@i42)
+    end
+
+    it "skips whitespace after tokens" do
+      '42'.should be_parsed_as(@i42)
+      '42 '.should be_parsed_as(@i42)
+      "42\t".should be_parsed_as(@i42)
+      "42\r".should be_parsed_as(@i42)
+      "42\n".should be_parsed_as(@i42)
+      '42   '.should be_parsed_as(@i42)
+    end
+
+    it "handles lexical errors" do
+      '@#%'.should not_be_parsed("Unexpected character: \"@\".")
+    end
+
+    it "handles syntax errors" do
+      '42 43'.should not_be_parsed("Unexpected token: \"43\".")
+    end
+  end
+end

data/spec/machete_spec.rb

@@ -0,0 +1,39 @@
+require "spec_helper"
+
+describe Machete do
+  describe "matches?" do
+    it "returns true when passed matching node and pattern" do
+      Machete.matches?('42'.to_ast, 'FixnumLiteral<value = 42>').should be_true
+    end
+
+    it "returns false when passed non-matching node and pattern" do
+      Machete.matches?('43'.to_ast, 'FixnumLiteral<value = 42>').should be_false
+    end
+  end
+
+  describe "find" do
+    it "returns [] when no node matches the pattern" do
+      Machete.find('"abcd"'.to_ast, 'FixnumLiteral').should == []
+    end
+
+    it "returns root node if it matches the pattern" do
+      nodes = Machete.find('42'.to_ast, 'FixnumLiteral')
+
+      nodes.size.should == 1
+      nodes[0].should be_instance_of(Rubinius::AST::FixnumLiteral)
+      nodes[0].value.should == 42
+    end
+
+    it "returns child nodes if they match the pattern" do
+      nodes = Machete.find('42 + 43 + 44'.to_ast, 'FixnumLiteral').sort_by(&:value)
+
+      nodes.size.should == 3
+      nodes[0].should be_instance_of(Rubinius::AST::FixnumLiteral)
+      nodes[0].value.should == 42
+      nodes[1].should be_instance_of(Rubinius::AST::FixnumLiteral)
+      nodes[1].value.should == 43
+      nodes[2].should be_instance_of(Rubinius::AST::FixnumLiteral)
+      nodes[2].value.should == 44
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require "machete"
+
+RSpec.configure do |c|
+  c.color_enabled = true
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification 
+name: machete
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- David Majda
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-27 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: racc
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: Machete is a simple tool for matching Rubinius AST nodes against patterns. You can use it if you are writing any kind of tool that processes Ruby code and needs to do some work on specific types of nodes, needs to find patterns in the code, etc.
+email: dmajda@suse.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .yardopts
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/machete.rb
+- lib/machete/matchers.rb
+- lib/machete/parser.y
+- lib/machete/version.rb
+- machete.gemspec
+- spec/machete/matchers_spec.rb
+- spec/machete/parser_spec.rb
+- spec/machete_spec.rb
+- spec/spec_helper.rb
+- lib/machete/parser.rb
+has_rdoc: true
+homepage: https://github.com/openSUSE/machete
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Simple tool for matching Rubinius AST nodes against patterns
+test_files: []
+