astrolabe 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b3016609691bcb111bfe66a66ff77da7e533aab
-  data.tar.gz: f3314ca723a831d03df024b7e5be1539a5483f76
+  metadata.gz: c17d30b9bee8cee926de9b4b2527950eb5c50763
+  data.tar.gz: 218e6135e0a8019b136651f4b92c0ca8648326a2
 SHA512:
-  metadata.gz: 59af596675bb9815ee963ab92275f636034031c2ec1e245163af0a77b3602a82cdf01072191e958d1faa746d1248a7737fe27907eae741225858d172eaf6c854
-  data.tar.gz: c200880804038aa30c87fe8d64f0c50d51823ef5c7c878d7bb3ad6d319238557dd47c2e8585e988efc0a18c8ba3f7a62b451739919ad5a95da1125bb0a4dc3d9
+  metadata.gz: 0e705c920bc838e45e1e0abc555e21582647c37f857e43ad36bea9057db9e9e50431c0e6eb6a9a57a7f271d8f0ec66bf45735907e1a03c159ec7016ddaf9d72b
+  data.tar.gz: 255f1615ab127be042ead82d9c363c06667c1e50caf9983920330313e2c9ac95fdcf09ff3b255449469a8b557e616fce7de0f02a6858b31463110ac7f4a0ceda

data/README.md

@@ -90,18 +90,33 @@ if you don't need to track context of AST.
 
 ```ruby
 # Iterate ancestor nodes in the order from parent to root.
-node.each_ancestor do |ancestor_node|
-  p ancestor_node
-end
+node.each_ancestor { |ancestor_node| ... }
 
 # This is different from `node.children.each { |child| ... }`
 # which yields all children including non-node element.
-node.each_child_node do |child_node|
-  p child_node
-end
-
-# Collect all lvar nodes under the receiver node.
-lvar_nodes = node.each_descendant.select(&:lvar_type?)
+node.each_child_node { |child_node| ... }
+
+# These iteration methods can be chained by Enumerable methods.
+# Find the first lvar node under the receiver node.
+lvar_node = node.each_descendant.find(&:lvar_type?)
+
+# Iterate the receiver node itself and the descendant nodes.
+# This would be useful when you treat the receiver node as a root of tree
+# and want to iterate all nodes in the tree.
+ast.each_node { |node| ... }
+
+# Yield only specific type nodes.
+ast.each_node(:send) { |send_node| ... }
+# This is equivalent to:
+ast.each_node.select(&:send_type?).each { |send_node| ... }
+
+# Yield only nodes matching any of the types.
+ast.each_node(:send, :block) { |send_or_block_node| ... }
+ast.each_node([:send, :block]) { |send_or_block_node| ... }
+# These are equivalent to:
+ast.each_node
+  .select { |node| [:send, :block].include?(node.type) }
+  .each { |send_or_block_node| ... }
 ```
 
 ## Compatibility

data/benchmark/performance_spec.rb

@@ -67,9 +67,10 @@ describe 'performance' do
           def each_descendant
             return to_enum(__method__) unless block_given?
 
-            each_child_node do |child_node|
-              yield child_node
-              child_node.each_descendant { |node| yield node }
+            children.each do |child|
+              next unless child.is_a?(self.class)
+              yield child
+              child.each_descendant { |node| yield node }
             end
           end
         end
@@ -82,9 +83,10 @@ describe 'performance' do
           def each_descendant(&block)
             return to_enum(__method__) unless block_given?
 
-            each_child_node do |child_node|
-              yield child_node
-              child_node.each_descendant(&block)
+            children.each do |child|
+              next unless child.is_a?(self.class)
+              yield child
+              child.each_descendant(&block)
             end
           end
         end
@@ -100,9 +102,10 @@ describe 'performance' do
 
             proc_object ||= block
 
-            each_child_node do |child_node|
-              proc_object.call(child_node)
-              child_node.each_descendant(proc_object)
+            children.each do |child|
+              next unless child.is_a?(self.class)
+              proc_object.call(child)
+              child.each_descendant(proc_object)
             end
           end
         end

data/lib/astrolabe/node.rb

@@ -16,8 +16,8 @@ module Astrolabe
   #   # Non-word characters (other than a-zA-Z0-9_) in type names are omitted.
   #   node.defined_type? # Equivalent to: `node.type == :defined?`
   #
