jekyll_plugin_support 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0856ddeea29e8a1e24f0a4997aecb7f6b6b22eae587ca8466142686b65557b7
-  data.tar.gz: ac8a8a047666f89b055b6ab90d6535b59e7f34441405852f5905ed6a517cbc27
+  metadata.gz: 75b8116adff0e7869b3d9d05def0b7cb702b67860e596e3b9901dce1f43182e7
+  data.tar.gz: 86da2a9936cbeffb9f381d3d2031f58acee7f79d8efd7a37b2f4864c3201b20e
 SHA512:
-  metadata.gz: 8122412d70d1c99a6195834a51faa25f0d7beb59a23c18db0beba2883c83f5625920a63495b7ff21abf891faf97ae2ffe085c764c2be9d178bfeb37a7ae4e2f5
-  data.tar.gz: abd34bf8420c7040e7015ce131a8ae3ea01158a552637a4e8d63c51095c138bdf87fd11bff1c3fb3f35fbd3e8b728a09934c4aefe0bbe29817703bdb032a8114
+  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,9 @@
+## 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.2'.freeze
 end

data/lib/jekyll_plugin_support_helper.rb

@@ -75,9 +75,15 @@ class JekyllPluginHelper
       @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)
     return if @keys_values.empty? || @params.nil?
 
@@ -123,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) } unless respond_to?(:no_arg_parsing) && no_arg_parsing
   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.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-17 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