distorted-floor 0.7.0

data/lib/distorted-floor/error_code.rb

@@ -0,0 +1,55 @@
+# https://ruby-doc.org/core/Exception.html sez:
+# "It is recommended that a library should have one subclass of StandardError
+# or RuntimeError and have specific exception types inherit from it.
+# This allows the user to rescue a generic exception type to catch
+# all exceptions the library may raise even if future versions of
+# the library add new exception subclasses."
+class DistorteDError < StandardError; end
+
+# Normal "File not found" errors are platform-specific, in the Errno module,
+# so define our own generic one for DD:
+# https://ruby-doc.org/core/IOError.html
+# https://ruby-doc.org/core/Errno.html
+class DistorteDFileNotFoundError < DistorteDError; end
+
+# The built-in NotImplementedError is for "when a feature is not implemented
+# on the current platform", so make our own more appropriate ones.
+class MediaTypeNotImplementedError < DistorteDError
+  attr_reader :name
+  def initialize(name)
+    super
+    @name = name
+  end
+
+  def message
+    "No supported media type for #{name}"
+  end
+end
+
+class MediaTypeOutputNotImplementedError < MediaTypeNotImplementedError
+  attr_reader :type, :context
+  def initialize(name, type, context)
+    super(name)
+    @type = type
+    @context = context
+  end
+
+  def message
+    "Unable to save #{name} as #{type.to_s} from #{context}"
+  end
+end
+
+class MediaTypeNotFoundError < DistorteDError
+  attr_reader :name
+  def initialize(name)
+    super
+    @name = name
+  end
+
+  def message
+    "Failed to detect media type for #{name}"
+  end
+end
+
+
+class OutOfDateLibraryError < LoadError; end

data/lib/distorted-floor/floor.rb

@@ -0,0 +1,17 @@
+
+require 'set'
+require 'distorted-floor/monkey_business/set'
+
+require 'distorted-floor/invoker'
+require 'distorted-floor/click_again'
+require 'distorted-floor/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-floor/invoker.rb

@@ -0,0 +1,100 @@
+
+# Our custom Exceptions
+require 'distorted-floor/error_code'
+
+# File Typer
+require 'distorted-floor/checking_you_out'
+using ::DistorteD::CHECKING::YOU::OUT
+require 'distorted-floor/media_molecule'
+
+# Set.to_hash
+require 'distorted-floor/monkey_business/set'
+require 'set'
+
+Cooltrainer::DistorteD::GEM_ROOT = File.expand_path(File.join(__dir__, '..'.freeze, '..'.freeze))
+
+module Cooltrainer::DistorteD::Invoker
+  # Returns a Hash[CHECKING::YOU::OUT] => 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[CHECKING::YOU::OUT] => 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 `::CHECKING::YOU::OUT` objects common to the source file and our supported MediaMolecules.
+  # Each of these Molecules will be plugged to the current instance.
+  def type_mars
+    # TODO: Get rid of the redundant `Set[…].flatten` here once I stabilize CYO API.
+    @type_mars ||= Set[::CHECKING::YOU::OUT(path)].flatten & lower_world.keys.to_set
+    raise MediaTypeNotImplementedError.new(@name) if @type_mars.empty?
+    @type_mars
+  end
+
+  # MediaMolecule file-type plugger.
+  # Any call to a ::CHECKING::YOU::OUT'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 ::CHECKING::YOU::OUT::distorted_method_prefixes.values.map(&:to_s).include?(meth.to_s.split(::CHECKING::YOU::OUT::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(::CHECKING::YOU::OUT::type_separators)
+    ::CHECKING::YOU::OUT::distorted_method_prefixes.values.map(&:to_s).include?(parts[0]) && parts.length > 2 || super(meth, *a)
+  end
+
+end

data/lib/distorted-floor/media_molecule/font.rb

@@ -0,0 +1,200 @@
+require 'set'
+
+# Font metadata extraction
+require 'ttfunk'
+
+require 'distorted-floor/modular_technology/pango'
+require 'distorted-floor/modular_technology/ttfunk'
+require 'distorted-floor/modular_technology/vips/save'
+require 'distorted-floor/checking_you_out'
+using ::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::OUT::from_ietf_media_type('font/ttf') => nil,
+  }
+  OUTER_LIMITS = {
+    ::CHECKING::YOU::OUT::from_ietf_media_type('font/ttf') => nil,
+  }
+
+  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(change)
+    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 change.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(change)
+    # 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(change),
+      **{
+        # 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 => change.dpi&.to_i,
+      },
+    )
+  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]
+# 

