stationery 0.3.0 → 0.4.0

data/lib/stationery/tagging/writer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Tagging
+    # Writes a Tree as the catalog's /StructTreeRoot: one StructElem per
+    # element that holds content, and the /ParentTree mapping each page's
+    # /StructParents key to its elements by MCID.
+    class Writer
+      def initialize(tree, pages:, refs:)
+        @tree = tree
+        @page_refs = pages.zip(refs).to_h.compare_by_identity
+        @keys = pages.select { |page| tree.marked(page).any? }.each_with_index.to_h.compare_by_identity
+        @annotations = {}.compare_by_identity
+      end
+
+      # An annotation's entries: the /StructParent key of its element, when it
+      # belongs to one. `ref` is the annotation's reference, for the /OBJR.
+      def annotation(link, ref)
+        return {} unless link[:tag]
+
+        @annotations[link] = [ref, @keys.size + @annotations.size]
+        { StructParent: @annotations[link][1] }
+      end
+
+      # The page dictionary's entries: its parent tree key, when it has one.
+      def page_entries(page)
+        key = @keys[page]
+        key ? { StructParents: key } : {}
+      end
+
+      # Writes the tree and returns the catalog entries pointing at it.
+      def write(writer)
+        root = writer.reserve
+        @refs = {}.compare_by_identity
+        reserve(writer, @tree.root)
+        @refs.each_key { |element| writer.set(@refs[element], dictionary(element, root)) }
+        writer.set(root, { Type: :StructTreeRoot, K: [@refs[@tree.root]], ParentTree: { Nums: parent_tree },
+                           ParentTreeNextKey: @keys.size + @annotations.size })
+        { MarkInfo: { Marked: true }, StructTreeRoot: root }
+      end
+
+      private
+
+      def reserve(writer, element)
+        @refs[element] = writer.reserve
+        element.elements.each { |kid| reserve(writer, kid) unless kid.empty? }
+      end
+
+      def dictionary(element, root)
+        page = element.marked_content.first&.page
+        {
+          Type: :StructElem, S: element.type, P: element.parent ? @refs[element.parent] : root,
+          Pg: page && @page_refs[page], K: element.kids.filter_map { |kid| kid_entry(kid, page) },
+          Alt: element.alt && PDF::TextString.new(element.alt),
+          A: attributes(element)
+        }.compact
+      end
+
+      def kid_entry(kid, page)
+        case kid
+        when Element then @refs[kid]
+        when MarkedContent
+          kid.page.equal?(page) ? kid.mcid : { Type: :MCR, Pg: @page_refs[kid.page], MCID: kid.mcid }
+        when ObjectRef
+          ref, = @annotations[kid.annotation]
+          ref && { Type: :OBJR, Obj: ref, Pg: @page_refs[kid.page] }
+        end
+      end
+
+      def attributes(element)
+        list = element.attributes.map { |owner, values| { O: owner, **values } }
+        list.size > 1 ? list : list.first
+      end
+
+      def parent_tree
+        @keys.flat_map { |page, key| [key, @tree.marked(page).map { |element| @refs[element] }] } +
+          @annotations.flat_map { |link, (_, key)| [key, @refs[link[:tag]]] }
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "stringio"
 require "stationery"
+require_relative "structure_reader"
 
 module Stationery
   module Testing
@@ -63,6 +64,20 @@ module Stationery
         outlines ? titles(outlines[:First]) : []
       end
 
+      # The structure tree of a tagged PDF as nested arrays; see StructureReader.
+      def structure = @structure ||= StructureReader.new(reader).tree
+
+      # Whether the catalog marks the PDF as tagged and holds a structure tree.
+      def tagged?
+        catalog = objects.deref!(objects.trailer[:Root])
+        catalog.dig(:MarkInfo, :Marked) == true && !catalog[:StructTreeRoot].nil?
+      end
+
+      # Text shown outside any marked content (neither tagged nor an artifact).
+      def untagged_text
+        @untagged_text ||= reader.pages.flat_map { |page| MarkedText.read(page).unmarked }
+      end
+
       private
 
       def objects = reader.objects

