checking-you-out 0.7.0

data/lib/checking-you-out/inner_spirit.rb

@@ -0,0 +1,215 @@
+require 'set' unless defined? ::Set
+require 'pathname' unless defined? ::Pathname
+
+
+# Utility Modules/procs/lambdas/etc for generic operations like checking WeightedActions.
+require_relative 'party_starter' unless defined? ::CHECKING::YOU::WeightedAction
+
+
+# This base Struct will be used as the Hash key for its matching `OUT` subclass object,
+# and its members correspond to the three major parts of an IETF "Content-Type" String,
+# e.g. "application/x-saturn-rom" → :x, :application, :"saturn-rom".
+#
+# This is kind of a leaky abstraction since I want to support non-IETF type systems too,
+# but the IETF system is by far the most relevant one to us because the most exhaustive
+# source data (`shared-mime-info`) is based on that format and because, you know, Internet.
+# See the adjacent `auslandsgespräch.rb` for the parser and more info.
+#
+#
+# The instances of a `Struct` subclass with at most `RSTRUCT_EMBED_LEN_MAX` members
+# can fit entirely within an `RStruct` without additional heap allocation.
+# In MRI (at least as of 3.0) the `RSTRUCT_EMBED_LEN_MAX` is 3, so CYI uses three members.
+#
+# For more info see:
+# - https://github.com/ruby/ruby/blob/master/gc.c
+# - http://patshaughnessy.net/2013/2/8/ruby-mri-source-code-idioms-3-embedded-objects
+CHECKING::YOU::IN ||= Struct.new(
+  # Intentionally avoiding naming taxonomic ranks like "domain", "class", or "order"
+  # whose names are already common in computing.
+  :kingdom,
+  :phylum,
+  :genus,
+) do
+  # Promote any CYI to its CYO singleton. CYO has the opposites of these methods.
+  def out; ::CHECKING::YOU::OUT::new(self); end
+  def in; self; end
+end
+
+# Main Struct subclass for in-memory type representation.
+# Instances of the base `CHECKING::YOU::IN` Struct will refer to only one of these,
+# and this matching object will contain all relevant data about the type,
+# such as file extension(s), `magic` bytes, and variations of a base type like all of:
+# - "application/vnd.wordperfect;"
+# - "application/vnd.wordperfect;version=4.2"
+# - "application/vnd.wordperfect;version=5.0"
+# - "application/vnd.wordperfect;version=5.1"
+# - "application/vnd.wordperfect;version=6.x"
+# …will be represented in a single `CHECKING::YOU::OUT` object.
+class ::CHECKING::YOU::OUT < ::CHECKING::YOU::IN
+
+  # Absolute path to the root of the Gem — the directory containing `bin`,`docs`,`lib`, etc.
+  GEM_ROOT = proc { ::Pathname.new(__dir__).join(*Array.new(2, -'..')).expand_path.realpath }
+
+  # Time object representing the day this running CYO Gem was packaged.
+  #
+  # `Gem::Specification#date` can be slightly misleading when developing locally with Bundler using `bundle exec`.
+  # One might expect the result of `#date` to be "now" (including hours/minutes/seconds) in UTC for such a runtime-packaged Gem,
+  # but it will always be midnight UTC of the current day (also in UTC), i.e. a date that is always[0] in the past.
+  #
+  # After ${your-UTC-offset} hours before midnight localtime, this will give you a *day* that seems to be in the future
+  # compared to a system clock displaying localtime despite that *date* UTC still being in the past,
+  # e.g. as I write this comment at 2021-05-25 22:22 PST, `GEM_PACKAGE_TIME.call` returns `2021-05-26 00:00:00 UTC`.
+  #
+  # Rescue from `Gem::MissingSpecError`'s parent to support developing locally with just `require_relative` and no Bundler.
+  #
+  # [0]: unless you manage to `bundle exec` at exactly 00:00:00 UTC :)
+  GEM_PACKAGE_TIME = proc { begin; Gem::Specification::find_by_name(-'checking-you-out').date; rescue Gem::LoadError; Time.now; end }
+
+  Species = Struct.new(:name, :value) do
+    def self.from_string(param_string)
+      return self.new(*param_string.split(-?=))
+    end
+  end
+
+  # Main memoization Hash for our loaded Type data.
+  # { CHECKING::YOU::IN => CHECKING::YOU::OUT }
+  def self.all_night; @all_night ||= Hash.new(nil); end
+
+  # Return a singleton instance for any CYO.
+  def self.new(taxa)
+    # Support IETF String argument to this method, e.g. ::CHECKING::YOU::OUT::new('application/octet-stream')
+    return self.from_ietf_media_type(taxa) if taxa.is_a?(String)
+    # Otherwise return the memoized CYO singleton of this type.
+    self.all_night[
+      taxa.is_a?(::CHECKING::YOU::IN) ? taxa : super(*taxa)
+    ] ||= self.allocate.tap { |cyo| cyo.send(:initialize, *taxa) }
+  end
+
+  # Demote any CYO to a CYI that can be passed around in just 40 bytes.
+  # CYI has the opposites of these methods.
+  def out; self; end
+  def in; self.class.all_night.key(self); end
+
+
+  # Get a CYO, Set[CYO], or nil by file-extension, e.g. `doc` => { CYO msword, CYO rtf }.
+  POSTFIX_KEY = proc {
+    # Re-use a single search structure to avoid allocating an Object per search.
+    scratch = ::CHECKING::YOU::StickAround.new(-'')
+    # Additionally accelerate multiple searches for the same thing by avoiding `StickAround#replace`
+    # if the new search key already matches the previous search key.
+    # Mark `case_sensitive: false` here for testing arbitrarily-named input.
+    -> { scratch.eql?(_1) ? scratch : scratch.replace(_1, case_sensitive: false) }
+  }.call
+  def self.from_postfix(stick_around)
+    self.instance_variable_get(:@after_forever)[POSTFIX_KEY.call(stick_around)]
+  end
+
+  # Get a Hash[CYO] or nil for arbitrary non-file-extension glob match of a File basename.
+  def self.from_glob(stick_around)
+    self.instance_variable_get(:@stick_around).select { |k,v|
+      k.eql?(stick_around)
+    }.yield_self { |matched|
+      matched.empty? ? nil : matched
+    }
+  end
+
+  def self.from_pathname(pathname)
+    return self.from_glob(pathname) || self.from_postfix(pathname)
+  end
+
+
+  # Add a new Postfix or Glob for a specific type.
+  def add_pathname_fragment(fragment)
+    if fragment.start_with?(-'*.') and fragment.count(-?.) == 1 and fragment.count(-?*) == 1 then
+      ::CHECKING::YOU::INSTANCE_NEEDLEMAKER.call(:@postfixes, fragment, self)
+      ::CHECKING::YOU::CLASS_NEEDLEMAKER.call(:@after_forever, fragment, self)
+    else
+      ::CHECKING::YOU::INSTANCE_NEEDLEMAKER.call(:@globs, fragment, self)
+      ::CHECKING::YOU::CLASS_NEEDLEMAKER.call(:@stick_around, fragment, self)
+    end
+  end
+
+
+  # Get a `Set` of this CYO and all of its parent CYOs, at minimum just `Set[self]`.
+  def aka
+    return case @aka
+      when nil then Set[self.in]
+      when self.class, self.class.superclass then Set[self.in, @aka]
+      when ::Set then Set[self.in, *@aka]
+    end
+  end
+
+  # Take an additional CYI, store it locally, and memoize it as an alias for this CYO.
+  def add_aka(taxa)
+    taxa = taxa.is_a?(::CHECKING::YOU::IN) ? taxa : self.class.superclass.new(*taxa)
+    ::CHECKING::YOU::INSTANCE_NEEDLEMAKER.call(:@aka, taxa, self)
+    self.class.all_night[taxa] = self
+  end
+
+  # Forget a CYI alias of this Type. Capable of unsetting the "real" CYI as well if desired.
+  def remove_aka(taxa)
+    taxa = taxa.is_a?(::CHECKING::YOU::IN) ? taxa : self.class.superclass.new(*taxa)
+    self.class.all_night.delete(taxa) if self.class.all_night[taxa] === self
+  end
+
+  attr_reader :parents, :children
+
+  # Take an additional CYO, store it locally as our parent, and ask it to add ourselves as its child.
+  def add_parent(parent_cyo)
+    ::CHECKING::YOU::INSTANCE_NEEDLEMAKER.call(:@parents, parent_cyo, self)
+    parent_cyo.add_child(self) unless parent_cyo.children&.include?(self)
+  end
+
+  # Take an additional CYO, store it locally as our child, and ask it to add ourselves as its parent.
+  def add_child(child_cyo)
+    ::CHECKING::YOU::INSTANCE_NEEDLEMAKER.call(:@children, child_cyo, self)
+    child_cyo.add_parent(self) unless child_cyo.parents&.include?(self)
+  end
+
+  # Get a `Set` of this CYO and all of its parent CYOs, at minimum just `Set[self]`.
+  def adults_table
+    return case @parents
+      when nil then Set[self]
+      when self.class, self.class.superclass then Set[self, @parents]
+      when ::Set then Set[self, *@parents]
+    end
+  end
+
+  # Get a `Set` of this CYO and all of its child CYOs, at minimum just `Set[self]`.
+  def kids_table
+    return case @children
+      when nil then Set[self]
+      when self.class, self.class.superclass then Set[self, @children]
+      when ::Set then Set[self, *@children]
+    end
+  end
+
+  # Get a `Set` of this CYO and all parents and children, at minimum just `Set[self]`.
+  def family_tree; self.kids_table | self.adults_table; end
+
+  # Storage for descriptions (`<comment>`), acrnyms, suitable iconography, and other boring metadata, e.g.:
+  #   <mime-type type="application/vnd.oasis.opendocument.text">
+  #     <comment>ODT document</comment>
+  #     <acronym>ODT</acronym>
+  #     <expanded-acronym>OpenDocument Text</expanded-acronym>
+  #     <generic-icon name="x-office-document"/>
+  #     […]
+  #   </mini-type>
+  attr_accessor :description
+
+end
+
+# IETF Media-Type parser and methods that use that parser.
+require_relative 'auslandsgesprach' unless defined? ::CHECKING::YOU::IN::AUSLANDSGESPRÄCH
+::CHECKING::YOU::IN.extend(::CHECKING::YOU::IN::AUSLANDSGESPRÄCH)
+::CHECKING::YOU::IN.include(::CHECKING::YOU::IN::INLANDGESPRÄCH)
+::CHECKING::YOU::OUT.extend(::CHECKING::YOU::OUT::AUSLANDSGESPRÄCH)
+
+# Content matching à la `libmagic`/`file`.
+require_relative 'sweet_sweet_love_magic' unless defined? ::CHECKING::YOU::SweetSweet♥Magic
+::CHECKING::YOU::OUT.extend(::CHECKING::YOU::SweetSweet♡Magic)
+::CHECKING::YOU::OUT.prepend(::CHECKING::YOU::SweetSweet♥Magic)
+
+# Methods for loading type data from `shared-mime-info` package XML files.
+require_relative 'ghost_revival' unless defined? ::CHECKING::YOU::GHOST_REVIVAL
+::CHECKING::YOU::OUT.extend(::CHECKING::YOU::OUT::GHOST_REVIVAL)

