stationery 0.1.0 → 0.2.0

data/lib/stationery/testing/matchers.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "inspector"
+
+module Stationery
+  module Testing
+    # Framework-independent PDF matchers: each answers matches?(subject),
+    # failure_message, failure_message_when_negated and description, so RSpec
+    # uses them directly and Minitest assertions wrap them.
+    module Matchers
+      EXCERPT = 500
+
+      class Base
+        def initialize(expected = nil)
+          @expected = expected
+        end
+
+        def matches?(subject)
+          @inspector = subject.is_a?(Inspector) ? subject : Inspector.new(subject)
+          match?(@inspector)
+        end
+
+        def failure_message = "expected PDF to #{description}, #{actual}"
+        def failure_message_when_negated = "expected PDF not to #{description}, #{actual}"
+
+        private
+
+        def show(expected) = expected.is_a?(Regexp) ? expected.inspect : expected.to_s.inspect
+
+        def contains?(haystack, expected)
+          expected.is_a?(Regexp) ? expected.match?(haystack) : haystack.include?(expected.to_s)
+        end
+
+        def excerpt(text)
+          text.length > EXCERPT ? "#{text[0, EXCERPT]}…" : text
+        end
+      end
+
+      class HaveText < Base
+        def description = "have text #{show(@expected)}"
+
+        private
+
+        def match?(pdf) = contains?(pdf.text, @expected)
+        def actual = "got text:\n#{excerpt(@inspector.text)}"
+      end
+
+      class HaveTextOnPage < Base
+        def initialize(page, expected)
+          super(expected)
+          @page = page
+        end
+
+        def description = "have text #{show(@expected)} on page #{@page}"
+
+        private
+
+        def page_text = @inspector.page_texts.fetch(@page - 1, nil)
+        def match?(_pdf) = !page_text.nil? && contains?(page_text, @expected)
+
+        def actual
+          return "but it has #{@inspector.page_count} page(s)" if page_text.nil?
+
+          "got text on page #{@page}:\n#{excerpt(page_text)}"
+        end
+      end
+
+      class HavePageCount < Base
+        def description = "have #{@expected} page(s)"
+
+        private
+
+        def match?(pdf) = pdf.page_count == @expected
+        def actual = "got #{@inspector.page_count}"
+      end
+
+      class HaveLink < Base
+        def description = "have a link to #{show(@expected)}"
+
+        private
+
+        def match?(pdf) = pdf.links.any? { |url| @expected.is_a?(Regexp) ? @expected.match?(url) : url == @expected }
+        def actual = "got links #{@inspector.links.inspect}"
+      end
+
+      class HaveImageCount < Base
+        def description = "have #{@expected} image(s)"
+
+        private
+
+        def match?(pdf) = pdf.image_count == @expected
+        def actual = "got #{@inspector.image_count}"
+      end
+
+      class HaveBookmark < Base
+        def description = "have a bookmark #{show(@expected)}"
+
+        private
+
+        def match?(pdf) = pdf.bookmarks.include?(@expected)
+        def actual = "got bookmarks #{@inspector.bookmarks.inspect}"
+      end
+
+      class HaveNoWarnings < Base
+        def description = "have no warnings"
+
+        private
+
+        def match?(pdf) = pdf.warnings.empty?
+        def messages = @inspector.warnings.map(&:message)
+        def actual = messages.empty? ? "got none" : "got:\n#{messages.map { |m| "  - #{m}" }.join("\n")}"
+      end
+
+      def have_pdf_text(expected) = HaveText.new(expected)
+      def have_pdf_text_on_page(page, expected) = HaveTextOnPage.new(page, expected)
+      def have_page_count(expected) = HavePageCount.new(expected)
+      def have_pdf_link(expected) = HaveLink.new(expected)
+      def have_image_count(expected) = HaveImageCount.new(expected)
+      def have_bookmark(title) = HaveBookmark.new(title)
+      def have_no_warnings = HaveNoWarnings.new
+    end
+  end
+end

