jekyll_flexible_include 2.0.4 → 2.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60cf6d0ee5123d82f4a0ae31d85db6ffcbb7326693af3dc457dc64110de42d88
-  data.tar.gz: b06fcc1ef1439efdf98effed553c714583bbe600707719a7252c93079e8e7a5e
+  metadata.gz: 7728aa7304d9fef053bb7b6f0e5adb59938a13711764f5ec1615497d54e23845
+  data.tar.gz: 1ef45a4764e136856e80e9a874cfa6e30ac1a9bc2523a10a024fa79bafc1b3d5
 SHA512:
-  metadata.gz: 2eab4ce0e37112c0499703ecd30211b01ae2b38e1ec89f01f94b188dfdf539ec7dd1a5f8aa4f4be7a3d9dae7d30d71797687a8a00c916e1cf948d6b1326403ba
-  data.tar.gz: ab036ab986241031929f7f4ac335312e4fcb81a66019f196278c38d247292f22c69b009fe269b7e19633ea5a6645e1b86db81a2b60e172a16b3a6d4cb5791f96
+  metadata.gz: 33c164b768d259e680458b14fab226d7fe038685a8dc98b459140a812628c8e9978e200e1ea3da414be678ebaca5f73e3b42957f26879162d6ce9c874f5346d2
+  data.tar.gz: 43b56da5e19d31a4aa51c87ba21d284c57f1f242a2f25f16bf71d3524ad620df09ba98faf18b234992073ddb2b09fbe89a912a6a15877d9ce1b71608eaa6ea33

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,11 @@
+## 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
 

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.

data/lib/flexible_include/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllFlexibleIncludePluginVersion
-  VERSION = "2.0.4"
+  VERSION = "2.0.5"
 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, PluginMetaLogger.instance.config)
-    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)
+    @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,72 +80,37 @@ 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
 

data/lib/jekyll_tag_helper.rb

@@ -0,0 +1,81 @@
+# 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)
+    @liquid_context[name] || # Finds variables named like 'include.my_variable', found in @liquid_context.scopes.first
+      @page[name] || # Finds variables named like 'page.my_variable'
+      dereference_include_variable(name) ||
+      ""
+  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.4
+  version: 2.0.5
 platform: ruby
 authors:
 - Mike Slinn
+- Tan Nhu
+- Maarten Brakkee
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-06 00:00:00.000000000 Z
+date: 2022-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -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