jekyll_plugin_support 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53975ba14d38fdc37e99ed9363b3d30885a301541c254584ae70d18157fc0e3f
-  data.tar.gz: ccd9fc245d26fce6fa24bbc8edcda670faa017df3e08c75ec08effa760fa44ae
+  metadata.gz: d0856ddeea29e8a1e24f0a4997aecb7f6b6b22eae587ca8466142686b65557b7
+  data.tar.gz: ac8a8a047666f89b055b6ab90d6535b59e7f34441405852f5905ed6a517cbc27
 SHA512:
-  metadata.gz: f78badf8195aebeb9401a974aebd589b1f9af69e9d6c83a3dd7d7340f2edc93ad418ef6806915dc130cb4deab5c0beb80eca15cd27189cdca999bd15d1434081
-  data.tar.gz: dde45223b684b140e3c5e7d2633d96f39e974c148094243a979cebe60c33af5383e761c3e9aa6a60d34cdd71b90a550c39964f7e6e63c692660d536990074b39
+  metadata.gz: 8122412d70d1c99a6195834a51faa25f0d7beb59a23c18db0beba2883c83f5625920a63495b7ff21abf891faf97ae2ffe085c764c2be9d178bfeb37a7ae4e2f5
+  data.tar.gz: abd34bf8420c7040e7015ce131a8ae3ea01158a552637a4e8d63c51095c138bdf87fd11bff1c3fb3f35fbd3e8b728a09934c4aefe0bbe29817703bdb032a8114

data/.rubocop.yml

@@ -1,10 +1,17 @@
 AllCops:
   Exclude:
-      - vendor/**/*
-      - Gemfile*
+    - exe/**/*
+    - vendor/**/*
+    - Gemfile*
   NewCops: enable
   TargetRubyVersion: 2.6
 
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
 Layout/HashAlignment:
   Enabled: false
 
@@ -14,5 +21,21 @@ Layout/LineLength:
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - jekyll_plugin_support.gemspec
+
+Metrics/MethodLength:
+  Max: 25
+
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.5.1 / 2023-02-17
+  * `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/).)
+
 ## 0.4.1 / 2023-02-14
   * Fixed several problems
   * Added demo site

data/README.md

@@ -19,7 +19,7 @@ And then execute:
 
     $ bundle install
 
-## Usage
+## 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.
@@ -47,32 +47,74 @@ For block tags, a single parameter is required, which contains any text enclosed
 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
-# For a tag:
+require 'jekyll_plugin_support'
+
 module Jekyll
-  class Quote < JekyllSupport::JekyllTag
+  class MyTag < JekyllSupport::JekyllTag
+    VERSION = '0.1.0'.freeze
+
     def render_impl
-      site_data = @site.data
-      @break  = @helper.parameter_specified? 'break'
-      # ...
+      # Your code here
+    end
+
+    JekyllPluginHelper.register(self, 'demo_tag')
+  end
+end
+```
+
+### For a tag block:
+```ruby
+require 'jekyll_plugin_support'
+
+module Jekyll
+  class MyBlock < JekyllSupport::JekyllBlock
+    VERSION = '0.1.0'.freeze
+
+    def render_impl(text)
+      # Your code here
     end
+
+    JekyllPluginHelper.register(self, 'demo_block')
   end
 end
 ```
 
+Note that each tag or tag block must define a constant called `VERSION`.
+If your plugin is packaged as a gem, then you might need to include `version.rb` into the plugin class.
+For example, if `lib/my_plugin/version.rb` looks like this:
+
+```ruby
+module MyPluginVersion
+  VERSION = '0.5.1'.freeze
+end
+```
+
+Then your plugin can incorporate the `VERSION` constant into your plugin like this:
 ```ruby
-# For a tag block:
+require 'jekyll_plugin_support'
+require_relative 'my_block/version'
+
 module Jekyll
-  class Quote < JekyllSupport::JekyllBlock
+  class MyBlock < JekyllSupport::JekyllBlock
+    include MyPluginVersion
+
     def render_impl(text)
-      site_url = @site.url
-      @break  = @helper.parameter_specified? 'break'
-      # ...
+      # Your code here
     end
+
+    JekyllPluginHelper.register(self, 'demo_tag')
   end
 end
 ```
 
+### `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`.
+
+
 ## Additional Information
 More information is available on
 [Mike Slinn&rsquo;s website](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).

data/Rakefile

