jekyll_plugin_support 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d4b97854b427b9113f6db8e175608ac5e2b3fc5866c0062449c9b7e5c530798
-  data.tar.gz: 39c0b2b1ee1b457df3e339edb166d295fdf14b83faeb44a6261be39993fc82f4
+  metadata.gz: 89499adafe6c65e0579f3a9bb6a1e724001dda3465777f189ba67407ae105f73
+  data.tar.gz: 284b6a91b644e2989e4f28decb8a29c597b0b1baaf30549b611ea21939d00990
 SHA512:
-  metadata.gz: db5aa2fe02695556bb5bc7c95e53c5eb98990688fd1920bcab97503262979ef4266ac95210da7fc5d60a67f635b2fe11e7b18ebd3d35ab6e4bdbeedc1d116442
-  data.tar.gz: accae0af9a79e92f812980db24e23e33b7555362f24e28f9dd099f6faa57e7484a7043ddeccb16aa10f1d6a7d187cf6ee9f023bbd030d8cb49bf9984dc8049eb
+  metadata.gz: 1bb5b49b8bcf8d7ac2f6a8b0650c4ddf2e405db76295190cf5257154495db1f4f2491c676842a01c1c8607f4abd666655336fd4675828df716eff85bf0f66483
+  data.tar.gz: 54bc0d824c5e635be5143b70088a0229cd79b6a80992284e53119c2578b3e7a6fb3e57a31ec0b23f2dec5a8ed6afffd800213d0b5e1617d1d2d087241651d3b9

data/CHANGELOG.md

