jekyll_all_collections 0.3.6 → 0.4.0

data/jekyll_all_collections.gemspec

@@ -3,19 +3,14 @@ require_relative 'lib/jekyll_all_collections/version'
 Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_all_collections'
 
-  spec.authors = ['Mike Slinn']
-  spec.bindir = 'exe'
+  spec.authors     = ['Mike Slinn']
   spec.description = <<~END_OF_DESC
-    Provides a collection of all collections in site.all_collections.
+    Provides normalized collections and extra functionality for Jekyll websites.
   END_OF_DESC
-  spec.email = ['mslinn@mslinn.com']
-  spec.executables = []
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
-
+  spec.email    = ['mslinn@mslinn.com']
+  spec.files    = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
   spec.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_all_collections.html'
-  spec.license = 'MIT'
+  spec.license  = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
     'bug_tracker_uri'   => "#{github}/issues",
@@ -23,13 +18,15 @@ Gem::Specification.new do |spec|
     'homepage_uri'      => spec.homepage,
     'source_code_uri'   => github,
   }
-  spec.name = 'jekyll_all_collections'
-  spec.require_paths = ['lib']
+  spec.name                  = 'jekyll_all_collections'
+  spec.platform              = Gem::Platform::RUBY
+  spec.require_paths         = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
-  spec.summary = 'Provides a collection of all collections in site.all_collections.'
-  spec.version = JekyllAllCollectionsVersion::VERSION
+  spec.summary               = 'Provides normalized collections and extra functionality for Jekyll websites.'
+  spec.version               = JekyllAllCollectionsVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
   spec.add_dependency 'jekyll_draft'
   spec.add_dependency 'jekyll_plugin_support'
+  spec.add_dependency 'sorted_set'
 end

data/lib/hooks/a_page.rb

@@ -0,0 +1,69 @@
+module AllCollectionsHooks
+  class APage
+    attr_reader :content, :data, :date, :description, :destination, :draft, :excerpt, :ext, :extname, :href,
+                :label, :last_modified, :layout, :origin, :path, :relative_path, :tags, :title, :type, :url
+
+    def initialize(obj, origin)
+      @origin = origin
+      data_field_init obj
+      obj_field_init obj
+      @draft = Jekyll::Draft.draft? obj
+      @href = @url if @href.nil?
+      # @href = "/#{@href}" if @origin == 'individual_page'
+      @href = "#{@href}index.html" if @href.end_with? '/'
+      @name = File.basename(@href)
+      @title = if @data&.key?('title')
+                 @data['title']
+               elsif obj.respond_to?(:title)
+                 obj.title
+               else
+                 "<code>#{@href}</code>"
+               end
+    rescue StandardError => e
+      JekyllSupport.error_short_trace(@logger, e)
+      # JekyllSupport.warn_short_trace(@logger, e)
+    end
+
+    def to_s
+      @label || @date.to_s
+    end
+
+    private
+
+    def data_field_init(obj)
+      return unless obj.respond_to? :data
+
+      @data = obj.data
+
+      @categories = @data['categories'] if @data.key? 'categories'
+      @date = (@data['date'].to_date if @data&.key?('date')) || Date.today
+      @description = @data['description'] if @data.key? 'description'
+      @excerpt = @data['excerpt'] if @data.key? 'excerpt'
+      @ext ||= @data['ext'] if @data.key? 'ext'
+      @last_modified = @data['last_modified'] || @data['last_modified_at'] || @date
+      @last_modified_field = case @data
+                             when @data.key?('last_modified')
+                               'last_modified'
+                             when @data.key?('last_modified_at')
+                               'last_modified_at'
+                             end
+      @layout = @data['layout'] if @data.key? 'layout'
+      @tags = @data['tags'] if @data.key? 'tags'
+    end
+
+    def obj_field_init(obj)
+      @content = obj.content if obj.respond_to? :content
+
+      # TODO: What _config.yml setting should be passed to destination()?
+      @destination = obj.destination('') if obj.respond_to? :destination
+      @ext = obj.extname
+      @extname = @ext # For compatibility with previous versions of all_collections
+      @label = obj.collection.label if obj.respond_to?(:collection) && obj.collection.respond_to?(:label)
+      @path = obj.path if obj.respond_to? :path
+      @relative_path = obj.relative_path if obj.respond_to? :relative_path
+      @type = obj.type if obj.respond_to? :type
+      @url = obj.url
+      @url = "#{@url}index.html" if @url.end_with? '/'
+    end
+  end
+end

data/lib/hooks/all_collections_hooks.rb