data/lib/stationery/text/entities/html4.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Text
+    module Entities
+      # The 252 named character references of HTML 4.
+      HTML4 = { # rubocop:disable Metrics/CollectionLiteralLength
+        "AElig" => "Æ", "Aacute" => "Á", "Acirc" => "Â", "Agrave" => "À", "Alpha" => "Α", "Aring" => "Å",
+        "Atilde" => "Ã", "Auml" => "Ä", "Beta" => "Β", "Ccedil" => "Ç", "Chi" => "Χ", "Dagger" => "‡", "Delta" => "Δ",
+        "ETH" => "Ð", "Eacute" => "É", "Ecirc" => "Ê", "Egrave" => "È", "Epsilon" => "Ε", "Eta" => "Η", "Euml" => "Ë",
+        "Gamma" => "Γ", "Iacute" => "Í", "Icirc" => "Î", "Igrave" => "Ì", "Iota" => "Ι", "Iuml" => "Ï", "Kappa" => "Κ",
+        "Lambda" => "Λ", "Mu" => "Μ", "Ntilde" => "Ñ", "Nu" => "Ν", "OElig" => "Œ", "Oacute" => "Ó", "Ocirc" => "Ô",
+        "Ograve" => "Ò", "Omega" => "Ω", "Omicron" => "Ο", "Oslash" => "Ø", "Otilde" => "Õ", "Ouml" => "Ö",
+        "Phi" => "Φ", "Pi" => "Π", "Prime" => "″", "Psi" => "Ψ", "Rho" => "Ρ", "Scaron" => "Š", "Sigma" => "Σ",
+        "THORN" => "Þ", "Tau" => "Τ", "Theta" => "Θ", "Uacute" => "Ú", "Ucirc" => "Û", "Ugrave" => "Ù",
+        "Upsilon" => "Υ", "Uuml" => "Ü", "Xi" => "Ξ", "Yacute" => "Ý", "Yuml" => "Ÿ", "Zeta" => "Ζ", "aacute" => "á",
+        "acirc" => "â", "acute" => "´", "aelig" => "æ", "agrave" => "à", "alefsym" => "ℵ", "alpha" => "α", "amp" => "&",
+        "and" => "∧", "ang" => "∠", "aring" => "å", "asymp" => "≈", "atilde" => "ã", "auml" => "ä", "bdquo" => "„",
+        "beta" => "β", "brvbar" => "¦", "bull" => "•", "cap" => "∩", "ccedil" => "ç", "cedil" => "¸", "cent" => "¢",
+        "chi" => "χ", "circ" => "ˆ", "clubs" => "♣", "cong" => "≅", "copy" => "©", "crarr" => "↵", "cup" => "∪",
+        "curren" => "¤", "dArr" => "⇓", "dagger" => "†", "darr" => "↓", "deg" => "°", "delta" => "δ", "diams" => "♦",
+        "divide" => "÷", "eacute" => "é", "ecirc" => "ê", "egrave" => "è", "empty" => "∅", "emsp" => "\u2003",
+        "ensp" => "\u2002", "epsilon" => "ε", "equiv" => "≡", "eta" => "η", "eth" => "ð", "euml" => "ë", "euro" => "€",
+        "exist" => "∃", "fnof" => "ƒ", "forall" => "∀", "frac12" => "½", "frac14" => "¼", "frac34" => "¾",
+        "frasl" => "⁄", "gamma" => "γ", "ge" => "≥", "gt" => ">", "hArr" => "⇔", "harr" => "↔", "hearts" => "♥",
+        "hellip" => "…", "iacute" => "í", "icirc" => "î", "iexcl" => "¡", "igrave" => "ì", "image" => "ℑ",
+        "infin" => "∞", "int" => "∫", "iota" => "ι", "iquest" => "¿", "isin" => "∈", "iuml" => "ï", "kappa" => "κ",
+        "lArr" => "⇐", "lambda" => "λ", "lang" => "〈", "laquo" => "«", "larr" => "←", "lceil" => "⌈", "ldquo" => "“",
+        "le" => "≤", "lfloor" => "⌊", "lowast" => "∗", "loz" => "◊", "lrm" => "\u200E", "lsaquo" => "‹", "lsquo" => "‘",
+        "lt" => "<", "macr" => "¯", "mdash" => "—", "micro" => "µ", "middot" => "·", "minus" => "−", "mu" => "μ",
+        "nabla" => "∇", "nbsp" => "\u00A0", "ndash" => "–", "ne" => "≠", "ni" => "∋", "not" => "¬", "notin" => "∉",
+        "nsub" => "⊄", "ntilde" => "ñ", "nu" => "ν", "oacute" => "ó", "ocirc" => "ô", "oelig" => "œ", "ograve" => "ò",
+        "oline" => "‾", "omega" => "ω", "omicron" => "ο", "oplus" => "⊕", "or" => "∨", "ordf" => "ª", "ordm" => "º",
+        "oslash" => "ø", "otilde" => "õ", "otimes" => "⊗", "ouml" => "ö", "para" => "¶", "part" => "∂", "permil" => "‰",
+        "perp" => "⊥", "phi" => "φ", "pi" => "π", "piv" => "ϖ", "plusmn" => "±", "pound" => "£", "prime" => "′",
+        "prod" => "∏", "prop" => "∝", "psi" => "ψ", "quot" => "\"", "rArr" => "⇒", "radic" => "√", "rang" => "〉",
+        "raquo" => "»", "rarr" => "→", "rceil" => "⌉", "rdquo" => "”", "real" => "ℜ", "reg" => "®", "rfloor" => "⌋",
+        "rho" => "ρ", "rlm" => "\u200F", "rsaquo" => "›", "rsquo" => "’", "sbquo" => "‚", "scaron" => "š",
+        "sdot" => "⋅", "sect" => "§", "shy" => "\u00AD", "sigma" => "σ", "sigmaf" => "ς", "sim" => "∼", "spades" => "♠",
+        "sub" => "⊂", "sube" => "⊆", "sum" => "∑", "sup" => "⊃", "sup1" => "¹", "sup2" => "²", "sup3" => "³",
+        "supe" => "⊇", "szlig" => "ß", "tau" => "τ", "there4" => "∴", "theta" => "θ", "thetasym" => "ϑ",
+        "thinsp" => "\u2009", "thorn" => "þ", "tilde" => "˜", "times" => "×", "trade" => "™", "uArr" => "⇑",
+        "uacute" => "ú", "uarr" => "↑", "ucirc" => "û", "ugrave" => "ù", "uml" => "¨", "upsih" => "ϒ", "upsilon" => "υ",
+        "uuml" => "ü", "weierp" => "℘", "xi" => "ξ", "yacute" => "ý", "yen" => "¥", "yuml" => "ÿ", "zeta" => "ζ",
+        "zwj" => "\u200D", "zwnj" => "\u200C"
+      }.freeze
+    end
+  end
+end