data/lib/checking-you-out/party_starter.rb

@@ -0,0 +1,202 @@
+require 'set' unless defined? ::Set
+require 'pathname' unless defined? ::Pathname
+
+
+# This file defines/imports various utility Modules/procs/etc that should be available
+# to all other CYO components without `including`/`extending`.
+require_relative 'party_starter/weighted_action' unless defined? ::CHECKING::YOU::WeightedAction
+require_relative 'party_starter/stick_around' unless defined? ::CHECKING::YOU::StickAround
+
+class CHECKING::YOU
+
+  # The following two `proc`s handle classwide-memoization and instance-level assignment
+  # for values that may be Enumerable but often refer to only a single Object.
+  #
+  # For example, most `Postfix`es (file extensions) will only ever belong to a single CYO Object,
+  # but a handful represent possibly-multiple types, like how `.doc` can be an MSWord file or WordPad RTF.
+  #
+  # These assignment procs take a storage haystack, a needle to store, and the CYO receiver to which the needle refers.
+  # They will set `haystack[needle] => CYO` if that needle is unique and unset, or they will convert
+  # an existing single `haystack[needle] => CYO` assignment to `haystack[needle] => Set[existingCYO, newCYO]`.
+  #
+  # This is an admittedly-annoying complexity-for-performance tradeoff with the goal of allocating
+  # as few spurious containers as possible instead of explicitly initializing a Set for every needle
+  # when most of them would wastefully be a Set of just a single thing.
+  CLASS_NEEDLEMAKER = proc { |haystack, needle, receiver|
+    # Create the container if this is the very first invocation.
+    receiver.class.instance_variable_set(haystack, Hash.new(nil)) unless receiver.class.instance_variable_defined?(haystack)
+
+    # Set the `haystack` Hash's `needle` key to the `receiver` if the `key` is unset, otherwise
+    # to a `Set` of the existing value plus `receiver` if that value is not `receiver` already.
+    receiver.class.instance_variable_get(haystack).tap { |awen|
+      case awen[needle]
+      when nil then awen[needle] = receiver
+      when ::Set then awen[needle].add(receiver)
+      when receiver.class then awen[needle] = Set[awen[needle], receiver] unless awen[needle] == receiver
+      end
+    }
+  }
+
+  # This is the instance-level version of the above, e.g. a CYO with only one Postfix
+  # will assign `cyo.:@postfixes = Postfix`, and a CYO with many Postfixes will assign
+  # e.g. `cyo.:@postfixes = Set[post, fix, es, …]`.
+  INSTANCE_NEEDLEMAKER = proc { |haystack, needle, receiver|
+    if receiver.instance_variable_defined?(haystack) then
+      receiver.instance_variable_get(haystack).add(needle)
+    else
+      receiver.instance_variable_set(haystack, Set[needle])
+    end
+  }
+
+
+  # Test a Pathname representing an extant file whose contents and metadata we can use.
+  # This is separated into a lambda due to the complexity, since the entry-point might
+  # be given a String that could represent a Media Type, a hypothetical path,
+  # an extant path, or even raw stream contents. It could be given a Pathname representing
+  # either a hypothetical or extant file. It could be given an IO/Stream object.
+  # Several input possibilities will end up callin this lambda.
+  #
+  # Some of this complexity is my fault, since I'm doing a lot of variable juggling
+  # to avoid as many new-Object-allocations as possible in the name of performance
+  # since this library is the very core-est core of DistorteD;
+  # things like assigning Hash values to single CYO objects the first time that key is stored
+  # then replacing that value with a Set iff that key needs to reference any additional CYO.
+  #
+  # - `::from_xattr` can return `nil` or a single `CYO` depending on filesystem extended attributes.
+  #   It is very very unlikely that most people will ever use this, but I think it's cool 8)
+  #
+  # - `::from_postfix` can return `nil`, `CYO`, or `Set` since I decided to store Postfixes
+  #   separately from freeform globs since file-extension matches are the vast majority of globs.
+  #   Postfixes avoid needing to be weighted since they all represent the same final pathname component
+  #   and should never result in multiple conflicting Postfix key matches.
+  #   A single Postfix key can represent multiple CYOs, though; hence the possible `Set`.
+  #
+  # - `::from_glob` can return `nil` or `Hash` since even a single match will include the weighted key.
+  #
+  # - `::from_content` can return `nil` or `Hash` based on a `libmagic`-style match of file/stream contents.
+  #   Many common types can be determined from the first four bytes alone, but we support matching
+  #   arbitrarily-long sequences against arbitrarily-big byte range boundaries.
+  #   These keys will also be weighted, even for a single match.
+  TEST_EXTANT_PATHNAME = -> (pathname, so_deep: true, only_one_match: true) {
+
+    # Never return empty Enumerables.
+    # Yielding-self to this proc will `nil`-ify anything that's `:empty?`
+    # and will pass any non-Enumerable Objects through.
+    point_zero = proc { _1.respond_to?(:empty) ? (_1.empty? ? nil : _1) : _1 }
+
+    # Our matching block will return a single CYO when possible, and can optionally
+    # return multiple CYO matches for ambiguous files/streams.
+    # Multiple matching must be opted into with `only_one_match: false` so it doesn't need to be
+    # checked by every caller that's is fine with best-effort and wants to minimize allocations.
+    one_or_eight = proc { |huh|
+      case
+      when huh.nil? then nil
+      when huh.respond_to?(:empty?), huh.respond_to?(:first?)
+        if huh.empty? then nil
+        elsif huh.size == 1 then huh.is_a?(::Hash) ? huh.values.first : huh.first
+        elsif huh.size > 1 and only_one_match then huh.is_a?(::Hash) ? huh.values.first : huh.first
+        else huh
+        end
+      else huh
+      end
+    }
+
+    # Test all "glob" matches against all child Types of all "magic" matches to allow for
+    # nuanced detection of ambiguous streams where a `magic` match returns multiple possibilities,
+    # e.g. using a `.doc` Postfix-match to choose a `text-plain` glob-match for non-Word `.doc` files
+    #      or to choose a `application/msword` glob-match over a more generic `application/x-ole-storage`
+    #      magic-match when the magic weights alone are not enough information to make the correct choice.
+    # irb> ::CHECKING::YOU::OUT::from_postfix('doc')
+    # => #<Set: {#<CHECKING::YOU::OUT application/msword>, #<CHECKING::YOU::OUT text/plain>}>
+    #
+    # Again, a lot of the complexity here is "my fault" in that I could avoid it by explicitly using
+    # the same data structures for all the different inputs, but I need this to be as fast
+    # and as low-overhead as possible which means avoiding allocations of things like
+    # Enumerables that end up holding only a single other object.
+    # Obviously that leads to a lot of variation in result values from helper methods,
+    # so I'll own that here instead of ever making callsites deal with it.
+    #
+    # This `proc`'s output will introduce a little more of that same complexity since it will be `nil`
+    # if either input is `nil`, will be a single CYO if there is only one union match,
+    # or a `Set` if there are still multiple possibilities.
+    magic_children = proc { |glob, magic|
+      # NOTE: CYO deviates from `shared-mime-info`'s behavior very slightly here!
+      #
+      # `shared-mime-info`'s "Recommended checking order" documentation sez:
+      # "If any of the mimetypes resulting from a glob match is equal to or a subclass of the result
+      #  from the magic sniffing, use this as the result. This allows us for example to distinguish text files
+      #  called 'foo.doc' from MS-Word files with the same name, as the magic match for the MS-Word file would be 
+      #  `application/x-ole-storage` which the MS-Word type inherits."
+      #
+      # Our behavior is identical except it allows glob matches which are a *superclass* of a
+      # magic-match in addition to subclass or equal-to, i.e. using `:family_tree` for comparison here
+      # instead of using `:kids_table`. There might be a downside to this that I haven't found yet
+      # but it allows CYO to better match some things, e.g. matching a `'.flv'` video file as
+      # `'video/x-flv'` instead of as `'video/x-javafx'`, since fd.o has the latter as a subclass of the former.
+      case [glob, magic]
+        in ::NilClass,           *                    then nil
+        in *,                    ::NilClass           then nil
+        in ::Set,                ::Hash               then glob & magic.values.to_set.map(&:family_tree).reduce(&:&)
+        in ::Set,                ::CHECKING::YOU::OUT then glob & magic.kids_table
+        in ::Hash,               ::Hash               then glob.values.to_set & magic.values.to_set.map(&:family_tree).reduce(&:&)
+        in ::CHECKING::YOU::OUT, ::Hash               then magic.values.to_set.map(&:family_tree).reduce(&:&)&.include?(glob) ? glob : nil
+        in ::Hash,               ::CHECKING::YOU::OUT then glob.values.to_set & magic.kids_table
+        in ::CHECKING::YOU::OUT, ::CHECKING::YOU::OUT then glob == magic ? glob : nil
+        else nil
+      end.yield_self(&point_zero)
+    }
+
+    # "If a MIME type is provided explicitly (eg, by a ContentType HTTP header, a MIME email attachment,
+    #  an extended attribute or some other means) then that should be used instead of guessing."
+    # This will probably always be `nil` since this is a niche feature, but we have to test it first.
+    ::CHECKING::YOU::OUT::from_xattr(pathname) || begin
+
+      # "Start by doing a glob match of the filename. Keep only globs with the biggest weight."
+      # "If the patterns are different, keep only matched with the longest pattern."
+      #  If after this, there is one or more matching glob, and all the matching globs result in
+      #  the same mimetype, use that mimetype as the result."
+      # This can be `nil`, `CYO`, a `Set` of Postfix matches, or a `Hash` of weighted Glob matches.
+      glob_matched = ::CHECKING::YOU::OUT::from_pathname(pathname)
+
+      # "If the glob matching fails or results in multiple conflicting mimetypes,
+      # read the contents of the file and do magic sniffing on it.
+      # This can be `nil` or a `Hash` of weighted magic matches.
+      magic_matched = (glob_matched.nil? || glob_matched.is_a?(Enumerable) || so_deep) ? ::CHECKING::YOU::OUT::from_content(pathname) : nil
+
+      # Make a decision based on the two possible matches above plus a third match category
+      # based on a union between the glob match and all children of all magic matches.
+      # See the relevant proc above. Its result will always be `nil` if either input is `nil`.
+      #
+      # "If there was no glob match, use the magic match as the result."
+      # "Otherwise use the result of the glob match that has the highest weight."
+      return case [glob_matched, magic_matched, magic_children.call(glob_matched, magic_matched)]
+        in ::NilClass,           ::Hash,     ::NilClass                            then LEGENDARY_HEAVY_GLOW.call(magic_matched, :weight)
+        in ::CHECKING::YOU::OUT, ::NilClass, ::NilClass                            then glob_matched
+        in ::Set,                ::NilClass, ::NilClass                            then glob_matched
+        in ::Hash,               ::NilClass, ::NilClass                            then LEGENDARY_HEAVY_GLOW.call(glob_matched, [:weight, :length])
+        in *,                                ::CHECKING::YOU::OUT => only_one_type then only_one_type
+        in ::Set,                ::Hash,     ::Set => magic_children               then
+          # Choose the union-matched type having the the heaviest magic-matched weight.
+          LEGENDARY_HEAVY_GLOW.call(magic_matched.keep_if { |_magic, cyo| magic_children.include?(cyo) }, :weight)
+        in ::Hash,               ::Hash,     ::Set => magic_children               then
+          # Choose the union-matched type having the heaviest glob-matched weight,
+          # and then additionally the longest glob string if there are still multiple matches.
+          LEGENDARY_HEAVY_GLOW.call(glob_matched.keep_if { |_glob, cyo| magic_children.include?(cyo) }, [:weight, :length])
+        in ::CHECKING::YOU::OUT, ::Hash,     ::NilClass                            then glob_matched
+        in ::CHECKING::YOU::OUT, ::Hash,     ::Set => magic_children               then
+          # Choose the single glob-matched type iff it was also magic-matched,
+          # otherwise choose the heaviest magic-matched type.
+          magic_matched.values.include?(glob_matched) ? glob_matched : LEGENDARY_HEAVY_GLOW.call(magic_matched, :weight)
+        in ::NilClass,           ::NilClass, ::NilClass                            then
+          # "If no magic rule matches the data (or if the content is not available),
+          #  use the default type of application/octet-stream for binary data, or text/plain for textual data."
+          # "Note: Checking the first 128 bytes of the file for ASCII control characters is a good way to guess
+          #  whether a file is binary or text, but note that files with high-bit-set characters should still be
+          #  treated as text since these can appear in UTF-8 text, unlike control characters.
+          ::CHECKING::YOU::OUT::from_ietf_media_type('application/octet-stream')
+        else nil
+      end.yield_self(&one_or_eight)
+    end  # ::CHECKING::YOU::OUT::from_xattr(pathname) || begin
+  }  # TEST_EXTANT_PATHNAME
+
+end  # class CHECKING::YOU

