distorted 0.6.0 → 0.7.0

data/lib/distorted/element_of_media.rb

@@ -0,0 +1,2 @@
+require 'distorted/element_of_media/change'
+require 'distorted/element_of_media/compound'

data/lib/distorted/element_of_media/change.rb

@@ -0,0 +1,119 @@
+module Cooltrainer
+
+  # Fun Ruby Fact™: `false` is always object_id 0
+  # https://skorks.com/2009/09/true-false-and-nil-objects-in-ruby/
+  # irb(main):650:0> true.object_id
+  # => 20
+  # irb(main):651:0> false.object_id
+  # => 0
+  BOOLEAN_VALUES = Set[false, true]
+
+
+  # Struct to encapsulate all the data needed to perform one (1) MIME::Type transformation
+  # of a source media file into any supported MIME::Type, possibly even the same type as input.
+  Change = Struct.new(:type, :src, :basename, :molecule, :tag, :breaks, :atoms, keyword_init: true) do
+
+    # Customize the destination filename and other values before doing the normal Struct setup.
+    def initialize(type, src: nil, molecule: nil, tag: nil, breaks: Array.new, **atoms)
+      # `name` might have a leading slash if referenced as an absolute path as the Tag.
+      basename = File.basename(src, '.*'.freeze).reverse.chomp('/'.freeze).reverse
+
+      # Set the &default_proc on the kwarg-glob Hash instead of making a new Hash,
+      atoms.default_proc = lambda { |h,k| h[k] = Cooltrainer::Atom.new }
+      atoms.transform_values {
+        # We might get Atoms already instantiated, but do it for any that aren't.
+        # We won't have a default value for them in that case.
+        |v| v.is_a?(Cooltrainer::Atom) ? atom : Cooltrainer::Atom.new(v, nil)
+      }.each_key { |k|
+        # Define accessors for context-specific :atoms keys/values that aren't normal Struct members.
+        self.singleton_class.define_method(k) { self[:atoms]&.fetch(k, nil)&.get }
+        self.singleton_class.define_method("#{k}=".to_sym) { |v| self[:atoms][k] = v }
+      }
+
+      # And now back to your regularly-scheduled Struct
+      super(type: type, src: src, basename: basename, molecule: molecule, tag: tag, breaks: breaks, atoms: atoms)
+    end
+
+    # Returns the Change Type's :preferred_extension as a String with leading dot (.)
+    def extname
+      @extname ||= begin
+        dot = '.'.freeze unless type.preferred_extension.nil? || type.preferred_extension&.empty?
+        "#{dot}#{type.preferred_extension}"
+      end
+    end
+
+    # Returns an Array[String] of filenames this Change should generate,
+    # one 'full'/'original' plus any limit-breaks,
+    # e.g. ["DistorteD.png", "DistorteD-333.png", "DistorteD-555.png", "DistorteD-888.png", "DistorteD-1111.png"]
+    def names
+      Array[''.freeze].concat(self[:breaks]).map { |b|
+        filetag = (b.nil? || b&.to_s.empty?) ? ''.freeze : '-'.concat(b.to_s)
+        "#{self[:basename]}#{"-#{self.tag}" unless self.tag.nil?}#{filetag}#{extname}"
+      }
+    end
+
+    # Returns a String describing the :names but rolled into one,
+    # e.g. "IIDX-turntable-(400|800|1500).png"
+    def name
+      tags = self[:breaks].length > 1 ? "-(#{self[:breaks].join('|'.freeze)})" : ''.freeze
+      "#{self.basename}#{tags}#{self.extname}"
+    end
+
+    # Returns an Array[String] of all absolute destination paths this Change should generate,
+    # given a root destination directory.
+    def paths(dest_root = ''.freeze)  # Empty String will expand to current working directory
+      output_dir = self[:atoms]&.fetch(:dir, ''.freeze)
+      return self.names.map { |n| File.join(File.expand_path(dest_root), output_dir, n) }
+    end
+
+    # Returns a String absolute destination path for only one limit-break.
+    def path(dest_root, break_value)
+      output_dir = self[:atoms]&.fetch(:dir, ''.freeze)
+      return File.join(File.expand_path(dest_root), output_dir, "#{self.basename}#{"-#{self.tag}" unless self.tag.nil?}-#{break_value}#{self.extname}")
+    end
+
+    # A generic version of Struct#to_hash was rejected with good reason,
+    # but I'm going to use it here because I want the implicit Struct-to-Hash
+    # conversion to let me destructure these Structs with a double-splat:
+    # https://bugs.ruby-lang.org/issues/4862
+    #
+    # Defining this method causes Ruby 2.7 to emit a "Using the last argument as keyword parameters is deprecated" warning
+    # if this Struct is passed to a method as the final positional argument! Ruby 2.7 will actually do the
+    # conversion when calling the method in that scenario, causing incorrect behavior to methods expecting Struct.
+    # This is why DD-Floor's `:write` and DD-Jekyll's `:render_to_output_buffer` pass an empty kwargs Hash.
+    # https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+    def to_hash  # Implicit
+      Hash[self.members.reject{|m| m == :atoms}.zip(self.values.reject{|v| v.is_a?(Hash)})].merge(self[:atoms].transform_values(&:get))
+    end
+    # Struct#to_h does exist in stdlib, but redefine its behavior to match our `:to_hash`.
+    def to_h  # Explicit
+      Hash[self.members.reject{|m| m == :atoms}.zip(self.values.reject{|v| v.is_a?(Hash)})].merge(self[:atoms].transform_values(&:get))
+    end
+    def dig(*keys); self.to_hash.dig(*keys); end
+
+    # Support setting Atoms that were not defined at instantiation.
+    def method_missing(meth, *a, **k, &b)
+      # Are we a setter?
+      if meth.to_s[-1] == '='.freeze
+        # Set the :value of an existing Atom Struct
+        self[:atoms][meth.to_s.chomp('='.freeze).to_sym].value = a.first
+      else
+        self[:atoms]&.fetch(meth, nil)
+      end
+    end
+
+  end  # Struct Change
+
+
+  # Struct to wrap just the user and default values for a Compound or just for freeform usage.
+  Atom = Struct.new(:value, :default) do
+    # Return a value if set, otherwise a default. Both can be `nil`.
+    def get; self.value || self.default; end
+    # Override these default Struct methods with ones that reference our :get
+    def to_s; self.get.to_s; end    # Explicit
+    def to_str; self.get.to_s; end  # Implicit
+    # Send any unknown message through to a value/default.
+    def method_missing(meth, *a, **k, &b); self.get.send(meth, *a, **k, &b); end
+  end
+
+end

data/lib/distorted/element_of_media/compound.rb

@@ -0,0 +1,120 @@
+require 'optparse'
+require 'date'
+
+module Cooltrainer
+
+  # This is defined in writing in a comment in optparse.rb's RDoc,
+  # but I can't seem to find anywhere it's available directly in code,
+  # so I am going to build my own.
+  # Maybe I am missing something obvious, in which case I should use that
+  # and get rid of this :)
+  # Based on https://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#class-OptionParser-label-Type+Coercion
+  OPTIONPARSER_COERSIONS = [
+    Date,
+    DateTime,
+    Time,
+    URI,
+    #Shellwords,  # Stock in optparse, but under autoload. I don't want it.
+    String,
+    Integer,
+    Float,
+    Numeric,
+    TrueClass,
+    FalseClass,
+    Array,
+    Regexp,
+  ].concat(OptionParser::Acceptables::constants)
+
+
+  # Struct to wrap a MediaMolecule option/attribute datum.
+  Compound = Struct.new(:isotopes, :molecule, :valid, :default, :blurb, keyword_init: true) do
+
+    # Massage the data then call `super` to set the members/values and create the accessors.
+    def initialize(isotopes, molecule: nil, valid: nil, default: nil, blurb: nil)
+      super(
+        # The first argument defines the aliases for a single option and may be just a Symbol
+        # or may be an Enumerable[Symbol] in which case all items after the first are aliases for the first.
+        isotopes: isotopes.is_a?(Enumerable) ? isotopes.to_a : Array[isotopes],
+        # Hint the MediaMolecule that should execute this Change.
+        molecule: molecule,
+        # Valid values for this option may be expressed as a Class a value must be an instance of,
+        # a Regexp a String value must match, an Enumerable that a valid value must be in,
+        # a Range a Float/Integer must be within, a special Boolean Set, etc etc.
+        valid: case valid
+          when Set then valid.to_a
+          else valid
+        end,
+        # Optional default value to use when unset.
+        default: default,
+        # String description of this option's effect.
+        blurb: blurb,
+      )
+    end
+
+    # The first isotope is the """real""" option name. Any others are aliases for it.
+    def element; self.isotopes&.first; end
+    def to_s; self.element.to_s; end
+
+    # Returns a longform String representation of one option.
+    def inspect
+      # Intentionally not including the blurb here since they are pretty long and messy.
+      "#{self.isotopes.length > 1 ? self.isotopes : self.element}: #{"#{self.valid} " if self.valid}#{"(#{self.default})" if self.default}"
+    end
+
+    # Returns an Array of properly-formatted OptionParser::Switch strings for this Compound.
+    def to_options
+      # @isotopes is a Hash[Symbol] => Compound, allowing for Compound aliasing
+      # to multiple Hash keys, e.g. libvips' `:Q` and `:quality` are two Hash keys
+      # referencing the same Compound object.
+      self.isotopes.each_with_object(Array[]) { |aka, commands|
+        # Every Switch has at least one leading dash, and longer ones have two,
+        # e.g. `-Q` vs `--quality`.
+        command = "-"
+        if aka.length > 1
+          command << '-'.freeze
+        end
+
+        # Compounds that take a boolean should format their Switch string
+        # as `--[no]-whatever` (including the brackets!) instead of taking
+        # any kind of boolean-ish argument like true/false/yes/no.
+        #
+        # TODO: There seems to be a bug with Ruby optparse and multiple of these
+        # "--[no]-whatever"-style Switches where only the final Switch will display,
+        # so disable this for now in favor of separate --whatever/--no-whatever.
+        # I have a very basic standalone repro case that fails, so it's not just DD.
+        #
+        #if @valid == BOOLEAN_VALUES or @valid == BOOLEAN_VALUES.to_a
+        #  command << '[no]-'.freeze
+        #end
+
+        # Add the alias to form the command.
+        command << aka.to_s
+
+        # Format the valid values and/or default value and stick it on the end.
+        # https://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#class-OptionParser-label-Type+Coercion
+        if self.valid.is_a?(Range)
+          command << " [#{self.valid.to_s}]"
+        elsif self.valid == BOOLEAN_VALUES or self.valid == BOOLEAN_VALUES.to_a
+          # Intentional no-op
+        elsif self.valid.is_a?(Enumerable)
+          command << " [#{self.valid.join(', '.freeze)}]"
+        elsif not default.nil?
+          command << " [#{self.default}]"
+        else
+          command << " [#{self.element.upcase}]"
+        end
+
+        commands << command
+
+        # HACK around issue with multiple "--[no]-whatever"-style long arguments.
+        # See above note and the commented-out implementation I'd like to use
+        # instead of this. Remove this iff I can figure out what's wrong there.
+        if self.valid == BOOLEAN_VALUES or self.valid == BOOLEAN_VALUES.to_a
+          commands << "--no-#{aka}"
+        end
+      }
+    end  # to_options
+
+  end  # Compound
+
+end

data/lib/distorted/floor.rb

@@ -0,0 +1,17 @@
+
+require 'set'
+require 'distorted/monkey_business/set'
+
+require 'distorted/invoker'
+require 'distorted/click_again'
+require 'distorted/checking_you_out'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+
+class Cooltrainer::DistorteD::Floor
+  def initialize(src, dest, type: nil)
+    #TODO: Library-use entry-point
+  end
+end

data/lib/distorted/invoker.rb

@@ -0,0 +1,97 @@
+
+# Our custom Exceptions
+require 'distorted/error_code'
+
+# MIME::Typer
+require 'distorted/checking_you_out'
+require 'distorted/media_molecule'
+
+# Set.to_hash
+require 'distorted/monkey_business/set'
+require 'set'
+
+
+module Cooltrainer::DistorteD::Invoker
+  # Returns a Hash[MIME::Type] => Hash[MediaMolecule] => Hash[param_alias] => Compound
+  def lower_world
+    Cooltrainer::DistorteD::IMPLANTATION(:LOWER_WORLD).each_with_object(
+      Hash.new { |pile, type| pile[type] = Hash[] }
+    ) { |(key, types), pile|
+      types.each { |type, elements| pile.update(type => {key.molecule => elements}) { |k,o,n| o.merge(n) }}
+    }
+  end
+
+  # Returns a Hash[MediaMolecule] => Hash[MIME::Type] => Hash[param_alias] => Compound
+  def outer_limits(all: false)
+    Cooltrainer::DistorteD::IMPLANTATION(
+      :OUTER_LIMITS,
+      (all || type_mars.empty?) ? Cooltrainer::DistorteD::media_molecules : type_mars.each_with_object(Set[]) { |type, molecules|
+        molecules.merge(lower_world[type].keys)
+      },
+    ).each_with_object(Hash.new { |pile, type| pile[type] = Hash[] }) { |(key, types), pile|
+      types.each { |type, elements| pile.update(key.molecule => {type => elements}) { |k,o,n| o.merge(n) }}
+    }
+  end
+
+  # Filename without the dot-and-extension.
+  def basename
+    File.basename(@name, '.*')
+  end
+
+  # Returns a Set of MIME::Types common to the source file and our supported MediaMolecules.
+  # Each of these Molecules will be plugged to the current instance.
+  def type_mars
+    @type_mars ||= CHECKING::YOU::OUT(path, so_deep: true) & lower_world.keys.to_set
+    raise MediaTypeNotImplementedError.new(@name) if @type_mars.empty?
+    @type_mars
+  end
+
+  # MediaMolecule file-type plugger.
+  # Any call to a MIME::Type's distorted_method will end up here unless
+  # the Molecule that defines it has been `prepend`ed to our instance.
+  def method_missing(meth, *args, **kwargs, &block)
+    # Only consider method names with our prefixes.
+    if MIME::Type::DISTORTED_METHOD_PREFIXES.values.map(&:to_s).include?(meth.to_s.split(MIME::Type::SUB_TYPE_SEPARATORS)[0])
+      # TODO: Might need to handle cases here where the Set[Molecule]
+      # exists but none of them defined our method.
+      unless self.singleton_class.instance_variable_get(:@media_molecules)
+        unless outer_limits.empty?
+          self.singleton_class.instance_variable_set(
+            :@media_molecules,
+            outer_limits.keys.each_with_object(Set[]) { |molecule, molecules|
+              self.singleton_class.prepend(molecule)
+              molecules.add(molecule)
+            }
+          )
+          # `return` to ensure we don't fall through to #method_missing:super
+          # if we are going to do any work, otherwise a NoMethodError will
+          # still be raised despite the distorted_method :sends suceeding.
+          #
+          # Use :__send__ in case a Molecule defines a `:send` method.
+          # https://ruby-doc.org/core/Object.html#method-i-send
+          return self.send(meth, *args, **kwargs, &block)
+        end
+      end
+    end
+    # …and I still haven't found it! — What I'm looking for, that is.
+    # https://www.youtube.com/watch?v=xqse3vYcnaU
+    super
+  end
+
+  # Make sure :respond_to? works for yet-unplugged distorted_methods.
+  # http://blog.marc-andre.ca/2010/11/15/methodmissing-politely/
+  def respond_to_missing?(meth, *a)
+    # We can tell if a method looks like one of ours if it has at least 3 (maybe more!)
+    # underscore-separated components with a valid prefix as the first component
+    # and the media-type and sub-type as the rest, e.g.
+    #
+    # irb(main)> 'to_application_pdf'.split('_')
+    # => ["to", "application", "pdf"]
+    #
+    # irb(main)> CHECKING::YOU::OUT('.docx').first.distorted_file_method.to_s.split('_')
+    # => ["write", "application", "vnd", "openxmlformats", "officedocument", "wordprocessingml", "document"]
+    parts = meth.to_s.split(MIME::Type::SUB_TYPE_SEPARATORS)
+    MIME::Type::DISTORTED_METHOD_PREFIXES.values.map(&:to_s).include?(parts[0]) && parts.length > 2 || super(meth, *a)
+  end
+
+end

data/lib/distorted/media_molecule.rb

@@ -0,0 +1,58 @@
+require 'set'
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD
+
+  # Discover DistorteD MediaMolecules bundled with this Gem
+  # TODO: and any installed as separate Gems.
+  @@loaded_molecules rescue begin
+    Dir[File.join(__dir__, 'media_molecule', '*.rb')].each { |molecule| require molecule }
+    @@loaded_molecules = true
+  end
+
+  # Returns a Set[Module] of our discovered MediaMolecules.
+  def self.media_molecules
+    Cooltrainer::DistorteD::Molecule.constants.map { |molecule|
+      Cooltrainer::DistorteD::Molecule::const_get(molecule)
+    }.to_set
+  end
+
+  # Reusable IMPLANTATION Hash key, since instances of the same Struct subclass are equal:
+  # irb> Pair = Struct.new(:uno, :dos)
+  # irb> lol = Pair.new(:a, 1)
+  # irb> rofl = Pair.new(:a, 1)
+  # irb> lol === rofl
+  # => true
+  KEY = Struct.new(:molecule, :constant, :inherit) do
+    # Descend into ancestor Modules by default.
+    def initialize(molecule, constant, inherit = true); super(molecule, constant, inherit); end
+    def inspect; "#{molecule}#{'∫'.freeze if inherit}::#{constant}"; end
+  end
+
+  # Check and create attribute-memoizing Hash whose default_proc will fetch
+  # and collate the data for a given KEY.
+  @@implantation rescue begin
+    @@implantation = Hash.new { |piles, key| 
+      # Optionally limit search to top-level Module like `:const_defined?` with `inherit`
+      piles[key] = Set[key.molecule].merge(key.inherit ? key.molecule.ancestors : []).each_with_object(Hash.new) { |mod, pile|
+        mod.const_get(key.constant).each { |target, elements|
+          pile.update(target => elements) { |_key, existing, new| existing.merge(new) }
+        } rescue nil 
+      }
+    }
+  end
+
+  # Generic entry-point for attribute-collation of a given constant
+  # over a given Molecule or Enumerable of Molecules.
+  def self.IMPLANTATION(constant, corpus = self.media_molecules)
+    (corpus.is_a?(Enumerable) ? corpus : Array[corpus]).map { |molecule|
+      KEY.new(molecule, constant)
+    }.each_with_object(Hash[]) { |key, piles|
+      # Hash#slice doesn't trigger the default_proc, so access each directly.
+      piles.store(key, @@implantation[key])
+    }.yield_self { |piles|
+      # Return just the data when we were given a single Molecule to search.
+      corpus.is_a?(Enumerable) ? piles : piles.shift[1]
+    }
+  end
+end

data/lib/distorted/media_molecule/font.rb

@@ -0,0 +1,195 @@
+require 'set'
+
+# Font metadata extraction
+require 'ttfunk'
+
+require 'distorted/modular_technology/pango'
+require 'distorted/modular_technology/ttfunk'
+require 'distorted/modular_technology/vips/save'
+require 'distorted/checking_you_out'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::Font
+
+
+  # TODO: Test OTF, OTB, and others.
+  # NOTE: Traditional bitmap fonts won't be supported due to Pango 1.44
+  # and later switching to Harfbuzz from Freetype:
+  # https://gitlab.gnome.org/GNOME/pango/-/issues/386
+  # https://blogs.gnome.org/mclasen/2019/05/25/pango-future-directions/
+  LOWER_WORLD = CHECKING::YOU::IN(/^font\/ttf/).to_hash
+  OUTER_LIMITS = CHECKING::YOU::IN(/^font\/ttf/).to_hash
+
+  ATTRIBUTES = Set[
+    :alt,
+  ]
+  ATTRIBUTES_VALUES = {
+  }
+  ATTRIBUTES_DEFAULT = {
+  }
+
+
+  # Maybe T0DO: Process output with TTFunk instead of only using it
+  # to generate images and metadata.
+  self::LOWER_WORLD.keys.each { |t|
+    define_method(t.distorted_file_method) { |dest_root, change|
+      copy_file(change.paths(dest_root).first)
+    }
+  }
+
+  include Cooltrainer::DistorteD::Technology::TTFunk
+  include Cooltrainer::DistorteD::Technology::Pango
+  include Cooltrainer::DistorteD::Technology::Vips::Save
+
+
+  # irb(main):089:0> chars.take(5)
+  # => [[1, 255], [2, 1], [3, 2], [4, 3], [5, 4]]
+  # irb(main):090:0> chars.values.take(5)
+  # => [255, 1, 2, 3, 4]
+  # irb(main):091:0> chars.values.map(&:chr).take(5)
+  # => ["\xFF", "\x01", "\x02", "\x03", "\x04"]
+  def to_pango
+    output = '' << cr << '<span>' << cr
+
+    output << "<span size='35387'> #{font_name}</span>" << cr << cr
+
+    output << "<span size='24576'> #{font_description}</span>" << cr
+    output << "<span size='24576'> #{font_copyright}</span>" << cr
+    output << "<span size='24576'> #{font_version}</span>" << cr << cr
+
+    # Print a preview String in using the loaded font. Or don't.
+    if abstract(:title)
+      output << cr << cr << "<span size='24576' foreground='grey'> #{g_markup_escape_text(abstract(:title))}</span>" << cr << cr << cr
+    end
+
+    #                        /!\ MANDATORY READING /!\
+    # https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6cmap.html
+    #
+    # "The 'cmap' table maps character codes to glyph indices.
+    # The choice of encoding for a particular font is dependent upon the conventions
+    # used by the intended platform. A font intended to run on multiple platforms
+    # with different encoding conventions will require multiple encoding tables.
+    # As a result, the 'cmap' table may contain multiple subtables,
+    # one for each supported encoding scheme."
+    #
+    # Cmap#unicode is a convenient shortcut to sorting the subtables
+    # and removing any unusable ones:
+    # https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap.rb
+    #
+    # irb(main):174:0> font_meta.cmap.tables.count
+    # => 3
+    # irb(main):175:0> font_meta.cmap.unicode.count
+    # => 2
+    to_ttfunk.cmap.tables.each do |table|
+      next if !table.unicode?
+      # Each subtable's `code_map` is a Hash map of character codes (the Hash keys)
+      # to the glyph IDs from the original font (the Hash's values).
+      #
+      # Subtable::encode takes:
+      #  - a Hash mapping character codes to original font glyph IDs.
+      #  - the desired output encoding — Set[:mac_roman, :unicode, :unicode_ucs4]
+      #    https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+      # …and returns a Hash with keys:
+      #  - :charmap  — Hash mapping the characters in the input charmap
+      #                to a another hash containing both the `:old`
+      #                and `:new` glyph ids for each character code.
+      #  - :subtable — String encoded subtable for the given encoding.
+      encoded = TTFunk::Table::Cmap::Subtable::encode(table&.code_map, :unicode).dig(:charmap)
+
+      output << "<span size='49152'>"
+
+      i = 0
+      encoded.each_pair { |c, (old, new)|
+
+        begin
+          if glyph = to_ttfunk.glyph_outlines.for(c)
+            # Add a space on either side of the character so they aren't
+            # all smooshed up against each other and unreadable.
+            output << ' ' << g_markup_escape_char(c) << ' '
+            if i >= 15
+              output << cr
+              i = 0
+            else
+              i = i + 1
+            end
+          else
+          end
+        rescue NoMethodError => nme
+          # TTFunk's `glyph_outlines.for()` will raise this if we call it
+          # for a codepoint that does not exist in the font, which we will
+          # not do because we are enumerating the codepoints in the font,
+          # but we should still handle the possibility.
+          # irb(main):060:0> font.glyph_outlines.for(555555)
+          #
+          # Traceback (most recent call last):
+          #   6: from /usr/bin/irb:23:in `<main>'
+          #   5: from /usr/bin/irb:23:in `load'
+          #   4: from /home/okeeblow/.gems/gems/irb-1.2.4/exe/irb:11:in `<top (required)>'
+          #   3: from (irb):60
+          #   2: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/glyf.rb:35:in `for'
+          #   1: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/loca.rb:35:in `size_of'
+          # NoMethodError (undefined method `-' for nil:NilClass)
+        end
+      }
+
+      output << '</span>' << cr
+    end
+
+    output << '</span>'
+    output
+  end
+
+  # Return the `src` as the font_path since we aren't using
+  # any of the built-in fonts.
+  def font_path
+    path
+  end
+
+  def to_vips_image
+    # https://libvips.github.io/libvips/API/current/libvips-create.html#vips-text
+    Vips::Image.text(
+      # This string must be well-escaped Pango Markup:
+      # https://developer.gnome.org/pango/stable/pango-Markup.html
+      # However the official function for escaping text is
+      # not implemented in Ruby GLib, so we have to do it ourselves.
+      to_pango,
+      **{
+        # String absolute path to TTF
+        :fontfile => font_path,
+        # It's not enough to just specify the TTF path;
+        # we must also specify a font family, subfamily, and size.
+        :font => "#{font_name}",
+        # Space between lines (in Points).
+        :spacing => to_ttfunk.line_gap,
+        # Requires libvips 8.8
+        :justify => false,
+        :dpi => 144,
+      },
+    )
+  end
+
+end  # Font 
+
+
+# Notes on file-format specifics and software-library-specifics
+#
+# # TTF (via TTFunk)
+# 
+# ## Cmap
+#
+# Each TTFunk::Table::Cmap::Format<whatever> class responds to `:supported?`
+# with its own internal boolean telling us if that Format is usable in TTFunk.
+# This has nothing to do with any font file itself, just the library code.
+# irb(main)> font.cmap.tables.map{|t| t.supported?}
+# => [true, true, true]
+#
+# Any subclass of TTFunk::Table::Cmap::Subtable responds to `:unicode?`
+# with a boolean calculated from the instance `@platform_id` and `@encoding_id`,
+# and those numeric IDs are assigned to the symbolic (e.g. `:macroman`) names in:
+# https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+# irb(main)> font.cmap.tables.map{|t| t.unicode?}
+# => [true, false, true]
+#