@@ -0,0 +1,59 @@
+module AllCollectionsHooks
+  class << self
+    attr_accessor :logger
+  end
+  @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+
+  # No, all_collections is not defined for this hook
+  # Jekyll::Hooks.register(:site, :after_init, priority: :normal) do |site|
+  #   defined_msg = AllCollectionsHooks.all_collections_defined?(site)
+  #   @logger.debug { "Jekyll::Hooks.register(:site, :after_init: #{defined_msg}" }
+  # end
+
+  # Creates a `Array[APage]` property called site.all_collections if it does not already exist.
+  # The array is available from :site, :pre_render onwards
+  # Each `APage` entry is one document or page.
+  Jekyll::Hooks.register(:site, :post_read, priority: :normal) do |site|
+    @site = site
+    unless site.class.method_defined? :all_collections
+      defined_msg = AllCollectionsHooks.all_collections_defined? site
+      @logger.debug { "Jekyll::Hooks.register(:site, :post_read, :normal: #{defined_msg}" }
+      AllCollectionsHooks.compute(site) if !@site.class.method_defined?(:all_documents) || @site.all_documents.nil?
+    end
+  rescue StandardError => e
+    JekyllSupport.error_short_trace(@logger, e)
+    # JekyllSupport.warn_short_trace(@logger, e)
+  end
+
+  # Yes, all_collections is defined for this hook
+  # Jekyll::Hooks.register(:site, :post_read, priority: :low) do |site|
+  #   defined_msg = AllCollectionsHooks.all_collections_defined?(site)
+  #   @logger.debug { "Jekyll::Hooks.register(:site, :post_read, :low: #{defined_msg}" }
+  # rescue StandardError => e
+  #   JekyllSupport.error_short_trace(@logger, e)
+  #   # JekyllSupport.warn_short_trace(@logger, e)
+  # end
+
+  # Yes, all_collections is defined for this hook
+  # Jekyll::Hooks.register(:site, :post_read, priority: :normal) do |site|
+  #   defined_msg = AllCollectionsHooks.all_collections_defined?(site)
+  #   @logger.debug { "Jekyll::Hooks.register(:site, :post_read, :normal: #{defined_msg}" }
+  # rescue StandardError => e
+  #   JekyllSupport.error_short_trace(@logger, e)
+  #   # JekyllSupport.warn_short_trace(@logger, e)
+  # end
+
+  # Yes, all_collections is defined for this hook
+  # Jekyll::Hooks.register(:site, :pre_render, priority: :normal) do |site, _payload|
+  #   defined_msg = AllCollectionsHooks.all_collections_defined?(site)
+  #   @logger.debug { "Jekyll::Hooks.register(:site, :pre_render: #{defined_msg}" }
+  # rescue StandardError => e
+  #   JekyllSupport.error_short_trace(@logger, e)
+  #   # JekyllSupport.warn_short_trace(@logger, e)
+  # end
+end
+
+PluginMetaLogger.instance.logger.info do
+  "Loaded AllCollectionsHooks v#{JekyllAllCollectionsVersion::VERSION} :site, :pre_render, :normal hook plugin."
+end
+Liquid::Template.register_filter(AllCollectionsHooks)

data/lib/hooks/all_files.rb

@@ -0,0 +1,46 @@
+require_relative '../util/send_chain'
+
+# Insert the url of a Jekyll::Page into each LruFile instance,
+# along with the Page reference
+# todo: replace references to url and :url with reverse_url and :reverse_url
+LruFile = Struct.new(:url, :page) do
+  include SendChain
+
+  def <=>(other)
+    url <=> other.url
+  end
+end
+
+# Matches suffixes of an array of urls
+# Converts suffixes to prefixes
+class SortedLruFiles
+  attr_reader :msbs
+
+  def initialize
+    @msbs = MSlinnBinarySearch.new %i[url start_with?]
+  end
+
+  # @param apages [Array[APage]]
+  def add_pages(apages)
+    apages.each { |apage| insert apage.href, apage }
+    @msbs.enable_search
+  end
+
+  def enable_search
+    @msbs.enable_search
+  end
+
+  def find(suffix)
+    @msbs.find suffix
+  end
+
+  def insert(url, file)
+    lru_file = LruFile.new(url.reverse, file)
+    lru_file.new_chain [:url, %i[start_with? placeholder]]
+    @msbs.insert(lru_file)
+  end
+
+  def select(suffix)
+    @msbs.select_pages suffix
+  end
+end

data/lib/hooks/class_methods.rb

