furnace 0.3.0.beta1 → 0.3.0.beta2

data/.gitignore

@@ -1,6 +1,7 @@
-*.gem
 .bundle
 Gemfile.lock
 pkg/*
 .rbx/
-*.sublime-*
+*.sublime-*
+doc/
+.yardoc/

data/.yardopts

@@ -0,0 +1 @@
+-m markdown --protected

data/Gemfile

@@ -2,3 +2,4 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in furnace.gemspec
 gemspec
+gem 'bacon', github: 'chneukirchen/bacon'

data/Rakefile

@@ -1 +1,12 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'bundler/setup'
+
+task :default => :test
+
+task :test do
+  require 'bacon'
+  Bacon.summary_at_exit
+  Dir["test/**/*_test.rb"].each do |file|
+    load file
+  end
+end

data/furnace.gemspec

@@ -16,4 +16,7 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'bacon', '~> 1.1'
 end

data/lib/furnace/ast/node.rb

@@ -1,28 +1,105 @@
 module Furnace::AST
+  # Node is an immutable class, instances of which represent abstract
+  # syntax tree nodes. It combines semantic information (i.e. anything
+  # that affects the algorithmic properties of a program) with
+  # meta-information (line numbers or compiler intermediates).
+  #
+  # Notes on inheritance
+  # ====================
+  #
+  # The distinction between semantics and metadata is important. Complete
+  # semantic information should be contained within just the {#type} and
+  # {#children} of a Node instance; in other words, if an AST was to be
+  # stripped of all meta-information, it should remain a valid AST which
+  # could be successfully processed to yield a result with the same
+  # algorithmic properties.
+  #
+  # Thus, Node should never be inherited in order to define methods which
+  # affect or return semantic information, such as getters for `class_name`,
+  # `superclass` and `body` in the case of a hypothetical `ClassNode`. The
+  # correct solution is to use a generic Node with a {#type} of `:class`
+  # and three children. See also {Processor} for tips on working with such
+  # ASTs.
+  #
+  # On the other hand, Node can and should be inherited to define
+  # application-specific metadata (see also {#initialize}) or customize the
+  # printing format. It is expected that an application would have one or two
+  # such classes and use them across the entire codebase.
+  #
+  # The rationale for this pattern is extensibility and maintainability.
+  # Unlike static ones, dynamic languages do not require the presence of a
+  # predefined, rigid structure, nor does it improve dispatch efficiency,
+  # and while such a structure can certainly be defined, it does not add
+  # any value but incurs a maintaining cost.
+  # For example, extending the AST even with a transformation-local
+  # temporary node type requires making globally visible changes to
+  # the codebase.
+  #
   class Node
-    attr_reader :type, :children
+    # Returns the type of this node.
+    # @return [Symbol]
+    attr_reader :type
 
+    # Returns the children of this node.
+    # The returned value is frozen.
+    # @return [Array]
+    attr_reader :children
+
+    # Constructs a new instance of Node.
+    #
+    # The arguments `type` and `children` are converted with `to_sym` and
+    # `to_a` respectively. Additionally, the result of converting `children`
+    # is frozen. While mutating the arguments is generally considered harmful,
+    # the most common case is to pass an array literal to the constructor. If
+    # your code does not expect the argument to be frozen, use `#dup`.
+    #
+    # The `properties` hash is passed to {#assign_properties}.
     def initialize(type, children=[], properties={})
-      @type, @children = type.to_sym, children.to_a
+      @type, @children = type.to_sym, children.to_a.freeze
+
+      assign_properties(properties)
+
+      freeze
+    end
+
+    # By default, each entry in the `properties` hash is assigned to
+    # a local variable in this instance of Node. A subclass should define
+    # attribute readers for such variables. The values passed in the hash
+    # are not frozen or whitelisted; such behavior can also be implemented\
+    # by subclassing Node and overriding this method.
+    def assign_properties(properties)
       properties.each do |name, value|
         instance_variable_set :"@#{name}", value
       end
-      freeze
     end
+    protected :assign_properties
 
-    def update(type=nil, children=nil, properties={})
-      new_type     = type     || @type
-      new_children = children || @children
+    protected :dup
+
+    # Returns a new instance of Node where non-nil arguments replace the
+    # corresponding fields of `self`.
+    #
+    # For example, `Node.new(:foo, [ 1, 2 ]).updated(:bar)` would yield
+    # `(bar 1 2)`, and `Node.new(:foo, [ 1, 2 ]).updated(nil, [])` would
+    # yield `(foo)`.
+    #
+    # If the resulting node would be identical to `self`, does nothing.
+    def updated(type=nil, children=nil, properties=nil)
+      new_type       = type       || @type
+      new_children   = children   || @children
+      new_properties = properties || {}
 
       if @type == new_type &&
           @children == new_children &&
