jekyll_plugin_support 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 522c54334332d7fda1dc57bfa90647d419f458ff6153a7afe8bc8a60b0be7bca
-  data.tar.gz: 6ce396d28eefd925fa8a7a367fbca3991b2ca3625b85c0720bc9eb295a107b03
+  metadata.gz: cbe2d54d363697f10987c73cdd5e7f1f901f170109747f4319553b37251d14a5
+  data.tar.gz: 454e854eec50272cbb21bb107e9095585ea9dc4acaf066ee738cf322bdf6465a
 SHA512:
-  metadata.gz: 65ca01eb7f2a017675220b352ee4f041a87df21cf435ca280acb19e512c547f68004be72e9f8dcd51aaad099a1beaefc3544261a63eae0f44fc9b8a5e636f58a
-  data.tar.gz: 1049865b366c17bdc3b4d6b2e88e9826e3dfa849ff6b35f03b65b5c6d9b4367ccfe0477a4497ffab2cfea3e3210512ae2d8bf163f71450a05e5c5963d5960883
+  metadata.gz: 58712d203762e16b5ed848f4bff32cdfb43494871c69482b3a29b5d76180dc3b67406fe42b0662e14ded8174bf4d7a49eab16c1c81c66721402d38be4a24ecd4
+  data.tar.gz: 10782bbeb291185bdb17a0d0cd5e37ab999f3c74569b415bc5d3892221bf8e43426cd2244be37b4a5ebc90ae2aa3d9d0327f8f5e3c5b0c7da9d9b06cc1cc3546

data/.rubocop.yml

@@ -30,7 +30,7 @@ Layout/LineLength:
   Max: 150
 
 Metrics/AbcSize:
-  Max: 45
+  Max: 55
 
 Metrics/BlockLength:
   Exclude:
@@ -64,6 +64,9 @@ RSpec/IndexedLet:
 RSpec/MultipleExpectations:
   Max: 15
 
+Style/ClassVars:
+  Enabled: false
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Change Log
 
+
+## 0.8.2 / 2024-01-03
+
+* `JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag` subclasses now have automatically created error classes,
+  named after the subclass.
+* Error class methods have been provided for standardized and convenient error handling:
+  * `shorten_backtrace`
+  * `logger_message`
+  * `html_message`
+* Tags now self-report when registered.
+
+
+## 0.8.1 / 2023-12-10
+
+* Added the `JekyllPluginHelper.remove_html_tags` method.
+
+
 ## 0.8.0 / 2023-11-14
 
 * Restructured for better support of Liquid variables.

data/README.md

