jekyll_plugin_support 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3dd2c6f00993d77f9db69e844a1f70e52c21ac1ef66c47294cc7683dee5743
-  data.tar.gz: 121436f415bbcb0cddffa4f9b9c26f735e899aa733df38749e5be2856d56d238
+  metadata.gz: 75b8116adff0e7869b3d9d05def0b7cb702b67860e596e3b9901dce1f43182e7
+  data.tar.gz: 86da2a9936cbeffb9f381d3d2031f58acee7f79d8efd7a37b2f4864c3201b20e
 SHA512:
-  metadata.gz: b6d186e5d5347b7857cef3318a152a4a9db75e57ebe7dc244dd0574542b47b2c97c4ba55af03065099cca94c3ca3fb3e666268fb4e2427683b94a0c058388a7b
-  data.tar.gz: 1529488c906cc7c687356f22b65223f347d75eb35f1747742466166921b266c4f172233eaf638bb06af7fdf6fcd93e67d0f6ca25cbde0f98139edb05fb07d64a
+  metadata.gz: f944740ed80b93a8d5fa6e0e4d3a4b0fe04761aa546d2dfea10b3929d7650daf87afdcd295b3698d80ded0f50209fe04a9c918914f216cfcabc335314da7454a
+  data.tar.gz: c5d1f11b7fb11900a94ba1430faca977794d84fd4073e793cc50128e922c401adaee2ea5ecdc2eef16b3ed1450e0ac98e5eeff1b8dc96fcc9fda1610b04dc2f8

data/.rubocop.yml

@@ -1,5 +1,11 @@
+require:
+  - rubocop-rspec
+  - rubocop-rake
+  # - rubocop-jekyll
+
 AllCops:
   Exclude:
+    - demo/_site/**/*
     - exe/**/*
     - vendor/**/*
     - Gemfile*
@@ -13,16 +19,24 @@ Gemspec/RequireMFA:
   Enabled: false
 
 Layout/HashAlignment:
-  Enabled: false
+  EnforcedHashRocketStyle: table
 
 Layout/LineLength:
   Max: 150
 
+Layout/CommentIndentation:
+  Exclude:
+    - spec/**/*
+
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 
+Lint/RedundantCopDisableDirective:
+  Exclude:
+    - jekyll_plugin_support.gemspec
+
 Metrics/AbcSize:
-  Max: 20
+  Max: 30
 
 Metrics/BlockLength:
   Exclude:
@@ -31,11 +45,17 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Max: 25
 
-Style/FrozenStringLiteralComment:
-  Enabled: false
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 15
 
 Style/Documentation:
   Enabled: false
 
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 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.
+  * 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.
+
 ## 0.5.0 / 2023-02-15
   * Plugins now register themselves
   * Plugins now report their name and version

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,8 +47,10 @@ 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 MyTag < JekyllSupport::JekyllTag
     VERSION = '0.1.0'.freeze
@@ -56,12 +58,16 @@ module Jekyll
     def render_impl
       # Your code here
     end
+
+    JekyllPluginHelper.register(self, 'demo_tag')
   end
 end
 ```
 
+### For a tag block:
 ```ruby
-# For a tag block:
+require 'jekyll_plugin_support'
+
 module Jekyll
   class MyBlock < JekyllSupport::JekyllBlock
     VERSION = '0.1.0'.freeze
@@ -69,6 +75,8 @@ module Jekyll
     def render_impl(text)
       # Your code here
     end
+
+    JekyllPluginHelper.register(self, 'demo_block')
   end
 end
 ```
@@ -79,12 +87,15 @@ For example, if `lib/my_plugin/version.rb` looks like this:
 
 ```ruby
 module MyPluginVersion
-  VERSION = '0.5.0'.freeze
+  VERSION = '0.5.1'.freeze
 end
 ```
 
 Then your plugin can incorporate the `VERSION` constant into your plugin like this:
 ```ruby
+require 'jekyll_plugin_support'
+require_relative 'my_block/version'
+
 module Jekyll
   class MyBlock < JekyllSupport::JekyllBlock
     include MyPluginVersion
@@ -92,10 +103,71 @@ module Jekyll
     def render_impl(text)
       # Your code here
     end
