stationery 0.1.0 → 0.3.0

data/lib/stationery/fonts/installer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Copies a catalog pack into `<into>/<pack>/`: every file is fetched (or
+    # read from `from:`, a directory or .tar.gz, for offline installs) and its
+    # SHA-256 checked before anything is written, then each file is written to
+    # a temporary name and renamed into place. Existing files are kept unless
+    # `force:`. Development-time only; documents never download fonts.
+    class Installer
+      # Fetches an https URL, following up to five redirects.
+      HTTP = lambda do |url, redirects = 5|
+        require "net/http"
+        uri = URI(url)
+        raise Error, "refusing to download over #{uri.scheme}: #{url} (https only)" unless uri.scheme == "https"
+
+        response = Net::HTTP.get_response(uri)
+        case response
+        when Net::HTTPSuccess then response.body.b
+        when Net::HTTPRedirection
+          raise Error, "too many redirects fetching #{url}" if redirects.zero?
+
+          HTTP.call(uri.merge(response["location"]).to_s, redirects - 1)
+        else raise Error, "HTTP #{response.code} fetching #{url}"
+        end
+      end
+
+      attr_reader :into
+
+      def initialize(into: DEFAULT_DIR, force: false, from: nil, fetcher: HTTP, out: nil)
+        @into = into
+        @force = force
+        @from = from
+        @fetcher = fetcher
+        @out = out
+        @archives = {}
+      end
+
+      # Installs one pack; returns { style => path }.
+      def install(key)
+        pack = Catalog.fetch(key)
+        dir = File.join(@into, pack.key.to_s)
+        entries = [*pack.files.values, pack.license_file]
+        pending = entries.filter_map { |entry| [entry, File.join(dir, entry.last)] unless keep?(entry.last, dir) }
+        verified = pending.map { |(url, sha, name), target| [target, verify(name, sha, read(url, name))] }
+        verified.each { |target, bytes| write(target, bytes) }
+        pack.files.transform_values { |(*, name)| File.join(dir, name) }
+      end
+
+      private
+
+      def keep?(name, dir)
+        target = File.join(dir, name)
+        return false if @force || !File.exist?(target)
+
+        say "exists #{target} (--force replaces it)"
+        true
+      end
+
+      def read(url, name)
+        source = source_name(url, name)
+        return offline(source) if @from
+        return File.binread(File.join(Bundled::DIR, source)) unless url
+
+        location, member = url.split("#", 2)
+        bytes = @archives[location] ||= fetch(location)
+        member ? untar(bytes, location, member) { it == member } : bytes
+      end
+
+      def source_name(url, name) = url ? File.basename(url.split("#").last) : name
+
+      def fetch(url)
+        say "fetch #{url}"
+        @fetcher.call(url)
+      end
+
+      def offline(source)
+        if File.directory?(@from)
+          path = Dir.glob("**/#{source}", base: @from).min or raise Error, "#{source} not found in #{@from}"
+          File.binread(File.join(@from, path))
+        else
+          @archives[@from] ||= File.binread(@from)
+          untar(@archives[@from], @from, source) { File.basename(it) == source }
+        end
+      end
+
+      # The first file in a .tar.gz whose member name the block accepts.
+      def untar(bytes, label, wanted)
+        require "rubygems/package"
+        require "stringio"
+        require "zlib"
+        tar = StringIO.new(Zlib::GzipReader.new(StringIO.new(bytes)).read)
+        Gem::Package::TarReader.new(tar).each do |entry|
+          return entry.read.b if entry.file? && yield(entry.full_name)
+        end
+        raise Error, "#{wanted} not found in #{label}"
+      end
+
+      def verify(name, sha, bytes)
+        require "digest"
+        actual = Digest::SHA256.hexdigest(bytes)
+        return bytes if actual == sha
+
+        raise Error, "SHA-256 mismatch for #{name}: expected #{sha}, got #{actual}; nothing written"
+      end
+
+      def write(target, bytes)
+        require "fileutils"
+        FileUtils.mkdir_p(File.dirname(target))
+        temp = "#{target}.#{Process.pid}.tmp"
+        File.binwrite(temp, bytes)
+        File.rename(temp, target)
+        say "wrote #{target}"
+      ensure
+        FileUtils.rm_f(temp) if temp
+      end
+
+      def say(line) = @out&.puts(line)
+    end
+  end
+end

data/lib/stationery/fonts/kern_table.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Pair kerning from a TrueType `kern` table: the OpenType (version 0)
+    # layout with horizontal format 0 subtables. Apple's version 1 table,
+    # vertical, cross-stream and class-based subtables are ignored.
+    class KernTable
+      HORIZONTAL = 0x0001
+      CROSS_STREAM = 0x0004
+      OVERRIDE = 0x0008
+      SUBTABLE_HEADER = 6
+      PAIR = 6
+
+      # nil when the font has no usable kern table.
+      def self.parse(ttf)
+        offset = ttf.table_offset("kern")
+        return unless offset && ttf.u16(offset).zero?
+
+        pairs = {}
+        cursor = offset + 4
+        ttf.u16(offset + 2).times { cursor = read_subtable(ttf, cursor, pairs) }
+        new(pairs)
+      end
+
+      # Returns the offset of the next subtable. A format 0 subtable's length
+      # is derived from its pair count: large tables overflow the 16-bit field.
+      def self.read_subtable(ttf, offset, pairs)
+        coverage = ttf.u16(offset + 4)
+        return offset + ttf.u16(offset + 2) unless (coverage >> 8).zero?
+
+        count = ttf.u16(offset + SUBTABLE_HEADER)
+        start = offset + SUBTABLE_HEADER + 8
+        if coverage.anybits?(HORIZONTAL) && coverage.nobits?(CROSS_STREAM)
+          ttf.data.byteslice(start, count * PAIR).unpack("nns>" * count).each_slice(3) do |left, right, value|
+            key = (left << 16) | right
+            pairs[key] = coverage.nobits?(OVERRIDE) ? pairs.fetch(key, 0) + value : value
+          end
+        end
+        start + (count * PAIR)
+      end
+      private_class_method :read_subtable
+
+      def initialize(pairs)
+        @pairs = pairs.freeze
+        freeze
+      end
+
+      def adjust(left, right) = @pairs.fetch((left << 16) | right, 0)
+    end
+  end
+end

data/lib/stationery/fonts/kerning.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Chooses where a font's pair kerning comes from. Every source answers
+    # `adjust(left_gid, right_gid)` with an extra advance in font units.
+    module Kerning
+      # For fonts without kerning data.
+      module NONE
+        def self.adjust(_left, _right) = 0
+      end
+
+      # A GPOS `kern` feature takes precedence over the legacy `kern` table.
+      def self.for(ttf) = Gpos.parse(ttf) || KernTable.parse(ttf) || NONE
+    end
+  end
+end

data/lib/stationery/fonts/ligatures.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Chooses where a font's ligatures come from. Every source answers
+    # `substitute(gids)` with [[gid, source glyph count], ...].
+    module Ligatures
+      # For fonts without ligatures: every glyph stands for itself.
+      module NONE
+        def self.substitute(gids) = gids.map { |gid| [gid, 1] }
+      end
+
+      def self.for(ttf) = Gsub.parse(ttf) || NONE
+    end
+  end
+end

data/lib/stationery/fonts/packs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Font packs: `Fonts.install(:noto_sans)` copies a catalog pack into
+  # vendor/fonts/noto_sans/, after which `font_family "Noto Sans"` finds it
+  # through `Stationery.font_paths` (the Railtie adds vendor/fonts).
+  module Fonts
+    DEFAULT_DIR = "vendor/fonts"
+
+    def self.catalog = Catalog::PACKS
+
+    def self.install(key, into: DEFAULT_DIR, **) = Installer.new(into:, **).install(key)
+
+    # { style => path } for a pack installed under dir.
+    def self.paths(key, dir: DEFAULT_DIR)
+      pack = Catalog.fetch(key)
+      pack.files.transform_values { |(*, file)| File.join(dir, pack.key.to_s, file) }
+    end
+
+    # Ruby lines selecting an installed pack.
+    def self.usage(key, dir)
+      pack = Catalog.fetch(key)
+      short = "font_family #{pack.family.inspect}"
+      return [short] if Stationery.font_paths.include?(File.expand_path(dir))
+
+      ["#{short}  # when #{dir} is in Stationery.font_paths (Rails adds vendor/fonts)",
+       "#{short}, **Stationery::Fonts.paths(:#{pack.key}, dir: #{dir.inspect})"]
+    end
+
+    # Installed packs found by family name in Stationery.font_paths.
+    module Packs
+      def self.family(name)
+        Catalog::PACKS.each do |pack|
+          next unless pack.family.casecmp?(name.to_s)
+
+          Stationery.font_paths.each do |dir|
+            paths = Fonts.paths(pack.key, dir:).select { |_, path| File.file?(path) }
+            return Family.new(pack.family, **paths) if paths[:regular]
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/stationery/fonts/registry.rb

@@ -2,21 +2,24 @@
 
 module Stationery
   module Fonts
-    # Process-wide cache of parsed TrueType files, keyed by path and mtime so an
-    # edited font is re-read. Parsing is the expensive part; the per-document
-    # Font objects that track used glyphs are cheap wrappers around a parse.
+    # Process-wide cache of parsed TrueType files, keyed by path, face and
+    # mtime so an edited font is re-read. Parsing is the expensive part; the
+    # per-document Font objects that track used glyphs are cheap wrappers
+    # around a parse. A `#N` suffix on the path picks face N of a collection.
     module Registry
       SIZE = 16
+      FACE = /\A(.+)#(\d+)\z/
       @cache = {}
       @mutex = Mutex.new
 
       class << self
         def load(path)
-          path = File.expand_path(path.to_s)
+          path, index = split(path.to_s)
+          path = File.expand_path(path)
           raise UnsupportedFont, "font file not found: #{path}" unless File.file?(path)
 
           mtime = File.mtime(path)
-          @mutex.synchronize { fetch(path, mtime) }
+          @mutex.synchronize { fetch(path, index, mtime) }
         end
 
         def clear
@@ -25,10 +28,16 @@ module Stationery
 
         private
 
-        def fetch(path, mtime)
-          cached_mtime, ttf = @cache.delete(path)
-          ttf = TrueType.new(File.binread(path)) unless cached_mtime == mtime
-          @cache[path] = [mtime, ttf]
+        def split(path)
+          match = FACE.match(path)
+          match ? [match[1], match[2].to_i] : [path, 0]
+        end
+
+        def fetch(path, index, mtime)
+          key = [path, index]
+          cached_mtime, ttf = @cache.delete(key)
+          ttf = TrueType.new(File.binread(path), index:) unless cached_mtime == mtime
+          @cache[key] = [mtime, ttf]
           @cache.shift while @cache.size > SIZE
           ttf
         end

data/lib/stationery/fonts/sfnt_metrics.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # The hhea, post and OS/2 metrics of an sfnt font, with fallbacks for the
+    # optional tables. Included by TrueType.
+    module SfntMetrics
+      private
+
+      def parse_hhea
+        t = table_offset("hhea")
+        @ascender = i16(t + 4)
+        @descender = i16(t + 6)
+        @line_gap = i16(t + 8)
+        @number_of_hmetrics = u16(t + 34)
+      end
+
+      def parse_post
+        if (t = table_offset("post"))
+          @italic_angle = i16(t + 4) + (u16(t + 6) / 65_536.0)
+          @underline_position = i16(t + 8)
+          @underline_thickness = i16(t + 10)
+          @fixed_pitch = u32(t + 12) != 0
+        else
+          @italic_angle = 0
+          @underline_position = -@units_per_em / 10
+          @underline_thickness = @units_per_em / 20
+          @fixed_pitch = false
+        end
+      end
+
+      def parse_os2
+        if (t = table_offset("OS/2"))
+          @weight = u16(t + 4)
+          @strikeout_size = i16(t + 26)
+          @strikeout_position = i16(t + 28)
+          if u16(t) >= 2
+            @x_height = i16(t + 86)
+            @cap_height = i16(t + 88)
+          end
+        end
+
+        @weight ||= 400
+        @strikeout_size ||= @underline_thickness
+        @strikeout_position ||= (@ascender * 0.25).round
+        @x_height ||= (@ascender * 0.5).round
+        @cap_height = (@ascender * 0.7).round if @cap_height.nil?
+      end
+    end
+  end
+end

data/lib/stationery/fonts/to_unicode.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # The ToUnicode CMap mapping each two-byte character code a document drew
+    # back to its text, so the PDF extracts and searches correctly.
+    module ToUnicode
+      module_function
+
+      # `chars` is { code => text }; a ligature maps to several characters.
+      def cmap(chars)
+        mappings = chars.sort.map do |code, char|
+          format("<%<code>04X> <%<utf16>s>", code:, utf16: char.encode(Encoding::UTF_16BE).unpack1("H*").upcase)
+        end
+        blocks = mappings.each_slice(100).map { |slice| "#{slice.size} beginbfchar\n#{slice.join("\n")}\nendbfchar" }
+
+        <<~CMAP
+          /CIDInit /ProcSet findresource begin
+          12 dict begin
+          begincmap
+          /CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def
+          /CMapName /Adobe-Identity-UCS def
+          /CMapType 2 def
+          1 begincodespacerange
+          <0000> <FFFF>
+          endcodespacerange
+          #{blocks.join("\n")}
+          endcmap
+          CMapName currentdict /CMap defineresource pop
+          end
+          end
+        CMAP
+      end
+    end
+  end
+end

data/lib/stationery/fonts/true_type.rb

@@ -2,16 +2,20 @@
 
 module Stationery
   module Fonts
-    # Reads the tables of a TrueType (.ttf) font needed to measure text and to
-    # embed a subset of it. Static TrueType outlines only: CFF (.otf), font
-    # collections and web font wrappers are rejected with a named reason.
+    # Reads the sfnt tables of a static font needed to measure text and to
+    # embed it: TrueType outlines (.ttf) or CFF outlines (.otf), alone or as one
+    # face of a collection (.ttc), or unwrapped from a WOFF web font. Variable
+    # CFF2 fonts and WOFF2 are rejected with a named reason.
     class TrueType
-      REQUIRED_TABLES = %w[head hhea maxp hmtx loca glyf].freeze
+      include SfntMetrics
+
+      REQUIRED_TABLES = %w[head hhea maxp hmtx].freeze
+      OUTLINE_TABLES = { "OTTO" => ["CFF "] }.freeze
+      GLYF_TABLES = %w[loca glyf].freeze
+      SFNT_VERSIONS = ["\x00\x01\x00\x00".b, "true", "OTTO"].freeze
+      COLLECTION = "ttcf"
       SIGNATURES = {
-        "OTTO" => "OpenType fonts with CFF outlines (.otf) are not supported, use a TrueType (.ttf) font",
-        "ttcf" => "TrueType collections (.ttc) are not supported, use a single TrueType (.ttf) font",
-        "wOFF" => "WOFF web fonts are not supported, use the TrueType (.ttf) file",
-        "wOF2" => "WOFF2 web fonts are not supported, use the TrueType (.ttf) file"
+        "wOF2" => "WOFF2 needs Brotli; convert to .ttf or .woff"
       }.freeze
 
       attr_reader :data, :tables, :units_per_em, :bbox, :ascender, :descender, :line_gap, :num_glyphs,
@@ -19,22 +23,31 @@ module Stationery
                   :strikeout_position, :strikeout_size, :cap_height, :x_height, :weight, :postscript_name
 
       # A subset embedded in a PDF carries no cmap (the PDF maps glyphs itself),
-      # so reading one back passes `cmap: false`.
-      def initialize(data, cmap: true)
+      # so reading one back passes `cmap: false`. `index:` picks a face of a
+      # collection, face 0 by default.
+      def initialize(data, cmap: true, index: nil)
         @data = data.b
+        @data = WOFF.unpack(@data) if @data.start_with?(WOFF::SIGNATURE)
+        @sfnt = face_offset(index || 0)
         check_signature
         read_table_directory(cmap)
         parse_head
         parse_hhea
         parse_maxp
         parse_hmtx
-        parse_loca
+        parse_loca unless cff?
         @cmap = cmap ? Cmap.parse(self) : {}
         parse_post
         parse_os2
         @postscript_name = NameTable.postscript_name(self)
       end
 
+      def self.collection?(data) = data.byteslice(0, 4) == COLLECTION
+
+      def self.faces(data)
+        collection?(data) ? data.byteslice(8, 4).unpack1("N") : 1
+      end
+
       def inspect = "#<#{self.class} #{@postscript_name} glyphs=#{@num_glyphs}>"
 
       def glyph_id(codepoint)
@@ -57,6 +70,26 @@ module Stationery
         end
       end
 
+      # Pair kerning, read on first use. Shared by every document using this
+      # parse; the source is immutable once built.
+      def kerning
+        @kerning ||= Kerning.for(self)
+      end
+
+      # Standard ligatures, read on first use and shared like #kerning.
+      def ligatures
+        @ligatures ||= Ligatures.for(self)
+      end
+
+      def cff?
+        @tables.key?("CFF ")
+      end
+
+      # The CFF table, read on first use; nil for TrueType outlines.
+      def cff
+        @cff ||= CFF.new(table_data("CFF ")) if cff?
+      end
+
       def fixed_pitch?
         @fixed_pitch
       end
@@ -86,22 +119,36 @@ module Stationery
 
       private
 
+      # Table offsets in a collection are already absolute, so a face is read
+      # from the shared data at its own table directory.
+      def face_offset(index)
+        count = self.class.faces(@data)
+        unless index.between?(0, count - 1)
+          raise ArgumentError, "font face #{index} is out of range (numFonts #{count})"
+        end
+
+        self.class.collection?(@data) ? u32(12 + (index * 4)) : 0
+      end
+
       def check_signature
-        signature = @data.byteslice(0, 4)
-        return if ["\x00\x01\x00\x00".b, "true"].include?(signature)
+        signature = @data.byteslice(@sfnt, 4)
+        return if SFNT_VERSIONS.include?(signature)
 
         raise UnsupportedFont, SIGNATURES.fetch(signature, "not a TrueType font")
       end
 
       def read_table_directory(cmap)
         @tables = {}
-        u16(4).times do |i|
-          record = 12 + (i * 16)
+        u16(@sfnt + 4).times do |i|
+          record = @sfnt + 12 + (i * 16)
           @tables[@data.byteslice(record, 4)] = [u32(record + 8), u32(record + 12)]
         end
-        required = cmap ? REQUIRED_TABLES + ["cmap"] : REQUIRED_TABLES
+        raise UnsupportedFont, "variable CFF2 fonts are not supported" if @tables.key?("CFF2")
+
+        required = REQUIRED_TABLES + OUTLINE_TABLES.fetch(@data.byteslice(@sfnt, 4), GLYF_TABLES)
+        required += ["cmap"] if cmap
         missing = required.reject { |tag| @tables.key?(tag) }
-        raise UnsupportedFont, "font is missing the #{missing.join(", ")} table" if missing.any?
+        raise UnsupportedFont, "font is missing the #{missing.map(&:strip).join(", ")} table" if missing.any?
       end
 
       def parse_head
@@ -111,14 +158,6 @@ module Stationery
         @index_to_loc_format = i16(t + 50)
       end
 
-      def parse_hhea
-        t = table_offset("hhea")
-        @ascender = i16(t + 4)
-        @descender = i16(t + 6)
-        @line_gap = i16(t + 8)
-        @number_of_hmetrics = u16(t + 34)
-      end
-
       def parse_maxp
         @num_glyphs = u16(table_offset("maxp") + 4)
       end
@@ -137,38 +176,6 @@ module Stationery
                 end
         @glyf_offset = table_offset("glyf")
       end
-
-      def parse_post
-        if (t = table_offset("post"))
-          @italic_angle = i16(t + 4) + (u16(t + 6) / 65_536.0)
-          @underline_position = i16(t + 8)
-          @underline_thickness = i16(t + 10)
-          @fixed_pitch = u32(t + 12) != 0
-        else
-          @italic_angle = 0
-          @underline_position = -@units_per_em / 10
-          @underline_thickness = @units_per_em / 20
-          @fixed_pitch = false
-        end
-      end
-
-      def parse_os2
-        if (t = table_offset("OS/2"))
-          @weight = u16(t + 4)
-          @strikeout_size = i16(t + 26)
-          @strikeout_position = i16(t + 28)
-          if u16(t) >= 2
-            @x_height = i16(t + 86)
-            @cap_height = i16(t + 88)
-          end
-        end
-
-        @weight ||= 400
-        @strikeout_size ||= @underline_thickness
-        @strikeout_position ||= (@ascender * 0.25).round
-        @x_height ||= (@ascender * 0.5).round
-        @parse_os2 ||= (@ascender * 0.7).round
-      end
     end
   end
 end

data/lib/stationery/fonts/woff.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Stationery
+  module Fonts
+    # Unwraps a WOFF 1.0 web font into the sfnt it was made from: each table is
+    # inflated (or copied when stored) and laid out behind a fresh table
+    # directory, 4-byte aligned in directory order. Metadata and private data
+    # blocks are dropped.
+    module WOFF
+      SIGNATURE = "wOFF"
+      HEADER = 44
+      ENTRY = 20
+
+      module_function
+
+      def unpack(data)
+        data = data.b
+        flavor = data.byteslice(4, 4)
+        tables = Array.new(data.byteslice(12, 2).unpack1("n")) do |i|
+          tag, offset, compressed, length, checksum = data.byteslice(HEADER + (i * ENTRY), ENTRY).unpack("a4NNNN")
+          [tag, checksum, table(tag, data.byteslice(offset, compressed), length)]
+        end
+        assemble(flavor, tables)
+      end
+
+      def table(tag, bytes, length)
+        return bytes if bytes.bytesize >= length
+
+        Zlib::Inflate.inflate(bytes)
+      rescue Zlib::Error
+        raise UnsupportedFont, "corrupt WOFF table #{tag}"
+      end
+
+      def assemble(flavor, tables)
+        entry_selector = Math.log2(tables.size).floor
+        search_range = (2**entry_selector) * 16
+        directory = [flavor, tables.size, search_range, entry_selector, (tables.size * 16) - search_range]
+                    .pack("a4nnnn")
+        body = String.new(encoding: Encoding::BINARY)
+        offset = 12 + (tables.size * 16)
+
+        tables.each do |tag, checksum, bytes|
+          directory << [tag, checksum, offset + body.bytesize, bytes.bytesize].pack("a4NNN")
+          body << bytes << ("\0".b * (-bytes.bytesize % 4))
+        end
+        directory << body
+      end
+    end
+  end
+end

data/lib/stationery/html/document.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "tokenizer"
+require_relative "tree_builder"
+
+module Stationery
+  # Lenient HTML to rich-text blocks (see Stationery::Rich).
+  module HTML
+    def self.parse(source) = TreeBuilder.parse(Tokenizer.tokenize(source))
+  end
+end