aniero-treehouse 0.0.2

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2008-06-29
+
+* 1 major enhancement
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,43 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+examples/simple_assignment.rb
+lib/treehouse.rb
+lib/treehouse/metaid.rb
+lib/treehouse/node.rb
+lib/treehouse/node_creator.rb
+lib/treehouse/node_definition.rb
+lib/treehouse/visitor.rb
+lib/treehouse/visitor_definition.rb
+spec/fixtures/assignments.txt
+spec/fixtures/ey00-s00348.xen
+spec/grammars/assignments.rb
+spec/grammars/assignments.treetop
+spec/grammars/dot_xen.rb
+spec/grammars/dot_xen.treetop
+spec/grammars/magic.rb
+spec/integration/assignments_spec.rb
+spec/integration/dot_xen_spec.rb
+spec/integration/magic_spec.rb
+spec/node_creator_spec.rb
+spec/node_definition_spec.rb
+spec/node_spec.rb
+spec/spec_helper.rb
+spec/treehouse_spec.rb
+spec/visitor_definition_spec.rb
+spec/visitor_spec.rb
+tasks/ann.rake
+tasks/bones.rake
+tasks/gem.rake
+tasks/git.rake
+tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake
+tasks/test.rake
+treehouse.gemspec

data/README.txt

@@ -0,0 +1,102 @@
+Treehouse
+    by Nathan Witmer
+    http://github.com/aniero/treehouse
+
+== DESCRIPTION:
+
+Simple node and visitor definitions for Treetop grammars.
+
+== FEATURES/PROBLEMS:
+
+* Simple node definition syntax for defining an AST
+* Simple visitor definition to walk an AST
+
+== SYNOPSIS:
+
+Given a treetop grammar:
+
+  grammar SimpleAssignment
+    rule assignment
+      lhs:variable space* "=" space* rhs:variable <create_node(:assignment)>
+    end
+    rule variable
+      [a-z]+ <create_node(:variable)>
+    end
+    rule space
+      [ ]+
+    end
+  end
+
+You can use Treehouse to define nodes for the grammar:
+
+  module SimpleAssignment
+    include Treehouse::NodeDefinition
+
+    node :assignment, :lhs, :rhs
+    node :variable, :value => :text_value
+  end
+
+When you parse the grammar and call .build, it will return an AST using the nodes you defined, auto-building everything
+for you:
+
+  ast = Parser.parse("foo = bar").build
+
+  ast.class #=> SimpleAssignment::Assignment
+  ast.lhs.class #=> SimpleAssignment::Variable
+  ast.lhs.value #=> "foo"
+
+You can also define visitors for an AST:
+
+  module SimpleAssignment
+    include Treehouse::VisitorDefinition
+
+    visitor :hash_visitor do
+      visits Assignment do |a|
+        hash = {}
+        hash[ visit(lhs) ] = visit(rhs)
+        hash
+      end
+      visits Variable do |v|
+        v.value
+      end
+    end
+  end
+
+  SimpleAssignment::HashVisitor.visit(ast) #=> {"foo" => "bar"}
+
+  See examples/simple_assignment.rb for the full code.
+
+== REQUIREMENTS:
+
+* treetop
+* attributes
+* active_support
+
+== INSTALL:
+
+* sudo gem install aniero-treehouse -s http://gems.github.com
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Nathan Witmer
+
+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/Rakefile

@@ -0,0 +1,25 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'treehouse'
+
+task :default => 'spec:run'
+
+PROJ.name = 'treehouse'
+PROJ.authors = 'Nathan Witmer'
+PROJ.email = 'nwitmer at gmail dot com'
+PROJ.url = 'http://github.com/aniero/treehouse'
+PROJ.rubyforge.name = ''
+PROJ.version = Treehouse.version
+
+PROJ.spec.opts << '--color --format specdoc'
+
+# EOF
+
+depend_on "treetop"
+depend_on "attributes"
+depend_on "activesupport", ">= 2.0.2"

data/examples/simple_assignment.rb

