furnace 0.3.0.beta2 → 0.3.0.beta3

data/.yardopts

@@ -1 +1 @@
--m markdown --protected
+-r {Furnace} -m markdown --protected

data/Rakefile

@@ -9,4 +9,13 @@ task :test do
   Dir["test/**/*_test.rb"].each do |file|
     load file
   end
+end
+
+PAGES_REPO = 'git@github.com:whitequark/furnace'
+
+task :pages do
+  system "git clone #{PAGES_REPO} gh-temp/ -b gh-pages; rm gh-temp/* -rf" or abort
+  system "yardoc -o gh-temp/; cd gh-temp/; git add -A; git commit -m 'Updated pages.'" or abort
+  system "cd gh-temp/; git push -f origin gh-pages" or abort
+  FileUtils.rm_rf 'gh-temp'
 end

data/furnace.gemspec

@@ -19,4 +19,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'bacon', '~> 1.1'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
 end

data/lib/furnace.rb

@@ -1,3 +1,15 @@
+# Furnace is a set of tools for writing compilers, translators or
+# static analyzers--any programs which read, manipulate or transform
+# other programs.
+#
+# Currently it provides three independent modules, grouped by the main
+# data structure being used:
+#
+#  * Abstract syntax trees: {AST}
+#  * Control flow graphs: {CFG}
+#  * Transformations: {Transform}
+#
+# Additionally, a simple {Graphviz} adapter is provided.
 module Furnace
   require "furnace/version"
 

data/lib/furnace/ast.rb

@@ -8,11 +8,12 @@ module Furnace
   # garbage collector, but completely eliminates all concurrency
   # and aliasing problems.
   #
-  # See also {Node} and {Processor} for additional
+  # See also {Node}, {Processor} and {Sexp} for additional
   # recommendations and design patterns.
   module AST
   end
 
   require_relative "ast/node"
   require_relative "ast/processor"
+  require_relative "ast/sexp"
 end

data/lib/furnace/ast/node.rb

@@ -67,10 +67,14 @@ module Furnace::AST
     # 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.
+    #
+    # @return [nil]
     def assign_properties(properties)
       properties.each do |name, value|
         instance_variable_set :"@#{name}", value
       end
+
+      nil
     end
     protected :assign_properties
 
@@ -84,6 +88,11 @@ module Furnace::AST
     # yield `(foo)`.
     #
     # If the resulting node would be identical to `self`, does nothing.
+    #
+    # @param  [Symbol, nil] type
+    # @param  [Array, nil]  children
+    # @param  [Hash, nil]   properties
+    # @return [AST::Node]
     def updated(type=nil, children=nil, properties=nil)
       new_type       = type       || @type
       new_children   = children   || @children
@@ -100,6 +109,8 @@ module Furnace::AST
 
     # Compares `self` to `other`, possibly converting with `to_ast`. Only
     # `type` and `children` are compared; metadata is deliberately ignored.
+    #
+    # @return [Boolean]
     def ==(other)
       if equal?(other)
         true
@@ -113,11 +124,16 @@ module Furnace::AST
     end
 
     # Converts `self` to a concise s-expression, omitting any children.
+    #
+    # @return [String]
     def to_s
       "(#{fancy_type} ...)"
     end
 
     # Converts `self` to a pretty-printed s-expression.
+    #
+    # @param  [Integer] indent Base indentation level.
+    # @return [String]
     def to_sexp(indent=0)
       sexp = "#{"  " * indent}(#{fancy_type}"
 
@@ -139,7 +155,7 @@ module Furnace::AST
     end
     alias :inspect :to_sexp
 
-    # Returns `self`.
+    # @return [AST::Node] self
     def to_ast
       self
     end
@@ -149,6 +165,8 @@ module Furnace::AST
     # 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.
+    #
+    # @return [String]
     def fancy_type
       @type.to_s.gsub('_', '-')
     end

data/lib/furnace/ast/processor.rb

@@ -1,5 +1,234 @@
 module Furnace::AST
