use terminology for find_by that better aligns with NodeFilter (PR #3130)

- assume that true implies "accept"
- assume that false implies "skip"
- prefer :reject rather than :skip
- prefer :prune instead of :skip_children

3 files changed, 16 insertions, 15 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 007f0158..9d30490d 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -70,6 +70,7 @@ Enhancements / Compliance::
   * AbstractBlock#find_by finds table cells, which can be selected using the :table_cell context in the selector (#2524)
   * allow ampersand to be used in e-mail address (#2553)
   * propogate ID assigned to inline passthrough (#2912)
+  * rename control keywords in find_by to better align with the standard NodeFilter terminology
 
 Improvements::
 
diff --git a/lib/asciidoctor/abstract_block.rb b/lib/asciidoctor/abstract_block.rb
index 2e639993..f6ffff1a 100644
--- a/lib/asciidoctor/abstract_block.rb
+++ b/lib/asciidoctor/abstract_block.rb
@@ -142,16 +142,14 @@ class AbstractBlock < AbstractNode
     @next_section_index > 0
   end
 
-  # Public: Walk the document tree and find all block-level nodes that match
-  # the specified selector (context, style, id, role, and/or custom filter).
+  # Public: Walk the document tree and find all block-level nodes that match the specified selector (context, style, id,
+  # role, and/or custom filter).
   #
-  # If a Ruby block is given, it's treated as an supplemental filter. If the
-  # filter returns true, the node is accepted and traversal continues. If the
-  # filter returns false, the node is rejected, but traversal continues. If the
-  # filter returns :skip, the node and all its descendants are rejected. If the
-  # filter returns :skip_children, the node is accepted, but its descendants
-  # are rejected. If no selector or filter block is supplied, all block-level
-  # nodes in the tree are returned.
+  # If a Ruby block is given, it's applied as a supplemental filter. If the filter returns true (which implies :accept),
+  # the node is accepted and node traversal continues. If the filter returns false (which implies :skip), the node is
+  # skipped, but its children are still visited. If the filter returns :reject, the node and all its descendants are
+  # rejected. If the filter returns :prune, the node is accepted, but its descendants are rejected. If no selector
+  # or filter block is supplied, all block-level nodes in the tree are returned.
   #
   # Examples
   #
@@ -446,10 +444,12 @@ class AbstractBlock < AbstractNode
       elsif block_given?
         if (verdict = yield self)
           case verdict
-          when :skip_children
+          # the :skip_children keyword is deprecated
+          when :prune, :skip_children
             result << self
             return result
-          when :skip
+          # the :skip keyword is deprecated and may be repurposed
+          when :reject, :skip
             return result
           else
             result << self
diff --git a/test/api_test.rb b/test/api_test.rb
index 258d6319..e00b0e56 100644
--- a/test/api_test.rb
+++ b/test/api_test.rb
@@ -712,7 +712,7 @@ context 'API' do
       assert_equal 'Section', result[0].title
     end
 
-    test 'find_by should skip node and its children if block returns :skip' do
+    test 'find_by should reject node and its children if block returns :reject' do
       input = <<~'EOS'
       paragraph 1
 
@@ -730,7 +730,7 @@ context 'API' do
       result = doc.find_by do |candidate|
         ctx = candidate.context
         if ctx == :example
-          :skip
+          :reject
         elsif ctx == :paragraph
           true
         end
@@ -741,7 +741,7 @@ context 'API' do
       assert_equal :paragraph, result[1].context
     end
 
-    test 'find_by should accept node but skip its children if block returns :skip_children' do
+    test 'find_by should accept node but reject its children if block returns :prune' do
       input = <<~'EOS'
       ====
       paragraph 2
@@ -754,7 +754,7 @@ context 'API' do
       doc = Asciidoctor.load input
       result = doc.find_by do |candidate|
         if candidate.context == :example
-          :skip_children
+          :prune
         end
       end
       refute_nil result