distorted 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a96a3b49df5a194c2d18bae2a71d208e02aaad05c6af3eb5399c0f5c87167bd0
-  data.tar.gz: 7260d18a57ab0a14008bb92712c9dec322c5be4469329a656d5ef287c09e52bf
+  metadata.gz: 14d224830d6e35072b97427b9a07d8a97061510259c7fa94be189509e52cf453
+  data.tar.gz: 724f0479db6c93ec9f00cfae008524fb51cd519db0865915bd3f7e11f97eec77
 SHA512:
-  metadata.gz: e290cb8d83991ad9391bf3cfd1c495142692af34b3ff424da78be54439e85f38507612df20814d5cb98e935db20ea970095a6890ca3291a6d3e0e6805948d928
-  data.tar.gz: a5388b7db8e91e16ad74080295882ad9bf106257c062ad0b54fdd60813c6300073ec25a1c031f8356c0f4b46dae3150e3bbf14a9c32466faaa848b2c8b10e445
+  metadata.gz: 82886187c077e5f61cf976546ea2c15e77f5b3dabc79a69071b78e0153f69a6f9a41250d4ea3a2deb66e5caea67c8f5abeb41ef7ff2b6f50af171d3e2232c821
+  data.tar.gz: b2f17ab2f0807cc067bbb035c0bbe559e8e3df30cbd2e29feb27d79784fcadbb035ec9016b785dc29ace3ebc234c81b71a7b6879de0c0ed76b6956bcb90f128d

data/README.md

@@ -1,6 +1,6 @@
 # Cooltrainer::DistorteD
 
-`DistorteD-Ruby` is the core file-handling code for `DistorteD-Jekyll`.
+`DistorteD-Floor` is the core file-handling code for `DistorteD-Jekyll`.
 
 ## Installation
 
@@ -24,7 +24,7 @@ Or install it yourself as:
 Clone the DistorteD repository and modify your Jekyll `Gemfile` to refer to your local path instead of to the newest published version of the gem:
 
 ```
-gem 'distorted', :path => '~/repos/DistorteD/DistorteD-Ruby/'[, :branch => 'NEW-SENSATION']
+gem 'distorted', :path => '~/repos/DistorteD/DistorteD-Floor/'[, :branch => 'NEW-SENSATION']
 ```
 
 ## License

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "distorted"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/distorted

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'distorted/click_again'
+
+click = Cooltrainer::DistorteD::ClickAgain.new(ARGV, File.basename(__FILE__))
+click.write(Dir.pwd)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/distorted.rb

@@ -0,0 +1,2 @@
+#TODO: Genericize Ruby version-checking and use it here to require 2.7+
+require 'distorted/invoker'

data/lib/distorted/checking_you_out.rb

@@ -1,12 +1,83 @@
 require 'set'
 
+# CYO encapsulate all concepts related to media file identification for DistorteD!
+
+# General media type resources:
+# https://www.iana.org/assignments/media-types/media-types.xhtml
+
+
+# The Gem `ruby-mime-types` and its associated `mime-types-data` provide our core classes:
+# https://github.com/mime-types/ruby-mime-types
 require 'mime/types'