-  #   # Collect all lvar nodes under the receiver node.
-  #   lvar_nodes = node.each_descendant.select(&:lvar_type?)
+  #   # Find the first lvar node under the receiver node.
+  #   lvar_node = node.each_descendant.find(&:lvar_type?)
   class Node < Parser::AST::Node
     # @see http://rubydoc.info/gems/ast/AST/Node:initialize
     def initialize(type, children = [], properties = {})
@@ -66,16 +66,29 @@ module Astrolabe
     # Calls the given block for each ancestor node in the order from parent to root.
     # If no block is given, an `Enumerator` is returned.
     #
+    # @overload each_ancestor
+    #   Yield all nodes.
+    # @overload each_ancestor(type)
+    #   Yield only nodes matching the type.
+    #   @param [Symbol] type a node type
+    # @overload each_ancestor(type_a, type_b, ...)
+    #   Yield only nodes matching any of the types.
+    #   @param [Symbol] type_a a node type
+    #   @param [Symbol] type_b a node type
+    # @overload each_ancestor(types)
+    #   Yield only nodes matching any of types in the array.
+    #   @param [Array<Symbol>] types an array containing node types
     # @yieldparam [Node] node each ancestor node
     # @return [self] if a block is given
     # @return [Enumerator] if no block is given
-    def each_ancestor
+    def each_ancestor(*types)
       return to_enum(__method__) unless block_given?
 
+      types.flatten!
       last_node = self
 
       while (current_node = last_node.parent)
-        yield current_node
+        yield current_node if types.empty? || types.include?(current_node.type)
         last_node = current_node
       end
 
@@ -88,15 +101,29 @@ module Astrolabe
     # Note that this is different from `node.children.each { |child| ... }` which yields all
     # children including non-node element.
     #
+    # @overload each_child_node
+    #   Yield all nodes.
+    # @overload each_child_node(type)
+    #   Yield only nodes matching the type.
+    #   @param [Symbol] type a node type
+    # @overload each_child_node(type_a, type_b, ...)
+    #   Yield only nodes matching any of the types.
+    #   @param [Symbol] type_a a node type
+    #   @param [Symbol] type_b a node type
+    # @overload each_child_node(types)
+    #   Yield only nodes matching any of types in the array.
+    #   @param [Array<Symbol>] types an array containing node types
     # @yieldparam [Node] node each child node
     # @return [self] if a block is given
     # @return [Enumerator] if no block is given
-    def each_child_node
+    def each_child_node(*types)
       return to_enum(__method__) unless block_given?
 
+      types.flatten!
+
       children.each do |child|
         next unless child.is_a?(Node)
-        yield child
+        yield child if types.empty? || types.include?(child.type)
       end
 
       self
@@ -105,12 +132,25 @@ module Astrolabe
     # Calls the given block for each descendant node with depth first order.
     # If no block is given, an `Enumerator` is returned.
     #
+    # @overload each_descendant
+    #   Yield all nodes.
+    # @overload each_descendant(type)
+    #   Yield only nodes matching the type.
+    #   @param [Symbol] type a node type
+    # @overload each_descendant(type_a, type_b, ...)
+    #   Yield only nodes matching any of the types.
+    #   @param [Symbol] type_a a node type
+    #   @param [Symbol] type_b a node type
+    # @overload each_descendant(types)
+    #   Yield only nodes matching any of types in the array.
+    #   @param [Array<Symbol>] types an array containing node types
     # @yieldparam [Node] node each descendant node
     # @return [self] if a block is given
     # @return [Enumerator] if no block is given
-    def each_descendant(&block)
+    def each_descendant(*types, &block)
       return to_enum(__method__) unless block_given?
-      visit_descendants(&block)
+      types.flatten!
+      visit_descendants(types, &block)
       self
     end
 
@@ -120,22 +160,36 @@ module Astrolabe
     # This method would be useful when you treat the receiver node as a root of tree and want to
     # iterate all nodes in the tree.
     #
+    # @overload each_node
+    #   Yield all nodes.
+    # @overload each_node(type)
+    #   Yield only nodes matching the type.
+    #   @param [Symbol] type a node type
+    # @overload each_node(type_a, type_b, ...)
+    #   Yield only nodes matching any of the types.
+    #   @param [Symbol] type_a a node type
+    #   @param [Symbol] type_b a node type
+    # @overload each_node(types)
+    #   Yield only nodes matching any of types in the array.
+    #   @param [Array<Symbol>] types an array containing node types
     # @yieldparam [Node] node each node
     # @return [self] if a block is given
     # @return [Enumerator] if no block is given