data/lib/checking-you-out/party_starter/stick_around.rb

@@ -0,0 +1,260 @@
+require 'pathname' unless defined?(::Pathname)
+
+
+class CHECKING::YOU
+  # Provide case-optional String-like keys for Postfixes, Globs, etc.
+  #
+  # From Ruby's `Hash` docs: "Two objects refer to the same hash key when their hash value is identical
+  # and the two objects are eql? to each other"
+  # I tried to subclass String and just override `:eql?` and `:hash` for case-insensitive lookups,
+  # but it turns out not be that easy due to MRI's C comparison functions for String, Symbol, etc.
+  #
+  # It was super-confusing because I could call e.g. `'DOC'.eql? 'doc'` manually and get `true`,
+  # but it would always fail to work when used as a `Hash` key, when calling `uniq`, or in a `Set`:
+  #
+  # irb(main):049:1* Lol = Class.new(String).tap {
+  # irb(main):050:1*   _1.define_method(:hash) do; self[0..5].downcase!.hash; end;
+  # irb(main):051:1*   _1.define_method(:eql?) do |lol|; self[0..5].casecmp?(lol[0..5]); end;
+  # irb(main):052:1*   _1.alias_method(:==, :eql?)
+  # irb(main):053:0> }
+  # irb(main):054:0> fart = Lol.new("abcdefg")
+  # irb(main):055:0> butt = Lol.new("abcdefgh")
+  # irb(main):056:0> fart == butt
+  # => true
+  # irb(main):057:0> fart.eql? butt
+  # => true
+  # irb(main):058:0> fart.hash
+  # => 1243221847611081438
+  # irb(main):059:0> butt.hash
+  # => 1243221847611081438
+  # irb(main):060:0> {fart => "smella"}[butt]
+  # => nil
+  # irb(main):061:0> {fart => "smella"}[fart]
+  # => "smella"
+  #
+  # I'm not the first to run into this, as I found when searching for `"rb_str_hash_cmp"`:
+  # https://kate.io/blog/strange-hash-instances-in-ruby/
+  #
+  # To work around this I will explicitly `downcase` the actual String subclass' value
+  # and just let the hashes collide for differently-cased values, then `eql?` will decide.
+  # This is still slower than the all-C String code but is the fastest method I've found
+  # to achieve this without doubling my Object allocations by wrapping each String in a Struct.
+  StickAround = Class.new(::String) do
+
+    # Be case-insensitive by default so we can match any filename.
+    DEFAULT_SENSITIVITY = false
+
+    # These may be weighted just like byte sequences.
+    include WeightedAction
+
+    # This class needs to support being instantiated without a value due to the way our XML data gets loaded,
+    # but the superclass `String` has a default `str=""` argument here that works perfectly for that need.
+    def initialize(str=-'', *args, case_sensitive: DEFAULT_SENSITIVITY, **kwargs)
+      # Prime `#replace` to treat its next `String` as case-sensitive iff we were told.
+      instance_variable_set(:@case_sensitive, case_sensitive) if case_sensitive == true
+
+      # Don't pass an initial `str` value to `super` if we were given one,
+      # because `#replace` has case-sensitivity-handling functionality that must be called.
+      super(str, *args, **kwargs)
+      self.replace(str) unless str.empty?
+    end
+
+    # Mark intent to be case-sensitive. Our source data's `<glob>` Attributes are parsed one at a time,
+    # so we won't know at the time of instantiation if we want to be case sensitive.
+    def case_sensitive=(sensitivity)
+      # Don't bother allocating an IVar if we're just going to be the default (case-insensitive)
+      if sensitivity == false then
+        remove_instance_variable(:@case_sensitive) if instance_variable_defined?(:@case_sensitive)
+      else
+        instance_variable_set(:@case_sensitive, sensitivity)
+      end
+    end
+
+    # Return our case-sensitive String variation iff we are marked case-sensitive *and* have a String value,
+    # otherwise just return our frozen deduplicated self value.
+    def itself
+      instance_variable_get(:@case_sensitive)&.is_a?(::String) ? instance_variable_get(:@case_sensitive) : self
+    end
+
+    def case_sensitive
+      instance_variable_get(:@case_sensitive)&.is_a?(::String) ? instance_variable_get(:@case_sensitive) : nil
+    end
+
+    # Set an appropriate value for ourselves given a variety of input.
+    # Even though this is called `#replace` here and in `String`, this method will often be used
+    # to set initial instance values due to nondeterministic attribute order while parsing our XML data.
+    def replace(otra, case_sensitive: DEFAULT_SENSITIVITY)
+      # Extract a usable value from different input types/formats.
+      #
+      # `File::extname` will return the last dotted component of a String, prepended with the leading dot,
+      #  e.g. `File::extname("hello.jpg")` => `".jpg"`. We will prepend an asterisk to these to make a glob pattern.
+      #
+      # `File::extname` will be an empty String for input Strings which contain no dotted components
+      #  or only have a leading dot, e.g. `File::extname(".bash_profile") => `""`.
+      newbuild = case otra
+        when self.class then -otra.to_s
+        when ::Symbol   then -otra.name
+        when ::Pathname then otra.extname.empty? ? otra.basename.to_s.-@ : otra.extname.prepend(-?*).-@
+        when ::String   then (File.extname(otra).empty? or -otra[-1] == -?*) ? -otra : -File.extname(otra).prepend(-?*)
+        else -otra.to_s
+      end
+
+      # The `super` call in this condition statement will explicitly set the `self` value to the downcased version of our key,
+      # but we will then compare `super`'s return value to its input to decide if we should store a case-sensitive value too.
+      #
+      # If the computed key is already downcase we could still be case-sensitive if we were boolean-marked as such,
+      # otherwise we have no need for the IVar and can remove it if one is set.
+      #
+      # Explicitly check if the IVar == `true`, not just truthiness, because it may also be a `String`
+      # if we are `#replace`ing a previous case-sensitive value.
+      #
+      # NOTE: There is a hole in the logic here where any non-downcased input will cause case-sensitivity,
+      # but this is necessary since our XML parsing might give us a `pattern` attribute callback
+      # before we'd had a chance to set a `case-insensitive` mark.
+      # All of the `case-sensitive="true"` `<glob>`s in current fd.o XML have an upper-case component,
+      # so this hack will make sure we don't discard the proper-cased `String` if we see that callback before the mark.
+      if (super(-newbuild.downcase(:fold)) != newbuild) or case_sensitive or (instance_variable_get(:@case_sensitive) == true) then
+        instance_variable_set(:@case_sensitive, newbuild)
+      else
+        remove_instance_variable(:@case_sensitive) if instance_variable_defined?(:@case_sensitive)
+      end
+      self  # return the new downcased value we just set when we called `super`
+    end  # replace
+
+    # Return a boolean describing our case-sensitivity status.
+    def case_sensitive?
+      # The same-name IVar could contain a (non-default) boolean value, but it's far more likely to contain
+      # the desired-case variation of the `self` String. In that case this returns `true` instead of the value.
+      case instance_variable_get(:@case_sensitive)
+        when ::String    then true   # We have stored a String case-variation.
+        when ::TrueClass then true   # We have been marked for case-sensitivity next `#replace`.
+        else                  false  # NilClass, FalseClass, or anything else.
+      end
+    end
+
+    # Returns case-optional boolean equality between this `StickAround` and a given object `StickAround` or `String`.
+    # This is one of two methods necessary for matching Hash keys, but this method will be called only if `self#hash`
+    # and `otra#hash` return the same Integer value, complicated by the fact that MRI's C implementation of `rb_str_hash_cmp`
+    # won't use our overriden version of `#hash`.
+    # That's why we downcase ourselves in `#replace` and store case variations separately.
+    def eql?(otra)
+      # https://ruby-doc.org/core/File.html#method-c-fnmatch-3F
+      #
+      # The `File` Class has kinda-poorly-documented Integer constants to control the behavior of `File::fnmatch?`.
+      # If this feels non-Ruby-ish it's because this is a POSIX thing:
+      # https://pubs.opengroup.org/onlinepubs/9699919799/functions/fnmatch.html
+      #
+      #   irb(main):061:0> File::constants::keep_if { _1.to_s.include?('FNM_') }
+      #   => [:FNM_CASEFOLD, :FNM_EXTGLOB, :FNM_SYSCASE, :FNM_NOESCAPE, :FNM_PATHNAME, :FNM_DOTMATCH, :FNM_SHORTNAME]
+      #   irb(main):062:0> File::constants::keep_if { _1.to_s.include?('FNM_') }.map(&File::method(:const_get))
+      #   => [8, 16, 0, 1, 2, 4, 0]
+      #
+      #
+      # - `File::FNM_PATHNAME` controls wildcards in the haystack matching `File::SEPARATOR` in the needle:
+      #
+      #   irb> File.fnmatch?('*.jpg', '/hello.jpg', File::FNM_PATHNAME)
+      #   => false
+      #   irb> File.fnmatch?('*.jpg', '/hello.jpg')
+      #   => true
+      #   irb> File.fnmatch?('*.jpg', 'hello.jpg', File::FNM_PATHNAME)
+      #   => true
+      #   irb> File.fnmatch?('*.jpg', 'hello.jpg')
+      #   => true
+      #
+      #
+      # - `File::FNM_DOTMATCH` controls wildcard in the haystack matching `.` in the needle, like *nix-style "hidden" files:
+      #
+      #   irb> File.fnmatch?('*.jpg', '.hello.jpg', File::FNM_DOTMATCH)
+      #   => true
+      #   irb> File.fnmatch?('*.jpg', '.hello.jpg')
+      #   => false
+      #
+      #
+      # - `File::FNM_EXTGLOB` controls support for brace-delimited glob syntax for haystacks:
+      #
+      #   irb> File.fnmatch?('*.jp{e,}g', 'hello.jpg', File::FNM_EXTGLOB)
+      #   => true
+      #   irb> File.fnmatch?('*.jp{e,}g', 'hello.jpeg', File::FNM_EXTGLOB)
+      #   => true
+      #   irb> File.fnmatch?('*.jp{e,}g', 'hello.jpeg')
+      #   => false
+      #   irb> File.fnmatch?('*.jp{e,}g', 'hello.jpg')
+      #   => false
+      #
+      #
+      # - `File::FNM_CASEFOLD` and `File::FNM_SYSCASE` control the case-sensitivity when matching,
+      #   either by folding (explicit case-insensitivity) or by matching the behavior of the host operating system,
+      #   *not* the behavior of any specific filesystem on that OS (https://bugs.ruby-lang.org/issues/15363),
+      #   e.g. case-sensitive on BSD/Linux:
+      #
+      #   irb> RUBY_PLATFORM
+      #   => "x86_64-linux"
+      #   irb> File.fnmatch?('LOICENSE', 'loicense', File::FNM_SYSCASE)
+      #   => false
+      #   irb> File.fnmatch?('LOICENSE', 'loicense', File::FNM_CASEFOLD)
+      #   => true
+      #   irb> File.fnmatch?('LOICENSE', 'loicense')
+      #   => false
+      #
+      #
+      # - `File::FNM_NOESCAPE` (ominously) controls matching escape sequences literally:
+      #   https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
+      #
+      #   irb> File.fnmatch?("*.jpg\\", 'hello.jpg', File::FNM_NOESCAPE)
+      #   => false
+      #   irb> File.fnmatch?("*.jpg\\", 'hello.jpg')
+      #   => true
+      #
+      #
+      # - `File::FNM_SHORTNAME` seems to control eight-dot-three filename matching, per the documentation:
+      #   "Makes patterns to match short names if existing. Valid only on Microsoft Windows."
+      #
+      #
+      # - Multiple of these Integer Constants can be bitwise-`OR`ed together for simultaneous use:
+      #
+      #   irb> File.fnmatch?('*.jp{e,}g', '/root/.HeLlO.jPEg', File::FNM_EXTGLOB | File::FNM_CASEFOLD | File::FNM_DOTMATCH)
+      #   => true
+      #   irb> File.fnmatch?('*.jp{e,}g', '/root/.HeLlO.jPEg', File::FNM_EXTGLOB | File::FNM_CASEFOLD | File::FNM_DOTMATCH | File::FNM_PATHNAME)
+      #   => false
+      File.fnmatch?(
+        self.itself,           # Haystack
+        otra.itself,           # Needle
+        File::FNM_DOTMATCH  |
+          File::FNM_EXTGLOB |
+          (
+            # Support testing `otra` as either another `StickAround` or as a plain `String`,
+            # in which case it will not have a method `#case_sensitive?`.
+            # Use our own case-sensitivity setting when comparing against plain `Strings`.
+            (self.case_sensitive? or (otra.respond_to?(:case_sensitive?) ? otra.case_sensitive? : self.case_sensitive?)) ?
+            0 : File::FNM_CASEFOLD
+          )
+      )
+    end  # eql?
+
+    # Hash-key usage depends on `#eql?`, but `:==` should have identical behavior for our own uses.
+    alias_method(:==, :eql?)
+
+    # Return an Integer hash value for this object. This method and `#eql?` are used by `Hash`, `Set`, and `#uniq` to
+    # associate separate Objects with each other for deduplication or for use as `Hash` keys.
+    # The `eql?` method will be called only *after* two Integer `#hash` values match!
+    #
+    # NOTE: MRI will not use this function in many cases!
+    # It has C implementations of methods like `rb_str_hash_cmp` for `Hash` lookups, and this is usually a Good Thing™
+    # since it makes `Hash`es fast when using `String` or `Symbol` as keys.
+    # Subclassing built-in types like `String` allows/forces us to use these same accelerated code paths,
+    # and it was incredibly confusing for me why my custom String subclass was behaving so strangely
+    # when used as a Hash key until I had a hunch to read MRI's `string.c` and `hash.c` and confirmed.
+    # I found this write-up once I knew to search for "rb_str_hash_cmp": https://kate.io/blog/strange-hash-instances-in-ruby/
+    #
+    # I'm going to define this anyway because it could still be useful in certain corner cases, but be aware of the above!
+    # This is the reason I explicitly `downcase` our self value in `#replace`, because otherwise the Hash keys will never match
+    # and `#eql?` will never even be called.
+    def hash
+      if self.include?(-?*) and not self.start_with?(-?*) then self[...6].downcase!.hash
+      elsif self.include?(-?*) and not File.extname(self).empty? then File.extname(self).delete_prefix!(-?.)
+      else super
+      end
+    end
+
+  end  # StickAround
+end  # class CHECKING::YOU