@@ -2,4 +2,4 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
-task :default => :spec
+task default: :spec

data/jekyll_plugin_support.gemspec

@@ -21,26 +21,14 @@ Gem::Specification.new do |spec|
 
     Thanks for installing #{spec.name}!
 
-  END_MESSAGE
-  spec.post_install_message = <<~END_MESSAGE
-
-    Thanks for installing #{spec.name}!
-
   END_MESSAGE
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
   spec.summary = 'Provides support for writing Jekyll plugins.'
   spec.test_files = spec.files.grep %r{^(test|spec|features)/}
-  spec.version = JekyllQuoteVersion::VERSION
+  spec.version = JekyllPluginSupportVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
   spec.add_dependency 'jekyll_plugin_logger'
   spec.add_dependency 'key-value-parser'
-
-  spec.add_development_dependency 'debase'
-  spec.add_development_dependency 'rspec-match_ignoring_whitespace'
-  # spec.add_development_dependency 'rubocop-jekyll'
-  spec.add_development_dependency 'rubocop-rake'
-  spec.add_development_dependency 'rubocop-rspec'
-  spec.add_development_dependency 'ruby-debug-ide'
 end

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
-module JekyllQuoteVersion
-  VERSION = '0.4.1'.freeze
+module JekyllPluginSupportVersion
+  VERSION = '0.5.1'.freeze
 end

data/lib/jekyll_plugin_support.rb

@@ -5,6 +5,12 @@ require_relative 'jekyll_plugin_support/version'
 
 # @author Copyright 2022 Michael Slinn
 # @license SPDX-License-Identifier: Apache-2.0``
+module NoArgParsing
+  attr_accessor :no_arg_parsing
+
+  @no_arg_parsing = true
+end
+
 module JekyllSupport
   # Base class for Jekyll block tags
   class JekyllBlock < Liquid::Block
@@ -22,9 +28,10 @@ module JekyllSupport
     def initialize(tag_name, argument_string, parse_context)
       super
       @tag_name = tag_name
-      @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
-      @helper = JekyllPluginHelper.new(tag_name, argument_string, @logger)
       @argument_string = argument_string
+      @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))
     end
 
     # Method prescribed by the Jekyll plugin lifecycle.
@@ -33,8 +40,7 @@ module JekyllSupport
       text = super
       @helper.liquid_context = liquid_context
 
-      # The names of front matter variables are hash keys for @page
-      @page = liquid_context.registers[:page] # Jekyll::Drops::DocumentDrop
+      @page = liquid_context.registers[:page] # Type Jekyll::Drops::DocumentDrop
       @site = liquid_context.registers[:site]
       @config = @site.config
       @envs = liquid_context.environments.first
@@ -51,6 +57,17 @@ module JekyllSupport
     end
   end
 
+  class JekyllBlockNoArgParsing < JekyllBlock
+    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'}." }
+    end
+  end
+
   # Base class for Jekyll tags
   class JekyllTag < Liquid::Tag
     attr_reader :argument_string, :helper, :line_number, :logger, :page, :site
@@ -67,26 +84,46 @@ module JekyllSupport
     def initialize(tag_name, argument_string, parse_context)
       super
       @tag_name = tag_name
-      @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
-      @helper = JekyllPluginHelper.new(tag_name, argument_string, @logger)
       @argument_string = argument_string
+      @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))
     end
 
     # Method prescribed by the Jekyll plugin lifecycle.
     def render(liquid_context)
       @helper.liquid_context = liquid_context
-      @page = liquid_context.registers[:page]
-      @site = liquid_context.registers[:site]
+
+      @envs      = liquid_context.environments.first
+
+      @layout    = @envs[:layout]
+      @paginator = @envs[:paginator]
+      @theme     = @envs[:theme]
+
+      @page      = liquid_context.registers[:page]
+      @site      = liquid_context.registers[:site]
+
       @config = @site.config
-      @envs = liquid_context.environments.first
       @mode = @config['env']['JEKYLL_ENV'] || 'development'
+
       render_impl
     end
 
     # Jekyll plugins must override this method, not render, so their plugin can be tested more easily
     # @page and @site are available
     def render_impl
-      abort "JekyllTag render_impl for tag #{@tag_name} must be overridden, but it was not."
+      abort "#{self.class}.render_impl for tag #{@tag_name} must be overridden, but it was not."
+    end
+  end
+
+  class JekyllTagNoArgParsing < JekyllTag
+    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
   end
 end