-    def each_node(&block)
+    def each_node(*types, &block)
       return to_enum(__method__) unless block_given?
-      yield self
-      each_descendant(&block)
+      types.flatten!
+      yield self if types.empty? || types.include?(type)
+      visit_descendants(types, &block)
+      self
     end
 
     protected
 
-    def visit_descendants(&block)
+    def visit_descendants(types, &block)
       children.each do |child|
         next unless child.is_a?(Node)
-        yield child
-        child.visit_descendants(&block)
+        yield child if types.empty? || types.include?(child.type)
+        child.visit_descendants(types, &block)
       end
     end
   end

data/lib/astrolabe/version.rb

@@ -5,7 +5,7 @@ module Astrolabe
   # http://semver.org/
   module Version
     MAJOR = 0
-    MINOR = 4
+    MINOR = 5
     PATCH = 0
 
     def self.to_s

data/spec/astrolabe/node_spec.rb

@@ -52,6 +52,26 @@ module Astrolabe
       end
     end
 
+    shared_examples 'node enumerator' do |method_name|
+      context 'when no block is given' do
+        it 'returns an enumerator' do
+          expect(target_node.send(method_name)).to be_a Enumerator
+        end
+
+        describe 'the returned enumerator' do
+          subject(:enumerator) { target_node.send(method_name) }
+
+          it 'enumerates ancestor nodes' do
+            expected_types.each do |expected_type|
+              expect(enumerator.next.type).to eq(expected_type)
+            end
+
+            expect { enumerator.next }.to raise_error(StopIteration)
+          end
+        end
+      end
+    end
+
     describe '#each_ancestor' do
       let(:source) { <<-END }
         class SomeClass
@@ -94,21 +114,41 @@ module Astrolabe
         end
       end
 
-      context 'when no block is given' do
-        it 'returns an enumerator' do
-          expect(target_node.each_ancestor).to be_a Enumerator
+      include_examples 'node enumerator', :each_ancestor
+
+      context 'when a node type symbol is passed' do
+        it 'scans all the ancestor nodes but yields only nodes matching the type' do
+          yielded_types = []
+
+          target_node.each_ancestor(:begin) do |node|
+            yielded_types << node.type
+          end
+
+          expect(yielded_types).to eq([:begin])
         end
+      end
 
-        describe 'the returned enumerator' do
-          subject(:enumerator) { target_node.each_ancestor }
+      context 'when multiple node type symbols are passed' do
+        it 'scans all the ancestor nodes but yields only nodes matching any of the types' do
+          yielded_types = []
 
-          it 'enumerates ancestor nodes' do
-            expected_types.each do |expected_type|
-              expect(enumerator.next.type).to eq(expected_type)
-            end
+          target_node.each_ancestor(:begin, :def) do |node|
+            yielded_types << node.type
+          end
 
-            expect { enumerator.next }.to raise_error(StopIteration)
+          expect(yielded_types).to eq([:def, :begin])
+        end
+      end
+
+      context 'when an array including type symbols are passed' do
+        it 'scans all the ancestor nodes but yields only nodes matching any of the types' do
+          yielded_types = []
+
+          target_node.each_ancestor([:begin, :def]) do |node|
+            yielded_types << node.type
           end
+
+          expect(yielded_types).to eq([:def, :begin])
         end
       end
     end
@@ -146,21 +186,41 @@ module Astrolabe
         end
       end
 
-      context 'when no block is given' do
-        it 'returns an enumerator' do
-          expect(target_node.each_child_node).to be_a(Enumerator)
+      include_examples 'node enumerator', :each_child_node
+
+      context 'when a node type symbol is passed' do
+        it 'scans all the child nodes but yields only nodes matching the type' do
+          yielded_types = []
+
+          target_node.each_child_node(:send) do |node|
+            yielded_types << node.type
+          end
+
+          expect(yielded_types).to eq([:send])
         end
+      end
 
-        describe 'the returned enumerator' do
-          subject(:enumerator) { target_node.each_child_node }
+      context 'when multiple node type symbols are passed' do
+        it 'scans all the child nodes but yields only nodes matching any of the types' do
+          yielded_types = []
 
