distorted 0.5.4 → 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/error_code.rb

@@ -0,0 +1,51 @@
+# 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 StandardDistorteDError < StandardError
+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 < StandardDistorteDError
+  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 < StandardDistorteDError
+  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.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