@@ -199,6 +199,70 @@ both [`demo/_plugins/demo_inline_tag.rb`](demo/_plugins/demo_inline_tag.rb) and
 ```
 
 
+### Automatically Created Error Classes
+
+`JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag` subclasses
+automatically create error classes, named after the subclass.
+
+For example, if you create a `JekyllSupport::JekyllBlock` subclass called `DemoBlockTag`,
+the automatically generated error class will be called `DemoBlockTagError`.
+
+Although you could use it as you would any other error class, `JekyllPluginSupport` provides some helper methods.
+These methods fill in the page path and line number that caused the error, shorten the stack trace,
+log an error message, and can be used to return an HTML-friendly version of the message to the web page.
+
+The following example is a shortened version of `demo/_plugins/demo_block_tag.rb`.
+You might want to write similar code in your `rescue` blocks.
+
+```ruby
+class DemoBlock < JekyllSupport::JekyllBlock
+  VERSION = '0.1.2'.freeze
+
+  def render_impl(text)
+    raise DemoBlockTagError, 'Fall down, go boom.'
+  rescue DemoBlockTagError => e
+    e.shorten_backtrace
+    @logger.error e.logger_message
+    raise e if @die_on_demo_block_error
+
+    e.html_message
+  end
+end
+```
+
+Error class methods have been provided for standardized and convenient error handling:
+
+* `shorten_backtrace` - most of the lines that spew from a Jekyll backtrace are uninteresting.
+* `logger_message` - The message is constructed from the string provided when the error was raised,
+   with the page path and line number added.
+* `html_message` - The same as `logger_message`, but constructed with HTML.
+
+
+### Self-Reporting Upon Registration
+
+When each tag is registered, it self-reports, for example:
+
+```text
+INFO PluginMetaLogger: Loaded plugin demo_inline_tag v0.1.2. It has:
+  Error class: DemoTagError
+  CSS class for error messages: demo_tag_error
+
+  _config.yml contains the following configuration for this plugin:
+    {"die_on_demo_tag_error"=>false, "die_on_standard_error"=>false}
+
+
+INFO PluginMetaLogger: Loaded plugin demo_inline_tag_no_arg v0.1.0. It has:
+  Error class: DemoTagNoArgsError
+  CSS class for error messages: demo_tag_no_args_error
+
+  _config.yml does not contain configuration information for this plugin.
+  You could add a section containing default values by specifying a section for the tag name,
+  and an entry whose name starts with `die_on_`, followed by a snake_case version of the error name.
+
+    demo_inline_tag_no_arg:
+      die_on_demo_tag_no_args_error: false
+```
+
 ### Example
 
 [`demo/index.html`](demo/index.html), contains the following inline tag invocation:

data/lib/jekyll_custom_error.rb

@@ -0,0 +1,54 @@
+require 'facets/string/camelcase'
+require 'facets/string/snakecase'
+
+module Jekyll
+  # Use like this:
+  # CustomError.new(:MyError, 'blah', 'asdf')
+  class CustomError < StandardError
+    def self.factory(error_class_name)
+      return if Object.const_defined? "::#{error_class_name}"
+
+      Object.const_set error_class_name, Class.new(CustomError)
+    end
+
+    def error_name
+      self.class.name.split('::').last
+    end
+
+    def calling_file
+      file_fq, _line_number, _extra = backtrace[0].split(':')
+      file_fq
+    end
+
+    # @return HTML <div> tag with class set to the snake_case version of the error class name.
+    def html_message
+      shorten_backtrace
+      line_number = self.class.class_variable_get :@@line_number
+      path = self.class.class_variable_get :@@path
+      <<~END_MSG
+        <div class='#{error_name.snakecase}'>
+          #{self.class} raised in #{calling_file} while processing line #{line_number} (after front matter) of #{path}
+          #{message}
+        </div>
+      END_MSG
+    end
+
+    def logger_message
+      shorten_backtrace
+      kaller = caller(1..1).first
+      line_number = self.class.class_variable_get :@@line_number
+      path = self.class.class_variable_get :@@path
+      <<~END_MSG
+        #{error_name} raised in #{kaller} while processing line #{line_number} (after front matter) of #{path}
+          #{message}
+      END_MSG
+    end
+
+    def shorten_backtrace(backtrace_element_count = 3)
+      b = backtrace[0..backtrace_element_count - 1].map do |x|
+        x.gsub(Dir.pwd + '/', './')
+      end
+      set_backtrace b
+    end
+  end
+end

data/lib/jekyll_plugin_error_handling.rb

@@ -19,20 +19,23 @@ module JekyllSupportErrorHandling
   rescue StandardError => e
     file, line_number, caller = e.backtrace[caller_index].split(':')
     caller = caller.tr('`', "'")
-    warn "#{error.msg} #{caller} on line #{line_number} (after front matter) of #{file}".red
+    warn "#{error.message} #{caller} on line #{line_number} (after front matter) of #{file}".red
     # Process.kill('HUP', Process.pid) # generates huge stack trace
     exec "echo ''"
   end
 
+  # TODO: Delete this
   def format_error_message(message)
     page = " of #{@page['path']}" if @page
     remove_ansi_color "on line #{line_number} (after front matter)#{page}.\n#{message}"
   end
 
