resolves #3135 add AbstractBlock#get_by to locate first block that matches criteria

CHANGELOG.adoc

@@ -36,6 +36,7 @@ Enhancements::
   * Set logdev to $stderr if no arguments are passed to Logger constructor (#4250)
   * Add support for skipping TOML front matter (Hugo) when `skip-front-matter` attribute is set (#4300) (*@abhinav*)
   * Add support for Wistia using the video macro
+  * Add AbstractBlock#get_by to locate first matching block; add `:single_result` option to `find_by` to limit results to 1 (#3135)
 
 Compliance::
 

lib/asciidoctor/abstract_block.rb

@@ -182,6 +182,14 @@ def find_by selector = {}, &block
 
   alias query find_by
 
+  # Like find_by, but only returns the first result or nil if no matching block-level node is found
+  def get_by selector = {}, &block
+    find_by_internal (selector.merge single_result: true), (result = []), &block
+    result[0]
+  rescue ::StopIteration
+    result[0]
+  end
+
   # Move to the next adjacent block in document order. If the current block is the last
   # item in a list, this method will return the following sibling of the list block.
   def next_adjacent_block
@@ -451,28 +459,29 @@ def find_by_internal selector = {}, result = [], &block
         (!(style_selector = selector[:style]) || style_selector == @style) &&
         (!(role_selector = selector[:role]) || (has_role? role_selector)) &&
         (!(id_selector = selector[:id]) || id_selector == @id)
+      single_result = id_selector ? true : selector[:single_result]
       if block_given?
         if (verdict = yield self)
           case verdict
           when :prune
             result << self
-            raise ::StopIteration if id_selector
+            raise ::StopIteration if single_result
             return result
           when :reject
-            raise ::StopIteration if id_selector
+            raise ::StopIteration if single_result
             return result
           when :stop
             raise ::StopIteration
           else
             result << self
-            raise ::StopIteration if id_selector
+            raise ::StopIteration if single_result
           end
         elsif id_selector
           raise ::StopIteration
         end
       else
         result << self
-        raise ::StopIteration if id_selector
+        raise ::StopIteration if single_result
       end
     end
     case @context

test/api_test.rb

@@ -665,6 +665,37 @@ def [] key
       assert_equal 'shoe.png', result[1].attr('target')
     end
 
+    test 'find_by with :single_result option should return first block that match criteria' do
+      input = <<~'EOS'
+      = Document Title
+
+      preamble
+
+      == Section A
+
+      paragraph
+
+      --
+      Exhibit A::
+      +
+      [#tiger.animal]
+      image::tiger.png[Tiger]
+      --
+
+      image::shoe.png[Shoe]
+
+      == Section B
+
+      paragraph
+      EOS
+
+      doc = Asciidoctor.load input
+      result = doc.find_by context: :image, single_result: true
+      assert_equal 1, result.size
+      assert_equal :image, result[0].context
+      assert_equal 'tiger.png', result[0].attr('target')
+    end
+
     test 'find_by should return an empty Array if no matches are found' do
       input = 'paragraph'
       doc = Asciidoctor.load input
@@ -1063,6 +1094,60 @@ def [] key
       assert_kind_of Asciidoctor::ListItem, result[2]
     end
 
+    test 'get_by should return nil if no matches are found' do
+      doc = Asciidoctor.load 'paragraph'
+      assert_nil doc.get_by context: :section
+    end
+
+    test 'get_by should return first block in document tree that match criteria' do
+      input = <<~'EOS'
+      = Document Title
+
+      preamble
+
+      == Section A
+
+      paragraph
+
+      --
+      Exhibit A::
+      +
+      [#tiger.animal]
+      image::tiger.png[Tiger]
+      --
+
+      image::shoe.png[Shoe]
+
+      == Section B
+
+      paragraph
+      EOS
+
+      doc = Asciidoctor.load input
+      result = doc.get_by context: :image
+      refute_nil result
+      assert_equal :image, result.context
+      assert_equal 'tiger.png', (result.attr 'target')
+    end
+
+    test 'get_by should return result when matching by id' do
+      input = <<~'EOS'
+      == Section
+
+      content
+
+      [#subsection]
+      === Subsection
+
+      content
+      EOS
+      doc = Asciidoctor.load input
+      result = doc.get_by id: 'subsection'
+      refute_nil result
+      assert_equal :section, result.context
+      assert_equal 'Subsection', result.title
+    end
+
     test 'dlist item should always have two entries for terms and desc' do
       [
         'term w/o desc::',