distorted 0.5.3 → 0.6.0

data/lib/distorted/checking_you_out.rb

@@ -0,0 +1,116 @@
+require 'set'
+
+require 'mime/types'
+require 'ruby-filemagic'
+
+module MIME
+  class Type
+    # Give MIME::Type objects an easy way to get the DistorteD saver method name.
+    def distorted_method
+      # 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.
+      "to_#{self.media_type}_#{self.sub_type.gsub(/[-+\.]/, '_'.freeze)}".to_sym
+    end
+  end
+end
+
+module CHECKING
+  class YOU
+
+    # 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?
+        # 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
+      else
+        # 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
+      end
+    end
+
+    # 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
+    end
+
+    # 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)
+      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'
+
+      # 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))
+
+      # 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/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/injection_of_love.rb

@@ -0,0 +1,247 @@
+require 'set'
+require 'distorted/monkey_business/set'
+
+
+# This Module supports Module "Piles"* in DistorteD by merging
+# an arbitrarily-deep nest of attribute-definition constants
+# into a single combined datastructure per constant at include-/
+# extend-/prepend-time.
+# [*] 'Monad' doesn't feel quite right, but http://www.geekculture.com/joyoftech/joyimages/469.gif
+#
+# The combined structures can be accessed in one shot and trusted as
+# a source of truth, versus inspecting Module::nesting or whatever
+# to iterate over the masked same-Symbol constants we'd get when
+# including/extending/prepending in Ruby normally:
+#   - https://ruby-doc.org/core/Module.html#method-c-nesting
+#   - http://valve.github.io/blog/2013/10/26/constant-resolution-in-ruby/
+
+# There's some general redundancy here with Bundler's const_get_safely:
+# https://ruby-doc.org/stdlib/libdoc/bundler/rdoc/Bundler/SharedHelpers.html#method-i-const_get_safely
+#
+# …but even though I use (and enjoy using) Bundler it feels Wrong™ to me to have
+# that method in stdlib and especially in Core but not as part of Module since
+# 'Bundler' still feels like a third-party namespace to me v(._. )v
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::InjectionOfLove
+
+  # These hold (possibly-runtime-generated) Sets of MIME::Types (from our loader)*
+  # describing any supported input media-types (:LOWER_WORLD)
+  # and any supported output media-types (:OUTER_LIMITS).
+  TYPE_CONSTANTS = Set[
+    :LOWER_WORLD,
+    :OUTER_LIMITS,
+  ]
+  # These hold Hashes or Sets describing supported attributes,
+  # supported attribute-values (otherwise freeform),
+  # attribute defaults if any, and mappings for any of those things
+  # to any aliased equivalents for normalization and localization.
+  ATTRIBUTE_CONSTANTS = Set[
+    :ATTRIBUTES,
+    :ATTRIBUTES_DEFAULT,
+    :ATTRIBUTES_VALUES,
+  ]
+  # 🄒  All of the above.
+  DISTORTED_CONSTANTS = Set[].merge(TYPE_CONSTANTS).merge(ATTRIBUTE_CONSTANTS)
+
+  # Name of our fully-merged-Hash's class variable.
+  AFTERPARTY = :@@DistorteD
+
+
+  # Activate this module when it's included.
+  # We will merge DistorteD attributes to the singleton class from
+  # our including context and from out including context's included_modules,
+  # then we will define methods in the including context to perpetuate
+  # the merging process when that context is included/extended/prepended.
+  def self.included(otra)
+    self::Injection_Of_Love.call(otra)
+    super
+  end
+
+  # "Attribute" fragments are processed in one additional step to support
+  # aliased/equivalent attribute names and values.
+  # This is a quality-of-life feature to help normalize/localize attributes
+  # defined in a wide range of places by multiple unrelated upstream devs.
+  #
+  # For example, libvips savers expect a single-character upper-case
+  # `Q` argument for their 1–100 integer quality factor,
+  # and my VipsSave module's `:ATTRIBUTES` additionally aliases it
+  # to the more typical `quality` to provide consistent UX
+  # with other attributes from VIPS and other sources.
+  # https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-jpegsave
+  #
+  # VIPS also provides our example of the need for attribute-value equivalents,
+  # such as how it only accepts the spelling of "centre" and not "center"
+  # like myself and many millions of other people will reflexively enter :)
+  # https://libvips.github.io/libvips/API/current/libvips-conversion.html#VipsInteresting
+  def self.so_deep(fragment)
+    fragment.each_with_object(Array[]) { |(attribute, raw), to_merge|
+      # Each attribute's :raw may be an object (probably a Symbol),
+      # a Set (e.g. of aliases), or nil (for all values in a Set.to_hash)
+      case raw
+        when Set then raw.add(attribute)
+        when NilClass then [attribute]
+        else [attribute]
+      end.each{ |equivalent|
+        to_merge << [equivalent, attribute]
+      }
+    }.to_h
+  end
+
+  # Returns a block that will define methods in a given context
+  # such that when the given context is included/extended/prepended
+  # we will also merge our DD attributes into the new layer.
+  Injection_Of_Love = Proc.new { |otra|
+    # These are the methods that actively perform the include/extend/prepend process.
+    [:append_features, :prepend_features, :extend_object].each { |m|
+      otra.define_singleton_method(m) do |winter|
+        # Perform the normal include/extend/prepend that will mask our constants.
+        super(winter)
+
+        # Get new values to override masked constants.
+        pile = Cooltrainer::DistorteD::InjectionOfLove::trip_machine(winter)
+
+        # Record each constant individually as well as the entire pile.
+        # This doesn't currently get used, as this :class_variable_set call
+        # is broken in KRI:
+        #  - https://bugs.ruby-lang.org/issues/7475
+        #  - https://bugs.ruby-lang.org/issues/8297
+        #  - https://bugs.ruby-lang.org/issues/11022
+        winter.singleton_class.class_variable_set(AFTERPARTY, pile)
+        pile.each_pair{ |k, v|
+          if winter.singleton_class.const_defined?(k, false)
+            # Since we are setting constants in the singleton_class
+            # we must remove any old ones first to avoid a warning.
+            winter.singleton_class.send(:remove_const, k)
+          end
+          winter.singleton_class.const_set(k, v)
+        }
+      end
+    }
+    # These are the callback methods called after the above methods fire.
+    # Use them to perpetuate our merge by calling the thing that calls us :)
+    [:included, :prepended, :extended].each { |m|
+      otra.define_singleton_method(m) do |winter|
+        Cooltrainer::DistorteD::InjectionOfLove::Injection_Of_Love.call(winter)
+        super(winter)
+      end
+    }
+  }
+
+  # Returns an instance-level copy of the complete attribute pile.
+  def trip_machine
+    @DistorteD ||= Cooltrainer::DistorteD::InjectionOfLove::trip_machine(self.singleton_class)
+  end
+
+  # Builds the attribute pile (e.g. suported atrs, values, defaults, etc) for any given scope.
+  def self.trip_machine(scope)
+      attribute_aliases = Hash[]
+      alias_attributes = Hash[]
+      values = Hash[]
+      defaults = Hash[]
+
+      scope&.ancestors.each { |otra|
+        DISTORTED_CONSTANTS.each { |invitation|  # OUT OF CONTROL / MY WHEELS IN CONSTANT MOTION
+          if otra.const_defined?(invitation)
+            part = otra.const_get(invitation) rescue Hash[]
+
+            if invitation == :ATTRIBUTES
+              # Support both alias-to-attribute and attribute-to-aliases
+              attribute_aliases.merge!(part) { |invitation, old, new|
+                if old.nil?
+                  new.nil? ? Set[invitation] : Set[new]
+                elsif new.nil?
+                  old
+                elsif new.is_a?(Enumerable)
+                  old.merge(new)
+                else
+                  old << new
+                end
+              }
+              alias_attributes.merge!(Cooltrainer::DistorteD::InjectionOfLove::so_deep(part))
+            elsif invitation == :ATTRIBUTES_VALUES
+              # Regexes currently override Enumerables
+              to_merge = {}
+              part.each_pair { |attribute, values|
+                if values.is_a?(Regexp)
+                  to_merge.update(attribute => values)
+                else
+                  to_merge.update(attribute => Cooltrainer::DistorteD::InjectionOfLove::so_deep(values))
+                end
+              }
+              values.merge!(to_merge)
+            elsif invitation == :ATTRIBUTES_DEFAULT
+              defaults.merge!(part)
+            end
+
+          end
+        }
+      }
+
+      return {
+        :ATTRIBUTE_ALIASES => attribute_aliases,
+        :ALIAS_ATTRIBUTES => alias_attributes,
+        :ATTRIBUTES_VALUES => values,
+        :ATTRIBUTES_DEFAULT => defaults,
+      }
+  end
+
+  # Returns a value for any attribute.
+  # In order of priority, that means:
+  #  - A user-given value (Liquid, CLI, etc) iff it passes a validity check,
+  #  - the default value if the given value is not in the accepted Set,
+  #  - nil for unset attributes with no default defined.
+  def abstract(argument)
+    # Reject any unknown arguments.
+    if trip_machine.dig(:ATTRIBUTE_ALIASES)&.keys.include?(argument)
+      alias_possibilities = trip_machine.dig(:ATTRIBUTE_ALIASES)&.dig(argument) || Set[]
+      possibilities = user_arguments&.keys.to_set & alias_possibilities
+
+      # How many matching user-defined attributes are there for our aliases?
+      case possibilities.length
+      when 0
+        # None; take the default.
+        trip_machine.dig(:ATTRIBUTES_DEFAULT)&.dig(argument)
+      when 1
+        # One; does it look valid?
+        is_valid = false
+        user_value = user_arguments&.dig(argument)
+
+        # Supported values may be declared as:
+        #   - A Hash of values-and-their-aliases to values.
+        #   - A Regex.
+        #   - nil for freeform input.
+        valid_value = trip_machine.dig(:ATTRIBUTES_VALUES)&.dig(argument)
+        if valid_value.is_a?(Enumerable)
+          if valid_value.include?(user_value)
+            is_valid = true
+          end
+        elsif valid_value.is_a?(Regexp)
+          if valid_value.match(user_value.to_s)
+            is_valid = true
+          end
+        end
+
+        # Return a valid user value, a default, or nil if all else fails.
+        if is_valid
+          # TODO: boolean casting
+          user_value
+        else
+          trip_machine.dig(:ATTRIBUTES_DEFAULT)&.dig(argument)
+        end
+
+      else  # case user_values.length
+        # Two or more; what do??
+        raise RuntimeError("Can't have multiple settings for #{argument} and its aliases.")
+      end
+    else
+      # The programmer asked for the value of an attribute that is
+      # not supported by its MediaMolecule. This is most likely a bug.
+      raise RuntimeError("#{argument} is not supported for #{@name}")
+    end
+  end
+
+
+end

