resolves #2067 allow filter block passed to AbstractBlock#find_by to skip subtrees (PR #2902)

- interpret :skip return value of filter block to mean skip node and its descendants
- interpret :skip_children return value of filter block to mean accept node, but skip its descendants

1 files changed, 50 insertions, 0 deletions

diff --git a/test/api_test.rb b/test/api_test.rb
index c411a8fd..4daa3b20 100644
--- a/test/api_test.rb
+++ b/test/api_test.rb
@@ -576,6 +576,56 @@ content
       assert_equal 'Section', result[0].title
     end
 
+    test 'find_by should skip node and its children if block returns :skip' do
+      input = <<-EOS
+paragraph 1
+
+====
+paragraph 2
+
+term::
++
+paragraph 3
+====
+
+paragraph 4
+      EOS
+      doc = Asciidoctor.load input
+      result = doc.find_by do |candidate|
+        ctx = candidate.context
+        if ctx == :example
+          :skip
+        elsif ctx == :paragraph
+          true
+        end
+      end
+      refute_nil result
+      assert_equal 2, result.size
+      assert_equal :paragraph, result[0].context
+      assert_equal :paragraph, result[1].context
+    end
+
+    test 'find_by should accept node but skip its children if block returns :skip_children' do
+      input = <<-EOS
+====
+paragraph 2
+
+term::
++
+paragraph 3
+====
+      EOS
+      doc = Asciidoctor.load input
+      result = doc.find_by do |candidate|
+        if candidate.context == :example
+          :skip_children
+        end
+      end
+      refute_nil result
+      assert_equal 1, result.size
+      assert_equal :example, result[0].context
+    end
+
     test 'find_by should stop looking for blocks when StopIteration is raised' do
       input = <<-EOS
 paragraph 1