data/lib/stationery/text/entities.rb

@@ -14,10 +14,15 @@ module Stationery
           name = Regexp.last_match(1)
           if name.start_with?("#x") then [name[2..].to_i(16)].pack("U")
           elsif name.start_with?("#") then [name[1..].to_i].pack("U")
-          else NAMED.fetch(name, entity)
+          else NAMED.fetch(name) { html4.fetch(name, entity) }
           end
         end
       end
+
+      def html4
+        require_relative "entities/html4" unless defined?(HTML4)
+        HTML4
+      end
     end
   end
 end

data/lib/stationery/text/line.rb

@@ -7,12 +7,14 @@ module Stationery
     Fragment = Data.define(:text, :style, :font, :face, :width, :x)
 
     # One laid-out line. Vertical metrics come from its tallest fragment (or
-    # from the paragraph's base style when the line is empty).
+    # from the paragraph's base style when the line is empty). A soft-wrapped
+    # line is justifiable; the last line and one ended by a newline are not.
     class Line
       attr_reader :fragments, :width, :ascent, :descent, :height
 
-      def initialize(fragments, fallback)
+      def initialize(fragments, fallback, justifiable: false)
         @fragments = fragments
+        @justifiable = justifiable
         @width = fragments.sum(&:width)
         metrics = fragments.empty? ? [fallback] : fragments.map { |f| [f.font, f.style.render_size] }
         @ascent = metrics.map { |font, size| font.ascender(size) }.max