-  module Processor
+  # Processor is a class which helps transforming one AST into another.
+  # In a nutshell, the {#process} method accepts a {Node} and dispatches
+  # it to a handler corresponding to its type, and returns a (possibly)
+  # updated variant of the node.
+  #
+  # Processor has a set of associated design patterns. They are best
+  # explained with a concrete example. Let's define a simple arithmetic
+  # language and an AST format for it:
+  #
+  # Terminals (AST nodes which do not have other AST nodes inside):
+  #
+  #   * `(integer <int-literal>)`,
+  #
+  # Nonterminals (AST nodes with other nodes as children):
+  #
+  #   * `(add <node> <node>)`,
+  #   * `(multiply <node> <node>)`,
+  #   * `(divide <node> <node>)`,
+  #   * `(negate <node>)`,
+  #   * `(store <node> <string-literal>)`: stores value of `<node>` into a variable named `<string-literal>`,
+  #   * `(load <string-literal>)`: loads value of a variable named `<string-literal>`,
+  #   * `(each <node> ...): computes each of the `<node>`s and prints the result.
+  #
+  # Furnace AST nodes all have the same Ruby class, and therefore they don't
+  # know how to traverse themselves. (A solution which dynamically checks the
+  # type of children is possible, but is slow and error-prone.) So, a subclass
+  # of Processor which knows how to traverse the entire tree should be defined.
+  # Such subclass has a handler for each nonterminal node which recursively
+  # processes children nodes:
+  #
+  #     require 'furnace'
+  #     include Furnace
+  #
+  #     class ArithmeticsProcessor < AST::Processor
+  #       # This method traverses any binary operators such as (add) or (multiply).
+  #       def process_binary_op(node)
+  #         # Children aren't decomposed automatically; it is suggested to use Ruby
+  #         # multiple assignment expansion, as it is very convenient here.
+  #         left_expr, right_expr = node.children
+  #
+  #         # AST::Node#updated won't change node type if nil is passed as a first
+  #         # argument, which allows to reuse the same handler for multiple node types
+  #         # using `alias' (below).
+  #         node.updated(nil, [
+  #           process(left_expr),
+  #           process(right_expr)
+  #         ])
+  #       end
+  #       alias on_add      process_binary_op
+  #       alias on_multiply process_binary_op
+  #       alias on_divide   process_binary_op
+  #
+  #       def on_negate(node)
+  #         # It is also possible to use #process_all for more compact code
+  #         # if every child is a Node.
+  #         node.updated(nil, process_all(node.children))
+  #       end
+  #
+  #       def on_store(node)
+  #         expr, variable_name = node.children
+  #
+  #         # Note that variable_name is not a Node and thus isn't passed to #process.
+  #         node.updated(nil, [
+  #           process(expr),
+  #           variable_name
+  #         ])
+  #       end
+  #
+  #       # (load) is effectively a terminal node, and so it does not need
+  #       # an explicit handler, as the following is the default behavior.
+  #       def on_load(node)
+  #         nil
+  #       end
+  #
+  #       def on_each(node)
+  #         node.updated(nil, process_all(node.children))
+  #       end
+  #     end
+  #
+  # Let's test our ArithmeticsProcessor:
+  #
+  #     include AST::Sexp
+  #     expr = s(:add, s(:integer, 2), s(:integer, 2))
+  #
+  #     p ArithmeticsProcessor.new.process(expr) == expr # => true
+  #
+  # As expected, it does not change anything at all. This isn't actually
+  # very useful, so let's now define a Calculator, which will compute the
+  # expression values:
+  #
+  #     # This Processor folds nonterminal nodes and returns an (integer)
+  #     # terminal node.
+  #     class ArithmeticsCalculator < ArithmeticsProcessor
+  #       def compute_op(node)
+  #         # First, node children are processed and then unpacked to local
+  #         # variables.
+  #         nodes = process_all(node.children)
+  #
+  #         if nodes.all? { |node| node.type == :integer }
+  #           # If each of those nodes represents a literal, we can fold this
+  #           # node!
+  #           values = nodes.map { |node| node.children.first }
+  #           AST::Node.new(:integer, [
+  #             yield(values)
+  #           ])
+  #         else
+  #           # Otherwise, we can just leave the current node in the tree and
+  #           # only update it with processed children nodes, which can be
+  #           # partially folded.
+  #           node.updated(nil, nodes)
+  #         end
+  #       end
+  #
+  #       def on_add(node)
+  #         compute_op(node) { |left, right| left + right }
+  #       end
+  #
+  #       def on_multiply(node)
+  #         compute_op(node) { |left, right| left * right }
+  #       end
+  #     end
+  #
+  # Let's check:
+  #
+  #     p ArithmeticsCalculator.new.process(expr) # => (integer 4)
+  #
+  # Excellent, the calculator works! Now, a careful reader could notice that
+  # the ArithmeticsCalculator does not know how to divide numbers. What if we
+  # pass an expression with division to it?
+  #
+  #     expr_with_division = \
+  #       s(:add,
+  #         s(:integer, 1),
+  #         s(:divide,
+  #           s(:add, s(:integer, 8), s(:integer, 4)),
+  #           s(:integer, 3))) # 1 + (8 + 4) / 3
+  #
+  #     folded_expr_with_division = ArithmeticsCalculator.new.process(expr_with_division)
+  #     p folded_expr_with_division
+  #     # => (add
+  #     #      (integer 1)
+  #     #      (divide
+  #     #        (integer 12)
+  #     #        (integer 3)))
+  #
+  # As you can see, the expression was folded _partially_: the inner `(add)` node which
+  # could be computed was folded to `(integer 12)`, the `(divide)` node is left as-is
+  # because there is no computing handler for it, and the root `(add)` node was also left
+  # as it is because some of its children were not literals.
+  #
+  # Note that this partial folding is only possible because the _data_ format, i.e.
+  # the format in which the computed values of the nodes are represented, is the same as
+  # the AST itself.
+  #
+  # Let's extend our ArithmeticsCalculator class further.
+  #
+  #     class ArithmeticsCalculator
+  #       def on_divide(node)
+  #         compute_op(node) { |left, right| left / right }
+  #       end
+  #
+  #       def on_negate(node)
+  #         # Note how #compute_op works regardless of the operator arity.
+  #         compute_op(node) { |value| -value }
+  #       end
+  #     end
+  #
+  # Now, let's apply our renewed ArithmeticsCalculator to a partial result of previous
+  # evaluation:
+  #
+  #     p ArithmeticsCalculator.new.process(expr_with_division) # => (integer 5)
+  #
+  # Five! Excellent. This is also pretty much how CRuby 1.8 executed its programs.
+  #
+  # Now, let's do some automated bug searching. Division by zero is an error, right?
+  # So if we could detect that someone has divided by zero before the program is even
+  # run, that could save some debugging time.
+  #
+  #     class DivisionByZeroVerifier < ArithmeticsProcessor
+  #       class VerificationFailure < Exception; end
+  #
+  #       def on_divide(node)
+  #         # You need to process the children to handle nested divisions
+  #         # such as:
+  #         # (divide
+  #         #   (integer 1)
+  #         #   (divide (integer 1) (integer 0))
+  #         left, right = process_all(node.children)
+  #
+  #         if right.type == :integer &&
+  #            right.children.first == 0
+  #           raise VerificationFailure, "Ouch! This code divides by zero."
+  #         end
+  #       end
+  #
+  #       def divides_by_zero?(ast)
+  #         process(ast)
+  #         false
+  #       rescue VerificationFailure
+  #         true
+  #       end
+  #     end
+  #
+  #     nice_expr = \
+  #       s(:divide,
+  #         s(:add, s(:integer, 10), s(:integer, 2)),
+  #         s(:integer, 4))
+  #
+  #     p DivisionByZeroVerifier.new.divides_by_zero?(nice_expr)
+  #     # => false. Good.
+  #
+  #     bad_expr = \
+  #       s(:add, s(:integer, 10),
+  #         s(:divide, s(:integer, 1), s(:integer, 0)))
+  #
+  #     p DivisionByZeroVerifier.new.divides_by_zero?(bad_expr)
+  #     # => true. WHOOPS. DO NOT RUN THIS.
+  #
+  # Of course, this won't detect more complex cases... unless you use some partial
+  # evaluation before! The possibilites are endless. Have fun.
+  class Processor
+    # Dispatches `node`. If a node has type `:foo`, then a handler named
+    # `on_foo` is invoked with one argument, the `node`; if there isn't
+    # such a handler, {#handler_missing} is invoked with the same argument.
+    #
+    # If the handler returns `nil`, `node` is returned; otherwise, the return
+    # value of the handler is passed along.
+    #
+    # @param  [AST::Node, nil] node
+    # @return [AST::Node]
     def process(node)
       if node
         # Invoke a specific handler
