distorted-jekyll 0.5.3 → 0.6.0

data/README.md

@@ -1,19 +1,16 @@
-# Cooltrainer::DistorteD
+# Jekyll::DistorteD
 
-`DistorteD` is a multimedia framework for Jekyll websites.
-
-Right now this repo contains two Gems:
-- [`DistorteD-Jekyll`](https://rubygems.org/gems/distorted-jekyll) contains anything and everything that depends on Jekyll.
-- [`DistorteD-Ruby`](https://rubygems.org/gems/distorted) contains just the abstract media file format handling code. It's separate so I can use those functions in other contexts and/or easily replace the Ruby core if necessary.
+`DistorteD-Jekyll` is a multimedia framework for Jekyll websites.
 
 ## Motivation
 
-DD is my solution for displaying photos, videos, and other types of media on [cooltrainer.org](https://cooltrainer.org) due to my dissatisfaction with every other solution I could find.
+DistorteD is my solution for displaying photos, videos, and other types of media on [cooltrainer.org](https://cooltrainer.org) due to my dissatisfaction with every other solution I could find.
 
 My previous approach was similar to what's [described here](https://eduardoboucas.com/blog/2014/12/07/including-and-managing-images-in-jekyll.html), with small/medium/large image size variations generated with [Jekyll-MiniMagick](https://github.com/MattKevan/Jekyll-MiniMagick-new).
 
 Here are some already-existing ways to put pictures on your Jekyll site that are worth your consideration before choosing DistorteD:
 
+- Octopress' [image_tag](https://github.com/imathis/octopress/blob/master/plugins/image_tag.rb) plugin.
 - [jekyll-responsive-image](https://github.com/wildlyinaccurate/jekyll-responsive-image)
 - [jekyll_picture_tag](https://rbuchberger.github.io/jekyll_picture_tag/)
 - [jekyll-gallery-generator](https://github.com/ggreer/jekyll-gallery-generator)
@@ -95,7 +92,7 @@ will be transformed into.
 %}
 ```
 
-Or, for a DD grid:
+or, for a DD grid:
 
 ```
 {% distort %}
@@ -157,11 +154,10 @@ Clone the DistorteD repository and modify your Jekyll `Gemfile` to refer to your
 
 ```
 gem 'distorted-jekyll', :path => '~/repos/DistorteD/DistorteD-Jekyll/'[, :branch => 'NEW-SENSATION']
-gem 'distorted', :path => '~/repos/DistorteD/DistorteD-Ruby/'[, :branch => 'NEW-SENSATION']
 ```
 
 The `DistorteD-Jekyll` Gem will automatically use its local sibling `DistorteD-Ruby` Gem if used in this way.
 
 ## License
 
-DistorteD is available as open source under the terms of the [GNU Affero General Public License version 3](https://opensource.org/licenses/AGPL-3.0).
+The gem is available as open source under the terms of the [GNU Affero General Public License version 3](https://opensource.org/licenses/AGPL-3.0).

data/lib/distorted-jekyll.rb

@@ -0,0 +1,79 @@
+require 'distorted-jekyll/13th-style'
+require 'distorted-jekyll/blocks'
+require 'distorted-jekyll/md_injection'
+require 'distorted-jekyll/invoker'
+
+
+FATAL_FURY = true
+UPDATE_RUBY = "Please use DistorteD with Ruby 2.7.0 or later"
+def update_ruby
+  if defined? RUBY_PLATFORM
+    if (/freebsd/ =~ RUBY_PLATFORM) != nil
+      return 'pkg install lang/ruby27'
+    elsif (/darwin/ =~ RUBY_PLATFORM) != nil
+      return 'brew upgrade ruby'
+    elsif (/win/ =~ RUBY_PLATFORM) != nil
+      return 'https://rubyinstaller.org/'
+    elsif (/linux/ =~ RUBY_PLATFORM) != nil
+      if File.exists?('/etc/lsb-release')
+        lsb = File.read('/etc/lsb-release')
+        if (/Ubuntu|LinuxMint/ =~ lsb) != nil
+          return 'https://www.brightbox.com/docs/ruby/ubuntu/#installation'
+        end
+      end
+    end
+  end
+  return 'https://github.com/rbenv/ruby-build'
+end
+
+
+# I want to be able to use:
+# - Array#dig and Hash#dig (Ruby 2.3): https://bugs.ruby-lang.org/issues/11643
+# - Lonely operator (Ruby 2.3): https://bugs.ruby-lang.org/issues/11537
+# - Hash#transform_keys (Ruby 2.5): https://bugs.ruby-lang.org/issues/13583
+# - Enumerable#filter_map (Ruby 2.7): https://bugs.ruby-lang.org/issues/5663
+#     https://blog.saeloun.com/2019/05/25/ruby-2-7-enumerable-filter-map.html
+# - 'Real' kwargs in preparation for Ruby 3: https://bugs.ruby-lang.org/issues/14183
+#     https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+if [
+  Hash.method_defined?(:dig),  # 2.3
+  Hash.method_defined?(:transform_keys),  # 2.5
+  Enumerable.method_defined?(:filter_map),  # 2.7
+].all?
+  # Monkey-patch preferred_extensions iff we're going to load.
+  # My JPEGs coming out with a '.jpeg' file extension just annoys me so much.
+  require 'distorted/monkey_business/mnemoniq'
+
+  # Monkey-patch Jekyll::Cleaner to not nuke DistorteD-generated variations
+  # for our media files. This makes DistorteD fast!
+  require 'distorted-jekyll/monkey_business/jekyll/cleaner'
+
+  # Register DistorteD's entrypoint class with Liquid.
+  # `Invoker` will mix in the proper handler module for the given media.
+  Liquid::Template.register_tag('distorted', Jekyll::DistorteD::Invoker)
+
+  # Register a block version for arranging multiple pieces of media.
+  Liquid::Template.register_tag('distort', Jekyll::DistorteD::BLOCKS)
+
+  # Register a tag for basic DistorteD CSS.
+  Liquid::Template.register_tag('13th_style', Jekyll::DistorteD::ThirteenthStyle)
+
+  # Transform Markdown image syntax ![alt](url.jpg "title")
+  # to instances of our liquid tag {% distorted %}
+  # Available hooks can be seen here:
+  #   https://github.com/jekyll/jekyll/blob/master/lib/jekyll/hooks.rb
+  # `:documents` does not seem to include `_pages` but does include `_posts`.
+  Jekyll::Hooks.register(:pages, :pre_render, &md_injection)
+  Jekyll::Hooks.register(:posts, :pre_render, &md_injection)
+
+else
+  # Example of how this looks with the outdated Ruby 2.5 on my Mint 19 laptop:
+  #
+  # Bundler::GemRequireError: There was an error while trying to load the gem 'distorted-jekyll'.
+  # Gem Load Error is: Please use DistorteD with Ruby 2.7.0 or later: https://www.brightbox.com/docs/ruby/ubuntu/#installation
+  if FATAL_FURY
+    raise RuntimeError.new("#{UPDATE_RUBY}: #{update_ruby}")
+  else
+    Jekyll.logger.info('DistorteD', "#{UPDATE_RUBY}: #{update_ruby}")
+  end
+end

data/lib/distorted-jekyll/13th-style.rb

@@ -0,0 +1,58 @@
+
+# Slip in and out of phenomenon
+require 'liquid/tag'
+require 'liquid/tag/parser'
+
+# Explicitly required for l/t/parser since a1cfa27c27cf4d4c308da2f75fbae88e9d5ae893
+require 'shellwords'
+
+
+module Jekyll
+  module DistorteD
+    class ThirteenthStyle < Liquid::Tag
+
+      TAB_SEQUENCE = '  '.freeze  # two spaces
+
+      def initialize(tag_name, arguments, liquid_options)
+        super
+
+        # Liquid leaves argument parsing totally up to us.
+        # Use the envygeeks/liquid-tag-parser library to wrangle them.
+        parsed_arguments = Liquid::Tag::Parser.new(arguments)
+
+        # Specify how many levels to indent printed output.
+        # Indentation will apply to all lines after the first,
+        # because the first line's output will fall at the same
+        # place as our Liquid tag invocation.
+        @tabs = parsed_arguments[:tabs] || 0
+      end
+
+      # This is going to go away in a future Liquid version
+      # and render_to_output_buffer will be the standard approach.
+      # I'm going ahead and using it since we are building strings here.
+      def render(context)
+        return render_to_output_buffer(context, '')
+      end
+
+      def render_to_output_buffer(context, output)
+        css_filename = File.join(File.dirname(__FILE__), 'template'.freeze, '13th-style.css'.freeze)
+
+        # Use IO.foreach() to call a block on each line of our template file
+        # without slurping the entire file into memory like File.read() / File.readlines()
+        File.foreach(css_filename).with_index do |line, line_num|
+          # Don't indent the first line of the CSS file, because the first line
+          # will print starting at the position of our {% 13thStyle %} Liquid tag.
+          unless line_num == 0
+            output << TAB_SEQUENCE * @tabs
+          end
+          output << line
+        end
+        # Remove CSS comments from output so I can leave notes there
+        # without bloating up my output.
+        # Based on C-shebang-style comment regex from MRE3
+        return output.gsub(/\/\*[^*]*\*+(?:[^*\/][^*]*\*+)*\//, '')
+      end
+
+    end  # ThirteenthStyle
+  end  # DistorteD
+end  # Jekyll

data/lib/distorted-jekyll/_config_default.yml

@@ -0,0 +1,81 @@
+# Override any or all of this default configuration in your Jekyll site's `_config.yml`!
+
+# Is it possible to do a Set of Hashes using the Set syntax in YAML?
+# It works with the Array syntax, so that's what I'm using here,
+# but keep in mind any Arrays will be converted to Sets when loaded,
+# so duplicate Array values will be compacted!
+
+standard_image: &standard_image
+  - tag: full
+    crop: none
+  - tag: small
+    width: 400
+    height: 400
+    media: "(max-width: 400px)"
+  - tag: medium
+    width: 800
+    height: 800
+    media: "(min-width: 400px) and (max-width: 800px)"
+  - tag: large
+    width: 1500
+    height: 1500
+    media: "(min-width: 800px)"
+
+
+distorted:
+
+  # Liquid template caching is default as of Jekyll 4.0,
+  # but it can be disabled if needed.
+  # I just can't think of when it would be needed :)
+  cache_templates: true
+
+  # Should unrecognized media-types fall back to a bare
+  # <img> tag around the original media file?
+  # If not, the site build will fail when an unrecognized
+  # file is encountered.
+  last_resort: true
+
+  # Configure DistorteD format changes by media_type, then by sub_type.
+  # The list of target formats is plain text, media_type/sub_type.
+  # These are mostly based on IANA's official Media Types list:
+  # https://www.iana.org/assignments/media-types/media-types.xhtml
+  # but with some custom additions like using 'gif-sequence' for
+  # animated GIF and leaving 'image/gif' to refer to single-frame GIFs.
+  changes:
+    image:
+      jpeg:
+        ? image/jpeg
+        ? image/webp
+      png:
+        ? image/png
+        ? image/webp
+      gif:
+        ? image/gif
+        ? image/png
+        ? image/webp
+      gif-sequence:
+        ? image/gif-sequence
+      svg:
+        ? image/svg+xml
+        ? image/png
+        ? image/webp
+    text:
+      plain:
+        ? text/plain
+        ? image/png
+        ? image/webp
+      x-nfo:
+        ? text/x-nfo
+        ? image/png
+        ? image/webp
+    font:
+      ttf:
+        ? font/ttf
+        ? image/png
+        ? image/webp
+
+  outer_limits:
+    image:
+      jpeg: *standard_image
+      png: *standard_image
+      webp: *standard_image

data/lib/distorted-jekyll/blocks.rb

@@ -0,0 +1,16 @@
+
+module Jekyll
+  module DistorteD
+    class BLOCKS < Liquid::Block
+
+      def initialize(tag_name, arguments, liquid_options)
+        super
+      end
+
+      def render(context)
+        "<div class=\"distorted-block\">#{super}</div>"
+      end
+
+    end  # BLOCKS
+  end  # DistorteD
+end  # Jekyll

data/lib/distorted-jekyll/floor.rb

@@ -0,0 +1,266 @@
+require 'yaml'
+require 'jekyll'
+require 'set'
+
+require 'distorted/monkey_business/hash'
+require 'distorted/checking_you_out'
+
+
+module Jekyll
+  module DistorteD
+    module Floor
+
+      ATTRIBUTES = Set[:lower_world, :changes, :outer_limits]
+
+      # Top-level config key (once stringified) for Jekyll and Default YAML.
+      CONFIG_ROOT = :distorted
+
+      # Filename for default config YAML. Should be a sibling of this file.
+      # Don't move this file or the YAML defaults without changing this.
+      DEFAULT_CONFIG_FILE_NAME = '_config_default.yml'.freeze
+      DEFAULT_CONFIG_PATH = File.join(File.dirname(__FILE__), DEFAULT_CONFIG_FILE_NAME).freeze
+
+      # Separator character for pretty-printing config hierarchy.
+      PP_SEPARATOR = "\u21e2 ".encode('utf-8').freeze
+
+      # Path separator is almost always '/' internally, but support
+      # ALT_SEPARATOR platforms too.
+      # On Lunix - Ruby 2.7:
+      # irb(main):003:0> File::ALT_SEPARATOR
+      # => nil
+      # irb(main):004:0> File::SEPARATOR
+      # => "/"
+      PATH_SEPARATOR = (File::ALT_SEPARATOR || File::SEPARATOR).freeze
+
+
+      # Generic main config-loading function that will search, in order:
+      # - The memoized pre-transformed config data store in-memory.
+      # - Jekyll's Site config, for a passed-in site or for the default site.
+      # - DistorteD's Gem-internal default config YAML.
+      #
+      # Optionally provide a class to be used as a fallback for missing keys.
+      def self.config(*keys, **kw)
+        # Symbolize for our internal representation of the config path.
+        # The Jekyll config and default config are both YAML, so we want string
+        # keys for them. Go ahead and prepend the top-level search key here too.
+        memo_keys = keys.compact.map(&:to_sym).to_set
+        search_keys = keys.compact.map(&:to_s).map(&:freeze)
+        # Pretty print the config path for logging.
+        log_key = search_keys.join(PP_SEPARATOR.to_s).freeze
+        # Initialize memoization class variable as a Hash that will return nil
+        # for any key access that doesn't already contain something.
+        @@memories ||= Hash.new { |h,k| h[k] = h.class.new(&h.default_proc) }
+        # Try to load a memoized config if we can, to skip any filesystem
+        # access and data transformation steps.
+        config = @@memories&.dig(*memo_keys)
+        unless config.nil?
+          if config.is_a?(TrueClass) || config.is_a?(FalseClass)
+            return config
+          elsif config.is_a?(Enumerable)
+            unless config.empty?
+              # Can't check this at the top level because True/FalseClass
+              # don't respond to this message.
+              return config
+            end
+          end
+        end
+
+        # The key isn't memoized. Look for it first in Jekyll's Site config.
+        # Is it even possible to have more than one Site? Support being passed
+        # a `site` object just in case, but taking the first one should be fine.
+        site = kw[:site] || Jekyll.sites.first
+        # Get the config, or nil if the queried config path doesn't exist.
+        loaded_config = site.config.dig(*search_keys)
+        if loaded_config.nil?
+          # The wanted config key didn't exist in the Site config, so let's
+          # try our defaults!
+          # This file will always be small enough for a one-shot read.
+          default_config = YAML.load(File.read(DEFAULT_CONFIG_PATH))
+          loaded_config = default_config.dig(*search_keys)
+          unless loaded_config.nil?
+            Jekyll.logger.debug(['Default', log_key].join(PP_SEPARATOR.to_s).concat(':'.freeze), loaded_config)
+          end
+        else  # else Jekyll _config is not nil
+          Jekyll.logger.debug(['_config', log_key].join(PP_SEPARATOR.to_s).concat(':'.freeze), loaded_config)
+        end
+        # Was the desired config key found in the Gem defaults?
+        if loaded_config.nil?
+          # Nope.
+          return nil
+        else
+          # Symbolize any output keys and values, and convert Arrays and Ruby::YAML
+          # Sets-as-Hashes to Ruby stdlib Sets.
+          # Returning a Set instead of an Array should be fine since none of our
+          # configs can (read: should) contain duplicate values for any reason.
+          loaded_config = symbolic(set_me_free(loaded_config))
+        end
+        # Memoize any of our own config, but just return anything outside our tree.
+        if keys.first == CONFIG_ROOT
+          @@memories.bury(*memo_keys, loaded_config)
+          Jekyll.logger.debug(log_key, "Memoizing config: #{@@memories.dig(*memo_keys)}")
+          # And return a config to the caller. Don't return the `new`ly fetched
+          # data directly to ensure consistency between this first fetch and
+          # subsequent memoized fetches, and to let callers take advantage of
+          # the memo Hash's `default_proc` setup.
+          return @@memories.dig(*memo_keys)
+        else
+          return loaded_config
+        end
+      end
+
+      # AFAICT Ruby::YAML will not give me a Ruby Set[] for a YAML Set,
+      # just a Hash with all-nil-values which is what it is internally.
+      # distorted⇢ image Trying Jekyll _config key: {"(max-width: 400px)"=>nil, "(min-width: 800px)"=>nil, "(min-width: 1500px)"=>nil}
+      # It is possible with some sugar in the YAML files, but I don't
+      # want to ask anyone to do that :)
+      # https://rhnh.net/2011/01/31/yaml-tutorial/
+      def self.set_me_free(dunno)
+        if dunno.class == Array
+          return dunno&.to_set.map{|d| set_me_free(d)}
+        elsif dunno.class == Hash
+          if dunno&.values.all?{|v| v.nil?}
+            return dunno&.keys.to_set
+          else
+            return dunno&.transform_values!{|v| set_me_free(v)}
+          end
+        end
+        return dunno
+      end
+
+      # Transform arbitrary configuration data structure keys from
+      # strings to symbols before memoization.
+      # https://stackoverflow.com/a/8189435
+      def self.symbolic(dunno)
+        # Check message-handling responses to gauge emptiness since classes that
+        # don't respond to `:empty?` might not respond to `:method_exists?` either.
+        if dunno.nil?
+          return dunno
+        elsif dunno.class == Hash
+          return dunno.transform_keys!(&:to_sym).transform_values!{|v| symbolic(v)}
+        elsif dunno.class == Array
+          return dunno.map{|r| symbolic(r)}
+        elsif dunno.respond_to?(:to_sym)
+          # Plain types
+          return dunno.to_sym
+        elsif dunno.respond_to?(:to_str)
+          # Freeze string config values.
+          # Specifically :to_str, not :to_s. Usually implemented by actual Strings.
+          return dunno.to_str.freeze
+        end
+        return dunno
+      end
+
+      # Returns a Set of Arrays of search keys to try in config()
+      def search_keys(*keys)
+        # It's likely that we will get a default argument of [nil]
+        # here due to the output of abstract(:whatever) for unset attrs.
+        keys = keys.compact
+        # If a search key path was given, construct one based
+        # on the MIME::Type union Set between the source media
+        # and the plugged MediaMolecule.
+        if keys.empty? or keys.all?{|k| k.nil?}
+          try_keys = type_mars.map{ |t|
+            # Use only the first part of complex sub_types like 'svg+xml'
+            [t.media_type, t.sub_type.split('+').first].compact
+          }
+        else
+          # Or use a user-provided config path.
+          try_keys = Set[keys]
+        end
+      end
+
+      # Loads configuration data telling us how to open certain
+      # types of files.
+      def lower_world(*keys)
+        # Try each set of keys until we find a match
+        for try in search_keys(*keys)
+          tried = Jekyll::DistorteD::Floor::config(
+            Jekyll::DistorteD::Floor::CONFIG_ROOT,
+            :welcome,
+            *try,
+          )
+          # Is the YAML config of the appropriate structure?
+          if tried.is_a?(Hash)
+            # Non-Hashes may not respond to `empty?`
+            unless tried.empty?
+              return tried
+            end
+          end
+        end
+      end
+
+      # Load configuration telling us what media-types to generate
+      # for any given media-type input.
+      def changes(*keys)
+        out = Set[]
+        # `changes` media-type[sub_type] config will contain information about
+        # what variations output format are desired for what input format,
+        # e.g. {:image => {:jpeg => Set['image/jpeg', 'image/webp']}}
+        # It is not automatically implied that the source format is also
+        # an output format!
+        for try in search_keys(*keys)
+          tried = Jekyll::DistorteD::Floor::config(
+            Jekyll::DistorteD::Floor::CONFIG_ROOT,
+            :changes,
+            *try,
+          )
+          if tried.is_a?(Enumerable) and tried.all?{|t| t.is_a?(String)} and not tried.empty?
+            tried.each{ |t|
+              # MIME::Type.new() won't give us a usable Type object:
+              #
+              # irb> MIME::Types['image/svg+xml'].first.preferred_extension
+              # => "svg"
+              # irb> MIME::Type.new('image/svg+xml').preferred_extension
+              # => nil
+              out.merge(CHECKING::YOU::IN(t))
+            }
+          end
+        end
+
+        # If the config didn't give us any MIME::Type changes
+        # then we will just output the same type we loaded.
+        if out.empty?
+          return type_mars
+        else
+          return out
+        end
+      end
+
+      # Loads configuration telling us what variations to generate for any
+      # given type of file, or for an arbitrary key hierarchy.
+      def outer_limits(*keys)
+        out = Set[]
+        # See if any config data exists for each given key hierarchy,
+        # but under the root DistorteD config key.
+        for try in search_keys(*keys)
+          tried = Jekyll::DistorteD::Floor::config(
+            Jekyll::DistorteD::Floor::CONFIG_ROOT,
+            :outer_limits,
+            *try,
+          )
+
+          # Is the YAML config of the appropriate structure?
+          # Merge a shallow copy of it with the Liquid-given attrs.
+          # If we don't take a copy the attrs will be memoized into the config.
+          if tried.is_a?(Enumerable) and tried.all?{|t| t.is_a?(Hash)} and not tried.empty?
+            out.merge(tried.dup.map{ |d| d.merge(@liquid_liquid) })
+          end
+        end
+
+        # We should output something if the config didn't give us anything.
+        # This is kind of a mess right now with redundancies in the call sites
+        # of things like Molecule::Image. I'll come up with a better general-
+        # purpose fallback solution at some point, but for now this will get
+        # non-Image StaticFiles working with no config :)
+        if out.empty?
+          out << {
+            :tag => :full,
+          }
+        end
+
+        return out
+      end
+
+    end
+  end
+end