@@ -21,6 +23,10 @@ module Stationery
       end
 
       def text = fragments.map(&:text).join
+      def justifiable? = @justifiable
+
+      # U+0020 spaces only: justification stretches those, never tabs.
+      def space_count = fragments.sum { |fragment| fragment.text.count(" ") }
     end
   end
 end

data/lib/stationery/text/paragraph.rb

@@ -10,13 +10,13 @@ module Stationery
       attr_reader :runs, :lines, :width, :align, :leading
 
       def initialize(runs, book:, width:, align: :left, leading: 0, lines: nil, fallback_style: nil)
-        @runs = runs
+        @runs = lines ? runs : book.fallback(runs)
         @book = book
         @width = width
         @align = align
         @leading = leading
         @fallback_style = fallback_style || runs.first&.style
-        @lines = lines || Wrapper.new(book).wrap(runs, width, fallback_style: @fallback_style)
+        @lines = lines || Wrapper.new(book).wrap(@runs, width, fallback_style: @fallback_style)
       end
 
       def height
@@ -47,7 +47,12 @@ module Stationery
         top = y
         @lines.each do |line|
           offset = x + Geometry.align_offset(@align, @width, line.width)
-          line.fragments.each { |fragment| draw_fragment(canvas, fragment, offset, top, line) }
+          extra = word_spacing(line)
+          spaces = 0
+          line.fragments.each do |fragment|
+            draw_fragment(canvas, fragment, offset + (extra * spaces), top, line, extra)
+            spaces += fragment.text.count(" ")
+          end
           top += line.height + @leading
         end
       end
@@ -82,16 +87,32 @@ module Stationery
         @runs.map { |run| Run.new(run.text, run.style.with(size: [run.style.size * factor, MIN_SHRINK_SIZE].max)) }
       end
 
-      def draw_fragment(canvas, fragment, offset, top, line)
+      # Extra points per space that stretch a justifiable line to the width.
+      def word_spacing(line)
+        return 0 unless @align == :justify && line.justifiable? && line.space_count.positive?
+
+        [(@width - line.width) / line.space_count, 0].max
+      end
+
+      def draw_fragment(canvas, fragment, offset, top, line, word_spacing)
         style = fragment.style
+        count_missing(fragment)
         x = offset + fragment.x
-        canvas.text(fragment.text, x:, y: top + line.ascent, font: fragment.font, size: style.render_size,
-                                   color: style.color, letter_spacing: style.letter_spacing, rise: style.rise,
-                                   opacity: style.opacity, underline: style.underline,
-                                   strikethrough: style.strikethrough,
-                                   synthetic_bold: fragment.face.synthetic_bold,
-                                   synthetic_oblique: fragment.face.synthetic_oblique)
-        canvas.link(x, top, fragment.width, line.height, style.link) if style.link
+        width = canvas.text(fragment.text, x:, y: top + line.ascent, font: fragment.font, size: style.render_size,
+                                           color: style.color, letter_spacing: style.letter_spacing, rise: style.rise,
+                                           opacity: style.opacity, underline: style.underline,
+                                           strikethrough: style.strikethrough, kerning: style.kerning,
+                                           synthetic_bold: fragment.face.synthetic_bold,
+                                           synthetic_oblique: fragment.face.synthetic_oblique, word_spacing:)
+        canvas.link(x, top, width, line.height, style.link) if style.link
+      end
+
+      def count_missing(fragment)
+        fragment.text.each_char do |char|
+          next if Fonts::Fallback.carried?(char) || fragment.font.glyph?(char)
+
+          @book.warnings.missing_glyph(char, fragment.style.family)
+        end
       end
     end
   end

data/lib/stationery/text/runs_builder.rb

@@ -19,9 +19,17 @@ module Stationery
 
       # A block taking an argument is called with the builder (so it keeps its
       # own self and instance variables); one without is evaluated on it.
+      # Once a block has taken the builder as an argument, nested blocks are
+      # called as closures too, so `t.link(url) { t.color(tone, "go") }` can
+      # still reach the caller's methods.
       def capture(&block)
         before = @runs.size