+#
+# - Its MIME Types database ensures I don't have to constantly update DD with
+#   new filetypes as they are invented, like how AVIF is still currently brand-new as of 2021.
+# - Our main Type search method — :OUT() — wraps `MIME::Types.type_for`/`MIME::Types[]`
+#   to identify media types based on filename alone (e.g. even for hypothetical files).
+# - The Object we give callers will be a `MIME::Type`, not anything wrapped/renamed.
+# - I use its Loader class and YAML structure to ship additional Type definitions local to DD.
+#
+# NOTE: Type objects returned from the unwrapped MIME::Types interfaces will not have equality
+#       with instances of the same media type from CYO! This is because we load our own database.
+#   irb(main)> MIME::Types['image/jpeg'].object_id
+#   => 136400
+#   irb(main)> CHECKING::YOU::OUT['image/jpeg'].object_id
+#   => 90800
+
+
+# The Gem `ruby-filemagic` provides the ability to inspect the magic bytes of actual on-disk files.
+# https://github.com/blackwinter/ruby-filemagic
+# http://blackwinter.github.io/ruby-filemagic/
+#
+# NOTE: Unmaintained!
+# https://github.com/blackwinter/ruby-filemagic/commit/e1f2efd07da4130484f06f58fed016d9eddb4818
+#
+# Might consider replacing this with an FFI filemagic to eliminate the native-code compilation.
+# https://rubygems.org/gems/glongman-ffiruby-filemagic/
+# https://stuart.com/blog/ruby-bindings-extensions/
 require 'ruby-filemagic'
 
+
+# Monkey-patch some DistorteD-specific methods into MIME::Type objects.
 module MIME
   class Type
-    # Give MIME::Type objects an easy way to get the DistorteD saver method name.
-    def distorted_method
+
+    # Provide a few variations on the base :distorted_method for mixed workflows
+    # where it isn't feasible to overload a single method name and call :super.
+    # Jekyll, for example, renders its output markup upfront, collects all of
+    # the StaticFiles (or StaticStatic-includers, in our case), then calls their
+    # :write methods all at once after the rest of the site is built,
+    # and this precludes us from easily sharing method names between layers.
+    DISTORTED_METHOD_PREFIXES = Hash[
+      :buffer => 'to'.freeze,
+      :file => 'write'.freeze,
+      :template => 'render'.freeze,
+    ]
+    SUB_TYPE_SEPARATORS = /[-_+\.]/
+
+    # Returns a Symbol name of the method that should return a String buffer containing the file in this Type.
+    def distorted_buffer_method; "#{DISTORTED_METHOD_PREFIXES[:buffer]}_#{distorted_method_suffix}".to_sym; end
+
+    # Returns a Symbol name of the method that should write a file of this Type to a given path on a filesystem.
+    def distorted_file_method; "#{DISTORTED_METHOD_PREFIXES[:file]}_#{distorted_method_suffix}".to_sym; end
+
+    # Returns a Symbol name of the method that should returns a context-appropriate Object
+    # for displaying the file as this Type.
+    # Might be e.g. a String buffer containing Rendered Liquid in Jekylland,
+    # or a Type-appropriate frame in some GUI toolkit in DD-Booth.
+    def distorted_template_method; "#{DISTORTED_METHOD_PREFIXES[:template]}_#{distorted_method_suffix}".to_sym; end
+
+    # Returns an Array[Array[String]] of human-readable keys we can use for our YAML config,
+    # e.g. :media_type 'image' & :sub_type 'svg+xml' would be split to ['image', 'svg'].
+    # `nil` `:sub_type`s will just be compacted out.
+    # Every non-nil :media_type will also request a key path [media_type, '*']
+    # to allow for similar-type defaults, e.g. every image type outputting a fallback.
+    def settings_paths; [[self.media_type, '*'.freeze], [self.media_type, self.sub_type&.split('+'.freeze)&.first].compact]; end
+
+    private
+
+    # Provide a consistent base method name for context-specific DistorteD operations.
+    def distorted_method_suffix
       # Standardize MIME::Types' media_type+sub_type to DistorteD method mapping
       # by replacing all the combining characters with underscores (snake case)
       # to match Ruby conventions:
@@ -18,20 +89,29 @@ module MIME
       # :to_application_vnd_openxmlformats_officedocument_wordprocessingml_document
       # which would most likely be defined by the :included method of a library-specific
       # module for handling OpenXML MS Office documents.
-      "to_#{self.media_type}_#{self.sub_type.gsub(/[-+\.]/, '_'.freeze)}".to_sym
-    end
+      "#{self.media_type}_#{self.sub_type.gsub(SUB_TYPE_SEPARATORS, '_'.freeze)}"
+    end  # distorted_method_suffix
   end
 end
 