data/lib/distorted-floor/media_molecule/image.rb

@@ -0,0 +1,33 @@
+
+require 'set'
+
+require 'distorted-floor/checking_you_out'
+require 'distorted-floor/modular_technology/vips'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::Image
+
+
+  # Attributes for our <picture>/<img>.
+  # Automatically enabled as attrs for DD Liquid Tag.
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#Attributes
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#Attributes
+  # https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading
+  ATTRIBUTES = Set[:alt, :caption, :href, :loading]
+
+  # Defaults for HTML Element attributes.
+  # Not every attr has to be listed here.
+  # Many need no default and just won't render.
+  ATTRIBUTES_DEFAULT = {
+    :loading => :eager,
+  }
+  ATTRIBUTES_VALUES = {
+    :loading => Set[:eager, :lazy],
+  }
+
+  include Cooltrainer::DistorteD::Technology::Vips
+
+end  # Image

data/lib/distorted-floor/media_molecule/pdf.rb

@@ -0,0 +1,45 @@
+require 'set'
+
+require 'hexapdf'
+
+require 'distorted-floor/checking_you_out'
+using ::DistorteD::CHECKING::YOU::OUT
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::PDF
+
+
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/index.html#method-c-new
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/index.html#DefaultDocumentConfiguration
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Task/Optimize.html
+  PDF_TYPE = ::CHECKING::YOU::OUT::from_ietf_media_type('application/pdf')
+  LOWER_WORLD = Hash[
+    PDF_TYPE => nil,
+  ]
+  OUTER_LIMITS = Hash[
+    PDF_TYPE => nil,
+  ]
+
+  # TODO: Use MuPDF instead of libvips magick-based PDF loader.
+
+  def self.optimize(src, dest)
+    HexaPDF::Document.open(src) do |doc|
+      doc.task(
+        :optimize,
+        compact: true,
+        object_streams: :generate,
+        xref_streams: :generate,
+        compress_pages: false,
+      )
+      doc.write(dest)
+    end
+  end
+
+  define_method(PDF_TYPE.distorted_file_method) { |dest_root, change|
+    copy_file(change.paths(dest_root).first)
+  }
+
+end  # PDF

data/lib/distorted-floor/media_molecule/svg.rb

@@ -0,0 +1,46 @@
+require 'set'
+
+require 'svg_optimizer'  # https://github.com/fnando/svg_optimizer
+
+require 'distorted-floor/checking_you_out'
+using ::DistorteD::CHECKING::YOU::OUT
+require 'distorted-floor/modular_technology/vips/save'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::SVG
+
+  include Cooltrainer::DistorteD::Technology::Vips::Save
+
+  SVG_TYPE = ::CHECKING::YOU::OUT::from_ietf_media_type('image/svg+xml')
+
+  LOWER_WORLD = Hash[
+    SVG_TYPE => Cooltrainer::DistorteD::Technology::Vips::VipsType::loader_for(SVG_TYPE).map(&:options).reduce(&:merge)
+  ].merge(Hash[
+    :optimize => Cooltrainer::Compound.new(:optimize, valid: Cooltrainer::BOOLEAN_VALUES, default: false, blurb: 'SvgOptimizer'),
+  ])
+
+  # WISHLIST: Support VML for old IE compatibility.
+  #  Example: RaphaëlJS — https://en.wikipedia.org/wiki/Rapha%C3%ABl_(JavaScript_library)
+  OUTER_LIMITS = Hash[
+    SVG_TYPE => nil,
+  ]
+
+  def to_vips_image(change = nil)
+    # NOTE: libvips 8.9 added the `unlimited` argument to svgload.
+    # Loading SVGs >= 10MiB in size will fail on older libvips.
+    # https://github.com/libvips/libvips/commit/55e49831b801e05ddd974b1e2102fda7956c53f5
+    @vips_image ||= Vips::Image.new_from_file(path)
+  end
+
+  define_method(SVG_TYPE.distorted_file_method) { |dest_root, change|
+    if change.optimize
+      SvgOptimizer.optimize_file(path, change.paths(dest_root).first, SvgOptimizer::DEFAULT_PLUGINS)
+    else
+      copy_file(change.paths(dest_root).first)
+    end
+  }
+
+end