-        result = block.arity == 1 ? yield(self) : instance_exec(&block)
+        result = if block.arity == 1 || @yielding
+                   @yielding = true
+                   block.arity.zero? ? yield : yield(self)
+                 else
+                   instance_exec(&block)
+                 end
         plain(result) if result.is_a?(String) && @runs.size == before
       end
 

data/lib/stationery/text/style.rb

@@ -6,9 +6,9 @@ module Stationery
 
     # How a run of text looks. Immutable; derive variants with #with.
     Style = Data.define(:family, :size, :weight, :style, :color, :letter_spacing,
-                        :underline, :strikethrough, :script, :link, :opacity) do
+                        :underline, :strikethrough, :script, :link, :opacity, :kerning) do
       def initialize(family:, size: 10, weight: :regular, style: :normal, color: "#000000", letter_spacing: 0,
-                     underline: false, strikethrough: false, script: nil, link: nil, opacity: nil)
+                     underline: false, strikethrough: false, script: nil, link: nil, opacity: nil, kerning: true)
         super
       end
 

data/lib/stationery/text/wrapper.rb

@@ -91,7 +91,7 @@ module Stationery
 
       def finish(wrapped: false)
         segments = wrapped ? @current : @current + @pending_space
-        @lines << Line.new(fragments(trim_trailing(segments)), fallback_metrics)
+        @lines << Line.new(fragments(trim_trailing(segments)), fallback_metrics, justifiable: wrapped)
         @current = []
         @pending_space = []
       end
@@ -124,7 +124,8 @@ module Stationery
       end
 
       def measure(text, style)