+
 module CHECKING
   class YOU
 
+    # Returns a single Type with Array-style access.
+    class OUT
+      def self.[](type)
+        CHECKING::YOU::types[type].first
+      end
+    end
+
     # Returns a Set of MIME::Type for a given file path, by default only
     # based on the file extension. If the file extension is unavailable—
     # or if `so_deep` is enabled—the `path` will be used as an actual
     # path to look at the magic bytes with ruby-filemagic.
-    def self.OUT(path, so_deep: false)
-      unless so_deep || types.type_for(path).empty?
+    def self.OUT(path, so_deep: false, only_one_test: false)
+      return Set[] if path.nil?
+      if not (only_one_test || types.type_for(path).empty?)
         # NOTE: `type_for`'s return order is supposed to be deterministic:
         # https://github.com/mime-types/ruby-mime-types/issues/148
         # My use case so far has never required order but has required
@@ -43,7 +123,7 @@ module CHECKING
         # irb(main)> MIME::Types.type_for('lol.ttf')).to_set
         # => #<Set: {#<MIME::Type: font/ttf>, #<MIME::Type: application/font-sfnt>, #<MIME::Type: application/x-font-truetype>, #<MIME::Type: application/x-font-ttf>}>
         return types.type_for(path).to_set
-      else
+      elsif (so_deep && path[0] != '.'.freeze)  # Support taking hypothetical file extensions (e.g. '.jpg') without stat()ing anything.
         # Did we fail to guess any MIME::Types from the given filename?
         # We're going to have to look at the actual file
         # (or at least its first four bytes).
@@ -63,18 +143,31 @@ module CHECKING
           # irb(main)> "image/svg+xml; charset=us-ascii".split(';').first
           # => "image/svg+xml"
           mime = types[fm.file(path, false).split(';'.freeze).first].to_set
-        end
-      end
-    end
+        end  # FileMagic.open
+      else
+        # TODO: Warn here that we may need a custom type!
+        #p "NO MATCH FOR #{path}"
+        Set[]
+      end  # if
+    end  # self.OUT()
 
     # Returns a Set of MIME::Type objects matching a String search key of the
     # format MEDIA_TYPE/SUB_TYPE.
     # This can return multiple Types, e.g. 'font/collection' TTC/OTC variations:
     # [#<MIME::Type: font/collection>, #<MIME::Type: font/collection>]
-    def self.IN(type)
-      types[type, :complete => type.is_a?(Regexp)].to_set
+    def self.IN(wanted_type_or_types)
+      if wanted_type_or_types.is_a?(Enumerable)
+        # Support taking a list of String types for Molecules whose Type support
+        # isn't easily expressable as a single Regexp.
+        types.select{ |type| wanted_type_or_types.include?(type.to_s) }
+      else
+        # Might be a single String or Regexp
+        types[wanted_type_or_types, :complete => wanted_type_or_types.is_a?(Regexp)].to_set
+      end
     end
 
+    protected
+
     # Returns the MIME::Types container or loads one
     def self.types
       @@types ||= types_loader
@@ -88,17 +181,27 @@ module CHECKING
       # Load the upstream mime-types-data by providing a nil `path`:
       # path || ENV['RUBY_MIME_TYPES_DATA'] || MIME::Types::Data::PATH
       loader = MIME::Types::Loader.new(nil, container)
+      # TODO: Log this once I figure out a nice way to wrap Jekyll logger too.
+      #   irb> loader.load_columnar => #<MIME::Types: 2277 variants, 1195 extensions>
       loader.load_columnar
 
       # Change default JPEG file extension from .jpeg to .jpg
       # because it pisses me off lol
       container['image/jpeg'].last.preferred_extension = 'jpg'
 