@@ -0,0 +1,54 @@
+require File.join(File.dirname(__FILE__), "..", "lib", "treehouse")
+
+Treetop.load_from_string <<-GRAMMAR
+module SimpleAssignment
+  grammar Grammar
+    rule assignment
+      lhs:variable space* "=" space* rhs:variable <AST.create_node(:assignment)>
+    end
+    rule variable
+      [a-z]+ <AST.create_node(:variable)>
+    end
+    rule space
+      [ ]+
+    end
+  end
+end
+GRAMMAR
+
+module SimpleAssignment
+
+  # Define nodes for the AST
+  module AST
+    include Treehouse::NodeDefinition
+    node :assignment, :lhs, :rhs
+    node :variable, :value => :text_value
+  end
+
+  include Treehouse::VisitorDefinition
+
+  # Define a simple visitor to walk the AST and build a hash
+  visitor :hash_visitor do
+    visits AST::Assignment do |assignment|
+      { visit(assignment.lhs) => visit(assignment.rhs) }
+    end
+    visits AST::Variable do |var|
+      var.value
+    end
+  end
+
+  class Parser < ::Treetop::Runtime::CompiledParser
+    include Grammar
+    def self.parse(io)
+      new.parse(io).build
+    end
+  end
+
+end
+
+require "pp"
+ast = SimpleAssignment::Parser.parse("foo=bar")
+puts "----- AST -----"
+pp ast
+puts "\n----- visitor output -----"
+pp SimpleAssignment::HashVisitor.visit(ast)

data/lib/treehouse.rb

@@ -0,0 +1,52 @@
+module Treehouse
+
+  # :stopdoc:
+  VERSION = '0.0.2'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, *args)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Treehouse
+
+require "rubygems"
+gem "activesupport"
+gem "attributes"
+
+%w(active_support/core_ext/string attributes treetop).each { |lib| require lib }
+
+Treehouse.require_all_libs_relative_to __FILE__

data/lib/treehouse/metaid.rb

@@ -0,0 +1,16 @@
+# thanks, _why!
+class Object
+  # The hidden singleton lurks behind everyone
+  def metaclass; class << self; self; end; end
+  def meta_eval &blk; metaclass.instance_eval &blk; end
+
+  # Adds methods to a metaclass
+  def meta_def name, &blk
+    meta_eval { define_method name, &blk }
+  end
+
+  # Defines an instance method within a class
+  # def class_def name, &blk
+  #   class_eval { define_method name, &blk }
+  # end
+end

data/lib/treehouse/node.rb

@@ -0,0 +1,79 @@
+module Treehouse
+
+  # Treehouse nodes are auto-generated by node definitions (see Treehouse::NodeDefinition).
+  # A node is meant to be a part of an AST external to the AST that Treetop generates at parse-time
+  # with Treetop::Runtime::SyntaxNodes.
+  #
+  class Node
+
+    # Create a subclass of Node with the given attributes, both simple and mapped.
+    #
+    # (see NodeDefinitions#node for more information)
+    #
+    def self.create(*attribs)
+      Class.new(self) do
+        attribs.each do |attrib|
+          case attrib
+          when Symbol, String
+            attribute(attrib.to_s) { raise "no value given for #{attrib}" }
+          when Hash
+            attrib.each do |name, symbol|
+              attribute(name.to_s) { raise "no value given for #{name}" }
+              attribute_mapping[name.to_s] = symbol
+            end
+          end
+        end
+      end
+    end
+
+    # The mapping of attribute names to the auto-build values/methods/lambdas used by create_node
+    def self.attribute_mapping
+      @attribute_mapping ||= {}
+    end
+
+    # Instantiate a node.
+    #
+    # Values can either be a hash of values to set the values of this node's attributes, or a Treetop syntax node
+    # which is used to automatically build this node.
+    #
+    def initialize(values={})
+      if values.kind_of?(Treetop::Runtime::SyntaxNode)
+        build_from_parsed_node(values)
+      else
+        values.each do |name, value|
+          send("#{name}=", value)
+        end
+      end
+    end
+
+    protected
+
+    # Auto-builds this node using the provided parsed node and the defined attributes and mapped attributes.
+    def build_from_parsed_node(parsed_node)
+      attributes.each do |attrib|
+        if value = mapping(attrib)
+          if value.kind_of?(Proc)
+            value = value.call(parsed_node)
+          else
+            value = parsed_node.send(mapping(attrib))
+          end
+        else
+          value = parsed_node.send(attrib)
+        end
+        value = value.map { |val| val.respond_to?(:build) ? val.build : val } if value.kind_of?(Array)
+        value = value.build if value.respond_to?(:build)
+        send("#{attrib}=", value)
+      end
+    end
+
+    def attributes
+      self.class.attributes
+    end
+
+    def mapping(name)
+      self.class.attribute_mapping[name]
+    end
+
+  end
+
+end

data/lib/treehouse/node_creator.rb