-          properties.empty?
+          properties.nil?
         self
       else
-        dup.send :initialize, new_type, new_children, properties
+        dup.send :initialize, new_type, new_children, new_properties
       end
     end
 
+    # Compares `self` to `other`, possibly converting with `to_ast`. Only
+    # `type` and `children` are compared; metadata is deliberately ignored.
     def ==(other)
       if equal?(other)
         true
@@ -35,35 +112,43 @@ module Furnace::AST
       end
     end
 
+    # Converts `self` to a concise s-expression, omitting any children.
     def to_s
       "(#{fancy_type} ...)"
     end
 
+    # Converts `self` to a pretty-printed s-expression.
     def to_sexp(indent=0)
-      str = "#{"  " * indent}(#{fancy_type}"
+      sexp = "#{"  " * indent}(#{fancy_type}"
+
+      first_node_child = children.index do |child|
+        child.is_a?(Node) || child.is_a?(Array)
+      end || children.count
 
-      children.each do |child|
-        if (!children[0].is_a?(Node) && child.is_a?(Node)) ||
-            (children[0].is_a?(Node) && child.is_a?(Node) &&
-              child.children.any? { |c| c.is_a?(Node) || c.is_a?(Array) })
-          str << "\n#{child.to_sexp(indent + 1)}"
+      children.each_with_index do |child, idx|
+        if child.is_a?(Node) && idx >= first_node_child
+          sexp << "\n#{child.to_sexp(indent + 1)}"
         else
-          str << " #{child.inspect}"
+          sexp << " #{child.inspect}"
         end
       end
 
-      str << ")"
+      sexp << ")"
 
-      str
+      sexp
     end
     alias :inspect :to_sexp
 
+    # Returns `self`.
     def to_ast
       self
     end
 
     protected
 
+    # Returns `@type` with all underscores replaced by dashes. This allows
+    # to write symbol literals without quotes in Ruby sources and yet have
+    # nicely looking s-expressions.
     def fancy_type
       @type.to_s.gsub('_', '-')
     end

data/lib/furnace/ast/{strict_visitor.rb → processor.rb}

@@ -1,6 +1,6 @@
 module Furnace::AST
-  module StrictVisitor
-    def visit(node)
+  module Processor
+    def process(node)
       if node
         # Invoke a specific handler
         on_handler = :"on_#{node.type}"
@@ -16,9 +16,9 @@ module Furnace::AST
       node
     end
 
-    def visit_all(nodes)
+    def process_all(nodes)
       nodes.map do |node|
-        visit node
+        process node
       end
     end
 

data/lib/furnace/ast.rb

@@ -1,9 +1,18 @@
-require "furnace"
+module Furnace
+  # Furnace::AST is a library for manipulating abstract syntax trees.
+  #
+  # It embraces immutability; each AST node is inherently frozen at
+  # creation, and updating a child node requires recreating that node
+  # and its every parent, recursively.
+  # This is a design choice. It does create significant pressure on
+  # garbage collector, but completely eliminates all concurrency
+  # and aliasing problems.
+  #
+  # See also {Node} and {Processor} for additional
+  # recommendations and design patterns.
+  module AST
+  end
 
-require "furnace/ast/node"
-require "furnace/ast/visitor"
-require "furnace/ast/strict_visitor"
-
-require "furnace/ast/matcher/special"
-require "furnace/ast/matcher/dsl"
-require "furnace/ast/matcher"
+  require_relative "ast/node"
+  require_relative "ast/processor"
+end

data/lib/furnace/cfg/algorithms.rb