+      # Add a missing extension to MPEG-DASH manifests:
+      #   irb> MIME::Types['application/dash+xml'].first
+      #   => #<MIME::Type: application/dash+xml>
+      #   irb> MIME::Types['application/dash+xml'].first.preferred_extension
+      #   => nil
+      # https://www.iana.org/assignments/media-types/application/dash+xml
+      container['application/dash+xml'].last.preferred_extension = 'mpd'
+
       # Override the loader's path with the path to our local data directory
       # after we've loaded the upstream data.
       # :@path is set up in Loader::initialize and only has an attr_reader
       # but we can reach in and change it.
-      loader.instance_variable_set(:@path, File.join(__dir__, 'types'.freeze))
+      loader.instance_variable_set(:@path, File.join(__dir__, 'checking_you_out'.freeze))
 
       # Load our local types data. The YAML files are separated by type,
       # and :load_yaml will load all of them in the :@path we just set.

data/lib/distorted/checking_you_out/application.yaml

@@ -0,0 +1,33 @@
+# Define our own type to trigger fallback copy instead of abusing application/x-imagemap :)
+- !ruby/object:MIME::Type
+  content-type: application/x.distorted.never-let-you-down
+  xrefs:
+    person:
+      - okeeblow
+  registered: false
+
+
+# MATLAB files supported by VIPS Magick foreign loader.
+- !ruby/object:MIME::Type
+  content-type: application/x-matlab-data
+  encoding: 8bit
+  extensions:
+    - mat
+  xrefs_urls:
+    - "http://justsolve.archiveteam.org/wiki/MAT"
+  registered: false
+
+
+# Microsoft SilverLight multiple-zoom tiled-raster image archive formats.
+# I made this content-type up based on the convention of other 'vnd.microsoft' Types,
+# e.g. #<MIME::Type: application/vnd.microsoft.windows.thumbnail-cache>
+- !ruby/object:MIME::Type
+  content-type: application/vnd.microsoft.deep-zoom
+  extensions:
+    - dz
+    - dzi
+    - dzc
+    - xml
+  xrefs_urls:
+    - "http://msdn.microsoft.com/en-us/library/cc645077(VS.95).aspx"
+  registered: false

data/lib/distorted/checking_you_out/image.yaml

@@ -0,0 +1,108 @@
+# Define our own type to trigger a legacy <img> element src for <picture>
+- !ruby/object:MIME::Type
+  content-type: image/x.distorted.fallback
+  xrefs:
+    person:
+      - okeeblow
+  registered: false
+
+
+# libvips' internal format, unlikely to be used but may as well be supported :)
+- !ruby/object:MIME::Type
+  content-type: image/vips
+  extensions:
+    - v
+    - vips
+  xrefs_urls:
+    - "http://fileformats.archiveteam.org/wiki/VIPS"
+  registered: false
+
+
+# OpenEXR stuff
+- !ruby/object:MIME::Type
+  content-type:  image/x-exr
+  extensions:
+    - exr
+  xrefs_urls:
+    - "https://www.nationalarchives.gov.uk/PRONOM/fmt/1001"
+    - "https://en.wikipedia.org/wiki/OpenEXR"
+    - "http://fileformats.archiveteam.org/wiki/OpenEXR"
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.radiance
+  extensions:
+    - hdr
+  xrefs_urls:
+    - "https://en.wikipedia.org/wiki/RGBE_image_format"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/fits
+  extensions:
+    - fits
+    - fit
+    - fts
+  xrefs_urls:
+    - "https://www.iana.org/assignments/media-types/image/fits"
+    - "https://www.cv.nrao.edu/fits/"
+  registered: true
+
+# End OpenEXR stuff
+
+
+# OpenSlide stuff — https://openslide.org/formats/
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.scanscope.virtual.slide
+  extensions:
+    - svs  # Excluding tiff since that has a generic entry.
+  xrefs_urls:
+    - "https://openslide.org/formats/aperio/"
+    - "https://docs.openmicroscopy.org/bio-formats/latest/formats/aperio-svs-tiff.html"
+    - "http://justsolve.archiveteam.org/wiki/Aperio_SVS"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.hamamatsu
+  extensions:
+    - vms
+    - vmu
+    - ndpi
+  xrefs_urls:
+    - "https://openslide.org/formats/hamamatsu/"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.sakura
+  extensions:
+    - svslide
+  xrefs_urls:
+    - "https://openslide.org/formats/sakura/"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.mirax
+  extensions:
+    - mrxs 
+  xrefs_urls:
+    - "https://openslide.org/formats/mirax/"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.leica
+  extensions:
+    - scn
+  xrefs_urls:
+    - "https://openslide.org/formats/leica/"
+  registered: false
+
+- !ruby/object:MIME::Type
+  content-type:  image/vnd.ventana
+  extensions:
+    - bif
+  xrefs_urls:
+    - "https://openslide.org/formats/ventana/"
+  registered: false
+
+
+# End OpenSlide stuff