+  # TODO: Delete this
   def remove_ansi_color(string)
     string.gsub(/\e\[([;\d]+)?m/, '')
   end
 
+  # TODO: Delete this
   def maybe_reraise_error(error, throw_error: true)
     fmsg = format_error_message "#{error.class}: #{error.message.strip}"
     @logger.error { fmsg }

data/lib/jekyll_plugin_helper.rb

@@ -25,7 +25,7 @@ class JekyllPluginHelper
     @markup = markup
   rescue StandardError => e
     e.shorten_backtrace
-    @logger.error { e.msg }
+    @logger.error { e.message }
   end
 
   # @return undefined if parameter was specified, removes it from the available tokens and returns value

data/lib/jekyll_plugin_helper_class.rb

@@ -1,3 +1,7 @@
+require 'facets/string/camelcase'
+require 'facets/string/snakecase'
+require 'yaml'
+
 # Class methods for JekyllPluginHelper
 class JekyllPluginHelper
   # Expand an environment variable reference
@@ -11,19 +15,56 @@ class JekyllPluginHelper
     end
   end
 
-  def self.register(klass, name)
-    abort("Error: The #{name} plugin does not define VERSION") \
+  def self.generate_message(klass, tag_name, version)
+    error_name_stub = klass.name.include?('::') ? klass.name.split('::')[1] : klass.name
+    error_ruby_class_name = "#{error_name_stub.camelcase(:upper)}Error"
+    config_die_key = "die_on_#{error_ruby_class_name.snakecase}"
+    error_css_class_name = error_ruby_class_name.split('::').last.snakecase
+    config = YAML.load_file('_config.yml')
+    tag_config = config[tag_name]
+    tag_config_msg = if tag_config.nil?
+                       <<~END_MSG
+                         _config.yml does not contain configuration information for this plugin.
+                           You could add a section containing default values by specifying a section for the tag name,
+                           and an entry whose name starts with `die_on_`, followed by a snake_case version of the error name.
+
+                             #{tag_name}:
+                               #{config_die_key}: false
+                       END_MSG
+                     else
+                       <<~END_MSG
+                         _config.yml contains the following configuration for this plugin:
+                           #{tag_config}
+                       END_MSG
+                     end
+
+    <<~END_MSG
+      Loaded plugin #{tag_name} v#{version}. It has:
+        Error class: #{error_ruby_class_name}
+        CSS class for error messages: #{error_css_class_name}
+
+        #{tag_config_msg}
+    END_MSG
+  end
+
+  def self.register(klass, tag_name)
+    abort("Error: The #{tag_name} plugin does not define VERSION") \
       unless klass.const_defined?(:VERSION)
 
     version = klass.const_get(:VERSION)
 
-    abort("Error: The #{name} plugin is not an instance of JekyllSupport::JekyllBlock or JekyllSupport::JekyllTag") \
+    abort("Error: The #{tag_name} plugin is not an instance of JekyllSupport::JekyllBlock or JekyllSupport::JekyllTag") \
       unless klass.instance_of?(Class) &&
              (klass.ancestors.include?(JekyllSupport::JekyllBlock) ||
               klass.ancestors.include?(JekyllSupport::JekyllTag))
 
-    Liquid::Template.register_tag(name, klass)
-    PluginMetaLogger.instance.info { "Loaded #{name} v#{version} plugin." }
+    Liquid::Template.register_tag(tag_name, klass)
+    msg = generate_message(klass, tag_name, version)
+    PluginMetaLogger.instance.info { msg }
+  end
+
+  def self.remove_html_tags(string)
+    string.gsub(/<[^>]*>/, '').strip
   end
 
   # strip leading and trailing quotes if present

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '0.8.0'.freeze
+  VERSION = '0.8.2'.freeze
 end

data/lib/jekyll_plugin_support.rb

@@ -15,3 +15,4 @@ require_relative 'jekyll_plugin_support_block'
 require_relative 'jekyll_plugin_support_block_noarg'
 require_relative 'jekyll_plugin_support_tag'
 require_relative 'jekyll_plugin_support_tag_noarg'
+require_relative 'jekyll_custom_error'

data/lib/jekyll_plugin_support_block.rb

@@ -24,6 +24,9 @@ module JekyllSupport
       @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.
@@ -41,6 +44,8 @@ module JekyllSupport
       @config = @site.config
       @tag_config = @config[@tag_name]
 
+      set_error_context
+
       @layout    = @envs[:layout]
       @paginator = @envs[:paginator]
       @theme     = @envs[:theme]
@@ -58,11 +63,15 @@ module JekyllSupport
       render_impl text
     rescue StandardError => e
       e.shorten_backtrace
-      msg = format_error_message e.full_message
-      @logger.error msg
+      @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
 
-      "<div class='standard_error'>#{e.class}: #{msg}</div>"
+      <<~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,
@@ -73,5 +82,15 @@ module JekyllSupport
     def render_impl(text)
       text
     end
+
+    def set_error_context
+      return unless Object.const_defined? @error_name
+
+      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
   end
 end

data/lib/jekyll_plugin_support_class.rb

@@ -1,3 +1,5 @@
+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)
@@ -20,7 +22,7 @@ module JekyllSupport
 
   # @return a new StandardError subclass containing the shorten_backtrace method
   def define_error
