jekyll_plugin_support 1.0.3 → 3.0.0

data/lib/jekyll_plugin_support/jekyll_plugin_support_class.rb

@@ -1,5 +1,3 @@
-require_relative '../error/jekyll_custom_error'
-
 # Monkey patch StandardError so a new method called shorten_backtrace is added.
 class StandardError
   def shorten_backtrace(backtrace_element_count = 3)
@@ -12,7 +10,7 @@ class StandardError
 end
 
 module JekyllSupport
-  DISPLAYED_CALLS = 8
+  DISPLAYED_CALLS = 8 unless defined?(DISPLAYED_CALLS)
 
   def self.error_short_trace(logger, error)
     error.set_backtrace error.backtrace[0..DISPLAYED_CALLS]
@@ -22,11 +20,11 @@ module JekyllSupport
 
   # @return a new StandardError subclass containing the shorten_backtrace method
   def define_error
-    Class.new JekyllSupport::CustomError
+    Class.new ::JekyllSupport::CustomError
   end
   module_function :define_error
 
-  JekyllPluginSupportError = define_error
+  JekyllPluginSupportError = define_error unless defined?(JekyllPluginSupportError)
 
   def self.dump_vars(_logger, liquid_context)
     page = liquid_context.registers[:page]
@@ -39,23 +37,21 @@ module JekyllSupport
     END_MSG
   end
 
-  # Add variable definitions from _config.yml to liquid_context
-  # Modifies liquid_context in the caller
+  # Inject variable definitions from _config.yml into liquid_context
+  # Modifies liquid_context.scopes in the caller
   # (call by object reference, see https://stackoverflow.com/a/1872159/553865)
   # @return modified liquid_context
   # See README.md#configuration-variable-definitions
   # See demo/variables.html
-  def self.inject_vars(_logger, liquid_context)
-    # TODO: Modify a deep clone? Do I dare?
+  def self.inject_config_vars(liquid_context)
     site = liquid_context.registers[:site]
 
     plugin_variables = site.config['liquid_vars']
-    return liquid_context unless plugin_variables
 
     scope = liquid_context.scopes.last
 
     env = site.config['env']
-    mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
+    @mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
 
     # Set default values
     plugin_variables&.each do |name, value|
@@ -63,7 +59,7 @@ module JekyllSupport
     end
 
     # Override with environment-specific values
-    plugin_variables[mode]&.each do |name, value|
+    plugin_variables&.[](@mode)&.each do |name, value|
       scope[name] = value if value.instance_of? String
     end
 
@@ -85,34 +81,71 @@ module JekyllSupport
   # Modifies a clone of markup_original so variable references are replaced by their values
   # @param markup_original to be cloned
   # @return modified markup_original
-  def self.lookup_liquid_variables(liquid_context, markup_original)
+  def self.lookup_liquid_variables(logger, liquid_context, markup_original)
     markup = markup_original.clone
-    page = liquid_context.registers[:page]
+    page   = liquid_context.registers[:page]
     envs   = liquid_context.environments.first
     layout = envs[:layout]
 
-    # process layout variables
+    markup = process_layout_variables logger, layout, markup
+    markup = process_page_variables logger, page, markup
+    liquid_context.scopes&.each do |scope|
+      markup = process_included_variables logger, scope, markup
+      markup = process_liquid_variables logger, scope, markup
+    end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
+
+  def self.process_included_variables(logger, scope, markup)
+    scope['include']&.each do |name, value|
+      if value.nil?
+        value = ''
+        logger.warn { "include.#{name} is undefined." }
+      end
+      markup.gsub!("{{include.#{name}}}", value)
+    end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
+
+  def self.process_layout_variables(logger, layout, markup)
     layout&.each do |name, value|
+      if value.nil?
+        value = ''
+        logger.warn { "layout.#{value} is undefined." }
+      end
       markup.gsub!("{{layout.#{name}}}", value.to_s)
     end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
 