@@ -0,0 +1,193 @@
+module Furnace::CFG
+  module Algorithms
+    def eliminate_unreachable!
+      worklist  = Set[ entry, exit ]
+      reachable = Set[]
+
+      while worklist.any?
+        node = worklist.first
+        worklist.delete node
+        reachable.add node
+
+        node.targets.each do |target|
+          unless reachable.include? target
+            worklist.add target
+          end
+        end
+
+        if node.exception
+          unless reachable.include? node.exception
+            worklist.add node.exception
+          end
+        end
+      end
+
+      @nodes.each do |node|
+        unless reachable.include? node
+          @nodes.delete node
+          yield node if block_given?
+        end
+      end
+
+      flush
+    end
+
+    def merge_redundant!
+      worklist = @nodes.dup
+      while worklist.any?
+        node = worklist.first
+        worklist.delete node
+
+        target = node.targets[0]
+        next if target == @exit
+
+        # Skip explicitly non-redundant nodes
+        if node.metadata[:keep]
+          next
+        end
+
+        if node.targets.uniq == [target] &&
+            target.sources.uniq == [node] &&
+            node.exception == target.exception
+
+          yield node, target if block_given?
+
+          node.insns.delete node.cti
+          @nodes.delete target
+          worklist.delete target
+
+          node.insns.concat target.insns
+          node.cti           = target.cti
+          node.target_labels = target.target_labels
+
+          worklist.add node
+
+          flush
+        elsif node.targets.count == 1 &&
+            node.insns.empty?
+
+          target = node.targets.first
+
+          yield target, node if block_given?
+
+          node.sources.each do |source|
+            index = source.targets.index(node)
+            source.target_labels[index] = target.label
+          end
+
+          @nodes.delete node
+          worklist.delete node
+
+          if @entry == node
+            @entry = target
+          end
+
+          flush
+        end
+      end
+    end
+
+    # Shamelessly stolen from
+    # http://www.cs.colostate.edu/~mstrout/CS553/slides/lecture04.pdf
+    def compute_generic_domination(start, forward)
+      # values of β will give rise to dom!
+      dom = { start => Set[start] }
+
+      @nodes.each do |node|
+        next if node == start
+        dom[node] = @nodes.dup
+      end
+
+      change = true
+      while change
+        change = false
+        @nodes.each do |node|
+          next if node == start
+
+          # Are we computing dominators or postdominators?
+          if forward
+            edges = node.sources + node.exception_sources
+          elsif node.exception.nil?
+            edges = node.targets
+          else
+            edges = node.targets + [ node.exception ]
+          end
+
+          #   Key Idea [for dominators]
+          # If a node dominates all
+          # predecessors of node n, then it
+          # also dominates node n.
+          pred = edges.map do |source|
+            dom[source]
+          end.reduce(:&)
+
+          # An exception handler header node has no regular sources.
+          pred = [] if pred.nil?
+
+          current = Set[node].merge(pred)
+          if current != dom[node]
+            dom[node] = current
+            change = true
+          end
+        end
+      end
+
+      dom
+    end
+
+    def dominators
+      @dominators ||= compute_generic_domination(@entry, true)
+    end
+
+    def postdominators
+      @postdominators ||= compute_generic_domination(@exit, false)
+    end
+
+    # See also {#dominators} for references.
+    def identify_loops
+      loops = Hash.new { |h,k| h[k] = Set.new }
+
+      dom = dominators
+
+      @nodes.each do |node|
+        node.targets.each do |target|
+          #   Back edges
+          # A back edge of a natural loop is one whose
+          # target dominates its source.
+          if dom[node].include? target
+            loops[target].add node
+          end
+        end
+      end
+
+      # At this point, +loops+ contains a list of all nodes
+      # which have a back edge to the loop header. Expand
+      # it to the list of all nodes in the loop.
+      loops.each do |header, nodes|
+        #   Natural loop
+        # The natural loop of a back edge (m→n), where
+        # n dominates m, is the set of nodes x such that n
+        # dominates x and there is a path from x to m not
+        # containing n.
+        pre_header = dom[header]
+        all_nodes  = Set[header]
+
+        nodes.each do |node|
+          all_nodes.merge(dom[node] - pre_header)
+        end
+
+        nodes.replace all_nodes
+      end
+
+      loops.default = nil
+      loops
+    end
+
+    def flush
+      @dominators = nil
+      @postdominators = nil
+
+      super if defined?(super)
+    end
+  end
+end

data/lib/furnace/cfg/graph.rb

@@ -1,5 +1,7 @@
 module Furnace::CFG
   class Graph
+    include Algorithms
+
     attr_reader   :nodes
     attr_accessor :entry, :exit
 
@@ -21,190 +23,7 @@ module Furnace::CFG
       end
     end
 
