distorted 0.5.6 → 0.5.7

data/lib/distorted/error_code.rb

@@ -0,0 +1,8 @@
+# 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

data/lib/distorted/font.rb

@@ -0,0 +1,192 @@
+require 'set'
+
+# Font metadata extraction
+require 'ttfunk'
+
+require 'mime/types'
+
+# No need to do all the fancy library versioning in a subclass.
+require 'vips'
+
+require 'distorted/text'
+
+
+module Cooltrainer
+  module DistorteD
+    class Font < Text
+
+      MEDIA_TYPE = 'font'.freeze
+
+      # TODO: Test OTF, OTB, and others.
+      # NOTE: Traditional bitmap fonts won't be supported due to Pango 1.44
+      # and later switching to Harfbuzz from Freetype:
+      # https://gitlab.gnome.org/GNOME/pango/-/issues/386
+      # https://blogs.gnome.org/mclasen/2019/05/25/pango-future-directions/
+      MIME_TYPES = MIME::Types[/^#{self::MEDIA_TYPE}\/ttf/].to_set
+
+      ATTRS = Set[
+        :alt,
+      ]
+      ATTRS_VALUES = {
+      }
+      ATTRS_DEFAULT = {
+      }
+
+
+      # irb(main):089:0> chars.take(5)
+      # => [[1, 255], [2, 1], [3, 2], [4, 3], [5, 4]]
+      # irb(main):090:0> chars.values.take(5)
+      # => [255, 1, 2, 3, 4]
+      # irb(main):091:0> chars.values.map(&:chr).take(5)
+      # => ["\xFF", "\x01", "\x02", "\x03", "\x04"]
+      def to_pango
+        output = '' << cr << '<span>' << cr
+
+        output << "<span size='35387'> #{font_name}</span>" << cr << cr
+
+        output << "<span size='24576'> #{font_description}</span>" << cr
+        output << "<span size='24576'> #{font_copyright}</span>" << cr
+        output << "<span size='24576'> #{font_version}</span>" << cr << cr
+
+        # Print a preview String in using the loaded font. Or don't.
+        if @demo
+          output << cr << cr << "<span size='24576' foreground='grey'> #{g_markup_escape_text(@demo)}</span>" << cr << cr << cr
+        end
+
+        #                        /!\ MANDATORY READING /!\
+        # https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6cmap.html
+        #
+        # "The 'cmap' table maps character codes to glyph indices.
+        # The choice of encoding for a particular font is dependent upon the conventions
+        # used by the intended platform. A font intended to run on multiple platforms
+        # with different encoding conventions will require multiple encoding tables.
+        # As a result, the 'cmap' table may contain multiple subtables,
+        # one for each supported encoding scheme."
+        #
+        # Cmap#unicode is a convenient shortcut to sorting the subtables
+        # and removing any unusable ones:
+        # https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap.rb
+        #
+        # irb(main):174:0> font_meta.cmap.tables.count
+        # => 3
+        # irb(main):175:0> font_meta.cmap.unicode.count
+        # => 2
+        @font_meta.cmap.tables.each do |table|
+          next if !table.unicode?
+          # Each subtable's `code_map` is a Hash map of character codes (the Hash keys)
+          # to the glyph IDs from the original font (the Hash's values).
+          #
+          # Subtable::encode takes:
+          #  - a Hash mapping character codes to original font glyph IDs.
+          #  - the desired output encoding — Set[:mac_roman, :unicode, :unicode_ucs4]
+          #    https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+          # …and returns a Hash with keys:
+          #  - :charmap  — Hash mapping the characters in the input charmap
+          #                to a another hash containing both the `:old`
+          #                and `:new` glyph ids for each character code.
+          #  - :subtable — String encoded subtable for the given encoding.
+          encoded = TTFunk::Table::Cmap::Subtable::encode(table&.code_map, :unicode).dig(:charmap)
+
+          output << "<span size='49152'>"
+
+          i = 0
+          encoded.each_pair { |c, (old, new)|
+
+            begin
+              if glyph = @font_meta.glyph_outlines.for(c)
+                # Add a space on either side of the character so they aren't
+                # all smooshed up against each other and unreadable.
+                output << ' ' << g_markup_escape_char(c) << ' '
+                if i >= 15
+                  output << cr
+                  i = 0
+                else
+                  i = i + 1
+                end
+              else
+              end
+            rescue NoMethodError => nme
+              # TTFunk's `glyph_outlines.for()` will raise this if we call it
+              # for a codepoint that does not exist in the font, which we will
+              # not do because we are enumerating the codepoints in the font,
+              # but we should still handle the possibility.
+              # irb(main):060:0> font.glyph_outlines.for(555555)
+              #
+              # Traceback (most recent call last):
+              #   6: from /usr/bin/irb:23:in `<main>'
+              #   5: from /usr/bin/irb:23:in `load'
+              #   4: from /home/okeeblow/.gems/gems/irb-1.2.4/exe/irb:11:in `<top (required)>'
+              #   3: from (irb):60
+              #   2: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/glyf.rb:35:in `for'
+              #   1: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/loca.rb:35:in `size_of'
+              # NoMethodError (undefined method `-' for nil:NilClass)
+            end
+          }
+
+          output << '</span>' << cr
+        end
+
+        output << '</span>'
+        output
+      end
+
+      # Return the `src` as the font_path since we aren't using
+      # any of the built-in fonts.
+      def font_path
+        @src
+      end
+
+      def initialize(src, demo: nil)
+        @src = src
+        @demo = demo
+
+        # TODO: Check that src exists, because TTFunk won't and will just
+        # give us an unusable object instead.
+        @font_meta = TTFunk::File.open(src)
+
+        # https://libvips.github.io/libvips/API/current/libvips-create.html#vips-text
+        @image = Vips::Image.text(
+          # This string must be well-escaped Pango Markup:
+          # https://developer.gnome.org/pango/stable/pango-Markup.html
+          # However the official function for escaping text is
+          # not implemented in Ruby GLib, so we have to do it ourselves.
+          to_pango,
+          **{
+            # String absolute path to TTF
+            :fontfile => font_path,
+            # It's not enough to just specify the TTF path;
+            # we must also specify a font family, subfamily, and size.
+            :font => "#{font_name}",
+            # Space between lines (in Points).
+            :spacing => @font_meta.line_gap,
+            # Requires libvips 8.8
+            :justify => false,
+            :dpi => 144,
+          },
+        )
+      end
+
+    end  # Font 
+  end  # DistorteD
+end  # Cooltrainer
+
+
+# Notes on file-format specifics and software-library-specifics
+#
+# # TTF (via TTFunk)
+# 
+# ## Cmap
+#
+# Each TTFunk::Table::Cmap::Format<whatever> class responds to `:supported?`
+# with its own internal boolean telling us if that Format is usable in TTFunk.
+# This has nothing to do with any font file itself, just the library code.
+# irb(main)> font.cmap.tables.map{|t| t.supported?}
+# => [true, true, true]
+#
+# Any subclass of TTFunk::Table::Cmap::Subtable responds to `:unicode?`
+# with a boolean calculated from the instance `@platform_id` and `@encoding_id`,
+# and those numeric IDs are assigned to the symbolic (e.g. `:macroman`) names in:
+# https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+# irb(main)> font.cmap.tables.map{|t| t.unicode?}
+# => [true, false, true]
+# 

data/lib/distorted/image.rb

@@ -0,0 +1,121 @@
+# Requiring libvips 8.8 for HEIC/HEIF (moo) support, `justify` support in the
+# Vips::Image text operator, animated WebP support, and more:
+# https://libvips.github.io/libvips/2019/04/22/What's-new-in-8.8.html
+VIPS_MINIMUM_VER = [8, 8, 0]
+
+# Tell the user to install the shared library if it's missing.
+begin
+  require 'vips'
+
+  we_good = false
+  if Vips::version(0) >= VIPS_MINIMUM_VER[0]
+    if Vips::version(1) >= VIPS_MINIMUM_VER[1]
+      if Vips::version(2) >= VIPS_MINIMUM_VER[2]
+        we_good = true
+      end
+    end
+  end
+  unless we_good
+    raise LoadError.new("libvips is older than DistorteD's minimum requirement: needed #{VIPS_MINIMUM_VER.join('.'.freeze)} vs available '#{Vips::version_string}'")
+  end
+
+rescue LoadError => le
+  # Only match libvips.so load failure
+  raise unless le.message =~ /libvips.so/
+
+  # Multiple OS help
+  help = <<~INSTALL
+
+  Please install the libvips image processing library.
+
+  FreeBSD:
+    pkg install graphics/vips
+
+  macOS:
+    brew install vips
+
+  Debian/Ubuntu/Mint:
+    apt install libvips libvips-dev
+  INSTALL
+
+  # Re-raise with install message
+  raise $!, "#{help}\n#{$!}", $!.backtrace
+end
+
+require 'set'
+
+require 'mime/types'
+
+module Cooltrainer
+  module DistorteD
+    class Image
+
+      MEDIA_TYPE = 'image'.freeze
+
+      # SVG support is a sub-class and not directly supported here:
+      # `write_to_file': No known saver for '/home/okeeblow/Works/cooltrainer/_site/IIDX-turntable.svg'. (Vips::Error)
+      MIME_TYPES = MIME::Types[/^#{MEDIA_TYPE}\/(?!svg)/, :complete => true].to_set
+
+      # Attributes for our <picture>/<img>.
+      # Automatically enabled as attrs for DD Liquid Tag.
+      # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#Attributes
+      # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#Attributes
+      # https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading
+      # :crop is a Vips-only attr
+      ATTRS = Set[:alt, :caption, :href, :crop, :loading]
+
+      # Defaults for HTML Element attributes.
+      # Not every attr has to be listed here.
+      # Many need no default and just won't render.
+      ATTRS_DEFAULT = {
+        :crop => :attention,
+        :loading => :eager,
+      }
+      ATTRS_VALUES = {
+        # https://www.rubydoc.info/gems/ruby-vips/Vips/Interesting
+        :crop => Set[:none, :centre, :entropy, :attention],
+        :loading => Set[:eager, :lazy],
+      }
+
+
+      def initialize(src)
+        @image = Vips::Image.new_from_file(src)
+        @src = src
+      end
+
+      def rotate(angle: nil)
+        if angle == :auto
+          @image = @image&.autorot
+        end
+      end
+
+      def clean
+        # Nuke the entire site from orbit. It's the only way to be sure.
+        @image.get_fields.grep(/exif-ifd/).each {|field| @image.remove field}
+      end
+
+      def save(dest, width: nil, crop: nil)
+        begin
+          if width.nil? or width == :full
+            return @image.write_to_file(dest)
+          elsif width.respond_to?(:to_i)
+            ver = @image.thumbnail_image(
+              width.to_i,
+              # Use `self` namespace for constants so subclasses can redefine
+              **{:crop => crop || self.singleton_class.const_get(:ATTRS_DEFAULT)[:crop]},
+            )
+            return ver.write_to_file(dest)
+          end
+        rescue Vips::Error => v
+          if v.message.include?('No known saver')
+            # TODO: Handle missing output formats. Replacements? Skip it? Die?
+            return nil
+          else
+            raise
+          end
+        end
+      end  # save
+
+    end  # Image
+  end  # DistorteD
+end  # Cooltrainer

data/lib/distorted/modular_technology/pango.rb

@@ -0,0 +1,75 @@
+module Cooltrainer
+  module DistorteD
+    module Tech
+      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
+
+        # 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 `sprintf('&#x%x;', c.ord)`, but I want to copy
+          # the C implementation as closely as possible, which means using
+          # the named escape sequences for common characters and separating
+          # 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 0x7f..0x84, 0x86..0x9f
+            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

data/lib/distorted/monkey_business/hash.rb

@@ -0,0 +1,33 @@
+require 'set'
+
+class Hash
+
+  # Complement Ruby::YAML behavior, where usage of Set syntax
+  # returns a Hash with all-nil values.
+  # Calling :to_set on a Hash with all-nil values should return
+  # a Set of the Hash's keys.
+  this_old_set = instance_method(:to_set)
+  define_method(:to_set) do
+    if self.values.all?{ |v| v.nil? }
+      self.keys.to_set
+    else
+      this_old_set.bind(self).()
+    end
+  end
+  
+  # https://github.com/dam13n/ruby-bury/blob/master/hash.rb
+  # This is not packaged as a Gem or I'd be using it instead of including my own.
+  def bury(*args)
+    if args.count < 2
+      raise ArgumentError.new('2 or more arguments required')
+    elsif args.count == 2
+      self[args[0]] = args[1]
+    else
+      arg = args.shift
+      self[arg] = {} unless self[arg]
+      self[arg].bury(*args) unless args.empty?
+    end
+    self
+  end
+
+end

data/lib/distorted/monkey_business/mnemoniq.rb

@@ -0,0 +1,8 @@
+require 'mime/types'
+
+# MIME::Types#preferred_extension returns @extensions.first unless
+# otherwise set. I don't like some of the defaults, so this file
+# changes them.
+# Normally I don't like to monkey patch just on import without calling
+# some method, but this is one time I explicitly want to do that.
+MIME::Types['image/jpeg'].last.preferred_extension = 'jpg'

data/lib/distorted/monkey_business/set.rb

@@ -0,0 +1,15 @@
+require 'set'
+
+# Override Set.to_hash to complement Ruby::YAML's Set implementation,
+# where the YAML Set syntax returns a Hash with all-nil values,
+# at least without some decorator sugar in the YAML itself:
+# https://rhnh.net/2011/01/31/yaml-tutorial/
+#
+# Since Set is implemented using a Hash internally I think it makes
+# more sense for Set.to_hash to return a Hash with all-nil values
+# with keys matching the contents of the original Set.
+class Set
+  def to_hash
+    Hash[self.map { |s| [s, nil] }]
+  end
+end