data/lib/distorted/modular_technology/pango.rb

@@ -0,0 +1,90 @@
+module Cooltrainer
+  module DistorteD
+    module Technology
+      module Pango
+
+        # Escape text as necessary for Pango Markup, which is what Vips::Image.text()
+        # expects for its argv. This code should be in GLib but is unimplemented in Ruby's:
+        #
+        # https://ruby-gnome2.osdn.jp/hiki.cgi?Gtk%3A%3ALabel#Markup+%28styled+text%29
+        # "The markup passed to Gtk::Label#set_markup() must be valid; for example,
+        # literal </>/& characters must be escaped as &lt;, &gt;, and &amp;.
+        # If you pass text obtained from the user, file, or a network to
+        # Gtk::Label#set_markup(), you'll want to escape it
+        # with GLib::Markup.escape_text?(not implemented yet)."
+        #
+        # Base my own implementation on the original C version found in gmarkup:
+        # https://gitlab.gnome.org/GNOME/glib/-/blob/master/glib/gmarkup.c
+        def g_markup_escape_text(text)
+          text.map{ |c| g_markup_escape_char(c) }
+        end
+
+        # Returns a Pango-escaped Carriage Return.
+        # Use this for linebreaking Pango Markup output.
+        def cr
+          g_markup_escape_char(0x0D)
+        end
+
+        # Returns a Pango-escapped Line Feed.
+        # This isn't used/needed for anything with Pango
+        # but it felt weird to include CR and not LF lmao
+        def lf
+          g_markup_escape_char(0x0A)
+        end
+
+        # Returns a Pango'escaped CRLF pair.
+        # Also not needed for anything.
+        def crlf
+          cr << lf
+        end
+
+        # "Modified UTF-8" uses a normally-illegal byte sequence
+        # to encode the NULL character so 0x00 can exclusively
+        # be a string terminator.
+        def overlong_null
+          [0xC0, 0x80].pack('C*').force_encoding('UTF-8')
+        end
+
+        # The char-by-char actual function used by g_markup_escape_text
+        def g_markup_escape_char(c)
+          # I think a fully-working version of this function would
+          # be as simple as `sprintf('&#x%x;', c.ord)` ALL THE THINGS,
+          # but I want to copy the structure of the C implementation
+          # as closely as possible, which means using the named escape
+          # sequences for common characters and separating the
+          # Latin-1 Supplement range from the other
+          # the Unicode control characters (> 0x7f) even though three's no
+          # need to in Ruby.
+          case c.ord
+          when '&'.ord
+            '&amp;'
+          when '<'.ord
+            '&lt;'
+          when '>'.ord
+            '&gt;'
+          when '\''.ord
+            '&apos;'
+          when '"'.ord
+            '&quot;'
+          when 0x1..0x8, 0xb..0xc, 0xe..0x1f, 0x7f
+            sprintf('&#x%x;', c.ord)
+          when 0x80..0x84, 0x86..0x9f
+            # The original C implementation separates this range
+            # from the above range due to its need to handle the
+            # UTF control character bytes with gunichar:
+            # https://wiki.tcl-lang.org/page/UTF%2D8+bit+by+bit
+            # https://www.fileformat.info/info/unicode/utf8.htm
+            # Ruby has already done this for us here :)
+            sprintf('&#x%x;', c.ord)
+          when 0x0 # what's this…?
+            # Avoid a `ArgumentError: string contains null byte`
+            # by not printing one :)
+          else
+            c
+          end
+        end
+
+      end  # Pango
+    end  # Tech
+  end  # DistorteD
+end  # Cooltrainer