-    # process page variables
-    # puts "\nStarting page variable processing of #{page['path']}; stack has #{caller.length} elements".green
-    keys = page.keys
-    %w[excerpt output].each { |key| keys.delete key }
-    # puts "  Filtered keys: #{keys.join ' '}"
-    # keys.each { |key| puts "  #{key}: #{page[key]}" }
-    keys&.each do |key|
-      markup.gsub!("{{page.#{key}}}", page[key].to_s)
+  # Process assigned, captured and injected variables
+  def self.process_liquid_variables(logger, scope, markup)
+    scope&.each do |name, value|
+      next if name.nil?
+
+      value = '' if value.nil?
+      markup.gsub!("{{#{name}}}", value&.to_s)
     end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
 
-    # Process assigned, captured and injected variables
-    liquid_context.scopes.each do |scope|
-      scope&.each do |name, value|
-        markup.gsub!("{{#{name}}}", value.to_s)
-      end
+  def self.process_page_variables(logger, page, markup)
+    page&.each_key do |key|
+      next if %w[content excerpt next previous output].include? key # Skip problem attributes
+
+      markup.gsub!("{{page.#{key}}}", page[key].to_s)
     end
     markup
+  rescue StandardError => e
+    logger.error { e.full_message }
   end
 
   def self.warn_short_trace(logger, error)

data/lib/jekyll_plugin_support/jekyll_plugin_support_spec_support.rb

@@ -1,6 +1,4 @@
-require 'jekyll'
-
-Registers = Struct.new(:page, :site)
+Registers = Struct.new(:page, :site) unless defined?(Registers)
 
 # Mock for Collections
 class Collections

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '1.0.3'.freeze
+  VERSION = '3.0.0'.freeze unless defined?(VERSION)
 end

data/lib/jekyll_plugin_support.rb

@@ -1,13 +1,26 @@
-require 'colorator'
-require 'jekyll'
-require 'jekyll_plugin_logger'
-
 def require_directory(dir)
-  Dir[File.join(dir, '*.rb')].sort.each do |file|
+  Dir[File.join(dir, '*.rb')]&.sort&.each do |file|
     require file unless file == __FILE__
   end
 end
 
+require 'colorator'
+require 'jekyll'
+require 'jekyll_plugin_logger'
+require 'pry'
+require 'sorted_set'
+
+# require_directory __dir__
+require_directory "#{__dir__}/util"
+require_directory "#{__dir__}/error"
+require_directory "#{__dir__}/block"
+require_directory "#{__dir__}/generator"
+require_directory "#{__dir__}/helper"
+require_directory "#{__dir__}/jekyll_plugin_support"
+require_directory "#{__dir__}/tag"
+require_directory "#{__dir__}/jekyll_all_collections"
+require_directory "#{__dir__}/hooks"
+
 module JekyllSupport
   def self.redef_without_warning(const, value)
     send(:remove_const, const) if const_defined?(const)
@@ -21,14 +34,6 @@ module NoArgParsing
   @no_arg_parsing = true
 end
 
-require_directory __dir__
-require_directory "#{__dir__}/block"
-require_directory "#{__dir__}/error"
-require_directory "#{__dir__}/generator"
-require_directory "#{__dir__}/helper"
-require_directory "#{__dir__}/jekyll_plugin_support"
-require_directory "#{__dir__}/tag"
-
 module JekyllSupport
   class JekyllTag
     include JekyllSupportError

data/lib/tag/jekyll_plugin_support_tag.rb

@@ -1,6 +1,3 @@
-require 'pry'
-require_relative '../error/jekyll_plugin_error_handling'
-
 module JekyllSupport
   # Base class for Jekyll tags
   class JekyllTag < Liquid::Tag
@@ -9,31 +6,41 @@ module JekyllSupport
     # See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
     # @param tag_name [String] the name of the tag, which we usually know.
     # @param argument_string [String] the arguments passed to the tag, as a single string.