@@ -0,0 +1,50 @@
+module AllCollectionsHooks
+  class << self
+    attr_accessor :all_collections, :all_documents, :everything, :sorted_lru_files
+  end
+
+  # @sort_by = ->(apages, criteria) { [apages.sort(criteria)] } # todo delete this
+
+  # @return [String] indicating if :all_collections is defined or not
+  def self.all_collections_defined?(site)
+    "site.all_collections #{site.class.method_defined?(:all_collections) ? 'IS' : 'IS NOT'} defined"
+  end
+
+  # Create Array of AllCollectionsHooks::APage from objects
+  # @param objects [Array] An array of Jekyll::Document, Jekyll::Page or file names
+  # @param origin [String] Indicates type of objects being passed
+  def self.apages_from_objects(objects, origin)
+    pages = []
+    objects.each do |object|
+      page = APage.new(object, origin)
+      pages << page unless page.data['exclude_from_all'] || page.path == 'redirect.html'
+    end
+    pages
+  end
+
+  # Called by early, high-priority hook.
+  # Computes site.all_collections, site.all_documents, site.everything, and site.sorted_lru_files
+  def self.compute(site)
+    site.class.module_eval { attr_accessor :all_collections, :all_documents, :everything, :sorted_lru_files }
+
+    documents = site.collections
+                    .values
+                    .map { |x| x.class.method_defined?(:docs) ? x.docs : x }
+                    .flatten
+                    .compact
+    @all_collections = AllCollectionsHooks.apages_from_objects(documents, 'collection')
+    @all_documents   = @all_collections +
+                       AllCollectionsHooks.apages_from_objects(site.pages, 'individual_page')
+    @everything      = @all_documents +
+                       AllCollectionsHooks.apages_from_objects(site.static_files, 'static_file')
+    @sorted_lru_files = SortedLruFiles.new.add_pages @everything
+
+    site.all_collections  = @all_collections
+    site.all_documents    = @all_documents
+    site.everything       = @everything
+    site.sorted_lru_files = @sorted_lru_files
+  rescue StandardError => e
+    JekyllSupport.error_short_trace(AllCollectionsHooks.logger, e)
+    # JekyllSupport.warn_short_trace(AllCollectionsHooks.logger, e)
+  end
+end

data/lib/jekyll_all_collections/version.rb

@@ -1,3 +1,3 @@
 module JekyllAllCollectionsVersion
-  VERSION = '0.3.6'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/lib/jekyll_all_collections.rb

@@ -1,5 +1,17 @@
-require_relative 'all_collections_hooks'
-require_relative 'all_collections_tag'
+def require_directory(dir)
+  Dir[File.join(dir, '*.rb')]&.sort&.each do |file|
+    require file unless file == __FILE__
+  end
+end
+
+require 'jekyll'
+require 'jekyll_plugin_logger'
+require 'jekyll_plugin_support'
+
+require_relative 'jekyll_all_collections/version'
+require_directory "#{__dir__}/hooks"
+require_directory "#{__dir__}/tag"
+require_directory "#{__dir__}/util"
 
 module JekyllAllCollections
   include AllCollectionsHooks

data/lib/tag/all_collections_tag.rb