data/lib/jekyll_plugin_support_helper.rb

@@ -1,13 +1,11 @@
-# frozen_string_literal: true
-
 require 'shellwords'
 require 'key_value_parser'
 
 # Base class for all types of Jekyll plugin helpers
 class JekyllPluginHelper
-  attr_reader :argv, :keys_values, :liquid_context, :logger, :markup, :params, :tag_name
+  attr_reader :argv, :keys_values, :liquid_context, :logger, :markup, :no_arg_parsing, :params, :tag_name
 
-  # Expand a environment variable reference
+  # Expand an environment variable reference
   def self.expand_env(str, die_if_undefined: false)
     str.gsub(/\$([a-zA-Z_][a-zA-Z0-9_]*)|\${\g<1>}|%\g<1>%/) do
       envar = Regexp.last_match(1)
@@ -18,6 +16,21 @@ class JekyllPluginHelper
     end
   end
 
+  def self.register(klass, name)
+    abort("Error: The #{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") \
+      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." }
+  end
+
   # strip leading and trailing quotes if present
   def self.remove_quotes(string)
     string.strip.gsub(/\A'|\A"|'\Z|"\Z/, '').strip if string
@@ -32,20 +45,37 @@ class JekyllPluginHelper
   #        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, logger)
+  def initialize(tag_name, markup, logger, no_arg_parsing)
     @tag_name = tag_name
     @logger = logger
-    @logger.debug { "@keys_values='#{@keys_values}'" }
+    @no_arg_parsing = no_arg_parsing
     reinitialize(markup.strip)
+    @logger.debug { "@keys_values='#{@keys_values}'" }
+  end
+
+  def warn_fetch(variable)
+    abort "Error: Argument parsing was suppressed, but an attempt to obtain the value of #{variable} was made"
+  end
+
+  def warn_parse(meth)
+    abort "Error: Argument parsing was suppressed, but an attempt to invoke #{meth} was made"
   end
 
   def reinitialize(markup)
     # @keys_values was a Hash[Symbol, String|Boolean] but now it is Hash[String, String|Boolean]
-    @markup = markup # Useful for debugging
-    @argv = Shellwords.split(JekyllPluginHelper.expand_env(markup))
-    @keys_values = KeyValueParser \
-      .new({}, { array_values: false, normalize_keys: false, separator: /=/ }) \
-      .parse(@argv)
+    @markup = markup
+    if @no_arg_parsing
+      define_singleton_method(:argv) { warn_fetch :argv }
+      define_singleton_method(:keys_values) { warn_fetch :keys_values }
+      define_singleton_method(:params) { warn_fetch :params }
+      define_singleton_method(:parameter_specified?) { |_name| warn_parse(:parameter_specified?) }
+      define_singleton_method(:delete_parameter) { |_name| warn_parse(:delete_parameter) }
+    else
+      @argv = Shellwords.split(self.class.expand_env(markup))
+      @keys_values = KeyValueParser \
+        .new({}, { array_values: false, normalize_keys: false, separator: /=/ }) \
+        .parse(@argv)
+    end
   end
 
   def delete_parameter(key)
@@ -93,7 +123,7 @@ class JekyllPluginHelper
   # Sets @params by replacing any Liquid variable names with their values
   def liquid_context=(context)
     @liquid_context = context
-    @params = @keys_values.map { |k, _v| lookup_variable(k) }
+    @params = @keys_values.map { |k, _v| lookup_variable(k) } unless respond_to?(:no_arg_parsing) && no_arg_parsing
   end
 
   def lookup_variable(symbol)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-14 00:00:00.000000000 Z
+date: 2023-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -52,76 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: debase
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec-match_ignoring_whitespace
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: ruby-debug-ide
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description:
 email:
 - mslinn@mslinn.com
@@ -142,6 +72,7 @@ files:
 - spec/jekyll_block_plugin_support_spec.rb
 - spec/jekyll_tag_plugin_support_spec.rb
 - spec/spec_helper.rb
+- spec/status_persistence.txt
 homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#quote
 licenses:
 - MIT
@@ -177,4 +108,5 @@ test_files:
 - spec/jekyll_block_plugin_support_spec.rb
 - spec/jekyll_tag_plugin_support_spec.rb
 - spec/spec_helper.rb
+- spec/status_persistence.txt
 ...