@@ -0,0 +1,28 @@
+module Treehouse
+  class NodeCreator
+
+    # Creates a node creator for the given node class. This is meant to act as a stand-in for the treetop
+    # syntax node class.
+    #
+    def initialize(node_class)
+      @node_class = node_class
+    end
+
+    # Returns a new treetop syntax node to act as a standin for a normal syntax node. Before returning the node, 
+    # this defines a build method on the syntax node that will instantiate the node class using the auto-build
+    # functionality. If this build method isn't enough, you'll have to define one yourself inline in the treetop
+    # gramamr.
+    #
+    def new(*args)
+      parsed_node = Treetop::Runtime::SyntaxNode.new(*args)
+
+      node_class = @node_class # local scope for the block below
+      parsed_node.meta_def :build do
+        node_class.new(self)
+      end
+
+      parsed_node
+    end
+
+  end
+end

data/lib/treehouse/node_definition.rb

@@ -0,0 +1,106 @@
+module Treehouse::NodeDefinition
+
+  module ModuleMethods
+
+    # Returns a NodeCreator to act as a stand-in for a normal node class definition.
+    # According to the treetop metagrammar, node class definitions can have more than just a class in them.
+    # For example:
+    #
+    #   rule variable
+    #     [a-z]+ <Variable>
+    #   end
+    #
+    # Instead, use this method to use AST node auto-build functionality. Given
+    #
+    #   node :variable, :value => :text_value
+    #
+    # You can define the grammar as
+    #
+    #   rule variable
+    #     [a-z]+ <create_node(:variable)>
+    #   end
+    #
+    def create_node(name)
+      Treehouse::NodeCreator.new(const_get(name.to_s.camelize))
+    end
+
+    # Define a node.
+    #
+    # This creates a new class (a subclass of Treehouse::Node) with the given attribute names.
+    #
+    # Attribute names can be lists of symbols (simple attributes) and/or a hash of name-value pairs (mapped attributes).
+    # The new class will have attributes matching the names and hash keys given. More on the hash values in a minute.
+    #
+    #   node :foo
+    #
+    # Creates a Foo class in the local scope.
+    #
+    #   node :calculation, :left, :right, :operator => lambda { |node| node.elements[1] }
+    #
+    # Creates a Calculation class with left, right, and operator attributes.
+    #
+    # There are two ways to instantiate a class generated by this method.
+    #
+    # The first method is to provide a hash with name/value pairs for the attributes:
+    #
+    #   c = Calculation.new(:left => "lhs", :right => "rhs", :operator => "=")
+    #   c.left # => "lhs"
+    #
+    # If an attribute isn't initialized in this way, you will get an exception if you try to access it.
+    #
+    # This simple way of instantiating a node can be used in a grammar to build an AST with these nodes manually.
+    #
+    # The second method takes a treetop syntax node and auto-builds the node using the syntax node as a basis.
+    # The auto-build functionality uses the attribute names and mapped attributes in the following way:
+    #
+    # * Simple attributes: calls the method by that name on the syntax node
+    # * Mapped attributes: if the attribute value is a symbol or a string, it calls that method on the syntax node.
+    #   If the attribute value is a lambda, it yields the syntax node to the lambda.
+    #
+    # If the value (or array of values) returned by one of these methods is another syntax node, the auto-build code
+    # will call the build method on each syntax node or array item (assuming each syntax node has a build method,
+    # usually auto-defined using create_node). Any value not responding to the build method is left alone.
+    #
+    # Simple example:
+    #
+    #   rule assignment
+    #     variable:lhs "=" variable:rhs <create_node(:assignment)>
+    #   end
+    #
+    #   node :assignment, :lhs, :rhs
+    #
+    #   Assignment.new(syntax_node) will return an instance with an lhs and rhs set from that node.
+    #
+    # If a block is given, the block is evaluated in the context of the new class (for method definitions, etc.) e.g.
+    #
+    #   node :foo do
+    #     def name; "hello!"; end
+    #   end
+    #   Foo.new.name #=> "hello!"
+    #
+    def node(name, *attribute_names, &blk)
+      klass = Treehouse::Node.create *attribute_names
+      const_set name.to_s.camelize, klass
+      klass.class_eval &blk if block_given?
+    end
+
+  end
+
+  # Include this module to get access to the node and create_node methods.
+  # A good place to include this is in a separate AST module, e.g.
+  #
+  #   module AST
+  #     include NodeDefinition
+  #     node :foo
+  #   end
+  #
+  # And then in your grammar:
+  #
+  #   rule foo
+  #     "foo" <AST.create_node(:foo)>
+  #   end
+  #
+  def self.included(base)
+    base.extend ModuleMethods
+  end
+end