+
+    JekyllPluginHelper.register(self, 'demo_tag')
   end
 end
 ```
 
+### Argument Parsing
+Tag arguments can be obtained within `render_impl`.
+Both keyword options and name/value parameters are supported.
+
+Both `JekyllTag` and `JekyllBlock` use the standard Ruby mechanism for parsing command-line options:
+[`shellwords`](https://ruby-doc.org/stdlib-2.5.1/libdoc/shellwords/rdoc/Shellwords.html) and
+[`key_value_parser`](https://www.rubydoc.info/gems/key-value-parser).
+
+All your code has to do is to specify the keywords to search for in the string passed from the HTML page that your tag is embedded in.
+The included `demo` website has examples; both [`demo/_plugins/demo_tag.rb`](demo/_plugins/demo_tag.rb) and
+[`demo/_plugins/demo_block.rb`](demo/_plugins/demo_block.rb) contain the following:
+
+```ruby
+@keyword1  = @helper.parameter_specified? 'keyword1'
+@keyword2  = @helper.parameter_specified? 'keyword2'
+@name1  = @helper.parameter_specified? 'name1'
+@name2  = @helper.parameter_specified? 'name2'
+```
+
+In [`demo/index.html`](demo/index.html), the following invoked the tag:
+
+```html
+{% demo_tag keyword1 name1='value1' unreferenced_key unreferenced_name="unreferenced_value" %}
+```
+
+The `demo/_plugins/demo_tag.rb` plugin uses `@helper.parameter_specified?` provided by
+`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,
+    that keyword option is removed from the argument string.
+  - 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"`.
+
+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`
+
+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'`
+
+#### 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`.
+
+
 ## Additional Information
 More information is available on
 [Mike Slinn&rsquo;s website](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
@@ -128,7 +200,7 @@ jekyll_plugin_support (0.1.0)
     License: MIT
     Installed at: /home/mslinn/.gems
 
-    Generates Jekyll logger with colored output.
+    Provides support for writing Jekyll plugins.
 ```
 
 

data/jekyll_plugin_support.gemspec

@@ -1,6 +1,6 @@
 require_relative 'lib/jekyll_plugin_support/version'
 
-Gem::Specification.new do |spec|
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   github = 'https://github.com/mslinn/jekyll_plugin_support'
 
   spec.bindir = 'exe'

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '0.5.0'.freeze
+  VERSION = '0.5.2'.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,9 +84,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.
@@ -94,7 +112,18 @@ module JekyllSupport
     # 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

@@ -3,7 +3,7 @@ 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 an environment variable reference
   def self.expand_env(str, die_if_undefined: false)
@@ -45,20 +45,43 @@ 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
+    @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
-    @argv = Shellwords.split(self.class.expand_env(markup))
-    @keys_values = KeyValueParser \
-      .new({}, { array_values: false, normalize_keys: false, separator: /=/ }) \
-      .parse(@argv)
+    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)
+      @params = @keys_values.map { |k, _v| lookup_variable(k) } unless respond_to?(:no_arg_parsing) && no_arg_parsing
+    end
+  end
+
+  # Call this method to return the remaining markup after `parameter_specified?` has been invoked.
+  def remaining_markup
+    @argv.join(' ')
   end
 
   def delete_parameter(key)
@@ -106,7 +129,6 @@ 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) }
   end
 
   def lookup_variable(symbol)

data/spec/jekyll_block_plugin_support_spec.rb

@@ -1,41 +1,60 @@
 require 'jekyll_plugin_logger'
-# require 'rspec/match_ignoring_whitespace'
+require 'rspec/match_ignoring_whitespace'
 require_relative '../lib/jekyll_plugin_support'
 require_relative '../lib/jekyll_plugin_support_spec_support'
 
-# Lets get this party started
 class MyTest
-  RSpec.describe JekyllSupport::JekyllBlock do
-    let(:logger) do
-      PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+  RSpec.describe JekyllPluginHelper do
+    logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+
+    it 'parses quoted string options' do
+      helper = described_class.new('my_tag', "colors='blue or green' blah ick", logger, false)
+      expect(helper.keys_values.keys).to eq(%w[colors blah ick])
+
+      colors = helper.parameter_specified? 'colors'
+      expect(colors).to eq('blue or green')
+
+      expect(helper.keys_values.keys).to eq(%w[blah ick])
+    end
+
+    it 'parses unquoted string options' do
+      helper = described_class.new('my_tag', 'color=blue blah ick', logger, false)
+      expect(helper.keys_values.keys).to eq(%w[color blah ick])
+
+      color = helper.parameter_specified? 'color'
+      expect(color).to eq('blue')
+
+      expect(helper.keys_values.keys).to eq(%w[blah ick])
+    end
+
+    it 'parses quoted booleans' do
+      helper = described_class.new('my_tag', "bool1='true' bool2='false' blah ick", logger, false)
+      expect(helper.keys_values.keys).to eq(%w[bool1 bool2 blah ick])
+
+      bool1 = helper.parameter_specified? 'bool1'
+      expect(bool1).to be true
+
+      bool2 = helper.parameter_specified? 'bool2'
+      expect(bool2).to be false
+
+      expect(helper.keys_values.keys).to eq(%w[blah ick])
+
+      expect(helper.remaining_markup).to eq('blah ick')
     end
 
-    let(:parse_context) { TestParseContext.new }
-
-    # Example for plugin authors to refer to:
-    #
-    # let(:helper) do
-    #   JekyllTagHelper.new(
-    #     'quote',
-    #     "cite='This is a citation' url='https://blah.com' This is the quoted text.",
-    #     logger
-    #   )
-    # end
-    #
-    # fit 'is created properly' do
-    #   command_line = "cite='This is a citation' url='https://blah.com' This is the quoted text.".dup
-    #   quote = Jekyll::Quote.send(
-    #     :new,
-    #     'quote',
-    #     command_line,
-    #     parse_context
-    #   )
-    #   result = quote.send(:render_impl, command_line)
-    #   expect(result).to match_ignoring_whitespace <<-END_RESULT
-    #     <div class='quote'>
-    #       This is the quoted text.
-    #     </div>
-    #   END_RESULT
-    # end
+    it 'parses unquoted booleans' do
+      helper = described_class.new('my_tag', 'bool1=true bool2=false blah ick', logger, false)
+      expect(helper.keys_values.keys).to eq(%w[bool1 bool2 blah ick])
+
+      bool1 = helper.parameter_specified? 'bool1'
+      expect(bool1).to be true
+
+      bool2 = helper.parameter_specified? 'bool2'
+      expect(bool2).to be false
+
+      expect(helper.keys_values.keys).to eq(%w[blah ick])
+
+      expect(helper.remaining_markup).to eq('blah ick')
+    end
   end
 end

data/spec/spec_helper.rb

@@ -3,7 +3,7 @@ require_relative '../lib/jekyll_plugin_support'
 
 RSpec.configure do |config|
   config.filter_run :focus
-  config.order = 'random'
+  # config.order = 'random'
   config.run_all_when_everything_filtered = true
 
   # See https://relishapp.com/rspec/rspec-core/docs/command-line/only-failures

data/spec/status_persistence.txt

@@ -0,0 +1,6 @@
+example_id                                                                                        | status | run_time        |
+------------------------------------------------------------------------------------------------- | ------ | --------------- |
+/mnt/_/work/jekyll/my_plugins/jekyll_plugin_support/spec/jekyll_block_plugin_support_spec.rb[1:1] | passed | 0.00335 seconds |
+/mnt/_/work/jekyll/my_plugins/jekyll_plugin_support/spec/jekyll_block_plugin_support_spec.rb[1:2] | passed | 0.00019 seconds |
+/mnt/_/work/jekyll/my_plugins/jekyll_plugin_support/spec/jekyll_block_plugin_support_spec.rb[1:3] | passed | 0.00337 seconds |
+/mnt/_/work/jekyll/my_plugins/jekyll_plugin_support/spec/jekyll_block_plugin_support_spec.rb[1:4] | passed | 0.00026 seconds |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-16 00:00:00.000000000 Z
+date: 2023-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -70,7 +70,6 @@ files:
 - lib/jekyll_plugin_support_helper.rb
 - lib/jekyll_plugin_support_spec_support.rb
 - 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
@@ -106,7 +105,6 @@ specification_version: 4
 summary: Provides support for writing Jekyll plugins.
 test_files:
 - spec/jekyll_block_plugin_support_spec.rb
-- spec/jekyll_tag_plugin_support_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
 ...

data/spec/jekyll_tag_plugin_support_spec.rb

@@ -1,41 +0,0 @@
-require 'jekyll_plugin_logger'
-# require 'rspec/match_ignoring_whitespace'
-require_relative '../lib/jekyll_plugin_support'
-require_relative '../lib/jekyll_plugin_support_spec_support'
-
-# Lets get this party started
-class MyTest
-  RSpec.describe JekyllSupport::JekyllTag do
-    let(:logger) do
-      PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
-    end
-
-    let(:parse_context) { TestParseContext.new }
-
-    # Example for plugin authors to refer to:
-    #
-    # let(:helper) do
-    #   JekyllTagHelper.new(
-    #     'quote',
-    #     "cite='This is a citation' url='https://blah.com' This is the quoted text.",
-    #     logger
-    #   )
-    # end
-    #
-    # fit 'is created properly' do
-    #   command_line = "cite='This is a citation' url='https://blah.com' This is the quoted text.".dup
-    #   quote = Jekyll::Quote.send(
-    #     :new,
-    #     'quote',
-    #     command_line,
-    #     parse_context
-    #   )
-    #   result = quote.send(:render_impl, command_line)
-    #   expect(result).to match_ignoring_whitespace <<-END_RESULT
-    #     <div class='quote'>
-    #       This is the quoted text.
-    #     </div>
-    #   END_RESULT
-    # end
-  end
-end