@@ -1,56 +1,101 @@
+# Change Log
+
+## 0.7.2 / 2023-08-14
+
+* Hopefully takes care of issue [#4](../../issues/4).
+
+
+## 0.7.1 / 2023-08-11
+
+* Suppressed stack trace from issue [#4](../../issues/4).
+* Now using Shopify `ruby-lsp` instead of `rebornix.Ruby` by Peng Lv
+* Debug configurations changed to `rdbg` instead of `ruby`, so the `debase` development dependency was changed to
+  [`debug`](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg),
+  which provides the `rdgb` command.
+  The `ruby-debug-ide` development dependency is also no longer required.
+
+
 ## 0.7.0 / 2023-05-22
-  * Added `error_short_trace` and `warn_short_trace` methods for displaying non-fatal errors on the console.
+
+* Added `error_short_trace` and `warn_short_trace` methods for displaying non-fatal errors on the console.
 
 ## 0.6.2 / 2023-05-15
-  * Removed annoying blank line output when attribute was invoked.
+
+* Removed annoying blank line output when attribute was invoked.
 
 ## 0.6.1 / 2023-04-12
-  * Added `CallChain.excerpt_caller` to detect if an excerpt is being generated.
+
+* Added `CallChain.excerpt_caller` to detect if an excerpt is being generated.
+
 
 ## 0.6.0 / 2023-04-05
-  * Added attribution support
-  * Renamed `jekyll_plugin_support_helper.rb` to `jekyll_plugin_helper.rb`.
-  * Now returns `undefined` instead of `false'` when `@keys_values.empty?`
-    and parameter is not specified.
+
+* Added attribution support
+* Renamed `jekyll_plugin_support_helper.rb` to `jekyll_plugin_helper.rb`.
+* Now returns `undefined` instead of `false'` when `@keys_values.empty?`
+  and parameter is not specified.
+
 
 ## 0.5.3 / 2023-03-19
-  * Added properties `argv_original`, `keys_values_original`, `remaining_markup_original`,
+
+* Added properties `argv_original`, `keys_values_original`, `remaining_markup_original`,
     and `params_original`, which are the original values of `argv`, `keys_values`,
     `remaining_markup`, and `params`, before environment variable expansion.
 
+
 ## 0.5.2 / 2023-03-17
-  * Added `@helper.remaining_markup` public method, which returns remaining markup passed to your tag, after keyword and name/value parsing is complete.
+
+* Added `@helper.remaining_markup` public method, which returns remaining markup passed to your tag,
+  after keyword and name/value parsing is complete.
   * Finally wrote proper `rspec` tests.
   * Finally documented argument parsing.
   * Fixed bug introduced in v0.5.1 which did not remove elements from `@params`.
 
+
 ## 0.5.1 / 2023-02-17
-  * `no_arg_parsing` optimization added.
+
+* `no_arg_parsing` optimization added.
+
 
 ## 0.5.0 / 2023-02-15
-  * Plugins now register themselves
-  * Plugins now report their name and version
-  * `@layout`, `@paginator`, and `@theme` have values if supported by the version of Jekyll, and they are active. (See [Jekyll docs](https://jekyllrb.com/docs/variables/).)
+
+* Plugins now register themselves
+* Plugins now report their name and version
+* `@layout`, `@paginator`, and `@theme` have values if supported by the version of Jekyll, and they are active.
+  (See [Jekyll docs](https://jekyllrb.com/docs/variables/).)
+
 
 ## 0.4.1 / 2023-02-14
-  * Fixed several problems
-  * Added demo site
+
+* Fixed several problems
+* Added demo site
+
 
 ## 0.4.0 / 2023-02-12
- * `render_impl` for tags and blocks now predefines more instance variables:
-   - `@liquid_context` – passed to `render`
-   - `@config` Jekyll configuration
-   - `@envs` Environment variables
-   - `@mode` ('development', 'test' or 'production')
+
+* `render_impl` for tags and blocks now predefines more instance variables:
+
+  * `@liquid_context` – passed to `render`
+  * `@config` Jekyll configuration
+  * `@envs` Environment variables
+  * `@mode` ('development', 'test' or 'production')
+
 
 ## 0.3.1 / 2023-02-07
-  * `JekyllBlock.render_impl` and `JekyllTag.render_impl` now define `@page` and `@site`.
+
+* `JekyllBlock.render_impl` and `JekyllTag.render_impl` now define `@page` and `@site`.
+
 
 ## 0.3.0 / 2023-01-14
-  * Added support for tags, which should subclass JekyllSupport::JekyllTag
+
+* Added support for tags, which should subclass JekyllSupport::JekyllTag
+
 
 ## 0.2.0 / 2023-01-12
-  * Refactored
+
+* Refactored
+
 
 ## 0.1.0 / 2023-01-10
-  * Initial version; only supports Jekyll block tags
+
+* Initial version; only supports Jekyll block tags

data/README.md

@@ -1,16 +1,17 @@
-`jekyll_plugin_support`
-[![Gem Version](https://badge.fury.io/rb/jekyll_plugin_support.svg)](https://badge.fury.io/rb/jekyll_plugin_support)
-===========
+# `jekyll_plugin_support` [![Gem Version](https://badge.fury.io/rb/jekyll_plugin_support.svg)](https://badge.fury.io/rb/jekyll_plugin_support)
 
 `Jekyll_plugin_support` is a Ruby gem that facilitates writing and testing Jekyll plugins.
 At present, only Jekyll tags and blocks are supported.
 
 
 ## Installation
+
 `Jekyll_plugin_support` can be used to create simple Jekyll plugins in the `_plugins/` directory, or gem-based Jekyll plugins.
 
-### Simple `_plugins`
-Add this line to your Jekyll plugin's Gemfile:
+### Simple Plugins
+
+For jekyll plugins defined in the `_plugins/` directory,
+add this line to your Jekyll plugin's `Gemfile`:
 
 ```ruby
 group :jekyll_plugins do
@@ -20,10 +21,13 @@ end
 
 And then execute:
 
-    $ bundle install
+```shell
+$ bundle
+```
 
 
 ### Gem-Based Plugins
+
 Add this line to your Jekyll plugin's `.gemspec`:
 
 ```ruby
@@ -32,16 +36,20 @@ spec.add_dependency 'jekyll_plugin_support'
 
 And then execute:
 
-    $ bundle install
+```shell
+$ bundle
+```
 
 
 ## General Usage
+
 `JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag`
 provide support for Jekyll tag blocks and Jekyll tags, respectively.
 They are very similar in construction and usage.
 
 Instead of subclassing your Jekyll block tag class from `Liquid::Block`,
 subclass from `JekyllSupport::JekyllBlock` instead.
+
 Similarly, instead of subclassing your Jekyll tag class from `Liquid::Tag`,
 subclass from `JekyllSupport::JekyllTag` instead.
 
@@ -64,6 +72,7 @@ Your implementation of `render_impl` can access `@page` and `@site`,
 and can parse parameters passed to the tag / block tag, [as described here](https://mslinn.com/jekyll/10100-jekyll-plugin-background.html#params):
 
 ### For a tag:
+
 ```ruby
 require 'jekyll_plugin_support'
 
@@ -84,6 +93,7 @@ end
 ```
 
 ### For a tag block:
+
 ```ruby
 require 'jekyll_plugin_support'
 
@@ -116,6 +126,7 @@ end
 ```
 
 Then your plugin can incorporate the `VERSION` constant into your plugin like this:
+
 ```ruby
 require 'jekyll_plugin_support'
 require_relative 'my_block/version'
@@ -139,6 +150,7 @@ end
 ```
 
 ### Argument Parsing
+
 Tag arguments can be obtained within `render_impl`.
 Both keyword options and name/value parameters are supported.
 
@@ -167,42 +179,45 @@ The `demo/_plugins/demo_tag.rb` plugin uses `@helper.parameter_specified?` provi
 `jekyll_support_plugin` to parse the string passed to the tag, which is
 `keyword1 name1='value1' unreferenced_key unreferenced_name="unreferenced_value"`.
 
-  - Because `keyword1` was referenced by `@helper.parameter_specified?` above,
+* Because `keyword1` was referenced by `@helper.parameter_specified?` above,
     that keyword option is removed from the argument string.
-  - Because the `name1` key/value parameter was referenced by `@helper.parameter_specified?` above,
+* Because the `name1` key/value parameter was referenced by `@helper.parameter_specified?` above,
     that name/value pair is removed from the argument string.
-  - The remainder of the argument string is now `unreferenced_key unreferenced_name="unreferenced_value"`.
+* The remainder of the argument string is now `unreferenced_key unreferenced_name="unreferenced_value"`.
 
 Name/value parameters can be quoted; if the value consists of only one token then it does not need to be quoted.
 The following name/value parameters all have the same result:
 
-  - `pay_tuesday="true"`
-  - `pay_tuesday='true'`
-  - `pay_tuesday=true`
-  - `pay_tuesday`
+* `pay_tuesday="true"`
+* `pay_tuesday='true'`
+* `pay_tuesday=true`
+* `pay_tuesday`
 
 The following also have the same result, however note that because the value has more than one token, quotes must be used:
 
-  - `pay_tuesday="maybe not"`
-  - `pay_tuesday='maybe not'`
+* `pay_tuesday="maybe not"`
+* `pay_tuesday='maybe not'`
 
 #### Remaining Markup
+
 After your plugin has parsed all the keyword options and name/value parameters,
 call `@helper.remaining_markup` to obtain the remaining markup that was passed to your plugin.
 
 
 ### `no_arg_parsing` Optimization
+
 If your tag or block plugin only needs access to the raw arguments passed from the web page,
 without tokenization, and you expect that the plugin might be invoked with large amounts of text,
 derive your plugin from `JekyllBlockNoArgParsing` or `JekyllTagNoArgParsing`.
 
 
 ## Subclass Attribution
+
 `JekyllTag` and `JekyllBlock` subclasses of `jekyll_plugin_support` can utilize the `attribution` option IFF they are published as a gem.
 `JekyllTagNoArgParsing` and `JekyllBlockNoArgParsing` subclasses cannot.
 
- - When used as a keyword option, a default value is used for the attribution string.
- - When used as a name/value option, the attribution string can be specified.
+* When used as a keyword option, a default value is used for the attribution string.
+* When used as a name/value option, the attribution string can be specified.
 
 Using the `attribution` option cause subclasses to replace their usual output with HTML that looks like:
 
@@ -218,9 +233,10 @@ The `id` attribute is in the sample HTML above is randomized so more than one at
 
 
 ### Usage
+
 Typical usage for the `attribution` tag is:
 
-```
+```html
 {% my_tag attribution %}
 ```
 
@@ -239,14 +255,17 @@ The `date` property is obtained from the plugin/gem publishing date.
 
 An alternative attribution string can be specified properties can be output using any of the above properties:
 
-```
+```html
 {% my_tag attribution="Generated by the #{name} #{version} Jekyll plugin, written by #{author} #{date}" %}
 ```
 
 ### Attribution Generation
-You can decide where you want the attribution string for your Jekyll tag to appear by invoking `@helper.attribute`. For example, this is how the [`jekyll_outline` tag](https://github.com/mslinn/jekyll_outline/blob/v1.1.1/lib/outline_tag.rb#L32-L46) generates output:
 
-```
+You can decide where you want the attribution string for your Jekyll tag to appear by invoking `@helper.attribute`.
+For example, this is how the
+[`jekyll_outline` tag](https://github.com/mslinn/jekyll_outline/blob/v1.1.1/lib/outline_tag.rb#L32-L46) generates output:
+
+```html
 <<~HEREDOC
 <div class="outer_posts">
 #{make_entries(collection)&.join("\n")}
@@ -257,8 +276,9 @@ HEREDOC
 
 
 ## Additional Information
+
 More information is available on
-[Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll/10200-jekyll-plugin-support.html).
+[Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html).
 
 
 ## Development
@@ -269,6 +289,7 @@ You can also run `bin/console` for an interactive prompt that will allow you to
 
 
 To build and install this gem onto your local machine, run:
+
 ```shell
 $ bundle exec rake install
 jekyll_plugin_support 0.1.0 built to pkg/jekyll_plugin_support-0.1.0.gem.
@@ -276,6 +297,7 @@ jekyll_plugin_support (0.1.0) installed.
 ```
 
 Examine the newly built gem:
+
 ```shell
 $ gem info jekyll_plugin_support
 
@@ -293,39 +315,48 @@ jekyll_plugin_support (0.1.0)
 
 
 ## Demo
+
 A demo / test website is provided in the `demo` directory.
 It can be used to debug the plugin or to run freely.
 
 ### Run Freely
+
  1. Run from the command line:
+
     ```shell
     $ demo/_bin/debug -r
     ```
 
-  2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+ 2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
 
 ### Plugin Debugging
+
  1. Set breakpoints in Visual Studio Code.
 
  2. Initiate a debug session from the command line:
+
     ```shell
     $ demo/_bin/debug
     ```
 
-  3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch
-     configuration called `Attach rdebug-ide`.
+ 3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch
+     configuration called `Attach with rdbg`.
 
-  4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+ 4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
 
 
 ### Build and Push to RubyGems
+
 To release a new version,
+
   1. Update the version number in `version.rb`.
   2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
   3. Run the following:
+
      ```shell
      $ bundle exec rake release
      ```
+
      The above creates a git tag for the version, commits the created tag,
      and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
 

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '0.7.0'.freeze
+  VERSION = '0.7.2'.freeze
 end

data/lib/jekyll_plugin_support.rb

@@ -1,3 +1,4 @@
+require 'colorator'
 require 'jekyll'
 require 'jekyll_plugin_logger'
 require_relative 'jekyll_plugin_helper'
@@ -15,7 +16,7 @@ module JekyllSupport
   DISPLAYED_CALLS = 8
 
   def self.error_short_trace(logger, error)
-    remaining = e.backtrace.length - DISPLAYED_CALLS
+    remaining = error.backtrace.length - DISPLAYED_CALLS
     logger.error do
       error.message + "\n" + # rubocop:disable Style/StringConcatenation
         error.backtrace.take(DISPLAYED_CALLS).join("\n") +
@@ -24,7 +25,7 @@ module JekyllSupport
   end
 
   def self.warn_short_trace(logger, error)
-    remaining = e.backtrace.length - DISPLAYED_CALLS
+    remaining = error.backtrace.length - DISPLAYED_CALLS
     logger.warn do
       error.message + "\n" + # rubocop:disable Style/StringConcatenation
         error.backtrace.take(DISPLAYED_CALLS).join("\n") +
@@ -75,14 +76,12 @@ module JekyllSupport
       @paginator = @envs[:paginator]
       @theme     = @envs[:theme]
 
-      @mode = @config['env']['JEKYLL_ENV'] || 'development'
+      @mode = @config['env']&.key?('JEKYLL_ENV') ? @config['env']['JEKYLL_ENV'] : 'development'
 
       render_impl text
     rescue StandardError => e
       @logger.error { "#{self.class} died with a #{e.full_message}" }
-      # raise SystemExit, 3, []
-      e.set_backtrace []
-      raise e
+      JekyllSupport.error_short_trace(@logger, e)
     end
 
     # Jekyll plugins should override this method, not render,
@@ -109,7 +108,7 @@ module JekyllSupport
       @logger.debug { "#{self.class}: respond_to?(:o_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
     rescue StandardError => e
       @logger.error { "#{self.class} died with a #{e.full_message}" }
-      exit 2
+      JekyllSupport.error_short_trace(@logger, e)
     end
 
     def warn_short_trace(error)
@@ -139,6 +138,29 @@ module JekyllSupport
       @helper = JekyllPluginHelper.new(tag_name, argument_string, @logger, respond_to?(:no_arg_parsing))
     end
 
+    # If a Jekyll plugin needs to crash exit, and stop Jekyll, call this method.
+    # It does not generate a stack trace.
+    # This method does not return because the process is abruptly terminated.
+    #
+    # @param error StandardError or a subclass of StandardError is required
+    #
+    # Do not raise the error before calling this method, just create it via 'new', like this:
+    # exit_without_stack_trace StandardError.new('This is my error message')
+    #
+    # If you want to call this method from a handler method, the default index for the backtrace array must be specified.
+    # The default backtrace index is 1, which means the calling method.
+    # To specify the calling method's caller, pass in 2, like this:
+    # exit_without_stack_trace StandardError.new('This is my error message'), 2
+    def exit_without_stack_trace(error, caller_index = 1)
+      raise error
+    rescue StandardError => e
+      file, line_number, caller = e.backtrace[caller_index].split(':')
+      caller = caller.tr('`', "'")
+      warn "#{self.class} died with a '#{error.message}' #{caller} on line #{line_number} of #{file}".red
+      # Process.kill('HUP', Process.pid) # generates huge stack trace
+      exec "echo ''"
+    end
+
     # @return line number where tag or block was found, relative to the start of the page
     def jekyll_line_number
       @page['front_matter'].count("\n") + @line_number
@@ -160,12 +182,11 @@ module JekyllSupport
       @site      = liquid_context.registers[:site]
 
       @config = @site.config
-      @mode = @config['env']['JEKYLL_ENV'] || 'development'
+      @mode = @config['env']&.key?('JEKYLL_ENV') ? @config['env']['JEKYLL_ENV'] : 'development'
 
       render_impl
     rescue StandardError => e
-      @logger.error { "#{self.class} died with a #{e.full_message}" }
-      exit 3
+      JekyllSupport.error_short_trace(@logger, e)
     end
 
     # Jekyll plugins must override this method, not render, so their plugin can be tested more easily

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-06 00:00:00.000000000 Z
+date: 2023-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -88,6 +88,7 @@ files:
 - lib/jekyll_plugin_support_spec_support.rb
 - spec/jekyll_plugin_helper_options_spec.rb
 - spec/spec_helper.rb
+- spec/status_persistence.txt
 homepage: https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html
 licenses:
 - MIT
@@ -122,4 +123,5 @@ summary: Provides support for writing Jekyll plugins.
 test_files:
 - spec/jekyll_plugin_helper_options_spec.rb
 - spec/spec_helper.rb
+- spec/status_persistence.txt
 ...