distorted-jekyll 0.5.3 → 0.6.0

data/lib/distorted-jekyll/invoker.rb

@@ -0,0 +1,259 @@
+# Our custom Exceptions
+require 'distorted/error_code'
+
+# MIME::Typer
+require 'distorted/checking_you_out'
+
+# Configuration-loading code
+require 'distorted-jekyll/floor'
+require 'distorted-jekyll/static_state'
+
+# Media-type drivers
+require 'distorted-jekyll/molecule/font'
+require 'distorted-jekyll/molecule/image'
+require 'distorted-jekyll/molecule/text'
+require 'distorted-jekyll/molecule/pdf'
+require 'distorted-jekyll/molecule/svg'
+require 'distorted-jekyll/molecule/video'
+require 'distorted-jekyll/molecule/lastresort'
+
+# Set.to_hash
+require 'distorted/monkey_business/set'
+
+# Slip in and out of phenomenon
+require 'liquid/tag'
+require 'liquid/tag/parser'
+
+# Explicitly required for l/t/parser since a1cfa27c27cf4d4c308da2f75fbae88e9d5ae893
+require 'shellwords'
+
+# Set is in stdlib but is not in core.
+require 'set'
+
+# I mean, this is why we're here, right?
+require 'jekyll'
+
+
+module Jekyll
+  module DistorteD
+    class Invoker < Liquid::Tag
+
+      GEM_ROOT = File.dirname(__FILE__).freeze
+
+      # Mix in config-loading methods.
+      include Jekyll::DistorteD::Floor
+      include Jekyll::DistorteD::StaticState
+
+      # Enabled media_type drivers. These will be attempted back to front.
+      # TODO: Make this configurable.
+      MEDIA_MOLECULES = [
+        Jekyll::DistorteD::Molecule::LastResort,
+        Jekyll::DistorteD::Molecule::Font,
+        Jekyll::DistorteD::Molecule::Text,
+        Jekyll::DistorteD::Molecule::PDF,
+        Jekyll::DistorteD::Molecule::SVG,
+        Jekyll::DistorteD::Molecule::Video,
+        Jekyll::DistorteD::Molecule::Image,
+      ]
+      # Reduce the above to a Hash of Sets of MediaMolecules-per-Type, keyed by Type.
+      TYPE_MOLECULES = MEDIA_MOLECULES.reduce(
+        Hash.new{|hash, key| hash[key] = Set[]}
+      ) { |types, molecule|
+        if molecule.const_defined?(:LOWER_WORLD)
+          molecule.const_get(:LOWER_WORLD).each { |t|
+            types.update(t => Set[molecule]) { |k,o,n| o.merge(n) }
+          }
+        end
+        types
+      }
+
+      # Any any attr value will get a to_sym if shorter than this
+      # totally arbitrary length, or if the attr key is in the plugged
+      # Molecule's set of attrs that take only a defined set of values.
+      # My chosen boundary length fits all of the outer-limit tag names I use,
+      # like 'medium'. It fits the longest value of Vips::Interesting too,
+      # though `crop` will be symbolized based on the other condition.
+      ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY = 13
+
+
+      # 𝘏𝘖𝘞 𝘈𝘙𝘌 𝘠𝘖𝘜 𝘎𝘌𝘕𝘛𝘓𝘌𝘔𝘌𝘕 ！！
+      def initialize(tag_name, arguments, liquid_options)
+        super
+        # Tag name as given to Liquid::Template.register_tag().
+        @tag_name = tag_name.to_sym
+
+        # 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)
+
+        # Filename is the only non-keyword argument our tag should ever get.
+        # It's spe-shul and gets its own definition outside the attr loop.
+        if parsed_arguments.key?(:src)
+          @name = parsed_arguments.delete(:src)
+        else
+          @name = parsed_arguments.delete(:argv1)
+        end
+        @liquid_liquid = parsed_arguments.select{ |attr, val|
+          not [nil, ''.freeze].include?(val)
+        }.transform_keys { |attr|
+          attr.length <= ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY ? attr.to_sym : attr.freeze
+        }.transform_values { |val|
+          if val.respond_to?(:length)
+            val.length <= ARBITRARY_ATTR_SYMBOL_STRING_LENGTH_BOUNDARY ? val.to_sym : val.freeze
+          else
+            val
+          end
+        }
+
+        # If we didn't get one of the two above options there is nothing we
+        # can do but bail.
+        unless @name
+          raise "Failed to get a usable filename from #{arguments}"
+        end
+
+      end
+
+      # Returns a Set of DD MIME::Types descriving our file,
+      # optionally falling through to a plain file copy.
+      def type_mars
+        @type_mars ||= begin
+          mime = CHECKING::YOU::OUT(@name)
+          if mime.empty?
+            if Jekyll::DistorteD::Floor::config(Jekyll::DistorteD::Floor::CONFIG_ROOT, :last_resort)
+              mime = Jekyll::DistorteD::Molecule::LastResort::LOWER_WORLD
+            end
+          end
+          mime
+        end
+      end
+
+      # Return any arguments given by the user to our Liquid tag.
+      # This method name is generic across all DD entrypoints so it can be
+      # referenced from lower layers in the pile.
+      def user_arguments
+        @liquid_liquid || Hash[]
+      end
+
+      # Decides which MediaMolecule is most appropriate for our file and returns it.
+      def media_molecule
+        available_molecules = TYPE_MOLECULES.keys.to_set & type_mars
+        # TODO: Handle multiple molecules for the same file
+        case available_molecules.length
+        when 0
+          raise MediaTypeNotImplementedError.new(@name)
+        when 1
+          return TYPE_MOLECULES[available_molecules.first].first
+        end
+      end
+
+      def plug
+        unless self.singleton_class.instance_variable_defined?(:@media_molecule)
+          self.singleton_class.instance_variable_set(:@media_molecule, media_molecule)
+          self.singleton_class.prepend(media_molecule)
+          Jekyll.logger.info(@name, "Plugging #{media_molecule}")
+        end
+      end
+
+      # Called by Jekyll::Renderer
+      # https://github.com/jekyll/jekyll/blob/HEAD/lib/jekyll/renderer.rb
+      # https://jekyllrb.com/tutorials/orderofinterpretation/
+      def render(context)
+        plug
+        render_to_output_buffer(context, '')
+      end
+
+      # A future Liquid version (5.0?) will call this function directly
+      # instead of calling render()
+      def render_to_output_buffer(context, output)
+        plug
+        # Get Jekyll Site object back from tag rendering context registers so we
+        # can get configuration data and path information from it and
+        # then pass it along to our StaticFile subclass.
+        @site = context.registers[:site]
+
+        # The rendering context's `first` page will be the one that invoked us.
+        page_data = context.environments.first['page'.freeze]
+
+        #
+        # Our subclass' additional args:
+        # dest - The String path to the generated `url` folder of the page HTML output
+        @base = @site.source
+
+        # `relative_path` doesn't seem to always exist, but `path` does? idk.
+        # I was testing with `relative_path` only with `_posts`, but it broke
+        # when I invoked DD on a _page. Both have `path`.
+        @dir = File.dirname(page_data['path'.freeze])
+
+        # Every one of Ruby's `File.directory?` / `Pathname.directory?` /
+        # `FileTest.directory?` methods actually tests that path on the
+        # real filesystem, but we shouldn't look at the FS here because
+        # this function gets called when the Site.dest directory does
+        # not exist yet!
+        # Hackily look at the last character to see if the URL is a
+        # directory (like configured on cooltrainer) or a `.html`
+        # (or other extension) like the default Jekyll config.
+        # Get the dirname if the url is not a dir itself.
+        @relative_dest = page_data['url'.freeze]
+        unless @relative_dest[-1] == Jekyll::DistorteD::Floor::PATH_SEPARATOR
+          @relative_dest = File.dirname(@relative_dest)
+          # Append the trailing slash so we don't have to do it
+          # in the Liquid templates.
+          @relative_dest << Jekyll::DistorteD::Floor::PATH_SEPARATOR
+        end
+
+        # Add our new file to the list that will be handled
+        # by Jekyll's built-in StaticFile generator.
+        @site.static_files << self
+        output
+      end
+
+      # Generic Liquid template loader that will be used in every MediaMolecule.
+      # Callers will call `render(**{:template => vars})` on the Object returned
+      # by this method.
+      def parse_template(site: nil, name: nil)
+        site = site || @site || Jekyll.sites.first
+        begin
+          # Use a given filename, or detect one based on media-type.
+          if name.nil?
+            # e.g. Jekyll::DistorteD::Molecule::Image -> 'image.liquid'
+            name = "#{self.singleton_class.instance_variable_get(:@media_molecule).name.gsub(/^.*::/, '').downcase}.liquid".freeze
+          elsif not name.include?('.liquid'.freeze)
+            # Support filename arguments with and without file extension.
+            # The given String might already be frozen, so concatenating
+            # the extension might fail. Just set a new version.
+            name = "#{name}.liquid"
+          end
+          template = File.join(
+            self.singleton_class.const_get(:GEM_ROOT),
+            'template'.freeze,
+            name,
+          )
+
+          # Jekyll's Liquid renderer caches in 4.0+.
+          if Jekyll::DistorteD::Floor::config(
+              Jekyll::DistorteD::Floor::CONFIG_ROOT,
+              :cache_templates,
+          )
+            # file(path) is the caching function, with path as the cache key.
+            # The `template` here will be the full path, so no versions of this
+            # gem should ever conflict. For example, right now during dev it's:
+            # `/home/okeeblow/Works/DistorteD/lib/image.liquid`
+            Jekyll.logger.debug('DistorteD', "Parsing #{template} with caching renderer.")
+            site.liquid_renderer.file(template).parse(File.read(template))
+          else
+            # Re-read the template just for this piece of media.
+            Jekyll.logger.debug('DistorteD', "Parsing #{template} with fresh (uncached) renderer.")
+            Liquid::Template.parse(File.read(template))
+          end
+
+        rescue Liquid::SyntaxError => l
+          # This shouldn't ever happen unless a new version of Liquid
+          # breaks syntax compatibility with our templates somehow.
+          l.message
+        end
+      end  # parse_template
+
+
+    end
+  end
+end