-    def eliminate_unreachable!
-      worklist  = Set[ entry, exit ]
-      reachable = Set[]
-
-      while worklist.any?
-        node = worklist.first
-        worklist.delete node
-        reachable.add node
-
-        node.targets.each do |target|
-          unless reachable.include? target
-            worklist.add target
-          end
-        end
-
-        if node.exception
-          unless reachable.include? node.exception
-            worklist.add node.exception
-          end
-        end
-      end
-
-      @nodes.each do |node|
-        unless reachable.include? node
-          @nodes.delete node
-          yield node if block_given?
-        end
-      end
-
-      flush
-    end
-
-    def merge_redundant!
-      worklist = @nodes.dup
-      while worklist.any?
-        node = worklist.first
-        worklist.delete node
-
-        target = node.targets[0]
-        next if target == @exit
-
-        # Skip explicitly non-redundant nodes
-        if node.metadata[:keep]
-          next
-        end
-
-        if node.targets.uniq == [target] &&
-            target.sources.uniq == [node] &&
-            node.exception == target.exception
-
-          yield node, target if block_given?
-
-          node.insns.delete node.cti
-          @nodes.delete target
-          worklist.delete target
-
-          node.insns.concat target.insns
-          node.cti           = target.cti
-          node.target_labels = target.target_labels
-
-          worklist.add node
-
-          flush
-        elsif node.targets.count == 1 &&
-            node.insns.empty?
-
-          target = node.targets.first
-
-          yield target, node if block_given?
-
-          node.sources.each do |source|
-            index = source.targets.index(node)
-            source.target_labels[index] = target.label
-          end
-
-          @nodes.delete node
-          worklist.delete node
-
-          if @entry == node
-            @entry = target
-          end
-
-          flush
-        end
-      end
-    end
-
-    # Shamelessly stolen from
-    # http://www.cs.colostate.edu/~mstrout/CS553/slides/lecture04.pdf
-    def compute_generic_domination(start, forward)
-      # values of β will give rise to dom!
-      dom = { start => Set[start] }
-
-      @nodes.each do |node|
-        next if node == start
-        dom[node] = @nodes.dup
-      end
-
-      change = true
-      while change
-        change = false
-        @nodes.each do |node|
-          next if node == start
-
-          # Are we computing dominators or postdominators?
-          if forward
-            edges = node.sources + node.exception_sources
-          elsif node.exception.nil?
-            edges = node.targets
-          else
-            edges = node.targets + [ node.exception ]
-          end
-
-          #   Key Idea [for dominators]
-          # If a node dominates all
-          # predecessors of node n, then it
-          # also dominates node n.
-          pred = edges.map do |source|
-            dom[source]
-          end.reduce(:&)
-
-          # An exception handler header node has no regular sources.
-          pred = [] if pred.nil?
-
-          current = Set[node].merge(pred)
-          if current != dom[node]
-            dom[node] = current
-            change = true
-          end
-        end
-      end
-
-      dom
-    end
-
-    def dominators
-      @dominators ||= compute_generic_domination(@entry, true)
-    end
-
-    def postdominators
-      @postdominators ||= compute_generic_domination(@exit, false)
-    end
-
-    # See also {#dominators} for references.
-    def identify_loops
-      loops = Hash.new { |h,k| h[k] = Set.new }
-
-      dom = dominators
-
-      @nodes.each do |node|
-        node.targets.each do |target|
-          #   Back edges
-          # A back edge of a natural loop is one whose
-          # target dominates its source.
-          if dom[node].include? target
-            loops[target].add node
-          end
-        end
-      end
-
-      # At this point, +loops+ contains a list of all nodes
-      # which have a back edge to the loop header. Expand
-      # it to the list of all nodes in the loop.
-      loops.each do |header, nodes|
-        #   Natural loop
-        # The natural loop of a back edge (m→n), where
-        # n dominates m, is the set of nodes x such that n
-        # dominates x and there is a path from x to m not
-        # containing n.
-        pre_header = dom[header]
-        all_nodes  = Set[header]
-
-        nodes.each do |node|
-          all_nodes.merge(dom[node] - pre_header)
-        end
-
-        nodes.replace all_nodes
-      end
-
-      loops.default = nil
-      loops
-    end
-
-    def sources_for(node, exceptions=false)
+    def sources_for(node, find_exceptions=false)
       unless @source_map
         @source_map = Hash.new { |h, k| h[k] = [] }
         @exception_source_map = Hash.new { |h, k| h[k] = [] }
@@ -226,7 +45,7 @@ module Furnace::CFG
         end
       end
 
-      if exceptions
+      if find_exceptions
         @exception_source_map[node]
       else
         @source_map[node]
@@ -237,8 +56,7 @@ module Furnace::CFG
       @source_map = nil
       @label_map.clear
 
-      @dominators = nil
-      @postdominators = nil
+      super if defined?(super)
     end
 
     def to_graphviz

data/lib/furnace/cfg.rb

@@ -1,6 +1,7 @@
 require "set"
 
-require "furnace"
-
-require "furnace/cfg/graph"
-require "furnace/cfg/node"
+module Furnace
+  require_relative "cfg/node"
+  require_relative "cfg/algorithms"
+  require_relative "cfg/graph"
+end

data/lib/furnace/version.rb

@@ -1,3 +1,3 @@
 module Furnace
-  VERSION = "0.3.0.beta1"
+  VERSION = "0.3.0.beta2"
 end