jekyll_plugin_support 0.7.2 → 0.8.1

data/lib/jekyll_plugin_support_block.rb

@@ -0,0 +1,94 @@
+require_relative 'jekyll_plugin_error_handling'
+
+module JekyllSupport
+  # Base class for Jekyll block tags
+  class JekyllBlock < Liquid::Block
+    attr_reader :argument_string, :helper, :line_number, :logger, :page, :site, :text
+
+    include JekyllSupportErrorHandling
+    extend JekyllSupportErrorHandling
+
+    def set_error_context
+      error_class = Object.const_get error_class_name
+      error_class.class_variable_set(:@@argument_string, @argument_string)
+      error_class.class_variable_set(:@@line_number, @line_number)
+      error_class.class_variable_set(:@@path, @page['path'])
+      error_class.class_variable_set(:@@tag_name, @tag_name)
+    end
+
+    # 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
+    # @return [void]
+    def initialize(tag_name, markup, parse_context)
+      super
+      @tag_name = tag_name
+      @argument_string = markup.to_s # Vars in plugin parameters cannot be replaced yet
+      @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, markup, @logger, respond_to?(:no_arg_parsing)
+
+      @error_name = "#{tag_name.camelcase(:upper)}Error"
+      Jekyll::CustomError.factory @error_name
+    end
+
+    # Method prescribed by the Jekyll plugin lifecycle.
+    # Defines @config, @envs, @mode, @page and @site
+    # @return [String]
+    def render(liquid_context)
+      @helper.liquid_context = JekyllSupport.inject_vars @logger, liquid_context
+      text = super # Liquid variable values in content are looked up and substituted
+
+      @envs      = liquid_context.environments.first
+      @page      = liquid_context.registers[:page] # hash
+      @scopes    = liquid_context.scopes
+      @site      = liquid_context.registers[:site]
+
+      @config = @site.config
+      @tag_config = @config[@tag_name]
+
+      set_error_context @error_name
+
+      @layout    = @envs[:layout]
+      @paginator = @envs[:paginator]
+      @theme     = @envs[:theme]
+
+      @mode = @config['env']&.key?('JEKYLL_ENV') ? @config['env']['JEKYLL_ENV'] : 'development'
+
+      @helper.reinitialize(@markup.strip)
+
+      @attribution = @helper.parameter_specified?('attribution') || false unless @no_arg_parsing
+      @logger.debug { "@keys_values='#{@keys_values}'" }
+
+      markup = JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
+      @helper.reinitialize markup
+
+      render_impl text
+    rescue StandardError => e
+      e.shorten_backtrace
+      @logger.error { "#{e.class} on line #{@line_number} of #{e.backtrace[0].split(':').first} by #{tag_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 #{e.backtrace[0].split(':').first} by #{tag_name}: #{e.message}
+        </div>
+      END_MSG
+    end
+
+    # Jekyll plugins should override this method, not render,
+    # so they can be tested more easily.
+    # The following variables are predefined:
+    #   @argument_string, @config, @envs, @helper, @layout, @logger, @mode, @page, @paginator, @site, @tag_name and @theme
+    # @return [String] The result to be rendered to the invoking page
+    def render_impl(text)
+      text
+    end
+  end
+end

data/lib/jekyll_plugin_support_block_noarg.rb

@@ -0,0 +1,30 @@
+require_relative 'jekyll_plugin_error_handling'
+
+module JekyllSupport
+  class JekyllBlockNoArgParsing < JekyllBlock
+    attr_reader :argument_string, :helper, :line_number, :logger, :page, :site
+
+    include JekyllSupportErrorHandling
+    extend JekyllSupportErrorHandling
+
+    def initialize(tag_name, argument_string, parse_context)
+      class << self
+        include NoArgParsing
+      end
+
+      super
+      @logger.debug { "#{self.class}: respond_to?(:o_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
+    rescue StandardError => e
+      e.shorten_backtrace
+      @logger.error { e.full_message }
+      JekyllSupport.error_short_trace(@logger, e)
+    end
+
+    # Jekyll plugins must override this method, not render, so their plugin can be tested more easily
+    # The following variables are predefined:
+    #   @argument_string, @config, @envs, @helper, @layout, @logger, @mode, @page, @paginator, @site, @tag_name and @theme
+    def render_impl
+      abort "#{self.class}.render_impl for tag #{@tag_name} must be overridden, but it was not."
+    end
+  end
+end

data/lib/jekyll_plugin_support_class.rb

@@ -0,0 +1,88 @@
+require_relative 'jekyll_custom_error'
+
+# Monkey patch StandardError so a new method called shorten_backtrace is added.
+class StandardError
+  def shorten_backtrace(backtrace_element_count = 3)
+    # self.backtrace = backtrace[0..backtrace_element_count].map do |x|
+    #   raise JekyllPluginSupportError, "backtrace contains a #{x.class} with value '#{x}'." unless x.instance_of? String
+
+    #   x.gsub(Dir.pwd + '/', './')
+    # end
+  end
+end
+
+module JekyllSupport
+  DISPLAYED_CALLS = 8
+
+  def self.error_short_trace(logger, error)
+    error.set_backtrace error.backtrace[0..DISPLAYED_CALLS]
+    logger.error { error }
+    error
+  end
+
+  # @return a new StandardError subclass containing the shorten_backtrace method
+  def define_error
+    Class.new Jekyll::CustomError
+  end
+  module_function :define_error
+
+  JekyllPluginSupportError = define_error
+
+  def self.dump_vars(_logger, liquid_context)
+    page = liquid_context.registers[:page]
+    vars = liquid_context.scopes.map do |scope|
+      scope.map { |name, value| "  #{name} = #{value}" }.join("\n")
+    end.join("\n")
+    puts <<~END_MSG
+      #{page['name']} variables after injecting any defined in _config.yml:
+      #{vars}
+    END_MSG
+  end
+
+  # Add variable definitions from _config.yml to liquid_context
+  # Modifies liquid_context in the caller (call by reference)
+  # @return modified liquid_context
+  # See README.md#configuration-variable-definitions
+  # See demo/variables.html
+  def self.inject_vars(_logger, 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'
+
+    # Set default values
+    plugin_variables&.each do |name, value|
+      scope[name] = value if value.instance_of? String
+    end
+
+    # Override with environment-specific values
+    plugin_variables[mode]&.each do |name, value|
+      scope[name] = value if value.instance_of? String
+    end
+
+    liquid_context
+  end
+
+  def self.lookup_liquid_variables(liquid_context, markup)
+    liquid_context.scopes.each do |scope|
+      scope.each do |name, value|
+        markup = markup.gsub("{{#{name}}}", value.to_s)
+      end
+    end
+    markup
+  end
+
+  def self.warn_short_trace(logger, error)
+    remaining = error.backtrace.length - DISPLAYED_CALLS
+    logger.warn do
+      error.message + "\n" +
+        error.backtrace.take(DISPLAYED_CALLS).join("\n") +
+        "\n...Remaining #{remaining} call sites elided.\n"
+    end
+  end
+end

data/lib/jekyll_plugin_support_tag.rb

@@ -0,0 +1,91 @@
+require 'pry'
+require_relative 'jekyll_plugin_error_handling'
+
+module JekyllSupport
+  # Base class for Jekyll tags
+  class JekyllTag < Liquid::Tag
+    attr_reader :argument_string, :helper, :line_number, :logger, :page, :site
+
+    include JekyllSupportErrorHandling
+    extend JekyllSupportErrorHandling
+
+    # 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
+    # @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
+      @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"
+      Jekyll::CustomError.factory @error_name
+    end
+
+    def set_error_context
+      error_class = Object.const_get @error_name
+      error_class.class_variable_set(:@@argument_string, @argument_string)
+      error_class.class_variable_set(:@@line_number, @line_number)
+      error_class.class_variable_set(:@@path, @page['path'])
+      error_class.class_variable_set(:@@tag_name, @tag_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
+
+      @envs      = liquid_context.environments.first
+      @page      = liquid_context.registers[:page]
+      @scopes    = liquid_context.scopes
+      @site      = liquid_context.registers[:site]
+
+      @config = @site.config
+      @tag_config = @config[@tag_name]
+      @jps = @config['jekyll_plugin_support']
+      @pry_on_standard_error = @jps['pry_on_standard_error'] || false if @jps
+
+      set_error_context @error_name
+
+      # @envs.keys are :content, :highlighter_prefix, :highlighter_suffix, :jekyll, :layout, :page, :paginator, :site, :theme
+      @layout    = @envs[:layout]
+      @paginator = @envs[:paginator]
+      @theme     = @envs[:theme]
+
+      @mode = @config['env']&.key?('JEKYLL_ENV') ? @config['env']['JEKYLL_ENV'] : 'development'
+
+      @helper.reinitialize JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
+
+      render_impl
+    rescue StandardError => e
+      e.shorten_backtrace
+      @logger.error { "#{e.class} on line #{@line_number} of #{e.backtrace[0].split(':').first} while processing #{tag_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 #{e.backtrace[0].split(':').first} while processing #{tag_name}: #{e.message}
+        </div>
+      END_MSG
+    end
+
+    # Jekyll plugins must override this method, not render, so their plugin can be tested more easily
+    # The following variables are predefined:
+    #   @argument_string, @config, @envs, @helper, @layout, @logger, @mode, @page, @paginator, @site, @tag_name and @theme
+    def render_impl
+      abort "#{self.class}.render_impl for tag #{@tag_name} must be overridden, but it was not."
+    end
+  end
+end

data/lib/jekyll_plugin_support_tag_noarg.rb

@@ -0,0 +1,26 @@
+require_relative 'jekyll_plugin_error_handling'
+
+module JekyllSupport
+  class JekyllTagNoArgParsing < JekyllTag
+    attr_reader :argument_string, :helper, :line_number, :logger, :page, :site
+
+    include JekyllSupportErrorHandling
+    extend JekyllSupportErrorHandling
+
+    def initialize(tag_name, argument_string, parse_context)
+      class << self
+        include NoArgParsing
+      end
+
+      super
+      @logger.debug { "#{self.class}: respond_to?(:no_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
+    end
+
+    # Jekyll plugins must override this method, not render, so their plugin can be tested more easily
+    # The following variables are predefined:
+    #   @argument_string, @config, @envs, @helper, @layout, @logger, @mode, @page, @paginator, @site, @tag_name and @theme
+    def render_impl
+      abort "#{self.class}.render_impl for tag #{@tag_name} must be overridden, but it was not."
+    end
+  end
+end

data/spec/custom_error_spec.rb

@@ -0,0 +1,39 @@
+require_relative '../lib/jekyll_custom_error'
+require_relative '../lib/jekyll_plugin_support_class'
+
+class Dummy
+  def just_for_testing; end
+end
+
+class CustomErrorSpec
+  tag_name = 'test_tag'
+  argument_string = 'This is the argument string'
+  AnError = JekyllSupport.define_error
+  AnError.class_variable_set(:@@tag_name, tag_name)
+  AnError.class_variable_set(:@@argument_string, argument_string)
+
+  puts "AnError is a #{AnError.class}; StandardError is a #{StandardError.class}"
+  begin
+    raise AnError, 'Oops'
+  rescue AnError => e
+    puts "Caught AnError: #{e.message}"
+  rescue Jekyll::CustomError => e
+    puts "Caught CustomError: #{e.message}"
+  end
+
+  RSpec.describe JekyllPluginHelper do
+    it 'generates messages' do
+      msg = described_class.generate_message(Dummy, tag_name, '0.1.0')
+      puts msg
+      expect(msg).to include(match(/Error class. DummyError/))
+      expect(msg).to include(match(/CSS class for error messages. dummy_error/))
+      expect(msg).to include(match(/die_on_dummy_error. false/))
+    end
+  end
+
+  RSpec.describe Jekyll::CustomError do
+    it 'can create custom errors' do
+      expect { raise AnError, 'Oops' }.to raise_error(AnError)
+    end
+  end
+end

data/spec/liquid_variable_parsing_spec.rb

@@ -0,0 +1,34 @@
+require 'jekyll_plugin_logger'
+require 'rspec/match_ignoring_whitespace'
+require_relative '../lib/jekyll_plugin_support'
+require_relative '../lib/jekyll_plugin_support_spec_support'
+
+class LiquidVariableParsing
+  # @return copy of str with references to defined variables replaced by the values of the variables
+  def variable_replace(str, scopes)
+    result = str.clone
+    match_data_list = str.to_enum(:scan, /{{[a-z_][a-zA-Z_0-9]*}}/).map { Regexp.last_match }.reverse
+    match_data_list.each do |md|
+      from = md.begin(0)
+      to = md.end(0) - 1
+      ref = str[from..to]
+      name = ref[2..-3]
+      scopes.each do |scope|
+        value = scope.key?(name) ? scope[name] : ref
+        # puts "str=#{str}; from=#{from}; to=#{to}; name=#{name} value=#{value}"
+        result[from..to] = value
+      end
+    end
+    result
+  end
+
+  RSpec.describe JekyllPluginHelper do
+    it 'substitutes variable references for values without recursion' do
+      scopes = [{ 'a' => '{{', 'b' => 'asdf', 'c' => '}}' }]
+      str = '{{a}}{{b}}{{c}} This should be unchanged: {{d}}'
+      new_str = variable_replace(str, scopes)
+      expect(str).to start_with('{{a}}')
+      expect(new_str).to be('{{asdf}} This should be unchanged: {{d}}')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -2,9 +2,8 @@ require 'jekyll'
 require_relative '../lib/jekyll_plugin_support'
 
 RSpec.configure do |config|
-  config.filter_run :focus
+  config.filter_run_when_matching focus: true
   # config.order = 'random'
-  config.run_all_when_everything_filtered = true
 
   # See https://relishapp.com/rspec/rspec-core/docs/command-line/only-failures
   config.example_status_persistence_file_path = 'spec/status_persistence.txt'

data/spec/status_persistence.txt

@@ -0,0 +1,6 @@
+example_id                                       | status | run_time        |
+------------------------------------------------ | ------ | --------------- |
+./spec/jekyll_plugin_helper_options_spec.rb[1:1] | passed | 0.00559 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:2] | passed | 0.00583 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:3] | passed | 0.00543 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:4] | passed | 0.00157 seconds |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.1
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-14 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - mslinn@mslinn.com
@@ -80,13 +94,22 @@ files:
 - README.md
 - Rakefile
 - jekyll_plugin_support.gemspec
-- lib/call_chain.rb
-- lib/gem_support.rb
+- lib/jekyll_custom_error.rb
+- lib/jekyll_plugin_error_handling.rb
 - lib/jekyll_plugin_helper.rb
+- lib/jekyll_plugin_helper_attribution.rb
+- lib/jekyll_plugin_helper_class.rb
 - lib/jekyll_plugin_support.rb
 - lib/jekyll_plugin_support/version.rb
+- lib/jekyll_plugin_support_block.rb
+- lib/jekyll_plugin_support_block_noarg.rb
+- lib/jekyll_plugin_support_class.rb
 - lib/jekyll_plugin_support_spec_support.rb
+- lib/jekyll_plugin_support_tag.rb
+- lib/jekyll_plugin_support_tag_noarg.rb
+- spec/custom_error_spec.rb
 - spec/jekyll_plugin_helper_options_spec.rb
+- spec/liquid_variable_parsing_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
 homepage: https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html
@@ -116,12 +139,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
-summary: Provides support for writing Jekyll plugins.
+summary: Provides a framework for writing and testing Jekyll plugins
 test_files:
+- spec/custom_error_spec.rb
 - spec/jekyll_plugin_helper_options_spec.rb
+- spec/liquid_variable_parsing_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
 ...

data/lib/call_chain.rb

@@ -1,54 +0,0 @@
-# TODO: File not used, delete
-
-# See https://stackoverflow.com/a/23363883/553865
-module CallChain
-  ACaller = Struct.new(:filepath, :line, :method_name)
-
-  def self.caller_method(depth = 1)
-    parse_caller(caller(depth + 1).first).method_name
-  end
-
-  def self.parse_caller(at)
-    return unless /^(.+?):(\d+)(?::in `(.*)')?/ =~ at
-
-    last_match = Regexp.last_match.to_a
-    ACaller.new(
-      last_match[1],
-      last_match[2].to_i,
-      last_match[3]
-    )
-  end
-
-  def self.excerpt_caller
-    call_sequence = caller
-    call_sequence.each do |caller_|
-      parsed_caller = parse_caller caller_
-      filepath = parsed_caller.filepath
-      excerpt = filepath.match? %r{jekyll[.0-9-]*/lib/jekyll/excerpt.rb\z}
-      puts "excerpt matched #{filepath}" if excerpt
-      return true if excerpt
-    end
-    false
-  end
-
-  # Return ACaller prior to jekyll_plugin_support
-  def self.jpsh_subclass_caller
-    state = :nothing_found
-    call_sequence = caller
-    call_sequence.each do |caller_|
-      parsed_caller = parse_caller caller_
-      filepath = parsed_caller.filepath
-      dirname = File.dirname filepath
-      jpsh = dirname.match? %r{jekyll_plugin_support[.0-9-]*/lib\z}
-      liquid = dirname.match? %r{liquid[.0-9-]*/lib/\z}
-      case state
-      when :nothing_found
-        state = :jpsh_found if jpsh
-      when :jpsh_found
-        # puts "Called from #{parsed_caller.filepath}, on line #{parsed_caller.line}, by method '#{parsed_caller.method_name}'" unless jpsh
-        return parsed_caller unless jpsh || liquid
-      end
-    end
-    nil
-  end
-end

data/lib/gem_support.rb

@@ -1,19 +0,0 @@
-# See https://stackoverflow.com/a/75890279/553865
-module GemSupport
-  # @param file must be a fully qualified file name that points to a file within a gem.
-  # @return Gem::Specification of gem that file points into, or nil if not called from a gem
-  def self.current_spec(file)
-    abort 'GemSupport::current_spec: file is nil' if file.nil?
-    return nil unless File.exist?(file)
-
-    searcher = if Gem::Specification.respond_to?(:find)
-                 Gem::Specification
-               elsif Gem.respond_to?(:searcher)
-                 Gem.searcher.init_gemspecs
-               end
-
-    searcher&.find do |spec|
-      file.start_with? spec.full_gem_path
-    end
-  end
-end