-        @book.resolve(style).first.width_of(text, style.render_size, letter_spacing: style.letter_spacing)
+        font = @book.resolve(style).first
+        font.width_of(text, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning)
       end
     end
   end

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/stationery/warnings.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Everything a render noticed but did not raise on. One collector per
+  # render; equal warnings are kept once and missing glyphs are counted per
+  # character and family.
+  class Warnings
+    include Enumerable
+
+    Overflow = Layout::Overflow
+
+    MissingGlyph = Data.define(:char, :family, :count) do
+      def message
+        times = count == 1 ? "once" : "#{count} times"
+        format('missing glyph "%<char>s" (U+%<code>04X) in %<family>s, drawn %<times>s as .notdef',
+               char:, code: char.ord, family:, times:)
+      end
+    end
+
+    UnknownFamily = Data.define(:requested, :used) do
+      def message = %(font family "#{requested}" is not registered, using "#{used}")
+    end
+
+    UnsupportedSvg = Data.define(:elements, :source) do
+      def message = %(SVG "#{source}" uses unsupported elements: #{elements.join(", ")})
+    end
+
+    SkippedImage = Data.define(:source, :reason) do
+      def message = %(image "#{source}" skipped: #{reason})
+    end
+
+    UnresolvedLink = Data.define(:name, :page) do
+      def message = %(link to "#{name}" on page #{page} has no matching anchor)
+    end
+
+    DuplicateAnchor = Data.define(:name, :page) do
+      def message = %(anchor "#{name}" on page #{page} is already defined)
+    end
+
+    def initialize
+      @items = []
+      @glyphs = Hash.new(0)
+    end
+
+    def <<(warning)
+      @items << warning unless @items.include?(warning)
+      self
+    end
+
+    def missing_glyph(char, family)
+      @glyphs[[char, family]] += 1
+    end
+
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @items.each(&)
+      @glyphs.each { |(char, family), count| yield MissingGlyph.new(char:, family:, count:) }
+      self
+    end
+
+    def size = @items.size + @glyphs.size
+    def empty? = size.zero?
+  end
+end

data/lib/stationery.rb

@@ -6,13 +6,31 @@ require_relative "stationery/pdf/types"
 require_relative "stationery/pdf/serializer"
 require_relative "stationery/pdf/stream"
 require_relative "stationery/pdf/writer"
+require_relative "stationery/fonts/sfnt_metrics"
 require_relative "stationery/fonts/true_type"
+require_relative "stationery/fonts/cff"
+require_relative "stationery/fonts/cff_subset"
 require_relative "stationery/fonts/cmap"
 require_relative "stationery/fonts/name_table"
+require_relative "stationery/fonts/kern_table"
+require_relative "stationery/fonts/gpos"
+require_relative "stationery/fonts/gpos/coverage"
+require_relative "stationery/fonts/gpos/class_def"
+require_relative "stationery/fonts/gpos/pair_pos"
+require_relative "stationery/fonts/kerning"
 require_relative "stationery/fonts/subset"
 require_relative "stationery/fonts/registry"
+require_relative "stationery/fonts/glyph_run"
+require_relative "stationery/fonts/to_unicode"
+require_relative "stationery/fonts/embedding/base"
+require_relative "stationery/fonts/embedding/true_type"
+require_relative "stationery/fonts/embedding/cff"
 require_relative "stationery/fonts/font"
 require_relative "stationery/fonts/family"
+require_relative "stationery/fonts/bundled"
+require_relative "stationery/fonts/catalog"
+require_relative "stationery/fonts/packs"
+require_relative "stationery/fonts/installer"
 require_relative "stationery/images/images"
 require_relative "stationery/images/cache"
 require_relative "stationery/images/scanlines"
@@ -24,9 +42,12 @@ require_relative "stationery/page"
 require_relative "stationery/resources"
 require_relative "stationery/canvas/path"
 require_relative "stationery/canvas/text"
+require_relative "stationery/canvas/debug"
 require_relative "stationery/canvas"
+require_relative "stationery/pdf/outline_writer"
 require_relative "stationery/pdf/assembler"
 require_relative "stationery/text/style"
+require_relative "stationery/fonts/fallback"
 require_relative "stationery/fonts/font_book"
 require_relative "stationery/text/entities"
 require_relative "stationery/text/markup"
@@ -35,24 +56,54 @@ require_relative "stationery/text/line"
 require_relative "stationery/text/wrapper"
 require_relative "stationery/text/paragraph"
 require_relative "stationery/layout/node"
+require_relative "stationery/warnings"
 require_relative "stationery/layout/flow"
 require_relative "stationery/layout/box"
 require_relative "stationery/layout/row"
 require_relative "stationery/layout/text"
 require_relative "stationery/layout/image"
 require_relative "stationery/layout/leaves"
+require_relative "stationery/layout/mark"
+require_relative "stationery/layout/table_of_contents"
+require_relative "stationery/layout/table_of_contents/entry"
 require_relative "stationery/layout/table"
 require_relative "stationery/layout/table/widths"
 require_relative "stationery/layout/table/cell"
+require_relative "stationery/layout/table/grid"
 require_relative "stationery/layout/table/selection"
+require_relative "stationery/layout/table/row_splitter"
 require_relative "stationery/layout/paginator"
+require_relative "stationery/svg/path_data"
+require_relative "stationery/svg/arc"
+require_relative "stationery/svg/parser"
+require_relative "stationery/svg/transform"
+require_relative "stationery/svg/style"
+require_relative "stationery/svg/shapes"
+require_relative "stationery/svg/document"
+require_relative "stationery/layout/svg"
+require_relative "stationery/layout/wrap"
 require_relative "stationery/layout/positioned"
+require_relative "stationery/layout/list_item"
+require_relative "stationery/list_markers"
+require_relative "stationery/outline"
 require_relative "stationery/builder"
 require_relative "stationery/elements"
+require_relative "stationery/elements/lists"
+require_relative "stationery/elements/rich"
 require_relative "stationery/component"
+require_relative "stationery/regions"
 require_relative "stationery/page_templates"
+require_relative "stationery/structure"
 require_relative "stationery/document"
 
 # Pure-Ruby PDF documents built from Phlex-style components.
 module Stationery
+  @font_paths = []
+
+  class << self
+    # Directories searched for font files; the Railtie appends the app's.
+    attr_reader :font_paths
+  end
+  # Names of the font families shipped inside the gem.
+  def self.bundled_fonts = Fonts::Bundled.names
 end