jekyll_plugin_support 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4efc790e49d3b2d98eb4e96bee8c75a18df25fcf7c08d66a44ef96d7c6db19c6
-  data.tar.gz: 6629e04d2170911427e4914c0d356e3f9c95149b7a673b2638242ba43cbe11fa
+  metadata.gz: cbe2d54d363697f10987c73cdd5e7f1f901f170109747f4319553b37251d14a5
+  data.tar.gz: 454e854eec50272cbb21bb107e9095585ea9dc4acaf066ee738cf322bdf6465a
 SHA512:
-  metadata.gz: 5afd0123f178c5fe89ddbfbf55e48a63630a3ebdffe07b28b60e6ba5d0df0ee1c7f6c5b4dc25ca0c77c5e0fe4329a46cf9902585cadbcc9ea90fed032dc4b459
-  data.tar.gz: fd6cb95f84f50655b12e81a069a6cdf85ec265f244159b200909ec9d7c8559871c4a781ddf162b10dd9a53eefb07614ed7cec172877130a52e2859a306df0512
+  metadata.gz: 58712d203762e16b5ed848f4bff32cdfb43494871c69482b3a29b5d76180dc3b67406fe42b0662e14ded8174bf4d7a49eab16c1c81c66721402d38be4a24ecd4
+  data.tar.gz: 10782bbeb291185bdb17a0d0cd5e37ab999f3c74569b415bc5d3892221bf8e43426cd2244be37b4a5ebc90ae2aa3d9d0327f8f5e3c5b0c7da9d9b06cc1cc3546

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

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

@@ -5,11 +5,10 @@ module Jekyll
   # Use like this:
   # CustomError.new(:MyError, 'blah', 'asdf')
   class CustomError < StandardError
-    def self.factory(name)
-      return if Object.const_defined? name
+    def self.factory(error_class_name)
+      return if Object.const_defined? "::#{error_class_name}"
 
-      puts "Defining #{name}".yellow
-      eval "#{name} = Class.new Jekyll::CustomError" # rubocop:disable Style/EvalWithLocation, Security/Eval
+      Object.const_set error_class_name, Class.new(CustomError)
     end
 
     def error_name

data/lib/jekyll_plugin_helper_class.rb

@@ -16,23 +16,24 @@ class JekyllPluginHelper
   end
 
   def self.generate_message(klass, tag_name, version)
-    error_ruby_class_name = "#{klass.name.camelcase(:upper)}Error"
+    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_file_fq = File.realpath 'demo/_config.yml'
-    config = YAML.load_file('demo/_config.yml')
+    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 like this:
+                           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
+                             #{tag_name}:
+                               #{config_die_key}: false
                        END_MSG
                      else
                        <<~END_MSG
-                         _config.yml contains the following configuration for this plugin is:
+                         _config.yml contains the following configuration for this plugin:
                            #{tag_config}
                        END_MSG
                      end
@@ -59,7 +60,7 @@ class JekyllPluginHelper
 
     Liquid::Template.register_tag(tag_name, klass)
     msg = generate_message(klass, tag_name, version)
-    PluginMetaLogger.instance.info msg
+    PluginMetaLogger.instance.info { msg }
   end
 
   def self.remove_html_tags(string)

data/lib/jekyll_plugin_support/version.rb

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

data/lib/jekyll_plugin_support_block.rb

@@ -8,14 +8,6 @@ module JekyllSupport
     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.
@@ -52,7 +44,7 @@ module JekyllSupport
       @config = @site.config
       @tag_config = @config[@tag_name]
 
-      set_error_context @error_name
+      set_error_context
 
       @layout    = @envs[:layout]
       @paginator = @envs[:paginator]
@@ -90,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_tag.rb

@@ -32,14 +32,6 @@ module JekyllSupport
       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
@@ -56,7 +48,7 @@ module JekyllSupport
       @jps = @config['jekyll_plugin_support']
       @pry_on_standard_error = @jps['pry_on_standard_error'] || false if @jps
 
-      set_error_context @error_name
+      set_error_context
 
       # @envs.keys are :content, :highlighter_prefix, :highlighter_suffix, :jekyll, :layout, :page, :paginator, :site, :theme
       @layout    = @envs[:layout]
@@ -87,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/status_persistence.txt

@@ -1,6 +1,9 @@
 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 |
+./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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Mike Slinn
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Provides a framework for writing and testing Jekyll plugins