-    Class.new StandardError
+    Class.new Jekyll::CustomError
   end
   module_function :define_error
 
@@ -78,7 +80,7 @@ module JekyllSupport
   def self.warn_short_trace(logger, error)
     remaining = error.backtrace.length - DISPLAYED_CALLS
     logger.warn do
-      error.msg + "\n" +
+      error.message + "\n" +
         error.backtrace.take(DISPLAYED_CALLS).join("\n") +
         "\n...Remaining #{remaining} call sites elided.\n"
     end

data/lib/jekyll_plugin_support_tag.rb

@@ -27,6 +27,9 @@ module JekyllSupport
       @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
 
     # Method prescribed by the Jekyll plugin lifecycle.
@@ -45,6 +48,8 @@ module JekyllSupport
       @jps = @config['jekyll_plugin_support']
       @pry_on_standard_error = @jps['pry_on_standard_error'] || false if @jps
 
+      set_error_context
+
       # @envs.keys are :content, :highlighter_prefix, :highlighter_suffix, :jekyll, :layout, :page, :paginator, :site, :theme
       @layout    = @envs[:layout]
       @paginator = @envs[:paginator]
@@ -57,12 +62,15 @@ module JekyllSupport
       render_impl
     rescue StandardError => e
       e.shorten_backtrace
-      msg = format_error_message e.full_message
-      @logger.error msg
+      @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
 
-      "<div class='standard_error'>#{e.class}: #{msg}</div>"
+      <<~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
@@ -71,5 +79,15 @@ module JekyllSupport
     def render_impl
       abort "#{self.class}.render_impl for tag #{@tag_name} must be overridden, but it was not."
     end
+
+    def set_error_context
+      return unless Object.const_defined? @error_name
+
+      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
   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/status_persistence.txt

@@ -1,7 +1,9 @@
 example_id                                       | status | run_time        |
 ------------------------------------------------ | ------ | --------------- |
-./spec/jekyll_plugin_helper_options_spec.rb[1:1] | failed | 0.00009 seconds |
-./spec/jekyll_plugin_helper_options_spec.rb[1:2] | failed | 0.00004 seconds |
-./spec/jekyll_plugin_helper_options_spec.rb[1:3] | failed | 0.00002 seconds |
-./spec/jekyll_plugin_helper_options_spec.rb[1:4] | failed | 0.00002 seconds |
+./spec/custom_error_spec.rb[1:1]                 | failed | 0.00772 seconds |
+./spec/custom_error_spec.rb[2:1]                 | passed | 0.0011 seconds  |
+./spec/jekyll_plugin_helper_options_spec.rb[1:1] | failed | 0.00005 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:2] | failed | 0.00003 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:3] | failed | 0.00003 seconds |
+./spec/jekyll_plugin_helper_options_spec.rb[1:4] | failed | 0.00003 seconds |
 ./spec/liquid_variable_parsing_spec.rb[1:1]      | failed | 0.00003 seconds |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-22 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -94,6 +94,7 @@ files:
 - README.md
 - Rakefile
 - jekyll_plugin_support.gemspec
+- lib/jekyll_custom_error.rb
 - lib/jekyll_plugin_error_handling.rb
 - lib/jekyll_plugin_helper.rb
 - lib/jekyll_plugin_helper_attribution.rb
@@ -106,6 +107,7 @@ files:
 - 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
@@ -142,6 +144,7 @@ signing_key:
 specification_version: 4
 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