@@ -16,12 +245,20 @@ module Furnace::AST
       node
     end
 
+    # {#process}es each node from `nodes` and returns an array of results.
+    #
+    # @param  [Array<AST::Node>] nodes
+    # @return [Array<AST::Node>]
     def process_all(nodes)
       nodes.map do |node|
         process node
       end
     end
 
+    # Default handler. Does nothing.
+    #
+    # @param  [AST::Node] node
+    # @return [AST::Node, nil]
     def handler_missing(node)
     end
   end

data/lib/furnace/ast/sexp.rb

@@ -0,0 +1,30 @@
+module Furnace::AST
+  # This simple module is very useful in the cases where one needs
+  # to define deeply nested ASTs from Ruby code, for example, in
+  # tests. It should be used like this:
+  #
+  #     describe YourLanguage::AST do
+  #       include Sexp
+  #
+  #       it "should correctly parse expressions" do
+  #         YourLanguage.parse("1 + 2 * 3").should ==
+  #             s(:add,
+  #               s(:integer, 1),
+  #               s(:multiply,
+  #                 s(:integer, 2),
+  #                 s(:integer, 3)))
+  #       end
+  #     end
+  #
+  # This way the amount of boilerplate code is greatly reduced.
+  module Sexp
+    # Creates a {Node} with type `type` and children `children`.
+    # Note that the resulting node is of the type AST::Node and not a
+    # subclass.
+    # This would not pose a problem with comparisons, as {Node#==}
+    # ignores metadata.
+    def s(type, *children)
+      Node.new(type, children)
+    end
+  end
+end