data/lib/distorted-jekyll/md_injection.rb

@@ -0,0 +1,305 @@
+require 'kramdown'
+
+# Replace standard Markdown image syntax with instances of DistorteD
+# via its Liquid tag.
+#
+#
+### SYNTAX
+#
+# I'm calling individual media elements "images" here because I'm overloading
+# the Markdown image syntax to express them. There is no dedicated
+# syntax for other media types in any flavor of Markdown as of 2019,
+# so that seemed like the cleanest and sanest way to deal
+# with non-images in DistorteD.
+#
+# DistorteD::Invoker will do the media type inspection and handling
+# once we get into Liquid Land. This is the approach suggested by
+# CommonMark: https://talk.commonmark.org/t/embedded-audio-and-video/441/15
+#
+# Media elements will display as a visibly related group when
+# two or more Markdown image tags exist in consecutive Markdown
+# unordered (e.g. *-+) list item or ordered (e.g. 1.) list item lines.
+# Their captions should be hidden until opened in a lightbox or as a tooltip
+# on desktop browsers via ::hover state.
+#
+# The inspiration for this display can be seen in the handling
+# of two, three, or four images in any single post on Tw*tter.
+# DistorteD expands on the concept by supporting things such as groups
+# of more than four media elements and elements of heterogeneous media types.
+#
+# Standalone image elements (not contained in list item) should be displayed
+# as single solo elements spanning the entire usable width of the
+# container element, whatever that happens to be at the point where
+# our regex excised a block of Markdown for us to work with.
+#
+#
+### TECHNICAL CONSIDERATIONS
+#
+# Jekyll processes Liquid templates before processing page/post Markdown,
+# so we can't rely on customizing the Markdown renderer's `:img` element
+# output as a means to invoke DistorteD.
+# https://jekyllrb.com/tutorials/orderofinterpretation/
+#
+# Prefer the POSIX-style bracket expressions (e.g. [[:digit:]]) over
+# basic character classes (e.g. \d) in regex because they match Unicode
+# instead of just ASCII.
+# https://ruby-doc.org/core/Regexp.html#class-Regexp-label-Character+Classes
+#
+#
+### INLINE ATTRIBUTE LISTS
+#
+# Support additional arguments passed to DistorteD via Kramdown-style
+# inline attribute lists.
+# https://kramdown.gettalong.org/syntax.html#images
+# https://kramdown.gettalong.org/syntax.html#inline-attribute-lists
+#
+# IALs can be on the same line or on a line before or after their
+# associated flow element.
+# In ambiguous situations (flow elements both before and after an IAL),
+# the IAL applies to the flow element before it.
+# All associated elements and IALs must be on contiguous lines.
+#
+# This page provides a regex for parsing IALs, Section 5.3:
+# https://golem.ph.utexas.edu/~distler/maruku/proposal.html
+#
+#
+### SOLUTION
+#
+# A `pre_render` hook uses this regex to process Markdown source files
+# and replace instances of the Markdown image syntax with instances of
+# DistorteD's Liquid tags.
+# Single images will be replaced with {% distorted %}.
+# Multiple list-item images will be replaced with a {% distort %} block.
+#
+# By doing with with a regex (sorry!!) I hope to avoid a hard dependency on
+# any one particular Markdown engine. Though I only support Kramdown for now,
+# any engine that supports IALs should be fine.
+#
+# High-level explanation of what we intend to match:
+#
+# {:optional_ial => line_before_image}  # Iff preceded by a blank line!
+# (optional_list_item)? ![alt](image){:optional_ial => same_line}
+# {:optional_ial => next_consecutive_line}
+# Repeat both preceding matches (together) any number of times to parse
+# a {% distort %} block.
+# See inline comments below for more detail.
+MD_IMAGE_REGEX = %r&
+  # Matching group of a single image tag.
+  (
+    # Optional preceding-line attribute list.
+    (
+      # One blank line, because:
+      # "If a block IAL is directly after and before a block-level element,
+      #  it is applied to preceding element."  —Kramdown BAL docs
+      #
+      # /\R/ - A linebreak: \n, \v, \f, \r \u0085 (NEXT LINE),
+      #   \u2028 (LINE SEPARATOR), \u2029 (PARAGRAPH SEPARATOR) or \r\n.
+      ^$\R
+      # Any amount of blank space on the line before block IAL
+      ^[[:blank:]]*
+      # IAL regex from Section 5.3:
+      # https://golem.ph.utexas.edu/~distler/maruku/proposal.html
+      (?<block_ial_before>\{:(\\\}|[^\}])*\})
+      # Any amount of trailing whitespace followed by a newline.
+      [[:blank:]]*$\R
+    )?  # Match all of that, or nothing.
+    # Begin matching the line that contains an image.
+    ^
+    # Match anything that might be between that start-of-line
+    # and the first character (!) of an image.
+    (
+      # From Gruber's original Markdown page:
+      # "List markers typically start at the left margin, but may be indented
+      # by up to three spaces."
+      # Include both unordered (-+*) and ordered (\d\. like `1.`) lists.
+      (?<li>[ ]{0,3}[-\*\+|\d\.]
+      # Support an optional IAL for the list element as shown in Kramdown docs:
+      # https://kramdown.gettalong.org/syntax.html#lists
+      # Ctrl+F "{:.cls}"
+      (?<li_ial>\{:(\\\}|[^\}])*\})?
+      # "List markers must be followed by one or more spaces or a tab."
+      # https://daringfireball.net/projects/markdown/syntax#list
+      ([ ]+|\t))
+    )?  # Although any preceding elements are optional!
+    # Match Markdown image syntax:
+    #   ![alt text](/some/path/to/image.png 'title text'){:other="options"}
+    #   beginning with the alt tag:
+    !\[(?<alt>(\\[[:print:]]|[^\]])*)\]
+    # Continuing with img src as anything after the '(' and before ')' or
+    # before anything that could be a title.
+    # Assume titles will be quoted.
+    \((?<src>(\\[[:print:]]|[^'")]+))
+    # Title is optional.
+    # Ignore double-quotes in single-quoted titles and single-quotes
+    # in double-quoted titles otherwise we can't use contractions.
+    # Don't include the title's opening or closing quotes in the capture.
+    ('(?<title>(\\[[:print:]]|[^']*))'|"(?<title>(\\[[:print:]]|[^"]*))")?
+    # The closing ')' will always be present, title or no.
+    \)
+    # Optional IAL on the same line as the :img element **with no space between them**:
+    # "A span IAL (or two or more span IALs) has to be put directly after
+    #  the span-level element to which it should be applied, no additional
+    #  character is allowed between, otherwise it is ignored and only
+    #  removed from the output."  —Kramdown IAL docs
+    (?<span_ial>\{:(\\\}|[^\}])*\})*[[:print:]]*$\R
+    # Also support optional BALs on the lines following the image.
+    (^[[:blank:]]*(?<block_ial_after>\{:(\\\}|[^\}])*\})+$\R)*
+  )+  # Capture multiple images together for block display.
+&x
+
+
+def md_injection
+  Proc.new { |document, payload|
+    # Compare any given document's file extension to the list of enabled
+    # Markdown file extensions in Jekyll's config.
+    if payload['site']['markdown_ext'].include? document.extname.downcase[1..-1]
+      # Convert Markdown images to {% distorted %} tags.
+      #
+      # Use the same Markdown parser as Jekyll to avoid parsing inconsistencies
+      # between this pre_render hook and the main Markdown render step.
+      # This is still effectively a Markdown-parsing regex (and still
+      # effectively a bad idea lol) but it's the cleanest way I can come up
+      # with right now for separating DistorteD-destined Markdown from
+      # the rest of any given page.
+      # NOTE: Attribute List Definitions elsewhere in a Markdown document
+      # will be lost when converting this way. I might end up just parsing
+      # the entire document once with my own `to_liquid` converter, but I've been
+      # avoiding that as it seems wasteful because Jekyll then renders the entire
+      # Markdown document a second time immediately after our Liquid tag.
+      # It's fast enough that I should stop trying to prematurely optimize this :)
+      # TODO: Implement MD → DD love using only the #{CONFIGURED_MARKDOWN_ENGINE},
+      # searching for :img elements inside :li elements to build BLOCKS.
+      document.content = document.content.gsub(MD_IMAGE_REGEX) { |match| 
+        Kramdown::Document.new(match).to_liquid
+      }
+    end
+  }
+end
+
+
+# Kramdown implementation of Markdown AST -> Liquid converter.
+# Renders Markdown element attributes as key=value, also under the assumption
+# of using gem 'liquid-tag-parser': https://github.com/dmalan/liquid-tag-parser
+module Kramdown
+  module Converter
+    class Liquid < Base
+
+      # The incoming parsed Markdown tree will include many spurious elements,
+      # like container paragraph elements and the list item elements when
+      # parsing DD Grid style Markdown. Use this function to map a tree of
+      # arbitrary elements to a flat list of elements of a single type.
+      def children(el, type)
+        matched = []
+
+        if el.is_a? Enumerable
+        # We might want to run this against an Array output from an
+        # earlier invokation of this method.
+          el.each {
+            |item| matched.push(*children(item, type))
+          }
+        elsif el.type.equal? type
+          # If we find the type we're looking for, stop and return it.
+          # Let it bring its children along with it instead of recursing
+          # into them. This will let us match container-only elements
+          # such as <li> by type without considering the type of its children,
+          # for situation where its children are really what we want.
+          matched.push(el)
+        else
+          # Otherwise keep looking down the tree.
+          unless el.children.empty?
+            el.children.each {
+              |child| matched.push(*children(child, type))
+            }
+          end
+        end
+        matched
+      end
+
+      def attrs(el, type = :img)
+        matched = []
+
+        if el.is_a? Enumerable
+          # Support an Array of elements...
+          el.each {
+            |child| matched.push(*attrs(child, type))
+          }
+        else
+          # ...or a tree of elements.
+          if el.type.equal? type
+            # Images won't have a `:value` — only `:attr`s — and the only
+            # important things in their `:options` (e.g. IAL contents)
+            # will be duplicated in `class` or some other `:attr` anyway.
+            # Those things should be added here if this is ever used in a
+            # more generic context than just parsing the image tags.
+            matched << el.attr unless el.attr.empty?
+          end
+          unless el.children.empty?
+            # Keep looking even if this element was one we are looking for.
+            el.children.each {
+              |child| matched.push(*attrs(child, type))
+            }
+          end
+        end
+        matched
+      end
+
+      # Convert Markdown element attributes to a string key=value,
+      # except for `src` (DD-specific)
+      def to_attrs(k, v)
+        # DistorteD prefers the media filename as a positional argument,
+        # not a named kwarg.
+        if k == 'src'
+          v.to_s
+        else
+          k.to_s + '="' + v.to_s + '"'
+        end
+      end
+
+      def distorted(attrs)
+        "{% distorted #{attrs.map{|k,v| to_attrs(k, v)}.join(' ')} %}"
+      end
+
+      # Kramdown entry point
+      def convert(el)
+        # The parsed "images" may also be audio, video, or some other
+        # media type. There is only one Markdown image tag, however.
+        imgs = children(el, :img)
+
+        # Enable conceptual-grouping (BLOCKS) mode if the count of list item
+        # elements matches the count of image elements in our
+        # chunk of Markdown. Technically I should check to make sure each
+        # image is the child of one of those list items,
+        # but this is way easier until I (hopefully never) find a parsing
+        # corner-case where this doesn't hold up.
+        lists = children(el, :li)
+        list_imgs = lists.map{|li| children(li, :img)}.flatten
+
+        case lists.count
+        when 0..1
+          # Render one (1) image/video/whatever. This behavior is the same
+          # regardless if the image is in a single-item list or just by itself.
+          distorted(attrs(imgs.first)&.first&.merge({
+            # Images default to `attention` cropping for desktop/mobile versatility.
+            # Override this for single images unless a cropping value was already set.
+            'crop'.freeze => attrs(imgs.first)&.first&.dig('crop'.freeze) || 'none'.freeze,
+          }))
+        else
+          # Render a conceptual group (DD::BLOCKS)
+
+          if imgs.count != list_imgs.count
+            # Sanity check :img count vs :img-in-:li count.
+            # We should support the corner case where the regex matches
+            # multiple consecutive lines, but with mixed list item status,
+            # e.g. a solo image abuts a conceptual group and gets globbed
+            # into a single match.
+            # For now, however:
+            raise "MD->img regex returned an unequal number of listed and unlisted tags."
+          end
+
+          "{% distort -%}\n#{list_imgs.map{|img| distorted(*attrs(img))}.join("\n")}\n{% enddistort %}"
+        end
+      end
+
+    end
+  end
+end