distorted 0.5.4 → 0.7.0

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

@@ -0,0 +1,219 @@
+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
+
+    # 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:
+      # https://rubystyle.guide/#snake-case-symbols-methods-vars
+      #
+      # For the worst possible example, an intended outout Type of
+      # "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+      # (a.k.a. a MSWord `docx` file) would map to a DistorteD saver method
+      # :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.
+      "#{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, 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
+        # many Set comparisons, so I am going to return a Set here
+        # and possibly throw the order away.
+        # In my experience the order is usually preserved anyway:
+        # irb(main)> MIME::Types.type_for(File.expand_path('lol.ttf'))
+        # => [#<MIME::Type: font/ttf>, #<MIME::Type: application/font-sfnt>, #<MIME::Type: application/x-font-truetype>, #<MIME::Type: application/x-font-ttf>]
+        # 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
+      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).
+        FileMagic.open(:mime) do |fm|
+          # The second argument makes fm.file return just the simple
+          # MIME::Type String, e.g.:
+          #
+          # irb(main)>   fm.file('/home/okeeblow/IIDX-turntable.svg')
+          # => "image/svg+xml; charset=us-ascii"
+          # irb(main)>   fm.file('/home/okeeblow/IIDX-turntable.svg', true)
+          # => "image/svg"
+          #
+          # However MIME::Types won't take short variants like 'image/svg',
+          # so explicitly have FM return long types and split it ourself
+          # on the semicolon:
+          #
+          # 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  # 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(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
+    end
+
+    # Returns a loaded MIME::Types container containing both the upstream
+    # mime-types-data and our own local data.
+    def self.types_loader
+      container = MIME::Types.new
+
+      # 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__, '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.
+      # MAYBE: Integrate MIME::Types YAML conversion scripts and commit
+      # JSON/Columnar artifacts for SPEEEEEED, but YAML is probably fine
+      # since we will have so few custom types compared to upstream.
+      # Convert.from_yaml_to_json
+      # Convert::Columnar.from_yaml_to_columnar
+      loader.load_yaml
+
+      container
+    end
+
+  end
+end

data/lib/distorted/checking_you_out/README

@@ -0,0 +1,4 @@
+# Some of these custom MIME::Types will be just for DD, but
+# I will submit some others of these to the mime-types-data project
+# if and when it makes sense to do so. Here's how:
+# https://github.com/mime-types/mime-types-data/blob/master/Contributing.md

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/font.yaml

@@ -0,0 +1,29 @@
+
+# RFC8081 defines the top-level `font` media-type and includes
+# definitions for font/ttf, font/otf, and font/collection,
+# but neglects to include the OpenType Collection (.otc)
+# file extension, meaning the IANA DB's font/collection
+# only covers TTC and not OTC:
+# 
+# https://tools.ietf.org/html/rfc8081#section-4.4.4
+# "Type name:  font
+#   Subtype name:  collection
+#   Required parameters:  None
+#   Optional parameters
+#      Name: outlines
+#      Values: a comma-separated subset of TTF, CFF, and SVG
+#
+# https://docs.microsoft.com/en-us/typography/opentype/spec/otff
+# "OpenType fonts may have the extension .OTF, .TTF, .OTC or .TTC.
+# The extensions .OTC and .TTC should only be used for font collection files."
+- !ruby/object:MIME::Type
+  content-type: font/collection
+  encoding: base64
+  extensions:
+  - otc
+  xrefs:
+    template:
+    - font/collection
+  xref_urls:
+    - "https://docs.microsoft.com/en-us/typography/opentype/spec/otff#filenames"
+  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