@@ -0,0 +1,158 @@
+require 'jekyll_draft'
+require 'jekyll_plugin_support'
+require 'securerandom'
+
+# @author Copyright 2020 Michael Slinn
+# @license SPDX-License-Identifier: Apache-2.0
+module AllCollectionsTag
+  PLUGIN_NAME = 'all_collections'.freeze
+  CRITERIA = %w[date destination draft label last_modified last_modified_at path relative_path title type url].freeze
+  DRAFT_HTML = '<i class="jekyll_draft">Draft</i>'.freeze
+
+  class AllCollectionsTag < JekyllSupport::JekyllTag
+    include JekyllAllCollectionsVersion
+
+    # Method prescribed by JekyllTag.
+    # @return [String]
+    def render_impl
+      parse_arguments # Defines instance variables like @sort_by
+      sort_lambda = init_sort_by @sort_by, @sort_by_param
+      @heading = @helper.parameter_specified?('heading') || default_head(@sort_by)
+      generate_output sort_lambda
+    rescue StandardError => e
+      JekyllSupport.error_short_trace @logger, e
+      # JekyllSupport.warn_short_trace @logger, e
+    end
+
+    # Descending sort keys reverse the order of comparison
+    # Example return values:
+    #   "->(a, b) { [a.last_modified] <=> [b.last_modified] }"
+    #   "->(a, b) { [b.last_modified] <=> [a.last_modified] }" (descending)
+    #   "->(a, b) { [a.last_modified, a.date] <=> [b.last_modified, b.date] }" (descending last_modified, ascending date)
+    #   "->(a, b) { [a.last_modified, b.date] <=> [b.last_modified, a.date] }" (ascending last_modified, descending date)
+    def self.create_lambda_string(criteria)
+      criteria_lhs_array = []
+      criteria_rhs_array = []
+      verify_sort_by_type(criteria).each do |c|
+        descending_sort = c.start_with? '-'
+        c.delete_prefix! '-'
+        abort("Error: '#{c}' is not a valid sort field. Valid field names are: #{CRITERIA.join ', '}") \
+          unless CRITERIA.include?(c)
+        criteria_lhs_array << (descending_sort ? "b.#{c}" : "a.#{c}")
+        criteria_rhs_array << (descending_sort ? "a.#{c}" : "b.#{c}")
+      end
+      "->(a, b) { [#{criteria_lhs_array.join(', ')}] <=> [#{criteria_rhs_array.join(', ')}] }"
+    end
+
+    def self.verify_sort_by_type(sort_by)
+      case sort_by
+      when Array
+        sort_by
+      when Enumerable
+        sort_by.to_a
+      when Date
+        [sort_by.to_i]
+      when String
+        [sort_by]
+      else
+        abort "Error: @sort_by was specified as '#{sort_by}'; it must either be a string or an array of strings"
+      end
+    end
+
+    private
+
+    def default_head(sort_by)
+      criteria = (sort_by.map do |x|
+        reverse = x.start_with? '-'
+        criterion = x.delete_prefix('-').capitalize
+        criterion += reverse ? ' (Newest to Oldest)' : ' (Oldest to Newest)'
+        criterion
+      end).join(', ')
+      "All Posts in All Categories Sorted By #{criteria}"
+    end
+
+    def evaluate(string)
+      self.eval string, binding, __FILE__, __LINE__
+    rescue StandardError => e
+      warn_short_trace e.red
+    end
+
+    def last_modified_value(apage)
+      @logger.debug do
+        "  apage.last_modified='#{apage.last_modified}'; " \
+          "apage.last_modified_at='#{apage.last_modified_at}'; " \
+          "@date_column='#{@date_column}'"
+      end
+      last_modified = if @date_column == 'last_modified' && apage.respond_to?(:last_modified)
+                        apage.last_modified
+                      elsif apage.respond_to? :last_modified_at
+                        apage.last_modified_at
+                      else
+                        apage.date
+                      end
+      last_modified ||= apage.date || Date.today
+      last_modified
+    end
+
+    def generate_output(sort_lambda)
+      id = @id.to_s.strip.empty? ? '' : " id='#{@id}'"
+      heading = @heading.strip.to_s.empty? ? '' : "<h2#{id}>#{@heading}</h2>"
+      data = case @data_selector
+             when 'all_collections'
+               @site.all_collections
+             when 'all_documents'
+               @site.all_documents
+             when 'everything'
+               @site.everything
+             else
+               raise AllCollectionsError, "Invalid value for @data_selector (#{data_selector})"
+             end
+      collection = data.sort(&sort_lambda)
+      posts = collection.map do |x|
+        last_modified = last_modified_value x
+        date = last_modified.strftime '%Y-%m-%d'
+        draft = x.draft ? DRAFT_HTML : ''
+        href = "<a href='#{x.href}'>#{x.title}</a>"
+        @logger.debug { "  date='#{date}' #{x.title}\n" }
+        "  <span>#{date}</span><span>#{href}#{draft}</span>"
+      end
+      <<~END_TEXT
+        #{heading}
+        <div class="posts">
+          #{posts.join "\n"}
+        </div>
+      END_TEXT
+    rescue ArgumentError => e
+      warn_short_trace e
+    end
+
+    # See https://stackoverflow.com/a/75377832/553865
+    def init_sort_by(sort_by, sort_by_param)
+      sort_lambda_string = AllCollectionsTag.create_lambda_string sort_by
+
+      @logger.debug do
+        "#{@page['path']} sort_by_param=#{sort_by_param}  " \
+          "sort_lambda_string = #{sort_lambda_string}\n"
+      end
+
+      evaluate sort_lambda_string
+    end
+
+    def parse_arguments
+      @data_selector = @helper.parameter_specified?('data_selector') || 'all_collections'
+      abort "Invalid data_selector #{@data_selector}" unless %w[all_collections all_documents everything].include? @data_selector
+
+      @date_column = @helper.parameter_specified?('date_column') || 'date'
+      unless %w[date last_modified].include?(@date_column)
+        raise AllCollectionsError "The date_column attribute must either have value 'date' or 'last_modified', " \
+                                  "but '#{@date_column}' was specified"
+      end
+
+      @id = @helper.parameter_specified?('id') || SecureRandom.hex(10)
+      @sort_by_param = @helper.parameter_specified? 'sort_by'
+      @sort_by = (@sort_by_param&.delete(' ')&.split(',') if @sort_by_param != false) || ['-date']
+    end
+
+    JekyllSupport::JekyllPluginHelper.register(self, PLUGIN_NAME)
+  end
+end

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,58 @@
+require_relative '../util/mslinn_binary_search'
+
+# 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

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require_relative '../../lib/jekyll_all_collections'
 
 class APageStub
   attr_reader :date, :last_modified, :label