ast 2.0.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0b74cff86763a30c7b0b92c2aae6467d904ad2c4
-  data.tar.gz: f829d02411d598e5b470ad57cf726d342349ff07
+SHA256:
+  metadata.gz: e1ea61250ad8d285c9857cb70e2529f827b561b673b01dc02e92cc7bcea81094
+  data.tar.gz: 88c407ffbff0293306bda599d2fe5146bb3504a389f2a69c2c43a8b5c2244446
 SHA512:
-  metadata.gz: 51d6106feef1199a6ae5f347c9121303479d155d13291292a0c733884fd88579f56be461237fd8d21551305649e85c9d556791aab1deaf45bee66ad387bb954c
-  data.tar.gz: a310e6c19a8b83477e855b8fa9d95c1c1de9398b2308d91a84cbf1b84a52004c5193a10ac522474e9ee20f058c469c4e4de38369df2d2d21114b4afc62d196ce
+  metadata.gz: dad932faea02614394a61c4075efb11a2932c6231f9cd11d59d8e7345d8f74d4e7602881fce0e77094017c137159466b92f13ebecaee17e4ee611a0091a3f17a
+  data.tar.gz: 59ea82e96f376f3dc4805a66baa37e577dec80bcad6485ba3a4bc440b27d0ba31ca5d789ca74e7594758f7cfbd279bc75195da8073af17b817e91f714192e874

data/README.YARD.md

@@ -8,5 +8,5 @@ This is a design choice. It does create some pressure on
 garbage collector, but completely eliminates all concurrency
 and aliasing problems.
 
-See also {AST::Node}, {AST::Processor} and {AST::Sexp} for additional
-recommendations and design patterns.
+See also {AST::Node}, {AST::Processor::Mixin} and {AST::Sexp} for
+additional recommendations and design patterns.

data/lib/ast.rb

@@ -7,8 +7,8 @@
 # garbage collector, but completely eliminates all concurrency
 # and aliasing problems.
 #
-# See also {AST::Node}, {AST::Processor} and {AST::Sexp} for additional
-# recommendations and design patterns.
+# See also {AST::Node}, {AST::Processor::Mixin} and {AST::Sexp} for
+# additional recommendations and design patterns.
 #
 module AST
   require 'ast/node'

data/lib/ast/node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AST
   # Node is an immutable class, instances of which represent abstract
   # syntax tree nodes. It combines semantic information (i.e. anything
@@ -42,8 +44,17 @@ module AST
 
     # Returns the children of this node.
     # The returned value is frozen.
+    # The to_a alias is useful for decomposing nodes concisely.
+    # For example:
+    #
+    #     node = s(:gasgn, :$foo, s(:integer, 1))
+    #     var_name, value = *node
+    #     p var_name # => :$foo
+    #     p value    # => (integer 1)
+    #
     # @return [Array]
     attr_reader :children
+    alias to_a children
 
     # Returns the precomputed hash value for this node
     # @return [Fixnum]
@@ -80,7 +91,7 @@ module AST
     # By default, each entry in the `properties` hash is assigned to
     # an instance 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\
+    # are not frozen or whitelisted; such behavior can also be implemented
     # by subclassing Node and overriding this method.
     #
     # @return [nil]
@@ -104,6 +115,7 @@ module AST
     def dup
       self
     end
+    alias :clone :dup
 
     # Returns a new instance of Node where non-nil arguments replace the
     # corresponding fields of `self`.
@@ -128,7 +140,9 @@ module AST
           properties.nil?
         self
       else
-        original_dup.send :initialize, new_type, new_children, new_properties
+        copy = original_dup
+        copy.send :initialize, new_type, new_children, new_properties
+        copy
       end
     end
 
@@ -166,57 +180,71 @@ module AST
 
     alias << append
 
-    # Converts `self` to a concise s-expression, omitting any children.
+    # Converts `self` to a pretty-printed s-expression.
     #
+    # @param  [Integer] indent Base indentation level.
     # @return [String]
-    def to_s
-      "(#{fancy_type} ...)"
-    end
+    def to_sexp(indent=0)
+      indented = "  " * indent
+      sexp = "#{indented}(#{fancy_type}"
 