-    # @param parse_context [Liquid::ParseContext] hash that stores Liquid options.
-    #        By default it has two keys: :locale and :line_numbers, the first is a Liquid::I18n object, and the second,
-    #        a boolean parameter that determines if error messages should display the line number the error occurred.
-    #        This argument is used mostly to display localized error messages on Liquid built-in Tags and Filters.
-    #        See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    # @param parse_context [Liquid::ParseContext] contains the following attributes:
+    #        @depth might have the value 0
+    #        @error_mode might have the value `:strict`
+    #        @line_number duplicates @ptions[:line_number]
+    #        @locale duplicates @ptions[:locale]
+    #        @options is a hash with the following two keys that holds Liquid options:
+    #          :locale is a Liquid::I18n object, used to display localized error messages on Liquid built-in tags and filters.
+    #          :line_number is the line number containing the plugin invocation.
+    #          See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    #        @partial Boolean, unclear what this indicates
+    #        @template_options Replicates @options
+    #        @trim_whitespace might have the value `false`
+    #        @warnings array
     # @return [void]
     def initialize(tag_name, markup, parse_context)
       super
       @tag_name = tag_name
       raise JekyllPluginSupportError, "markup is a #{markup.class} with value '#{markup}'." unless markup.instance_of? String
 
-      @argument_string = markup
+      # Vars in plugin parameters cannot be replaced yet
+      @argument_string = markup.to_s # Lookup variable names with values in markup in render because site and config are not available here
+
       @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
       @logger.debug { "#{self.class}: respond_to?(:no_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
       @helper = JekyllPluginHelper.new(tag_name, @argument_string, @logger, respond_to?(:no_arg_parsing))
 
       @error_name = "#{tag_name.camelcase(:upper)}Error"
-      JekyllSupport::CustomError.factory @error_name
+      ::JekyllSupport::CustomError.factory @error_name
     end
 
     # Method prescribed by the Jekyll plugin lifecycle.
     def render(liquid_context)
       return if @helper.excerpt_caller
 
-      @helper.liquid_context = JekyllSupport.inject_vars @logger, liquid_context
+      @helper.liquid_context = JekyllSupport.inject_config_vars liquid_context # modifies liquid_context
 
       @envs      = liquid_context.environments.first
       @page      = liquid_context.registers[:page]
@@ -55,8 +62,12 @@ module JekyllSupport
       env = @config['env']
       @mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
 
-      markup = JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
-      @helper.reinitialize markup.strip
+      @argument_string = JekyllSupport.lookup_liquid_variables @logger, @helper.liquid_context, @argument_string.to_s.strip
+      @helper.reinitialize @argument_string.to_s.strip
+
+      # @argument_string = JekyllSupport.lookup_liquid_variables @logger, liquid_context, @argument_string # Is this redundant?
+      # @argument_string.strip! # Is this redundant?
+      # @helper.reinitialize @argument_string # Is this redundant?
 
       render_impl
     rescue StandardError => e
@@ -64,13 +75,13 @@ module JekyllSupport
       file_name = e.backtrace[0]&.split(':')&.first
       in_file_name = "in '#{file_name}' " if file_name
       of_page = "of '#{@page['path']}'" if @page
-      @logger.error { "#{e.class} on line #{@line_number} #{of_page}while processing #{tag_name} #{in_file_name}- #{e.message}" }
+      @logger.error { "#{e.class} on line #{@line_number} #{of_page} while processing #{tag_name} #{in_file_name}- #{e.message}" }
       binding.pry if @pry_on_standard_error # rubocop:disable Lint/Debugger
       raise e if @die_on_standard_error
 
       <<~END_MSG
         <div class='standard_error'>
-          #{e.class} on line #{@line_number} #{of_page}while processing #{tag_name} #{in_file_name} - #{e.message}
+          #{e.class} on line #{@line_number} #{of_page} while processing #{tag_name} #{in_file_name} - #{JekyllPluginHelper.remove_html_tags e.message}
         </div>
       END_MSG
     end

data/lib/tag/jekyll_plugin_support_tag_noarg.rb

@@ -1,5 +1,3 @@
-require_relative '../error/jekyll_plugin_error_handling'
-
 module JekyllSupport
   class JekyllTagNoArgParsing < JekyllTag
     attr_reader :argument_string, :helper, :line_number, :logger, :page, :site

data/lib/util/mslinn_binary_search.rb

@@ -0,0 +1,152 @@
+unless defined?(MSlinnBinarySearchError)
+  class MSlinnBinarySearchError < StandardError
+  end
+end
+
+# Ruby's binary search is unsuitable because the value to be searched for changes the required ordering for String compares
+class MSlinnBinarySearch
+  attr_reader :accessor_chain, :array # For testing only
+
+  def initialize(accessor_chain)
+    @array = SortedSet.new # [LruFile] Ordered highest to lowest
+    @accessor_chain = accessor_chain
+  end
+
+  # Convert the SortedSet to an Array
+  def enable_search
+    @array = @array.to_a
+  end
+
+  # A match is found when the Array[LruFile] has an href which starts with the given stem
+  # @param stem [String]
+  # @return first item from @array.url that matches, or nil if no match
+  def find(stem)
+    raise MSlinnBinarySearchError, 'Invalid find because stem to search for is nil.' if stem.nil?
+
+    index = find_index(stem)
+    return nil if index.nil?
+
+    @array[index]
+  end
+
+  # @param stem [String]
+  # @return index of first matching stem, or nil if @array is empty, or 0 if no stem specified
+  def find_index(stem)
+    return nil if @array.empty?
+    return 0 if stem.nil? || stem.empty?
+
+    mets = stem.reverse
+    return nil if @array[0].url[0...mets.size] > mets # TODO: use chain eval for item
+    return nil if @array[0].url[0] != mets[0]
+
+    _find_index(mets, 0, @array.length - 1)
+  end
+
+  # @param stem [String]
+  # @return [index] of matching values, or [] if @array is empty, or entire array if no stem specified
+  def find_indices(stem)
+    return [] if @array.empty?
+    return @array if stem.nil? || stem.empty?
+
+    first_index = _find_index(stem, 0, @array.length - 1)
+    last_index = first_index
+    last_index += 1 while @array[last_index].url.start_with? stem
+    [first_index..last_index]
+  end
+
+  # @param item [LruFile]
+  # @return [int] index of matching LruFile in @array, or nil if not found
+  def index_of(lru_file)
+    raise MSlinnBinarySearchError, 'Invalid index_of lru_file (nil).' if lru_file.nil?
+
+    find_index lru_file.url
+  end
+
+  # @return [LruFile] item at given index in @array
+  def item_at(index)
+    if index > @array.length - 1
+      raise MSlinnBinarySearchError,
+            "Invalid item_at index (#{index}) is greater than maximum stem (#{@array.length - 1})."
+    end
+    raise MSlinnBinarySearchError, "Invalid item_at index (#{index}) is less than zero." if index.negative?
+
+    @array[index]
+  end
+
+  # @param lru_file [LruFile]
+  def insert(lru_file)
+    raise MSlinnBinarySearchError, 'Invalid insert because new item is nil.' if lru_file.nil?
+    raise MSlinnBinarySearchError, "Invalid insert because new item has no chain (#{lru_file})" if lru_file.chain.nil?
+
+    @array.add lru_file
+  end
+
+  # TODO: Cache this method
+  # @param suffix [String] to use stem search on
+  # @return nil if @array is empty
+  # @return the first item in @array if suffix is nil or an empty string
+  def prefix_search(suffix)
+    return nil if @array.empty?
+    return @array[0] if suffix.empty? || suffix.nil?
+
+    low = search_index { |x| x.evaluate_with suffix }
+    return [] if low.nil?
+
+    high = low
+    high += 1 while high < @array.length &&
+                    @array[high].evaluate_with(suffix)
+    @array[low..high]
+  end
+
+  # @param stem [String]
+  # @return [APage] matching APages, or [] if @array is empty, or entire array if no stem specified
+  def select_pages(stem)
+    first_index = find_index stem
+    return [] if first_index.nil?
+
+    last_index = first_index
+    while last_index < @array.length - 1
+      # LruFile.url is reversed, bug LruFile.page is not
+      break unless @array[last_index + 1].url.start_with?(stem.reverse)
+
+      last_index += 1
+    end
+    Range.new(first_index, last_index).map { |i| @array[i].page }
+  end
+
+  private
+
+  # A match is found when the Array[LruFile] has an href which starts with the given stem
+  # @param stem [String]
+  # @return [int] first index in @array that matches, or nil if no match
+  def _find_index(mets, min_index, max_index)
+    raise MSlinnBinarySearchError, "_find_index min_index(#{min_index})<0" if min_index.negative?
+    raise MSlinnBinarySearchError, "_find_index min_index(#{min_index})>max_index(#{max_index})" if min_index > max_index
+    raise MSlinnBinarySearchError, "_find_index max_index(#{max_index})>=@array.length(#{@array.length})" if max_index >= @array.length
+
+    return min_index if (min_index == max_index) && @array[min_index].url.start_with?(mets)
+
+    while min_index < max_index
+      mid_index = (min_index + max_index) / 2
+      mid_value = @array[mid_index].url[0...(mets.size)] # TODO: use chain eval for item
+
+      if mid_value == mets # back up until the first match is found
+        index = mid_index
+        loop do
+          return 0 if index.zero?
+
+          return index unless @array[index - 1].url.start_with?(mets)
+
+          index -= 1
+        end
+      elsif mid_value > mets
+        max_index = mid_index - 1
+        return _find_index(mets, min_index, max_index)
+      else
+        min_index = mid_index + 1
+        return _find_index(mets, min_index, max_index)
+      end
+    end
+    nil
+  end
+end

data/lib/util/send_chain.rb

@@ -0,0 +1,56 @@
+# Supports one chain at a time
+module SendChain
+  # See https://stackoverflow.com/a/79333706/553865
+  # This method can be called directly if no methods in the chain require arguments
+  # Does not use any external state
+  def send_chain(chain)
+    Array(chain).inject(self) { |o, a| o.send(*a) }
+  end
+
+  # Saves @chain structure containing :placeholders for arguments to be supplied later
+  # Call when a different chain with :placeholders is desired
+  def new_chain(chain)
+    abort "new_chain error: chain must be an array ('#{chain}' was an #{chain.class.name})" \
+      unless chain.instance_of?(Array)
+    @chain = chain
+  end
+
+  # Call after new_chain, to evaluate @chain with values
+  def substitute_and_send_chain_with(values)
+    send_chain substitute_chain_with values
+  end
+
+  alias evaluate_with substitute_and_send_chain_with
+
+  # Call this method after calling new_chain to perform error checking and replace :placeholders with values.
+  # @chain is not modified.
+  # @return [Array] Modified chain
+  def substitute_chain_with(values)
+    values = [values] unless values.instance_of?(Array)
+
+    placeholder_count = @chain.flatten.count { |x| x == :placeholder }
+    if values.length != placeholder_count
+      abort "with_values error: number of values (#{values.length}) does not match the number of placeholders (#{placeholder_count})"
+    end
+
+    eval_chain @chain, values
+  end
+
+  private
+
+  # Replaces :placeholders with values
+  # Does not use any external state
+  # @return modified chain
+  def eval_chain(chain, values)
+    chain.map do |c|
+      case c
+      when :placeholder
+        values.shift
+      when Array
+        eval_chain c, values
+      else
+        c
+      end
+    end
+  end
+end

data/spec/all_collections_tag/all_collections_tag_sort_spec.rb

@@ -0,0 +1,112 @@
+require 'spec_helper'
+require_relative '../../lib/jekyll_all_collections'
+
+class APageStub
+  attr_reader :date, :last_modified, :label
+
+  def initialize(date, last_modified, label = '')
+    @date = Date.parse date
+    @last_modified = Date.parse last_modified
+    @label = label
+  end
+
+  def to_s
+    @label
+  end
+end
+
+def show(lambda_string, result, expected)
+  p "For lambda_string: #{lambda_string}"
+  p "  result: #{result.map(&:label).join(', ')}  <==>  expected: #{expected.map(&:label).join(', ')}"
+end
+
+# See https://stackoverflow.com/a/75388137/553865
+RSpec.describe(AllCollectionsTag::AllCollectionsTag) do
+  let(:o1) { APageStub.new('2020-01-01', '2020-01-01', 'a_A') }
+  let(:o2) { APageStub.new('2021-01-01', '2020-01-01', 'b_A') }
+  let(:o3) { APageStub.new('2021-01-01', '2023-01-01', 'b_B') }
+  let(:o4) { APageStub.new('2022-01-01', '2023-01-01', 'c_B') }
+  let(:objs) { [o1, o2, o3, o4] }
+
+  it 'defines sort_by lambda with last_modified' do
+    sort_lambda = ->(a, b) { [a.last_modified] <=> [b.last_modified] }
+    result = objs.sort(&sort_lambda)
+    expect(result).to eq([o1, o2, o3, o4])
+  end
+
+  it 'makes sort_by lambdas from stringified date' do
+    sort_lambda = eval '->(a, b) { a.last_modified <=> b.last_modified }',
+                       NullBinding.new.min_binding, __FILE__, __LINE__ - 1
+    result = objs.sort(&sort_lambda)
+    expect(result).to eq([o1, o2, o3, o4])
+  end
+
+  it 'makes sort_by lambdas from stringified array of last_modified' do
+    sort_lambda = eval '->(a, b) { [a.last_modified] <=> [b.last_modified] }',
+                       NullBinding.new.min_binding, __FILE__, __LINE__ - 1
+    result = objs.sort(&sort_lambda)
+    expect(result).to eq([o1, o2, o3, o4])
+  end
+
+  it 'makes sort_by lambdas with descending keys from stringified array of last_modified' do
+    sort_lambda = eval '->(a, b) { [b.last_modified] <=> [a.last_modified] }',
+                       NullBinding.new.min_binding, __FILE__, __LINE__ - 1
+    result = objs.sort(&sort_lambda)
+    expected = [o3, o4, o1, o2]
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 1 date key, descending' do
+    lambda_string = described_class.create_lambda_string('-last_modified')
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o3, o4, o1, o2]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 1 date key, ascending' do
+    lambda_string = described_class.create_lambda_string('date')
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o1, o2, o3, o4]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 2 date keys, both ascending' do
+    lambda_string = described_class.create_lambda_string(%w[date last_modified])
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o1, o2, o3, o4]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 2 date keys, both descending' do
+    lambda_string = described_class.create_lambda_string(['-date', '-last_modified'])
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o4, o3, o2, o1]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 2 date keys, first descending and second ascending' do
+    lambda_string = described_class.create_lambda_string(['-date', 'last_modified'])
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o4, o2, o3, o1]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+
+  it 'create_lambda with 2 date keys, first ascending and second descending' do
+    lambda_string = described_class.create_lambda_string(['date', '-last_modified'])
+    sort_lambda = described_class.evaluate(lambda_string)
+    result = objs.sort(&sort_lambda)
+    expected = [o1, o3, o2, o4]
+    # show(lambda_string, result, expected)
+    expect(result).to eq(expected)
+  end
+end