data/lib/stationery/testing/marked_text.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Stationery
+  module Testing
+    # A pdf-reader receiver that collects a page's text by MCID, and the text
+    # shown outside any marked content. Text on a new baseline starts after
+    # a space, so a paragraph's lines read as one string.
+    class MarkedText
+      extend Forwardable
+
+      STATE = %i[save_graphics_state restore_graphics_state concatenate_matrix begin_text_object end_text_object
+                 set_text_font_and_size move_text_position move_text_position_and_set_leading
+                 set_text_matrix_and_text_line_matrix move_to_start_of_next_line set_text_leading
+                 set_character_spacing set_word_spacing set_text_rise set_horizontal_text_scaling
+                 set_text_rendering_mode].freeze
+
+      def_delegators :@state, *STATE
+
+      # { MCID => text } and the strings shown outside marked content.
+      attr_reader :texts, :unmarked
+
+      def self.read(page) = new(page).tap { |receiver| page.walk(receiver) }
+
+      def initialize(page)
+        @state = ::PDF::Reader::PageState.new(page)
+        @open = []
+        @texts = {}
+        @baselines = {}
+        @unmarked = []
+      end
+
+      def begin_marked_content_with_pl(_tag, properties)
+        @open << (properties[:MCID] if properties.is_a?(Hash))
+      end
+
+      def begin_marked_content(_tag) = @open << nil
+      def end_marked_content = @open.pop
+      def show_text(string) = append(string)
+      def show_text_with_positioning(params) = params.grep(String).each { |string| append(string) }
+
+      private
+
+      def append(string)
+        font = @state.current_font
+        text = font.unpack(string).map { |code| font.to_utf8(code) }.join
+        return @unmarked << text if @open.empty?
+
+        mcid = @open.compact.last
+        return unless mcid
+
+        baseline = @state.trm_transform_point(0, 0).y.round(2)
+        separator = @texts.key?(mcid) && @baselines[mcid] != baseline ? " " : ""
+        @texts[mcid] = "#{@texts[mcid]}#{separator}#{text}"
+        @baselines[mcid] = baseline
+      end
+    end
+  end
+end

data/lib/stationery/testing/matchers.rb

@@ -111,6 +111,29 @@ module Stationery
         def actual = messages.empty? ? "got none" : "got:\n#{messages.map { |m| "  - #{m}" }.join("\n")}"
       end
 
+      class HaveStructure < Base
+        def description = "have structure #{@expected.inspect}"
+
+        private
+
+        def match?(pdf) = pdf.structure == @expected
+        def actual = "got #{@inspector.structure.inspect}"
+      end
+
+      class HaveTaggedContent < Base
+        def description = "be tagged with every text in marked content"
+
+        private
+
+        def match?(pdf) = pdf.tagged? && pdf.untagged_text.empty?
+
+        def actual
+          return "but it is not tagged" unless @inspector.tagged?
+
+          "got untagged text #{@inspector.untagged_text.inspect}"
+        end
+      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)
@@ -118,6 +141,8 @@ module Stationery
       def have_image_count(expected) = HaveImageCount.new(expected)
       def have_bookmark(title) = HaveBookmark.new(title)
       def have_no_warnings = HaveNoWarnings.new
+      def have_structure(expected) = HaveStructure.new(expected)
+      def have_tagged_content = HaveTaggedContent.new
     end
   end
 end