-    # Returns {#children}. This is very useful in order to decompose nodes
-    # concisely. For example:
-    #
-    #     node = s(:gasgn, :$foo, s(:integer, 1))
-    #     s
-    #     var_name, value = *node
-    #     p var_name # => :$foo
-    #     p value    # => (integer 1)
-    #
-    # @return [Array]
-    def to_a
-      children
+      children.each do |child|
+        if child.is_a?(Node)
+          sexp += "\n#{child.to_sexp(indent + 1)}"
+        else
+          sexp += " #{child.inspect}"
+        end
+      end
+
+      sexp += ")"
+
+      sexp
     end
 
-    # Converts `self` to a pretty-printed s-expression.
+    alias to_s to_sexp
+
+    # Converts `self` to a s-expression ruby string.
+    # The code return will recreate the node, using the sexp module s()
     #
     # @param  [Integer] indent Base indentation level.
     # @return [String]
-    def to_sexp(indent=0)
+    def inspect(indent=0)
       indented = "  " * indent
-      sexp = "#{indented}(#{fancy_type}"
-
-      first_node_child = children.index do |child|
-        child.is_a?(Node) || child.is_a?(Array)
-      end || children.count
+      sexp = "#{indented}s(:#{@type}"
 
-      children.each_with_index do |child, idx|
-        if child.is_a?(Node) && idx >= first_node_child
-          sexp << "\n#{child.to_sexp(indent + 1)}"
+      children.each do |child|
+        if child.is_a?(Node)
+          sexp += ",\n#{child.inspect(indent + 1)}"
         else
-          sexp << " #{child.inspect}"
+          sexp += ", #{child.inspect}"
         end
       end
 
-      sexp << ")"
+      sexp += ")"
 
       sexp
     end
-    alias :inspect :to_sexp
 
     # @return [AST::Node] self
     def to_ast
       self
     end
+    
+    # Converts `self` to an Array where the first element is the type as a Symbol,
+    # and subsequent elements are the same representation of its children. 
+    #
+    # @return [Array<Symbol, [...Array]>]
+    def to_sexp_array
+      children_sexp_arrs = children.map do |child|
+        if child.is_a?(Node)
+          child.to_sexp_array
+        else
+          child
+        end
+      end
+
+      [type, *children_sexp_arrs]
+    end
 
     protected
 

data/lib/ast/processor.rb

@@ -1,266 +1,12 @@
 module AST
-  # 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.
+  # This class includes {AST::Processor::Mixin}; however, it is
+  # deprecated, since the module defines all of the behaviors that
+  # the processor includes.  Any new libraries should use
+  # {AST::Processor::Mixin} instead of subclassing this.
   #
-  # 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.
-  #
-  # All AST nodes 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 'ast'
-  #
-  #     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
-  #
-  #         # 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))
-  #       end
-  #
-  #       def on_store(node)
-  #         expr, variable_name = *node
-  #
-  #         # 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))
-  #       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)
-  #
-  #         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)
-  #
-  #         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.
+  # @deprecated Use {AST::Processor::Mixin} instead.
   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, nil]
-    def process(node)
-      return if node.nil?
-
-      node = node.to_ast
-
-      # Invoke a specific handler
-      on_handler = :"on_#{node.type}"
-      if respond_to? on_handler
-        new_node = send on_handler, node
-      else
-        new_node = handler_missing(node)
-      end
-
-      node = new_node if new_node
-
-      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.to_a.map do |node|
-        process node
-      end
-    end
-
-    # Default handler. Does nothing.
-    #
-    # @param  [AST::Node] node
-    # @return [AST::Node, nil]
-    def handler_missing(node)
-    end
+    require 'ast/processor/mixin'
+    include Mixin
   end
 end

data/lib/ast/processor/mixin.rb

@@ -0,0 +1,288 @@
+module AST
+  class Processor
+    # The processor module is a module 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.
+    #
+    # The processor module 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.
+    #
+    # All AST nodes 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 class including the module which knows how
+    # to traverse the entire tree should be defined.  Such classes
+    # have a handler for each nonterminal node which recursively
+    # processes children nodes:
+    #
+    #     require 'ast'
+    #
+    #     class ArithmeticsProcessor
+    #       include AST::Processor::Mixin
+    #       # 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
+    #
+    #         # 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_method :on_add,      :process_binary_op
+    #       alias_method :on_multiply, :process_binary_op
+    #       alias_method :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))
+    #       end
+    #
+    #       def on_store(node)
+    #         expr, variable_name = *node
+    #
+    #         # 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.  Essentially, for any nodes that don't
+    #       # have a defined handler, the node remains unchanged.
+    #       def on_load(node)
+    #         nil
+    #       end
+    #
+    #       def on_each(node)
+    #         node.updated(nil, process_all(node))
+    #       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)
+    #
+    #         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)
+    #
+    #         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.
+    module Mixin
+      # 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, nil]
+      def process(node)
+        return if node.nil?
+
+        node = node.to_ast
+
+        # Invoke a specific handler
+        on_handler = :"on_#{node.type}"
+        if respond_to? on_handler
+          new_node = send on_handler, node
+        else
+          new_node = handler_missing(node)
+        end
+
+        node = new_node if new_node
+
+        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.to_a.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
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ast
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.4.1
 platform: ruby
 authors:
