jekyll_plugin_support 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0856ddeea29e8a1e24f0a4997aecb7f6b6b22eae587ca8466142686b65557b7
-  data.tar.gz: ac8a8a047666f89b055b6ab90d6535b59e7f34441405852f5905ed6a517cbc27
+  metadata.gz: 16fe00b243305d30e8dff85f604336e9c9802afe837a762dd295bd7283d8e1d4
+  data.tar.gz: c4ae30a570d27d77d17d7710be941731aefeaf11e4c2e19ec9f8fb773a9ad01d
 SHA512:
-  metadata.gz: 8122412d70d1c99a6195834a51faa25f0d7beb59a23c18db0beba2883c83f5625920a63495b7ff21abf891faf97ae2ffe085c764c2be9d178bfeb37a7ae4e2f5
-  data.tar.gz: abd34bf8420c7040e7015ce131a8ae3ea01158a552637a4e8d63c51095c138bdf87fd11bff1c3fb3f35fbd3e8b728a09934c4aefe0bbe29817703bdb032a8114
+  metadata.gz: f0abe907f3c564efdf0192279e1d7b2553f3fe97ecb9cbac989defe6a9051979c295db7b0e5917a9c954bc1faab1b42b3fb88b1ac6ef4d20cf3b49217b859fae
+  data.tar.gz: fe6027eaccdc0e46de5d98bc954e17600d088e988fbe3798cb2ad842cdcf8b5d417cd2fdd6bdb0d27f517831d81dd8956444235c23767db222634c579d2d60e6

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,14 @@
+## 0.5.3 / 2023-03-19
+  * 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.
+  * 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.
 

data/README.md

@@ -109,6 +109,59 @@ module Jekyll
 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,
@@ -147,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.1'.freeze
+  VERSION = '0.5.3'.freeze
 end

data/lib/jekyll_plugin_support_helper.rb

@@ -2,8 +2,10 @@ 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, :no_arg_parsing, :params, :tag_name
+class JekyllPluginHelper # rubocop:disable Metrics/ClassLength
+  attr_accessor :liquid_context
+  attr_reader :argv, :keys_values, :logger, :markup, :no_arg_parsing, :params, :tag_name,
+              :argv_original, :keys_values_original, :params_original
 
   # Expand an environment variable reference
   def self.expand_env(str, die_if_undefined: false)
@@ -53,12 +55,15 @@ class JekyllPluginHelper
     @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
+  # @return if parameter was specified, removes it from the available tokens and returns value
+  def parameter_specified?(name)
+    return false if @keys_values.empty?
 
-  def warn_parse(meth)
-    abort "Error: Argument parsing was suppressed, but an attempt to invoke #{meth} was made"
+    key = name
+    key = name.to_sym if @keys_values.first.first.instance_of?(Symbol)
+    value = @keys_values[key]
+    delete_parameter(name)
+    value
   end
 
   def reinitialize(markup)
@@ -71,30 +76,39 @@ class JekyllPluginHelper
       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)
+      parse markup
     end
   end
 
+  # Call this method to return the remaining markup after `parameter_specified?` has been invoked.
+  def remaining_markup
+    @argv.join(' ')
+  end
+
+  def remaining_markup_original
+    @argv_original.join(' ')
+  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
+
+  private
+
   def delete_parameter(key)
     return if @keys_values.empty? || @params.nil?
 
     @params.delete(key)
     @argv.delete_if { |x| x == key or x.start_with?("#{key}=") }
     @keys_values.delete(key)
-  end
 
-  # @return if parameter was specified, removes it from the available tokens and returns value
-  def parameter_specified?(name)
-    return false if @keys_values.empty?
-
-    key = name
-    key = name.to_sym if @keys_values.first.first.instance_of?(Symbol)
-    value = @keys_values[key]
-    delete_parameter(name)
-    value
+    @params_original.delete(key)
+    @argv_original.delete_if { |x| x == key or x.start_with?("#{key}=") }
+    @keys_values_original.delete(key)
   end
 
   PREDEFINED_SCOPE_KEYS = %i[include page].freeze
@@ -120,12 +134,6 @@ class JekyllPluginHelper
     value
   end
 
-  # 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) } unless respond_to?(:no_arg_parsing) && no_arg_parsing
-  end
-
   def lookup_variable(symbol)
     string = symbol.to_s
     return string unless string.start_with?('{{') && string.end_with?('}}')
@@ -136,4 +144,18 @@ class JekyllPluginHelper
   def page
     @liquid_context.registers[:page]
   end
+
+  def parse(markup)
+    @argv_original = Shellwords.split(markup)
+    @keys_values_original = KeyValueParser \
+      .new({}, { array_values: false, normalize_keys: false, separator: /=/ }) \
+      .parse(@argv_original)
+    @params_original = @keys_values_original.map { |k, _v| lookup_variable(k) } unless respond_to?(:no_arg_parsing) && no_arg_parsing
+
+    @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

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.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-17 00:00:00.000000000 Z
+date: 2023-03-19 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