data/lib/stationery/testing/structure_reader.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "marked_text"
+
+module Stationery
+  module Testing
+    # Reads a tagged PDF's structure tree as nested arrays, each element's
+    # text taken from the marked content it owns:
+    #
+    #   [[:Document, [[:H1, "Intro"], [:P, ["Read", [:Link, "the docs"], "now"]], [:Figure, "Logo"]]]]
+    #
+    # An element is [type, text] when it holds only text, [type, [kids]]
+    # when it holds elements (with its own text between them), [type] when
+    # empty. A Figure reads as its alt text. Untagged PDFs read as [].
+    class StructureReader
+      def initialize(reader)
+        @reader = reader
+        @objects = reader.objects
+        @texts = {}
+      end
+
+      def tree
+        root = @objects.deref(@objects.deref(@objects.trailer[:Root])[:StructTreeRoot])
+        root ? kids_of(root).grep(Array) : []
+      end
+
+      private
+
+      def element(dictionary)
+        return [dictionary[:S], dictionary[:Alt]].compact if dictionary[:Alt]
+
+        kids = merge(kids_of(dictionary, dictionary[:Pg]))
+        return [dictionary[:S]] if kids.empty?
+
+        [dictionary[:S], kids.size == 1 && kids.first.is_a?(String) ? kids.first : kids]
+      end
+
+      def kids_of(dictionary, page = nil)
+        Array(@objects.deref(dictionary[:K])).filter_map do |kid|
+          kid = @objects.deref(kid)
+          case kid
+          when Integer then text(page, kid)
+          when Hash then kid[:Type] == :MCR ? text(kid[:Pg], kid[:MCID]) : kid_element(kid)
+          end
+        end
+      end
+
+      def kid_element(kid) = kid[:Type] == :OBJR ? nil : element(kid)
+
+      # Adjacent strings (one element's marked content on two lines or pages) join with a space.
+      def merge(kids)
+        kids.each_with_object([]) do |kid, merged|
+          next if kid.is_a?(String) && kid.strip.empty?
+
+          if kid.is_a?(String) && merged.last.is_a?(String)
+            merged[-1] = "#{merged.last} #{kid.strip}"
+          else
+            merged << (kid.is_a?(String) ? kid.strip : kid)
+          end
+        end
+      end
+
+      def text(page, mcid) = page_texts(page)[mcid]
+
+      def page_texts(page)
+        index = @objects.page_references.index(page)
+        @texts[index] ||= MarkedText.read(@reader.page(index + 1)).texts
+      end
+    end
+  end
+end

data/lib/stationery/text/paragraph.rb

@@ -43,17 +43,32 @@ module Stationery
         shrink(max_height)
       end
 
-      def draw(canvas, x, y)
-        top = y
-        @lines.each do |line|
-          offset = x + Geometry.align_offset(@align, @width, line.width)
-          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(" ")
+      # `tag` is the structure element the text belongs to in a tagged PDF;
+      # linked runs become Link elements inside it.
+      def draw(canvas, x, y, tag: nil)
+        links = Links.new
+        canvas.tag_runs(tag) do |mark|
+          top = y
+          @lines.each do |line|
+            offset = x + Geometry.align_offset(@align, @width, line.width)
+            extra = word_spacing(line)
+            spaces = 0
+            line.fragments.each do |fragment|
+              link = links.for(fragment.style.link)
+              mark.call(link) { draw_fragment(canvas, fragment, offset + (extra * spaces), top, line, extra, link:) }
+              spaces += fragment.text.count(" ")
+            end
+            top += line.height + @leading
           end
-          top += line.height + @leading
+        end
+      end
+
+      # One Link element per run of fragments with the same link target.
+      class Links
+        def for(target)
+          @element = nil unless target == @target
+          @target = target
+          @element = target && (@element || Tagging::Element.new(:Link))
         end
       end
 
@@ -94,7 +109,7 @@ module Stationery
         [(@width - line.width) / line.space_count, 0].max
       end
 
-      def draw_fragment(canvas, fragment, offset, top, line, word_spacing)
+      def draw_fragment(canvas, fragment, offset, top, line, word_spacing, link: nil)
         style = fragment.style
         count_missing(fragment)
         x = offset + fragment.x
@@ -105,7 +120,7 @@ module Stationery
                                            ligatures: style.ligatures,
                                            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
+        canvas.link(x, top, width, line.height, style.link, tag: link) if style.link
       end
 
       def count_missing(fragment)

data/lib/stationery/version.rb

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

data/lib/stationery/warnings.rb