data/lib/furnace/version.rb

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

data/test/ast_test.rb

@@ -94,9 +94,7 @@ describe AST::Processor do
     lambda { |ast| ast.to_sexp == text }
   end
 
-  class MockProcessor
-    include AST::Processor
-
+  class MockProcessor < AST::Processor
     attr_reader :counts
 
     def initialize
@@ -163,4 +161,20 @@ describe AST::Processor do
     |  (invoke :func))
     SEXP
   end
+
+  extend Furnace::AST::Sexp
+
+  it 'should build sexps' do
+    s(:add,
+      s(:integer, 1),
+      s(:multiply,
+        s(:integer, 2),
+        s(:integer, 3))).should have_sexp(<<-SEXP)
+    |(add
+    |  (integer 1)
+    |  (multiply
+    |    (integer 2)
+    |    (integer 3)))
+    SEXP
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: furnace
 version: !ruby/object:Gem::Version
-  version: 0.3.0.beta2
+  version: 0.3.0.beta3
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-08 00:00:00.000000000 Z
+date: 2012-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -43,6 +43,38 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Furnace is a static code analysis framework for dynamic languages, aimed
   at efficient type and behavior inference.
 email:
@@ -61,6 +93,7 @@ files:
 - lib/furnace/ast.rb
 - lib/furnace/ast/node.rb
 - lib/furnace/ast/processor.rb
+- lib/furnace/ast/sexp.rb
 - lib/furnace/cfg.rb
 - lib/furnace/cfg/algorithms.rb
 - lib/furnace/cfg/graph.rb
@@ -85,7 +118,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1541160448532291935
+      hash: 4298627248929422388
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -99,3 +132,4 @@ signing_key:
 specification_version: 3
 summary: A static code analysis framework
 test_files: []
+has_rdoc: