jekyll_flexible_include 2.0.3 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa11b845ffd2d483de86a54aadce690978744f497bfd432e2a683a834204f6d6
-  data.tar.gz: 7cc4cbfecf9061a07802f35aeb9a119b6b5921b8aefc93c2d6f8d707c31d82f4
+  metadata.gz: fed2067800a2324df252ff3e8cfd48b21c9cb3754e5e5b474d135ebb307cd8bf
+  data.tar.gz: abbf8f05f739832f259d9cb16d16d552ae18ee3da17a5bf8a77cae933cdb9b76
 SHA512:
-  metadata.gz: d27e4488a061b886c166cd9bc6f77ef3b17e1ce686c7f18904665f0b1e5ce6445a487bb617c787d9abfafdeac7f2a9dee46c16a66425aaa3f49b44daf05f9c76
-  data.tar.gz: 995e5902bd70b1eb67dc67ff1d37235c9e231235693f686ab706015bf23b157e5db41c4d3a131f152d847eb685bf537fbc13d433ab7debd27df7d55c71045496
+  metadata.gz: b33745dc685acc809658f6ad42efaea735747c5b6816653e10ae56e5f001f957e0f13959d3e1cffe954d2ba8270309277a322568d8536864d9fc055938e00c48
+  data.tar.gz: c6926ffab7a700d4ef884237c0f606ed053d32e66ac97472458cc09102875df883d1cc656c55dfb6a769bc094ae7447abe6e2057bebfb9a74f6e183c57d2e625

data/.rubocop.yml

@@ -9,6 +9,9 @@ AllCops:
   NewCops: enable
   TargetRubyVersion: 2.6
 
+# Gemspec/RequireMFA:
+  # Enabled: false
+
 Layout/LineLength:
   Max: 150
 
@@ -18,6 +21,9 @@ Layout/MultilineMethodCallIndentation:
 Metrics/BlockLength:
   Enabled: false
 
+Style/CommandLiteral:
+  Enabled: false
+
 Style/PercentLiteralDelimiters:
   Enabled: false
 
@@ -29,6 +35,3 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   Enabled: false
-
-Gemspec/RequireMFA:
-  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.0.6 / 2022-04-11
+  * Niggling little bug thing. Gone.
+
+## 2.0.5 / 2022-04-11
+  * Now using <code>Shellwords</code> and <code>KeyValueParser</code> instead of a homegrown parser.
+  * Refactored helper methods to jekyll_tag_helper.rb
+  * Looks up values for liquid variable references from several scopes.
+  * Suppresses stack dump when an error occurs.
+  * Deleted a lot of old cruft.
+  * Added pre, label and copy_button optional parameters
+
+## 2.0.4 / 2022-04-05
+  * Updated to `jekyll_plugin_logger` v2.1.0
+
 ## 2.0.0 / 2022-03-11
   * Made into a Ruby gem and published on RubyGems.org as [jekyll_flexible_include](https://rubygems.org/gems/jekyll_flexible_include).
   * `bin/attach` script added for debugging

data/README.md

@@ -22,14 +22,27 @@ This plugin supports 4 types of includes:
 In addition, filenames that require environment expansion because they contain a <code>$</code> character are
 expanded according to the environment variables defined when <code>jekyll build</code> executes.
 
-### Syntax:
+### Syntax
+The following are equivalent:
 ```
-{% flexible_include path [ do_not_escape='true' ] %}
+{% flexible_include path [ OPTIONS ] %}
+{% flexible_include 'path' [ OPTIONS ] %}
+{% flexible_include "path" [ OPTIONS ] %}
 ```
 
-The included file will escape characters <code>&lt;</code>, <code>{</code> and <code>}</code> unless <code>do_not_escape</code>
-is specified with a value other than <code>false</code>.
-Note that the [square brackets] merely indicate an optional parameter and are not intended to be literally written.
+By default, the included file will escape characters <code>&lt;</code>, <code>{</code> and <code>}</code>
+unless <code>do_not_escape</code> is specified.
+Note that the [square brackets] merely indicate optional parameters and are not intended to be written literally.
+
+### Options
+  * `do_not_escape` includes the content without HTML escaping it.
+  * `pre` causes the included file to be wrapped inside a &lt;pre>&lt;/pre> tag, no label is generated.
+
+The following options imply `pre`:
+  * `download` uses the name of the file as a label, and displays it above the &lt;pre>&lt;/pre> tag. Clicking the label causes the file to be downloaded.
+  * `copy_button` draws an icon at the top right of the &lt;pre>&lt;/pre> tag that causes the included contents to be copied to the clipboard.
+  * `label` specifies that an automatically generated label be placed above the contents. There is no need to specify this option if `download` or `copy_button` options are provided.
+  * `label="blah blah"` specifies a label for the contents; this value overrides the default label. The value can be enclosed in single or double quotes.
 
 
 ### Additional Information
@@ -62,7 +75,7 @@ Or install it yourself as:
 
 ## Examples
 
-1. Include files without parameters; all four types of includes are shown.
+1. Include files, escaping any HTML markup so it appears as written; all four types of includes are shown.
    ```
    {% flexible_include '../../folder/outside/jekyll/site/foo.html' %}
    {% flexible_include 'folder/within/jekyll/site/bar.js' %}
@@ -74,7 +87,7 @@ Or install it yourself as:
 
 2. Include a JSON file (without escaping characters).
    ```
-   {% flexible_include '~/folder/under/home/directory/foo.html' do_not_escape='true' %}
+   {% flexible_include '~/folder/under/home/directory/foo.html' do_not_escape %}
    ```
 
 ## Additional Information
@@ -125,14 +138,14 @@ $ gem info jekyll_flexible_include
 
 *** LOCAL GEMS ***
 
-jekyll_flexible_include (1.0.0)
-    Author: Mike Slinn
-    Homepage:
-    https://github.com/mslinn/jekyll_flexible_include
+jekyll_flexible_include (2.0.4)
+    Authors: Mike Slinn, Tan Nhu, Maarten Brakkee
+    Homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#flexibleInclude
     License: MIT
-    Installed at: /home/mslinn/.gems
+    Installed at (2.0.4): /home/mslinn/.rbenv/versions/2.7.2/lib/ruby/gems/2.7.0
 
-    Generates Jekyll logger with colored output.
+    Jekyll plugin supports various ways to include content into the
+    generated site.
 ```
 
 

data/jekyll_flexible_include_plugin.gemspec

@@ -5,7 +5,7 @@ require_relative "lib/flexible_include/version"
 Gem::Specification.new do |spec|
   github = "https://github.com/mslinn/jekyll_flexible_include_plugin"
 
-  spec.authors = ["Mike Slinn"]
+  spec.authors = ["Mike Slinn", "Tan Nhu", "Maarten Brakkee"]
   spec.bindir = "exe"
   spec.description = <<~END_OF_DESC
     Jekyll's built-in include tag only supports including files within the _includes folder.
@@ -35,10 +35,10 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.6.0"
   spec.summary = "Jekyll plugin supports various ways to include content into the generated site."
   spec.test_files = spec.files.grep(%r!^(test|spec|features)/!)
-  spec.version = JekyllFlexibleIncludePlugin::VERSION
+  spec.version = JekyllFlexibleIncludePluginVersion::VERSION
 
   spec.add_dependency "jekyll", ">= 3.5.0"
-  spec.add_dependency "jekyll_plugin_logger", '~> 2.0.0'
+  spec.add_dependency "jekyll_plugin_logger", '~> 2.1.0'
 
   spec.add_development_dependency "debase"
   # spec.add_development_dependency "rubocop-jekyll"

data/lib/flexible_include/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module JekyllFlexibleIncludePlugin
-  VERSION = "2.0.3"
+module JekyllFlexibleIncludePluginVersion
+  VERSION = "2.0.6"
 end

data/lib/flexible_include.rb

@@ -2,139 +2,74 @@
 
 require "jekyll"
 require "jekyll_plugin_logger"
+require "securerandom"
 require_relative "flexible_include/version"
+require_relative "jekyll_tag_helper"
 
 module JekyllFlexibleIncludeName
   PLUGIN_NAME = "flexible_include"
 end
 
-class FlexibleIncludeError < StandardError
-  attr_accessor :path
-
-  def initialize(msg, path)
-    super
-    @path = path
-  end
-end
-
 class FlexibleInclude < Liquid::Tag
-  VALID_SYNTAX = %r!
-    ([\w-]+)\s*=\s*
-    (?:"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|([\w.-]+))
-  !x.freeze
-  VARIABLE_SYNTAX = %r!
-    (?<variable>[^{]*(\{\{\s*[\w\-.]+\s*(\|.*)?\}\}[^\s{}]*)+)
-    (?<params>.*)
-  !mx.freeze
-
-  FULL_VALID_SYNTAX = %r!\A\s*(?:#{VALID_SYNTAX}(?=\s|\z)\s*)*\z!.freeze
-  VALID_FILENAME_CHARS = %r!^[\w/\.-]+$!.freeze
-
-  def initialize(tag_name, markup, parse_context)
+  FlexibleIncludeError = Class.new(Liquid::Error)
+
+  # @param tag_name [String] the name of the tag, which we already know.
+  # @param markup [String] the arguments from the tag, as a single string.
+  # @param parse_context [Liquid::ParseContext] hash that stores Liquid options.
+  #        By default it has two keys: :locale and :line_numbers, the first is a Liquid::I18n object, and the second,
+  #        a boolean parameter that determines if error messages should display the line number the error occurred.
+  #        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
+  def initialize(tag_name, markup, _parse_context)
     super
-    @logger = PluginMetaLogger.instance.new_logger(self)
-    matched = markup.strip.match(VARIABLE_SYNTAX)
-    if matched
-      @file = matched["variable"].strip
-      @params = matched["params"].strip
-    else
-      @file, @params = markup.strip.split(%r!\s+!, 2)
+    @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+    @helper = JekyllTagHelper.new(tag_name, markup, @logger)
+  end
+
+  # @param liquid_context [Liquid::Context]
+  def render(liquid_context) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
+    @helper.liquid_context = liquid_context
+    @do_not_escape = @helper.parameter_specified? "do_not_escape"
+    @download = @helper.parameter_specified? "download"
+    @label = @helper.parameter_specified? "label"
+    @label_specified = @label
+    @copy_button = @helper.parameter_specified? "copyButton"
+    @pre = @copy_button || @download || @label_specified || @helper.parameter_specified?("pre") # Download or label implies pre
+    filename = @helper.params.first # Do this after all options have been checked for
+    @label ||= filename
+
+    # If a label was specified, use it, otherwise concatenate any dangling parameters and use that as the label
+    @label ||= @helper.params[1..].join(" ")
+
+    @logger.debug("filename=#{filename}")
+
+    path = JekyllTagHelper.expand_env(filename)
+    case path
+    when /\A\// # Absolute path
+      @logger.debug { "Absolute path=#{path}, filename=#{filename}" }
+    when /\A~/ # Relative path to user's home directory
+      @logger.debug { "User home start filename=#{filename}, path=#{path}" }
+      filename.slice! "~/"
+      path = File.join(ENV['HOME'], filename)
+      @logger.debug { "User home end filename=#{filename}, path=#{path}" }
+    when /\A!/ # Run command and return response
+      filename = JekyllTagHelper.remove_quotes(@helper.argv.first)
+      filename.slice! "!"
+      contents = run(filename)
+    else # Relative path
+      site = liquid_context.registers[:site]
+      source = File.expand_path(site.config['source']) # website root directory
+      path = File.join(source, filename) # Fully qualified path of include file from relative path
+      @relative = true
+      @logger.debug { "Relative end filename=#{filename}, path=#{path}" }
     end
-    @markup = markup
-    @logger.debug("initialize: @markup=#{@markup}")
-    @parse_context = parse_context
-  end
-
-  # @param context [Liquid::Context]
-  def render(context) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-    markup = @markup
-    @logger.debug { "markup='#{markup}'" }
-    markup = sanitize_parameter(markup)
-    markup = expand_env(markup)
-    path = markup
-    if /\A\//.match(markup)  # Is the file absolute?
-      @logger.debug { "Absolute path=#{path}, markup=#{markup}" }
-    elsif /\A~/.match(markup)  # Relative path to user's home directory?
-      @logger.debug { "Relative start markup=#{markup}, path=#{path}" }
-      markup.slice! "~/"
-      path = File.join(ENV['HOME'], markup)
-      @logger.debug { "Relative end markup=#{markup}, path=#{path}" }
-    elsif /\A\!/.match(markup)  # Run command and return response
-      markup.slice! "!"
-      @logger.debug { "Execute markup=#{markup}" }
-      contents = run(markup)
-    else  # The file is relative or it was passed as a parameter to an include and was not noticed before, e.g. @file='{{include.file}}'
-      @logger.debug { "Catchall start @file=#{@file}, markup=#{markup}, path=#{path}" }
-      file = render_variable(context)
-      markup = file if file
-      markup = expand_env(markup)
-      markup = sanitize_parameter(markup)
-      if /\A\//.match(markup) # Absolute path
-        path = markup
-      elsif /\A\!/.match(markup)
-        markup.slice! "!"
-        @logger.debug { "Execute markup=#{markup}" }
-        contents = run(markup)
-      elsif /\A~/.match(markup)  # Relative path to user's home directory?
-        markup.slice! "~/"
-        path = File.join(ENV['HOME'], markup)
-      else # Relative path
-        site = context.registers[:site]
-        source = File.expand_path(site.config['source']) # website root directory
-        path = File.join(source, markup) # Fully qualified path of include file from relative path
-      end
-      @logger.debug { "Catchall end markup=#{markup}, path=#{path}" }
-    end
-    render_completion(context, path, contents)
+    render_completion(path, contents)
+    # rescue StandardError => e
+    #   raise FlexibleIncludeError, e.message.red, [] # Suppress stack trace
   end
 
   private
 
-  def escape_html?(context)
-    do_not_escape = false
-    if @params
-      context["include"] = parse_params(context)
-      @logger.debug { "context['include']['do_not_escape'] = #{context['include']['do_not_escape']}" }
-      do_not_escape = context['include'].fetch('do_not_escape', 'false')
-      @logger.debug { "do_not_escape=#{do_not_escape}" }
-      @logger.debug { "do_not_escape=='false' = #{do_not_escape=='false'}" }
-    end
-    do_not_escape
-  end
-
-  def escape_html(string)
-    string.gsub("{", "&#123;").gsub("}", "&#125;").gsub("<", "&lt;")
-  end
-
-  def expand_env(str)
-    str.gsub(/\$([a-zA-Z_][a-zA-Z0-9_]*)|\${\g<1>}|%\g<1>%/) { ENV[$1] }
-  end
-
-  # Grab file read opts in the context
-  def file_read_opts(context)
-    context.registers[:site].file_read_opts
-  end
-
-  def parse_params(context)
-    params = {}
-    markup = @params
-
-    while (match = VALID_SYNTAX.match(markup))
-      markup = markup[match.end(0)..-1]
-
-      value = if match[2]
-                match[2].gsub(%r!\\"!, '"')
-              elsif match[3]
-                match[3].gsub(%r!\\'!, "'")
-              elsif match[4]
-                context[match[4]]
-              end
-
-      params[match[1]] = value
-    end
-    params
-  end
-
   def read_file(file)
     File.read(file)
   end
@@ -145,74 +80,39 @@ class FlexibleInclude < Liquid::Tag
     false
   end
 
-  def render_completion(context, path, contents)
-    begin
-      contents = read_file(path) unless contents
-    rescue StandardError => e
-      puts "flexible_include.rb error: #{e.message}".red
-      $stderr.reopen(IO::NULL)
-      $stdout.reopen(IO::NULL)
-      exit
-    end
-    escaped_contents = escape_html?(context) ? escape_html(contents) : contents
-    context.stack do # Temporarily push a new local scope onto the variable stack
-      begin
-        partial = Liquid::Template.parse(escaped_contents) # Type Liquid::Template
-      rescue StandardError => e
-        puts "flexible_include.rb error: #{e.message}".red
-        $stderr.reopen(IO::NULL)
-        $stdout.reopen(IO::NULL)
-        exit
-      end
-
-      begin
-        partial.render!(context)
-      rescue Liquid::Error => e
-        e.template_name = path
-        e.markup_context = "included " if e.markup_context.nil?
-        raise e
-      end
-    end
-  end
-
-  # @return setvalue of 'file' variable if defined
-  def render_variable(context)
-    if @file.match VARIABLE_SYNTAX
-      partial = context.registers[:site]
-        .liquid_renderer
-        .file("(variable)")
-        .parse(@file)
-      partial.render!(context)
-    end
+  def render_completion(path, contents)
+    contents ||= read_file(path)
+    contents2 = @do_not_escape ? contents : JekyllTagHelper.escape_html(contents)
+    @pre ? wrap_in_pre(path, contents2) : contents2
   end
 
   def run(cmd)
-    %x[ #{cmd} ].chomp
-  end
-
-  # strip leading and trailing quotes if present
-  def sanitize_parameter(parameter)
-    parameter.strip.gsub(/\A'|'\Z/, '').strip if parameter
-  end
-
-  def valid_include_file?(path, dir, safe)
-    !outside_site_source?(path, dir, safe) && File.file?(path)
-  end
-
-  def outside_site_source?(path, dir, safe)
-    safe && !realpath_prefixed_with?(path, dir)
-  end
-
-  def could_not_locate_message(file, includes_dirs, safe)
-    message = "Could not locate the included file '#{file}' in any of "\
-              "#{includes_dirs}. Ensure it exists in one of those directories and"
-    message + if safe
-                " is not a symlink as those are not allowed in safe mode."
-              else
-                ", if it is a symlink, does not point outside your site source."
-              end
+    @logger.debug { "Executing filename=#{cmd}" }
+    %x[#{cmd}].chomp
+  end
+
+  PREFIX = "<button class='copyBtn' data-clipboard-target="
+  SUFFIX = "title='Copy to clipboard'><img src='/assets/images/clippy.svg' alt='Copy to clipboard' style='width: 13px'></button>"
+
+  def wrap_in_pre(path, content)
+    basename = File.basename(path)
+    label_or_href = if @download
+                      label = @label_specified ? @label : basename
+                      <<~END_HREF
+                        <a href='data:text/plain;charset=UTF-8,#{basename}' download='#{basename}'
+                          title='Click on the file name to download the file'>#{label}</a>
+                      END_HREF
+                    else
+                      @label_specified ? @label : basename
+                    end
+    pre_id = "id#{SecureRandom.hex 6}"
+    copy_button = @copy_button ? "#{PREFIX}'##{pre_id}'#{SUFFIX}" : ""
+    <<~END_PRE
+      <div class="codeLabel">#{label_or_href}</div>
+      <pre data-lt-active="false" class="maxOneScreenHigh copyContainer" id="#{pre_id}">#{copy_button}#{content}</pre>
+    END_PRE
   end
 end
 
-PluginMetaLogger.instance.info { "Loaded #{JekyllFlexibleIncludeName::PLUGIN_NAME} v#{JekyllFlexibleIncludePlugin::VERSION} plugin." }
+PluginMetaLogger.instance.info { "Loaded #{JekyllFlexibleIncludeName::PLUGIN_NAME} v#{JekyllFlexibleIncludePluginVersion::VERSION} plugin." }
 Liquid::Template.register_tag('flexible_include', FlexibleInclude)

data/lib/jekyll_tag_helper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class JekyllTagHelper
+  attr_reader :argv, :liquid_context, :logger, :params, :tag_name
+
+  def self.escape_html(string)
+    string.gsub("{", "&#123;").gsub("}", "&#125;").gsub("<", "&lt;")
+  end
+
+  # Expand environment variable references
+  def self.expand_env(str)
+    str.gsub(/\$([a-zA-Z_][a-zA-Z0-9_]*)|\${\g<1>}|%\g<1>%/) { ENV[Regexp.last_match(1)] }
+  end
+
+  # strip leading and trailing quotes if present
+  def self.remove_quotes(string)
+    string.strip.gsub(/\A'|\A"|'\Z|"\Z/, '').strip if string
+  end
+
+  def initialize(tag_name, markup, logger)
+    @tag_name = tag_name
+    @argv = Shellwords.split(markup)
+    @keys_values = KeyValueParser.new.parse(@argv) # Hash[Symbol, String|Boolean]
+    @logger = logger
+    @logger.debug { "@keys_values='#{@keys_values}'" }
+  end
+
+  def delete_parameter(name)
+    @params.delete(name)
+    @argv.delete_if { |x| x.start_with? name }
+    @keys_values.delete(name.to_sym)
+  end
+
+  # @return if parameter was specified, returns value and removes it from the available tokens
+  def parameter_specified?(name)
+    value = @keys_values[name.to_sym]
+    delete_parameter(name)
+    value
+  end
+
+  PREDEFINED_SCOPE_KEYS = [:include, :page].freeze
+
+  # Finds variables defined in an invoking include, or maybe somewhere else
+  # @return variable value or nil
+  def dereference_include_variable(name)
+    @liquid_context.scopes.each do |scope|
+      next if PREDEFINED_SCOPE_KEYS.include? scope.keys.first
+
+      value = scope[name]
+      return value if value
+    end
+    nil
+  end
+
+  # @return value of variable, or the empty string
+  def dereference_variable(name)
+    value = @liquid_context[name] # Finds variables named like 'include.my_variable', found in @liquid_context.scopes.first
+    value ||= @page[name] if @page # Finds variables named like 'page.my_variable'
+    value ||= dereference_include_variable(name)
+    value ||= ""
+    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) }
+  end
+
+  def lookup_variable(symbol)
+    string = symbol.to_s
+    return string unless string.start_with?("{{") && string.end_with?("}}")
+
+    dereference_variable(string.delete_prefix("{{").delete_suffix("}}"))
+  end
+
+  def page
+    @liquid_context.registers[:page]
+  end
+end

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_flexible_include
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.6
 platform: ruby
 authors:
 - Mike Slinn
+- Tan Nhu
+- Maarten Brakkee
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-26 00:00:00.000000000 Z
+date: 2022-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,14 +32,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: debase
   requirement: !ruby/object:Gem::Requirement
@@ -85,6 +87,7 @@ files:
 - jekyll_flexible_include_plugin.gemspec
 - lib/flexible_include.rb
 - lib/flexible_include/version.rb
+- lib/jekyll_tag_helper.rb
 homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#flexibleInclude
 licenses:
 - MIT