-- Peter Zotov
+- whitequark
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-21 00:00:00.000000000 Z
+date: 2020-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
 - !ruby/object:Gem::Dependency
   name: bacon
   requirement: !ruby/object:Gem::Requirement
@@ -68,46 +68,18 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: json_pure
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: mime-types
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.25'
+        version: 0.8.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.25'
+        version: 0.8.23
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -143,22 +115,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".travis.yml"
-- ".yardopts"
-- CHANGELOG.md
-- Gemfile
 - LICENSE.MIT
 - README.YARD.md
-- README.md
-- Rakefile
-- ast.gemspec
 - lib/ast.rb
 - lib/ast/node.rb
 - lib/ast/processor.rb
+- lib/ast/processor/mixin.rb
 - lib/ast/sexp.rb
-- test/helper.rb
-- test/test_ast.rb
 homepage: https://whitequark.github.io/ast/
 licenses:
 - MIT
@@ -178,10 +141,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A library for working with Abstract Syntax Trees.
 test_files: []
-has_rdoc: 

data/.gitignore

@@ -1,8 +0,0 @@
-.bundle
-Gemfile.lock
-pkg/*
-.rbx/
-*.sublime-*
-doc/
-.yardoc/
-coverage/

data/.travis.yml

@@ -1,9 +0,0 @@
-language: ruby
-rvm:
- - 1.8.7
- - 1.9.2
- - 1.9.3
- - 2.0
- - jruby-18mode
- - jruby-19mode
- - rbx-2

data/.yardopts

@@ -1 +0,0 @@
--r README.YARD.md -m markdown --protected

data/CHANGELOG.md

@@ -1,9 +0,0 @@
-Changelog
-=========
-
-v1.1.0 (2013-06-17)
--------------------
-
-API changes:
-
-  * AST::Processor#process will return nil if passed nil, instead of raising NoMethodError.

data/Gemfile

@@ -1,4 +0,0 @@
-source "http://rubygems.org"
-
-# Specify your gem's dependencies in furnace.gemspec
-gemspec

data/README.md

@@ -1,23 +0,0 @@
-# AST
-
-[![Build Status](https://travis-ci.org/whitequark/ast.png?branch=master)](https://travis-ci.org/whitequark/ast)
-[![Code Climate](https://codeclimate.com/github/whitequark/ast.png)](https://codeclimate.com/github/whitequark/ast)
-[![Coverage Status](https://coveralls.io/repos/whitequark/ast/badge.png?branch=master)](https://coveralls.io/r/whitequark/ast)
-
-AST is a small library for working with immutable abstract syntax trees.
-
-## Installation
-
-    $ gem install ast
-
-## Usage
-
-See the documentation at [GitHub](http://whitequark.github.com/ast/frames.html) or [rdoc.info](http://rdoc.info/gems/ast).
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request

data/Rakefile

@@ -1,19 +0,0 @@
-require 'bundler/gem_tasks'
-require 'bundler/setup'
-
-task :default => :test
-
-desc "Run test suite"
-task :test do
-  sh "bacon -Itest -a"
-end
-
-PAGES_REPO = 'git@github.com:whitequark/ast'
-
-desc "Build and deploy documentation to GitHub pages"
-task :pages do
-  system "git clone #{PAGES_REPO} gh-temp/ -b gh-pages; rm gh-temp/* -rf; touch gh-temp/.nojekyll" or abort
-  system "yardoc -o gh-temp/;" or abort
-  system "cd gh-temp/; git add -A; git commit -m 'Updated pages.'; git push -f origin gh-pages" or abort
-  FileUtils.rm_rf 'gh-temp'
-end

data/ast.gemspec

@@ -1,28 +0,0 @@
-Gem::Specification.new do |s|
-  s.name        = 'ast'
-  s.version     = '2.0.0'
-  s.license     = 'MIT'
-  s.authors     = ["Peter Zotov"]
-  s.email       = ["whitequark@whitequark.org"]
-  s.homepage    = "https://whitequark.github.io/ast/"
-  s.summary     = %q{A library for working with Abstract Syntax Trees.}
-  s.description = s.summary
-
-  s.files         = `git ls-files`.split("\n")
-  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',                '~> 10.0'
-
-  s.add_development_dependency 'bacon',               '~> 1.2'
-  s.add_development_dependency 'bacon-colored_output'
-  s.add_development_dependency 'simplecov'
-
-  s.add_development_dependency 'coveralls'
-  s.add_development_dependency 'json_pure' # for coveralls on 1.9.2
-  s.add_development_dependency 'mime-types', '~> 1.25' # for coveralls on 1.8.7
-
-  s.add_development_dependency 'yard'
-  s.add_development_dependency 'kramdown'
-end

data/test/helper.rb

@@ -1,17 +0,0 @@
-require 'bacon'
-require 'bacon/colored_output'
-
-require 'simplecov'
-require 'coveralls'
-
-SimpleCov.start do
-  self.formatter = SimpleCov::Formatter::MultiFormatter[
-    SimpleCov::Formatter::HTMLFormatter,
-    Coveralls::SimpleCov::Formatter
-  ]
-
-  # Exclude the testsuite itself.
-  add_filter "/test/"
-end
-
-require 'ast'

data/test/test_ast.rb

@@ -1,243 +0,0 @@
-require 'helper'
-
-describe AST::Node do
-  extend AST::Sexp
-
-  class MetaNode < AST::Node
-    attr_reader :meta
-  end
-
-  before do
-    @node = AST::Node.new(:node, [ 0, 1 ])
-    @metanode = MetaNode.new(:node, [ 0, 1 ], :meta => 'value')
-  end
-
-  it 'should have accessors for type and children' do
-    @node.type.should.equal :node
-    @node.children.should.equal [0, 1]
-  end
-
-  it 'should set metadata' do
-    @metanode.meta.should.equal 'value'
-  end
-
-  it 'should be frozen' do
-    @node.frozen?.should.be.true
-    @node.children.frozen?.should.be.true
-  end
-
-  it 'should return self when duping' do
-    @node.dup.should.equal? @node
-  end
-
-  it 'should return an updated node, but only if needed' do
-    @node.updated().should.be.identical_to @node
-    @node.updated(:node).should.be.identical_to @node
-    @node.updated(nil, [0, 1]).should.be.identical_to @node
-
-    updated = @node.updated(:other_node)
-    updated.should.not.be.identical_to @node
-    updated.type.should.equal :other_node
-    updated.children.should.equal @node.children
-
-    updated.frozen?.should.be.true
-
-    updated = @node.updated(nil, [1, 1])
-    updated.should.not.be.identical_to @node
-    updated.type.should.equal @node.type
-    updated.children.should.equal [1, 1]
-
-    updated = @metanode.updated(nil, nil, :meta => 'other_value')
-    updated.meta.should.equal 'other_value'
-  end
-
-  it 'should use fancy type in to_s' do
-    node = AST::Node.new(:ast_node)
-    node.to_s.should.equal '(ast-node ...)'
-  end
-
-  it 'should format to_sexp correctly' do
-    AST::Node.new(:a, [ :sym, [ 1, 2 ] ]).to_sexp.should.equal '(a :sym [1, 2])'
-    AST::Node.new(:a, [ :sym, @node ]).to_sexp.should.equal "(a :sym\n  (node 0 1))"
-    AST::Node.new(:a, [ :sym,
-      AST::Node.new(:b, [ @node, @node ])
-    ]).to_sexp.should.equal "(a :sym\n  (b\n    (node 0 1)\n    (node 0 1)))"
-  end
-
-  it 'should return self in to_ast' do
-    @node.to_ast.should.be.identical_to @node
-  end
-
-  it 'should only use type and children to compute #hash' do
-    @node.hash.should.equal([@node.type, @node.children, @node.class].hash)
-  end
-
-  it 'should only use type and children in #eql? comparisons' do
-    # Not identical but equivalent
-    @node.eql?(AST::Node.new(:node, [0, 1])).should.be.true
-    # Not identical and not equivalent
-    @node.eql?(AST::Node.new(:other, [0, 1])).should.be.false
-    # Not identical and not equivalent because of differend class
-    @node.eql?(@metanode).should.be.false
-  end
-
-  it 'should only use type and children in #== comparisons' do
-    @node.should.equal @node
-    @node.should.equal @metanode
-    @node.should.not.equal :foo
-
-    mock_node = Object.new.tap do |obj|
-      def obj.to_ast
-        self
-      end
-
-      def obj.type
-        :node
-      end
-
-      def obj.children
-        [ 0, 1 ]
-      end
-    end
-    @node.should.equal mock_node
-  end
-
-  it 'should allow to decompose nodes with a, b = *node' do
-    node = s(:gasgn, :$foo, s(:integer, 1))
-
-    var_name, value = *node
-    var_name.should.equal :$foo
-    value.should.equal s(:integer, 1)
-  end
-
-  it 'should concatenate with arrays' do
-    node = s(:gasgn, :$foo)
-    (node + [s(:integer, 1)]).
-        should.equal s(:gasgn, :$foo, s(:integer, 1))
-  end
-
-  it 'should append elements' do
-    node = s(:array)
-    (node << s(:integer, 1) << s(:string, "foo")).
-        should.equal s(:array, s(:integer, 1), s(:string, "foo"))
-  end
-
-  begin
-    eval <<-CODE
-    it 'should not trigger a rubinius bug' do
-      bar = [ s(:bar, 1) ]
-      baz = s(:baz, 2)
-      s(:foo, *bar, baz).should.equal s(:foo, s(:bar, 1), s(:baz, 2))
-    end
-    CODE
-  rescue SyntaxError
-    # Running on 1.8, ignore.
-  end
-end
-
-describe AST::Processor do
-  extend AST::Sexp
-
-  def have_sexp(text)
-    text = text.lines.map { |line| line.sub /^ +\|(.+)/, '\1' }.join.rstrip
-    lambda { |ast| ast.to_sexp == text }
-  end
-
-  class MockProcessor < AST::Processor
-    attr_reader :counts
-
-    def initialize
-      @counts = Hash.new(0)
-    end
-
-    def on_root(node)
-      count_node(node)
-      node.updated(nil, process_all(node.children))
-    end
-    alias on_body on_root
-
-    def on_def(node)
-      count_node(node)
-      name, arglist, body = node.children
-      node.updated(:def, [ name, process(arglist), process(body) ])
-    end
-
-    def handler_missing(node)
-      count_node(node)
-    end
-
-    def count_node(node)
-      @counts[node.type] += 1; nil
-    end
-  end
-
-  before do
-    @ast = AST::Node.new(:root, [
-      AST::Node.new(:def, [ :func,
-        AST::Node.new(:arglist, [ :foo, :bar ]),
-        AST::Node.new(:body, [
-          AST::Node.new(:invoke, [ :puts, "Hello world" ])
-        ])
-      ]),
-      AST::Node.new(:invoke, [ :func ])
-    ])
-
-    @processor = MockProcessor.new
-  end
-
-  it 'should visit every node' do
-    @processor.process(@ast).should.equal @ast
-    @processor.counts.should.equal({
-      :root    => 1,
-      :def     => 1,
-      :arglist => 1,
-      :body    => 1,
-      :invoke  => 2,
-    })
-  end
-
-  it 'should be able to replace inner nodes' do
-    def @processor.on_arglist(node)
-      node.updated(:new_fancy_arglist)
-    end
-
-    @processor.process(@ast).should have_sexp(<<-SEXP)
-    |(root
-    |  (def :func
-    |    (new-fancy-arglist :foo :bar)
-    |    (body
-    |      (invoke :puts "Hello world")))
-    |  (invoke :func))
-    SEXP
-  end
-
-  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
-
-  it 'should return nil if passed nil' do
-    @processor.process(nil).should == nil
-  end
-
-  it 'should refuse to process non-nodes' do
-    lambda { @processor.process([]) }.should.raise NoMethodError, %r|to_ast|
-  end
-
-  it 'should allow to visit nodes with process_all(node)' do
-    @processor.process_all s(:foo, s(:bar), s(:integer, 1))
-    @processor.counts.should.equal({
-      :bar =>     1,
-      :integer => 1,
-    })
-  end
-end