data/spec/bsearch_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+# Ruby's binary search is unsuitable because ordering requirements are not stable.
+# the value to be searched for changes the required ordering
+
+RSpec.describe(Array) do
+  before { skip('Never gonna give you up/Never gonna let you down') }
+
+  sorted_ints = [0, 4, 7, 10, 12]
+  sorted_strings = %w[aaa aab aac bbb bbc bbd ccc ccd cce].sort.reverse
+
+  it 'returns index of first int match' do
+    actual = sorted_ints.bsearch_index { |x| x >= 4 }
+    expect(actual).to eq(1)
+
+    actual = sorted_ints.bsearch_index { |x| x >= 6 }
+    expect(actual).to eq(2)
+
+    actual = sorted_ints.bsearch_index { |x| x >= -1 }
+    expect(actual).to eq(0)
+
+    actual = sorted_ints.bsearch_index { |x| x >= 100 }
+    expect(actual).to be_nil
+  end
+
+  # See https://stackoverflow.com/q/79333097/553865
+  it 'returns index of first string match' do
+    puts(sorted_strings.map { |x| x.start_with? 'a' })
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'a' }
+    expect(sorted_strings[index]).to eq('aac')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'aa' }
+    expect(sorted_strings[index]).to eq('aac')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'aaa' }
+    expect(sorted_strings[index]).to eq('aaa')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'b' }
+    expect(sorted_strings[index]).to eq('bbd')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'bb' }
+    expect(sorted_strings[index]).to eq('bbd')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'bbc' }
+    expect(sorted_strings[index]).to eq('bbc')
+
+    index = sorted_strings.bsearch_index { |x| x.start_with? 'cc' }
+    expect(sorted_strings[index]).to eq('cce')
+  end
+end