-          it 'enumerates the child nodes' do
-            expected_types.each do |expected_type|
-              expect(enumerator.next.type).to eq(expected_type)
-            end
+          target_node.each_child_node(:send, :args) do |node|
+            yielded_types << node.type
+          end
 
-            expect { enumerator.next }.to raise_error(StopIteration)
+          expect(yielded_types).to eq([:args, :send])
+        end
+      end
+
+      context 'when an array including type symbols are passed' do
+        it 'scans all the child nodes but yields only nodes matching any of the types' do
+          yielded_types = []
+
+          target_node.each_child_node([:send, :args]) do |node|
+            yielded_types << node.type
           end
+
+          expect(yielded_types).to eq([:args, :send])
         end
       end
     end
@@ -207,21 +267,41 @@ module Astrolabe
         end
       end
 
-      context 'when no block is given' do
-        it 'returns an enumerator' do
-          expect(target_node.each_descendant).to be_a(Enumerator)
+      include_examples 'node enumerator', :each_descendant
+
+      context 'when a node type symbol is passed' do
+        it 'scans all the descendant nodes but yields only nodes matching the type' do
+          yielded_types = []
+
+          target_node.each_descendant(:send) do |node|
+            yielded_types << node.type
+          end
+
+          expect(yielded_types).to eq([:send, :send])
         end
+      end
 
-        describe 'the returned enumerator' do
-          subject(:enumerator) { target_node.each_descendant }
+      context 'when multiple node type symbols are passed' do
+        it 'scans all the descendant nodes but yields only nodes matching any of the types' do
+          yielded_types = []
 
-          it 'enumerates the descendant nodes' do
-            expected_types.each do |expected_type|
-              expect(enumerator.next.type).to eq(expected_type)
-            end
+          target_node.each_descendant(:send, :def) do |node|
+            yielded_types << node.type
+          end
 
-            expect { enumerator.next }.to raise_error(StopIteration)
+          expect(yielded_types).to eq([:send, :def, :send])
+        end
+      end
+
+      context 'when an array including type symbols are passed' do
+        it 'scans all the descendant nodes but yields only nodes matching any of the types' do
+          yielded_types = []
+
+          target_node.each_descendant([:send, :def]) do |node|
+            yielded_types << node.type
           end
+
+          expect(yielded_types).to eq([:send, :def, :send])
         end
       end
     end
@@ -252,7 +332,7 @@ module Astrolabe
       let(:expected_types) { [:class, :const, :begin, :send, :sym, :def, :args, :arg, :arg, :send] }
 
       context 'when a block is given' do
-        it 'yields itself and each descendant node with depth first order' do
+        it 'yields the node itself and each descendant node with depth first order' do
           yielded_types = []
 
           target_node.each_node do |node|
@@ -268,21 +348,41 @@ module Astrolabe
         end
       end
 
-      context 'when no block is given' do
-        it 'returns an enumerator' do
-          expect(target_node.each_node).to be_a(Enumerator)
+      include_examples 'node enumerator', :each_node
+
+      context 'when a node type symbol is passed' do
+        it 'scans all the nodes but yields only nodes matching the type' do
+          yielded_types = []
+
+          target_node.each_node(:send) do |node|
+            yielded_types << node.type
+          end
+
+          expect(yielded_types).to eq([:send, :send])
         end
+      end
 
-        describe 'the returned enumerator' do
-          subject(:enumerator) { target_node.each_node }
+      context 'when multiple node type symbols are passed' do
+        it 'scans all the nodes but yields only nodes matching any of the types' do
+          yielded_types = []
 
-          it 'enumerates the origin and the descendant nodes' do
-            expected_types.each do |expected_type|
-              expect(enumerator.next.type).to eq(expected_type)
-            end
+          target_node.each_node(:send, :def) do |node|
+            yielded_types << node.type
+          end
 
-            expect { enumerator.next }.to raise_error(StopIteration)
+          expect(yielded_types).to eq([:send, :def, :send])
+        end
+      end
+
+      context 'when an array including type symbols are passed' do
+        it 'scans all the nodes but yields only nodes matching any of the types' do
+          yielded_types = []
+
+          target_node.each_node([:send, :def]) do |node|
+            yielded_types << node.type
           end
+
+          expect(yielded_types).to eq([:send, :def, :send])
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: astrolabe
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yuji Nakayama