data/lib/distorted/click_again.rb

@@ -0,0 +1,333 @@
+require 'set'
+require 'distorted/monkey_business/set'
+
+require 'optparse'
+require 'shellwords'  # Necessary for inclusion in OptionParser coercions list.
+
+require 'distorted/invoker'
+require 'distorted/checking_you_out'
+require 'distorted/element_of_media/compound'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+
+class Cooltrainer::DistorteD::ClickAgain
+
+  include Cooltrainer::DistorteD::Invoker  # MediaMolecule plugger
+
+  attr_reader :global_options, :lower_options, :outer_options
+
+
+  # Set up and parse a given Array of command-line switches based on
+  # our global OptionParser and its Type/Molecule-specific sub-commands.
+  #
+  # :argv will be operated on destructively!
+  # Consider passing a duplicate of ARGV instead of passing it directly.
+  def initialize(argv, exe_name)
+
+    # Partition argv into (switches and their arguments) and (filenames or wanted type Strings)
+    switches, @get_out = partition_argv(argv)
+
+    # Initialize Hashes to store our three types of Options using a small
+    # custom subclass that will store items as a Set but won't store :nil alone.
+    @global_options = Hash.new { |h,k| h[k] = h.class.new(&h.default_proc) }
+    @lower_options = Hash.new { |h,k| h[k] = h.class.new(&h.default_proc) }
+    @outer_options = Hash.new { |h,k| h[k] = h.class.new(&h.default_proc) }
+    # Temporary Array for unmatched Switches when parsing subcommands.
+    sorry_try_again = Array.new
+
+    # Pass our executable name in for the global OptionParser's banner String,
+    # then parse the complete/raw user-given-arguments-list first with this Parser.
+    #
+    # I am intentionally using OptionParser's non-POSIXy :permute! method
+    # instead of the POSIX-compatible :order! method,
+    # because I want to :)
+    # Otherwise users would have to define all switch arguments
+    # ahead of all positional arguments in the command,
+    # and I think that would be frustrating and silly.
+    #
+    # In strictly-POSIX mode, one would have to call e.g.
+    #   `distorted -o image/png inputfile.webp outfilewithnofileextension`
+    # instead of
+    #   `distorted inputfile.webp -o image/png outfilewithnofileextension`,
+    # which I find to be much more intuitive.
+    #
+    # Note that `:parse!` would call one of the other of :order!/:permute! based on
+    # an invironment variable `POSIXLY_CORRECT`. Talk about a footgun!
+    # Be explicit!!
+    global = global_options(exe_name)
+    begin
+      switches = global.permute!(switches, into: @global_options)
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::ParseError => nope
+      nope.recover(sorry_try_again)  # Will :unshift the :nope value to the recovery Array.
+      #if switches&.first&.chr == '-'.freeze
+      #  sorry_try_again.unshift(switches.shift)
+      #end
+      retry
+    end
+    switches.unshift(*sorry_try_again.reverse)
+
+    # The global OptionParser#permute! call will strip our `:argv` Array of
+    # any `--help` or Molecule-picking switches.
+    # Molecule-specific switches (both 'lower' and 'outer') and positional
+    # file-name arguments remain.
+    #
+    # The first remaining `argv` will be our input filename if one was given!
+    #
+    # NOTE: Never assume this filename will be a complete, absolute, usable path.
+    # POSIX shells do not do tilde expansion, for example, on quoted switch arguments,
+    # so a quoted filename argument '~/cover.png' will come through to Ruby-land
+    # as the literal String '~/cover.png' while the same filename argument sans-quotes
+    # will be expanded to e.g. '/home/okeeblow/cover.png' (based on `$HOME` env var).
+    # Additional Ruby-side path validation will almost certainly be needed!
+    # https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_01
+    @name = @get_out&.shift
+
+    # Print some sort of help message or list of supported input/output Types
+    # if no source filename was given.
+    unless @name 
+      puts case
+      when @global_options.has_key?(:help) then global
+      when @global_options.has_key?(:"lower-world")
+        "Supported input media types:\n#{lower_world.keys.join("\n")}"
+      when @global_options.has_key?(:"outer-limits")
+        "Supported output media types:\n#{outer_limits(all: true).values.map{|m| m.keys}.join("\n")}"
+      else global
+      end
+      exit
+    end
+
+    # Here's that additional filename validation I was talking about.
+    # I don't do this as a one-shot with the argv.shift because
+    # File::expand_path raises an error on :nil argument,
+    # and we already checked for that when we checked for 'help' switches.
+    @name = File.expand_path(@name)
+
+    # Check for 'help' switches *again* now that we have a source file path,
+    # because the output can be file-specific instead of generic.
+    # This is where we display subcommands' help!
+    specific_help = case
+    when @get_out.empty?
+      # Only input filename given; no outputs; nothing left to do!
+      lower_subcommands.merge(outer_subcommands).values.unshift(Hash[:DistorteD => [global]]).map { |l|
+        l.values.join("\n")
+      }.join("\n")
+    when @global_options.has_key?(:help), @global_options.has_key?(:"lower-world")
+      lower_subcommands.values.map { |l|
+        l.values.join("\n")
+      }.join("\n")
+    when @global_options.has_key?(:"outer-limits")
+      # Trigger this help message on `-o` iff that switch is used bare.
+      # If `-o` is given an argument it will inform the MIME::Type
+      # of the same-index output file, e.g.
+      # `-o image/png -o image/webp pngnoextension webpnoextension`
+      # will work exactly as that example implies.
+      @global_options.dig(:"outer-limits")&.empty? ?
+      outer_subcommands.values.map { |o|
+        o.values.join("\n")
+      }.join("\n") : nil
+    else nil
+    end
+    if specific_help
+      puts specific_help
+      exit
+    end
+
+    # Our "subcommands" are additional instances of OptionParser,
+    # one for every MediaMolecule that can load the source file,
+    # and one for every intended output variation.
+    lower_subcommands.each_pair { |type, molecule_commands|
+      molecule_commands.each_pair { |molecule, subcommand|
+        begin
+          switches = subcommand.permute!(switches, into: @lower_options[type][molecule])
+        rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::ParseError => nope
+          nope.recover(sorry_try_again)  # Will :unshift the :nope value to the recovery Array.
+          retry
+        end
+        switches.unshift(*sorry_try_again.reverse)
+        @lower_options[type][molecule].store(:molecule, molecule)
+      }
+    }
+    outer_subcommands.each_pair { |molecule, type_commands|
+      type_commands.each_pair { |type, subcommand|
+        begin
+          switches = subcommand.permute!(switches, into: @outer_options[molecule][type])
+        rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::ParseError => nope
+          nope.recover(sorry_try_again)  # Will :unshift the :nope value to the recovery Array.
+          retry
+        end
+        switches.unshift(*sorry_try_again.reverse)
+        @outer_options[molecule][type].store(:molecule, molecule)
+      }
+    }
+  end
+
+  # Writes all intended output files to a given directory.
+  def write(dest_root)
+    changes.each { |change|
+      if self.respond_to?(change.type.distorted_file_method)
+        # WISHLIST: Remove the empty final positional Hash argument once we require a Ruby version
+        # that will not perform the implicit Change-to-Hash conversion due to Change's
+        # implementation of :to_hash. Ruby 2.7 will complain but still do the conversion,
+        # breaking downstream callers that want a Struct they can call arbitrary key methods on.
+        # https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+        self.send(change.type.distorted_file_method, dest_root, change, **{})
+      else
+        raise MediaTypeOutputNotImplementedError.new(change.name, change.type, self.class.name)
+      end
+    }
+  end
+
+  private
+
+  # Partitions the raw `argv` into two buckets — outer_limits (String relative filenames or "media/type" Strings) and switches/arguments.
+  #
+  # References:
+  # - glibc Program Argument Syntax Conventions https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
+  # - POSIX Utility Argument Syntax https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_01
+  # - Windows Command-line syntax key https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/command-line-syntax-key
+  #
+  # The filenames will be used as the source file (first member) and destination file(s) (any others).
+  # The switches/arguments will be passed to our global OptionParser's `:parse_in_order`
+  # which will return the unused remainder.
+  #
+  # I think it should be possible to achieve this same effect with our global OptionParser alone
+  # by specifying two required NoArgument Switches (source and first destination filename),
+  # specifying multiple optional NoArgument Switches (additional destinations),
+  # and parsing the unmodified `:argv` in permutation mode.
+  # I can't figure out how to wrangle OptionParser into doing that rn tho so welp here we are.
+  #
+  # There is a built-in Enumeraable#partition, but:
+  # - It doesn't take an accumulator variable natively.
+  # - I'm bad at chaining Enumerators and idk how to chain in a `:with_object` without returning only that object.
+  # - `:with_object` treats scalar types as immutable which precludes cleanly passing a boolean flag variable between iterations.
+  def partition_argv(argv)
+    switches, @get_out = argv.each_with_object(
+      # Accumulate to a three-key Hash containing the two wanted buckets and the flag that will be discarded.
+      Hash[:switches => Array.new, :get_out => Array.new, :want_value => false]
+    ) { |arg, partition|
+      # Switches and their values will be:
+      # - Any argument beginning with a single dash, e.g. long switches like '--crop' or short switches like '-Q90'.
+      # - Any non-dash argument if :want_value is flagged, e.g. the 'attention' value for the '--crop' switch.
+      # Filenames will be:
+      # - Anything else :)
+      if partition.fetch(:want_value) and not arg[0] == '-'.freeze
+        # `ARGV` Strings are frozen, so we have to replace instead of directly concat
+        partition[:switches].push(partition[:switches].pop.yield_self { |last| "#{last}#{'='.freeze unless arg[0] == '='.freeze}#{arg}" })
+      else
+        partition[(arg[0] == '-'.freeze or partition.fetch(:want_value)) ? :switches : :get_out].push(arg)
+      end
+      # The *next* argument should be a value for this iteration's argument iff:
+      # - This iteration is a long switch with no included value,  e.g. '--crop' but not '--crop=attention'.
+      # - This iteration is a short switch with no included value, e.g. '-Q' but not '-Q90' or '-Q=90'.
+      partition.store(:want_value, [
+        arg[0] == '-'.freeze,                           # e.g. '--crop' or '-Q'
+        !arg.include?('='.freeze),                      # e.g. not '--crop=attention' or '-Q=90'
+        [
+          arg[1] == '-'.freeze,                         # e.g. '--crop'
+          [arg[1] == '-'.freeze, arg.length > 2].none?  # e.g. not '-Q90'
+        ].any?
+      ].all?)
+    }.values.select(&Array.method(:===))  # Return only the Array members of the Hash
+  end
+
+  # Generic top-level OptionParser
+  def global_options(exe_name)
+    OptionParser.new do |opts|
+      opts.banner = "Usage: #{exe_name} [OPTION]… SOURCE DEST [DEST]…"
+      opts.on_tail('-h', '--help', 'Show this message')
+      opts.on('-v', '--[no-]verbose', 'Run verbosely')
+      opts.on('-l', '--lower-world', 'Show supported input media types')
+      opts.on('-o', '--outer-limits', 'Show supported output media types')
+    end
+  end
+
+  # Returns an Array[Change] for every intended output variation.
+  def changes
+    @changes ||= begin
+      # TODO: Consume @lower_options as well, and figure out how to specify Molecule
+      # for future situations where multiple Molecules may overlap.
+      # Until then, just collapse @outer_options to one Hash and take anything we find for our Type.
+      combined_outer_options = @outer_options.each_with_object(Array.new) { |(molecule,type_options),combined| combined.push(type_options) }.reduce(&:merge)
+      @get_out.each_with_object(Array[]) { |out, wanted|
+        # TODO: Nice way to check format for Type string here.
+        # Should be e.g. "image/png"
+        if CHECKING::YOU::OUT[out].nil?
+          name = out
+          type = CHECKING::YOU::OUT(out).first
+        else
+          name = @name
+          type = CHECKING::YOU::OUT[out]
+        end
+        wanted.push(Cooltrainer::Change.new(type, src: name, **(combined_outer_options.fetch(type, {}))))
+      }
+    end
+  end
+
+  # Returns an absolute String path to the source file.
+  def path
+    File.expand_path(@name)
+  end
+
+  # This is a CLI, so we always want to write new files when called.
+  def modified?
+    true
+  end
+
+  # And again.
+  def write?
+    true
+  end
+
+  # Generate an OptionParser for a flat Enumerable of Compounds
+  COMPOUND_OPTIONPARSER = Proc.new { |compounds, from, to|
+    OptionParser.new(banner = "#{from.to_s} ⟹   #{to.to_s}:") { |subopt|
+      compounds.map { |compound|
+        next if compound.nil?
+        parts = Array[
+          *compound.to_options,
+        ]
+        if compound.default == true
+          parts.append(TrueClass)
+        elsif compound.default == false
+          parts.append(FalseClass)
+        elsif compound.valid.is_a?(Range)
+          # TODO: decide how to handle Ranges that might be hundreds/thousands of items in length.
+        elsif compound.valid.is_a?(Enumerable)
+          parts.append(compound.valid.to_a)
+        elsif Cooltrainer::OPTIONPARSER_COERSIONS.include?(compound.valid.class)
+          parts.append(compound.valid)
+        end
+        parts.append(compound.blurb)
+        subopt.on(*parts)
+      }
+      subopt.on_tail('-h', '--help', 'Show this message')
+    }
+  }
+
+  # Generate a Hash[MIME::Type] => Hash[MediaMolecule] => OptionParser
+  # for file-specific input options.
+  def lower_subcommands
+    type_mars.each_with_object(Hash[]) { |type, commands|
+      lower_world[type].each_pair { |molecule, aka|
+        commands.update(type => {
+          molecule => COMPOUND_OPTIONPARSER.call(aka.values.to_set, type, molecule)
+        }) { |k,o,n| o.merge(n) }
+      }
+    }
+  end
+
+  # Generate a Hash[MediaMolecule] => Hash[MIME::Type] => OptionParser
+  # for file-specific output options.
+  def outer_subcommands(all: false)
+    outer_limits(all: all).each_with_object(Hash[]) { |(molecule, types), commands|
+      types.each_pair { |type, aka|
+        commands.update(molecule => {
+          type => COMPOUND_OPTIONPARSER.call(aka.values.to_set, molecule, type)
+        }) { |k,o,n| o.merge(n) }
+      }
+    }
+  end
+
+end