@@ -37,6 +37,14 @@ module Stationery
       def message = %(anchor "#{name}" on page #{page} is already defined)
     end
 
+    MissingAlt = Data.define(:kind, :page) do
+      def message = "#{kind} on page #{page} has no alt: text"
+    end
+
+    MissingLanguage = Data.define do
+      def message = "tagged PDF has no language: set metadata lang:"
+    end
+
     def initialize
       @items = []
       @glyphs = Hash.new(0)

data/lib/stationery.rb

@@ -49,11 +49,19 @@ require_relative "stationery/color"
 require_relative "stationery/geometry"
 require_relative "stationery/page"
 require_relative "stationery/resources"
+require_relative "stationery/tagging/element"
+require_relative "stationery/tagging/tree"
+require_relative "stationery/tagging/writer"
 require_relative "stationery/canvas/path"
 require_relative "stationery/canvas/text"
 require_relative "stationery/canvas/debug"
+require_relative "stationery/canvas/marking"
 require_relative "stationery/canvas"
 require_relative "stationery/pdf/outline_writer"
+require_relative "stationery/forms/metrics"
+require_relative "stationery/forms/field"
+require_relative "stationery/forms/appearance"
+require_relative "stationery/forms/acro_form"
 require_relative "stationery/pdf/assembler"
 require_relative "stationery/text/style"
 require_relative "stationery/fonts/fallback"
@@ -99,6 +107,7 @@ require_relative "stationery/svg/document"
 require_relative "stationery/layout/svg"
 require_relative "stationery/layout/wrap"
 require_relative "stationery/layout/positioned"
+require_relative "stationery/layout/field"
 require_relative "stationery/layout/list_item"
 require_relative "stationery/list_markers"
 require_relative "stationery/outline"
@@ -106,6 +115,7 @@ require_relative "stationery/builder"
 require_relative "stationery/elements"
 require_relative "stationery/elements/lists"
 require_relative "stationery/elements/rich"
+require_relative "stationery/elements/forms"
 require_relative "stationery/component"
 require_relative "stationery/regions"
 require_relative "stationery/page_templates"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -32,6 +32,7 @@ files:
 - lib/stationery/builder.rb
 - lib/stationery/canvas.rb
 - lib/stationery/canvas/debug.rb
+- lib/stationery/canvas/marking.rb
 - lib/stationery/canvas/path.rb
 - lib/stationery/canvas/text.rb
 - lib/stationery/cli.rb
@@ -41,6 +42,7 @@ files:
 - lib/stationery/component.rb
 - lib/stationery/document.rb
 - lib/stationery/elements.rb
+- lib/stationery/elements/forms.rb
 - lib/stationery/elements/lists.rb
 - lib/stationery/elements/rich.rb
 - lib/stationery/errors.rb
@@ -81,6 +83,10 @@ files:
 - lib/stationery/fonts/to_unicode.rb
 - lib/stationery/fonts/true_type.rb
 - lib/stationery/fonts/woff.rb
+- lib/stationery/forms/acro_form.rb
+- lib/stationery/forms/appearance.rb
+- lib/stationery/forms/field.rb
+- lib/stationery/forms/metrics.rb
 - lib/stationery/geometry.rb
 - lib/stationery/html/document.rb
 - lib/stationery/html/tokenizer.rb
@@ -94,6 +100,7 @@ files:
 - lib/stationery/images/png.rb
 - lib/stationery/images/scanlines.rb
 - lib/stationery/layout/box.rb
+- lib/stationery/layout/field.rb
 - lib/stationery/layout/flow.rb
 - lib/stationery/layout/image.rb
 - lib/stationery/layout/leaves.rb
@@ -164,8 +171,13 @@ files:
 - lib/stationery/svg/stylesheet.rb
 - lib/stationery/svg/text.rb
 - lib/stationery/svg/transform.rb
+- lib/stationery/tagging/element.rb
+- lib/stationery/tagging/tree.rb
+- lib/stationery/tagging/writer.rb
 - lib/stationery/testing/inspector.rb
+- lib/stationery/testing/marked_text.rb
 - lib/stationery/testing/matchers.rb
+- lib/stationery/testing/structure_reader.rb
 - lib/stationery/text/entities.rb
 - lib/stationery/text/entities/html4.rb
 - lib/stationery/text/line.rb