stationery 0.8.0 → 0.9.0

data/lib/stationery/html/tree_builder.rb

@@ -6,7 +6,9 @@ module Stationery
   module HTML
     # Builds a lenient element tree from tokens, closing what HTML5 closes implicitly (a p before a block,
     # an li before the next li, cells and rows before the next), ignoring stray end tags, then converts
-    # the tree into rich-text blocks.
+    # the tree into rich-text blocks. An element nested deeper than the Rich::Nesting limit is left out
+    # of the tree: what it holds goes to the deepest element kept, so everything that walks the tree
+    # (and the layout it becomes) recurses no deeper than the limit.
     class TreeBuilder
       Element = Data.define(:name, :attributes, :children)
 
@@ -16,6 +18,7 @@ module Stationery
       ].freeze
       HEADINGS = %w[h1 h2 h3 h4 h5 h6].freeze
       SECTIONS = %w[thead tbody tfoot].freeze
+      BLOCKS = (CLOSES_P + SECTIONS + %w[tr td th caption]).freeze
       IMPLIED = {
         "li" => [%w[li], %w[ul ol]],
         "dt" => [%w[dt dd], %w[dl]], "dd" => [%w[dt dd], %w[dl]],
@@ -24,11 +27,13 @@ module Stationery
         "thead" => [SECTIONS, %w[table]], "tbody" => [SECTIONS, %w[table]], "tfoot" => [SECTIONS, %w[table]]
       }.freeze
 
-      def self.parse(tokens) = Blocks.convert(new.build(tokens))
+      def self.parse(tokens, nesting = Rich::Nesting.new) = Blocks.convert(new(nesting).build(tokens))
 
-      def initialize
+      def initialize(nesting = Rich::Nesting.new)
         @root = Element.new("#root", {}, [])
         @stack = [@root]
+        @nesting = nesting
+        @flattened = [] # the names of the open elements left out of the tree
       end
 
       def build(tokens)
@@ -45,9 +50,13 @@ module Stationery
       private
 
       def start(name, attributes, self_closing)
+        return flatten(name, attributes, self_closing) unless @flattened.empty?
+
         close_nearest(%w[p], %w[table td th caption]) if CLOSES_P.include?(name)
         close_nearest(HEADINGS, []) if HEADINGS.include?(name) && HEADINGS.include?(@stack.last.name)
         close_nearest(*IMPLIED[name]) if IMPLIED.key?(name)
+        return flatten(name, attributes, self_closing) if @stack.size > @nesting.limit
+
         push("tr", {}, false) if %w[td th].include?(name) && %w[table thead tbody tfoot].include?(@stack.last.name)
         push(name, attributes, self_closing)
       end
@@ -58,9 +67,30 @@ module Stationery
         @stack << element unless self_closing
       end
 
+      # Too deep for the tree: a void element (br, img, hr) still takes its place in the deepest
+      # element kept, anything else is only remembered until its end tag, its content going there too.
+      def flatten(name, attributes, self_closing)
+        return push(name, attributes, true) if self_closing
+
+        @flattened << name
+        @nesting.record(@stack.size - 1 + @flattened.size)
+        separate(name)
+      end
+
       def finish(name)
+        flattened = @flattened.rindex(name)
+        return @flattened.slice!(flattened..).each { |left_out| separate(left_out) } if flattened
+
         index = @stack.rindex { |element| element.name == name }
-        @stack.slice!(index..) if index&.positive?
+        return unless index&.positive?
+
+        @stack.slice!(index..)
+        @flattened.clear
+      end
+
+      # A flattened block no longer parts its text from its neighbours'; a space does.
+      def separate(name)
+        @stack.last.children << " " if BLOCKS.include?(name)
       end
 
       def close_nearest(names, boundary)

data/lib/stationery/layout/image.rb

@@ -25,7 +25,7 @@ module Stationery
         super()
         @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
-        @name = source.is_a?(String) || source.is_a?(Pathname) ? File.basename(source.to_s) : "inline image"
+        @name = name_of(source)
         @max_ppi = max_ppi
         @downscale = downscale
         @width = width
@@ -58,6 +58,14 @@ module Stationery
 
       private
 
+      # What a warning calls the image: the file's name for a path, a
+      # Pathname or an open File (anything with a path), else "inline image".
+      # Asked by duck type: Pathname is not loaded in plain Ruby.
+      def name_of(source)
+        path = source.is_a?(String) ? source : (source.to_path if source.respond_to?(:to_path))
+        path ? File.basename(path) : "inline image"
+      end
+
       def paint_clipped(canvas, x, y, w, h)
         return paint_image(canvas, x, y, w, h) unless @fit == :cover || @radius.positive?
 

data/lib/stationery/layout/table/cell.rb

@@ -6,6 +6,7 @@ module Stationery
       # One table cell: content (a String, markup String or layout node) and its
       # options, which selections change until the table is laid out.
       class Cell
+        SIDES = %i[top right bottom left].freeze
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
@@ -103,14 +104,23 @@ module Stationery
           canvas.debug_rect(inner.x, inner.y, inner.width, inner.height, :cell_padding)
         end
 
+        # One path for the cell's border, centred on its edges: the rectangle
+        # when all four sides are drawn, else a line per side.
         def paint_borders(canvas, rect)
           width = @options[:border_width]
           return if width.nil? || width.zero?
 
-          color = @options[:border_color]
-          Array(@options[:borders]).each do |side|
-            x1, y1, x2, y2 = edge(side, rect)
-            canvas.line(x1, y1, x2, y2, color:, width:)
+          sides = Array(@options[:borders]).uniq
+          return if sides.empty?
+
+          canvas.path(stroke: @options[:border_color], line_width: width) do |path|
+            next path.rect(rect.x, rect.y, rect.width, rect.height) if (SIDES - sides).empty?
+
+            sides.each do |side|
+              x1, y1, x2, y2 = edge(side, rect)
+              path.move_to(x1, y1)
+              path.line_to(x2, y2)
+            end
           end
         end
 

data/lib/stationery/layout/table.rb

@@ -6,6 +6,13 @@ module Stationery
     # header rows repeated after a page break, and splitting between rows. A
     # row taller than a fresh page, or any row with split_rows: true, is cut
     # through its cells and continues below the repeated header.
+    #
+    # The fragments a page break cuts a table into keep the whole table's
+    # column metrics, so every page resolves the same column widths, and the
+    # widths and row heights measured for the cut, so a page break measures
+    # nothing again. Laid out at another width they resolve and measure anew.
+    # Where no cell spans rows a cut can fall before any row, so the rows
+    # still to come are not placed on a grid until a page paints them.
     class Table < Node
       DEFAULT_CELL = { padding: 5, borders: %i[top right bottom left], border_width: 0.5,
                        border_color: "#000000" }.freeze
@@ -30,7 +37,7 @@ module Stationery
       end
 
       def row_count = @cells.size
-      def column_count = grid.column_count
+      def column_count = @column_count ||= grid.column_count
       def cell(row, column) = grid.at(row, column)
 
       def rows(spec) = Selection.new(self, Selection.indexes(spec, row_count), (0...column_count).to_a)
@@ -53,6 +60,7 @@ module Stationery
         @column_widths = nil
         @column_metrics = nil
         @row_heights = nil
+        @column_count = nil
         @grid = nil
       end
 
@@ -80,10 +88,11 @@ module Stationery
       def paint(canvas, x, y, width, _height = nil, **)
         widths = column_widths(width)
         heights = row_heights(width)
+        lefts = offsets(widths)
+        tops = offsets(heights)
         canvas.structure(@tag) do
           grid.placements.each do |p|
-            rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
-                            widths[p.columns].sum, heights[p.rows].sum)
+            rect = Rect.new(x + lefts[p.column], y + tops[p.row], widths[p.columns].sum, heights[p.rows].sum)
             paint_cell(canvas, p, rect)
           end
         end
@@ -96,14 +105,45 @@ module Stationery
         count += 1 while count < row_count && used + heights[count] <= height + EPSILON && (used += heights[count])
         return [self, nil] if count == row_count
 
-        count = grid.boundaries.grep(@header..count).max
-        split_row(count, width, height - heights.first(count).sum, fresh: options[:fresh]) || split_before(count)
+        count = grid.boundaries.grep(@header..count).max if row_spans?
+        split_row(count, width, height - heights.first(count).sum, fresh: options[:fresh]) ||
+          split_before(count, width)
+      end
+
+      protected
+
+      # Becomes a fragment holding `rows`, with the column widths and row
+      # heights its table measured at `width`.
+      def carry(rows, continued, widths, heights)
+        @cells = rows
+        @continued = continued
+        @grid = nil
+        @column_widths = widths
+        @row_heights = heights
+        self
       end
 
       private
 
       def grid = @grid ||= Grid.new(@cells)
 
+      # Whether any cell spans rows, of the table a fragment was cut from too.
+      def row_spans?
+        return @row_spans if defined?(@row_spans)
+
+        @row_spans = @cells.any? { |row| row.any? { |cell| cell.rowspan > 1 } }
+      end
+
+      # The placements of one row, which no cell from above reaches into.
+      def placements_in(row)
+        return grid.placements.select { |placement| placement.row == row } if row_spans?
+
+        Grid.new([@cells[row]]).placements
+      end
+
+      # Where each column or row starts: the sizes before it, summed.
+      def offsets(sizes) = Array.new(sizes.size) { |index| sizes[0...index].sum }
+
       def paint_cell(canvas, placement, rect)
         cell = placement.cell
         paint = lambda do
@@ -123,28 +163,42 @@ module Stationery
       end
 
       def cell_tag(cell, header)
+        return Tagging::Element.new(:TD) unless header || cell.colspan > 1 || cell.rowspan > 1
+
         attributes = { Scope: (:Column if header), ColSpan: (cell.colspan if cell.colspan > 1),
                        RowSpan: (cell.rowspan if cell.rowspan > 1) }.compact
         Tagging::Element.new(header ? :TH : :TD, attributes: attributes.empty? ? {} : { Table: attributes })
       end
 
-      def split_before(count)
+      def split_before(count, width)
         return [nil, self] if count == @header
 
-        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count), continued: true)]
+        heights = row_heights(width)
+        [fragment(@cells.first(count), width, heights.first(count)),
+         fragment(@cells.first(@header) + @cells.drop(count), width,
+                  heights.first(@header) + heights.drop(count), continued: true)]
       end
 
       def split_row(row, width, space, fresh:)
         return unless @split_rows || (fresh && row == @header)
-        return unless grid.boundaries.include?(row + 1)
+        return if row_spans? && !grid.boundaries.include?(row + 1)
 
         widths = column_widths(width)
-        placements = grid.placements.select { |p| p.row == row }
+        placements = placements_in(row)
         heads, tails = RowSplitter.new(placements, widths:, context: @context).call(space)
         return unless heads
 
-        [with_rows(@cells.first(row) + [heads], widths:),
-         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:, continued: true)]
+        heights = row_heights(width)
+        above, below = [heads, tails].map { |cells| [row_height(placements, cells, widths)] }
+        [fragment(@cells.first(row) + [heads], width, heights.first(row) + above),
+         fragment(@cells.first(@header) + [tails] + @cells.drop(row + 1), width,
+                  heights.first(@header) + below + heights.drop(row + 1), continued: true)]
+      end
+
+      # The height of a cut row's part. No cell of a row that can be cut
+      # spans rows, so it is its tallest cell.
+      def row_height(placements, cells, widths)
+        placements.zip(cells).map { |placement, cell| cell.measure(@context, widths[placement.columns].sum) }.max
       end
 
       def build_cell(content, defaults)
@@ -187,9 +241,13 @@ module Stationery
         @row_heights[width] ||= grid.row_heights(column_widths(width)) { |p, span| p.cell.measure(@context, span) }
       end
 
-      def with_rows(rows, widths: @widths, continued: @continued)
-        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows,
-                             tag: @tag, continued:)
+      # A copy holding other rows of this table. Its cells are built and
+      # tagged already and its column metrics are this table's.
+      def fragment(rows, width, heights, continued: @continued)
+        %i[natural_width min_width].each { |metric| column_metric(metric) }
+        column_count
+        row_spans?
+        dup.carry(rows, continued, { width => column_widths(width) }, { width => heights })
       end
     end
   end

data/lib/stationery/markdown/block_parser/containers.rb

@@ -9,9 +9,30 @@ module Stationery
       module Containers
         QUOTE = /\A {0,3}> ?/
         LIST = /\A(?<indent> {0,3})(?<marker>[-+*]|(?<number>\d{1,9})[.)])(?<space> *)(?<rest>.*)\z/
+        MARKER = /\G[ \t]*(?:>|(?:[-+*]|\d{1,9}[.)])(?=[ \t]|\z))/
 
         private
 
+        def container?(line) = QUOTE.match?(line) || !list_marker(line).nil?
+
+        # Block quotes and lists nested past the limit: their lines, up to a blank one, as one
+        # paragraph with the markers dropped.
+        def flattened
+          lines = []
+          while (line = @lines[@index]) && !blank?(line)
+            lines << unmarked(line)
+            @index += 1
+          end
+          lines.reject!(&:empty?)
+          Rich::Paragraph.new(inlines: text(lines)) if lines.any?
+        end
+
+        def unmarked(line)
+          markers = line.scan(MARKER).size
+          @nesting.record(@depth + markers)
+          line.sub(/\A(?:#{MARKER.source.delete_prefix("\\G")})*[ \t]*/, "")
+        end
+
         def blockquote
           lines = []
           while (line = @lines[@index])

data/lib/stationery/markdown/block_parser.rb

@@ -10,6 +10,8 @@ module Stationery
     # Splits CommonMark source into blocks, line by line. Paragraph, heading and table cell text is left
     # raw (a String in place of inlines) for Markdown.parse to run through the inline parser once every
     # link reference definition, which this parser collects into `refs`, is known. Raw HTML stays text.
+    # Every block quote and list is parsed by a parser of its own, one level deeper; at the
+    # Rich::Nesting limit a further one becomes a paragraph of its text instead.
     class BlockParser
       include Containers
       include Tables
@@ -24,7 +26,7 @@ module Stationery
         (?:[ \t]+(?:"[^"]*"|'[^']*'|\([^)]*\)))?[ \t]*\z
       /x
 
-      def self.parse(source, refs) = new(lines(source), refs).blocks
+      def self.parse(source, refs, nesting = Rich::Nesting.new) = new(lines(source), refs, nesting).blocks
 
       def self.lines(source) = source.to_s.split(/\r\n?|\n/).map { |line| expand_tabs(line) }
 
@@ -39,9 +41,12 @@ module Stationery
         expanded + line[prefix.length..]
       end
 
-      def initialize(lines, refs)
+      # `depth` counts the block quotes and lists this parser is inside.
+      def initialize(lines, refs, nesting = Rich::Nesting.new, depth = 0)
         @lines = lines
         @refs = refs
+        @nesting = nesting
+        @depth = depth
         @index = 0
       end
 
@@ -62,6 +67,7 @@ module Stationery
         elsif (match = FENCE.match(line)) then fenced_code(match)
         elsif (match = ATX.match(line)) then atx(match)
         elsif THEMATIC.match?(line) then skip(Rich::Rule.new)
+        elsif container?(line) && @depth >= @nesting.limit then flattened
         elsif QUOTE.match?(line) then blockquote
         elsif (match = list_marker(line)) then list(match)
         elsif table_start? then table
@@ -135,7 +141,7 @@ module Stationery
 
       def blank?(line) = line.strip.empty?
       def indent(line) = line[/\A */].length
-      def nested(lines) = BlockParser.new(lines, @refs).blocks
+      def nested(lines) = BlockParser.new(lines, @refs, @nesting, @depth + 1).blocks
     end
   end
 end

data/lib/stationery/markdown/document.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "../rich/nesting"
 require_relative "block_parser"
 require_relative "inline_parser"
 
 module Stationery
   # A CommonMark subset (plus GFM tables and strikethrough) to rich-text blocks (see Stationery::Rich).
   module Markdown
-    def self.parse(source)
+    # Block quotes and lists nested deeper than `max_depth` are flattened into
+    # a paragraph; the block is then given how deep the source went.
+    def self.parse(source, max_depth: Rich::Nesting::DEFAULT)
+      nesting = Rich::Nesting.new(max_depth)
       Stationery.instrument("parse.stationery", format: :markdown, bytes: source.bytesize) do
         refs = {}
-        Resolver.new(refs).blocks(BlockParser.parse(source, refs))
+        Resolver.new(refs).blocks(BlockParser.parse(source, refs, nesting)).tap do
+          yield nesting.deepest if nesting.exceeded? && block_given?
+        end
       end
     end
 

data/lib/stationery/markdown/inline_parser/emphasis.rb

@@ -21,23 +21,30 @@ module Stationery
           end
         end
 
-        # Wraps matched delimiter pairs (and what lies between them) in place.
+        # Wraps matched delimiter pairs (and what lies between them) in place. `bottoms` remembers, per
+        # kind of closer, the index below which no opener is left for it, so a run of closers that
+        # nothing opens is not searched for again and again (CommonMark's openers_bottom).
         def process(nodes)
+          bottoms = Hash.new(0)
           index = 0
           while index < nodes.size
             closer = nodes[index]
-            opener = closer?(closer) && opener_for(nodes, index)
-            next index += 1 unless opener
+            next index += 1 unless closer?(closer)
 
-            index = wrap(nodes, opener, index)
+            opening = opener_for(nodes, index, bottoms[kind(closer)])
+            next index = wrap(nodes, opening, index, bottoms) if opening
+
+            bottoms[kind(closer)] = index
+            index += 1
           end
         end
 
-        def wrap(nodes, opening, index)
+        def wrap(nodes, opening, index, bottoms)
           opener = nodes[opening]
           closer = nodes[index]
           used = used(opener, closer)
           nodes[(opening + 1)...index] = [Nodes::Wrap.new(marks(closer.char, used), nodes[(opening + 1)...index])]
+          bottoms.each { |kind, bottom| bottoms[kind] = opening + 1 if bottom > opening + 1 }
           opener.remaining -= used
           closer.remaining -= used
           index = opening + 2
@@ -49,9 +56,9 @@ module Stationery
           index
         end
 
-        def opener_for(nodes, index)
+        def opener_for(nodes, index, bottom)
           closer = nodes[index]
-          (index - 1).downto(0).find do |i|
+          (index - 1).downto(bottom).find do |i|
             node = nodes[i]
             node.is_a?(Nodes::Delimiter) && node.opener && node.char == closer.char && node.remaining.positive? &&
               (closer.char != "~" || node.remaining == closer.remaining)
@@ -60,6 +67,9 @@ module Stationery
 
         def closer?(node) = node.is_a?(Nodes::Delimiter) && node.closer && node.remaining.positive?
 
+        # What decides which openers suit a closer: its character, and for `~` its length too.
+        def kind(closer) = closer.char == "~" ? [closer.char, closer.remaining] : closer.char
+
         def used(opener, closer)
           return closer.remaining if closer.char == "~"
 

data/lib/stationery/markdown/inline_parser/links.rb

@@ -3,9 +3,14 @@
 module Stationery
   module Markdown
     class InlineParser
-      # Brackets, inline and reference links, images and autolinks.
+      # Brackets, inline and reference links, images and autolinks. At most OPEN brackets wait for
+      # their `]` at once (the oldest gives way), and a link label is at most LABEL characters as
+      # CommonMark has it, so neither nesting nor the work per `]` grows with the input. A bracket's
+      # `position` is in bytes, which the scanner knows without counting characters.
       module Links
         Bracket = Struct.new(:index, :image, :active, :position)
+        OPEN = 64
+        LABEL = 999
 
         INLINE = /
           \(\s*
@@ -23,7 +28,8 @@ module Stationery
         private
 
         def open_bracket(image: false)
-          @brackets << Bracket.new(@nodes.size, image, true, @scanner.charpos)
+          @brackets.shift if @brackets.size >= OPEN
+          @brackets << Bracket.new(@nodes.size, image, true, @scanner.pos)
           add(image ? "![" : "[")
         end
 
@@ -31,7 +37,7 @@ module Stationery
           bracket = @brackets.pop
           return add("]") unless bracket&.active
 
-          href = inline_destination || reference(@source[bracket.position...(@scanner.charpos - 1)])
+          href = inline_destination || reference(bracket.position...(@scanner.pos - 1))
           return add("]") unless href
 
           children = @nodes.slice!(bracket.index..).drop(1)
@@ -48,18 +54,17 @@ module Stationery
           InlineParser.destination(@scanner[1] || @scanner[2])
         end
 
-        def reference(label)
+        # The target of `[text][label]`, `[text][]` or `[text]`, `span` being where the text lies.
+        def reference(span)
           position = @scanner.pos
-          if @scanner.scan(REFERENCE)
-            label = @scanner[1] unless @scanner[1].empty?
-            href = @refs[InlineParser.label(label)]
-            @scanner.pos = position unless href
-            href
-          else
-            @refs[InlineParser.label(label)]
-          end
+          label = @scanner[1] if @scanner.scan(REFERENCE) && !@scanner[1].empty?
+          href = defined_as(label || (@source.byteslice(span) if span.size <= LABEL * 4))
+          @scanner.pos = position unless href
+          href
         end
 
+        def defined_as(label) = label && label.length <= LABEL && @refs[InlineParser.label(label)]
+
         def autolink
           url = @scanner[1] || "mailto:#{@scanner[2]}"
           @nodes << Nodes::Wrap.new({ link: url }, [Nodes::Text.new(@scanner[1] || @scanner[2])])

data/lib/stationery/markdown/inline_parser/nodes.rb

@@ -14,20 +14,34 @@ module Stationery
 
         module_function
 
-        def flatten(nodes, marks = {}, out = [])
-          nodes.each do |node|
-            case node
-            when Text then out << Rich::Inline.new(text: node.text, marks:)
-            when Delimiter then out << Rich::Inline.new(text: node.char * node.remaining, marks:)
-            when Code then out << Rich::Inline.new(text: node.text, marks: marks.merge(code: true))
-            when Break then out << Rich::Inline.break
-            when Wrap then flatten(node.children, marks.merge(node.marks), out)
-            when Picture then out << picture(node)
-            end
+        # The tree as a flat list of inlines, each with the marks of the wraps around it. Walked with
+        # a stack of its own, not by recursion: emphasis nests as deep as its author types asterisks.
+        def flatten(nodes, marks = {})
+          out = []
+          pending = [[nodes, 0, marks]]
+          until pending.empty?
+            level = pending.last
+            node = level[0][level[1]]
+            next pending.pop unless node
+
+            level[1] += 1
+            next pending << [node.children, 0, level[2].merge(node.marks)] if node.is_a?(Wrap)
+
+            out << inline(node, level[2])
           end
           out
         end
 
+        def inline(node, marks)
+          case node
+          when Text then Rich::Inline.new(text: node.text, marks:)
+          when Delimiter then Rich::Inline.new(text: node.char * node.remaining, marks:)
+          when Code then Rich::Inline.new(text: node.text, marks: marks.merge(code: true))
+          when Break then Rich::Inline.break
+          when Picture then picture(node)
+          end
+        end
+
         def picture(node) = Rich::Image.new(src: node.src, alt: plain(node.children), width: nil, height: nil)
 
         def plain(nodes)

data/lib/stationery/markdown/inline_parser.rb

@@ -79,10 +79,16 @@ module Stationery
       end
 
       def delimiter
-        position = @scanner.charpos
+        before = previous_character
         run = @scanner.scan(/\*+|_+|~+/)
-        before = position.zero? ? " " : @source[position - 1]
-        @nodes << Emphasis.delimiter(run, before, @source[@scanner.charpos] || " ")
+        @nodes << Emphasis.delimiter(run, before, @scanner.check(/./m) || " ")
+      end
+
+      # The character before the scanner, read from the few bytes before it: a character position
+      # is counted from the start of the source, which a long paragraph would pay for at every run.
+      def previous_character
+        position = @scanner.pos
+        @source.byteslice([position - 4, 0].max...position).scrub("")[-1] || " "
       end
     end
   end

data/lib/stationery/minitest.rb

@@ -34,6 +34,10 @@ module Stationery
         assert_pdf(Matchers::HaveFacturX.new(profile:), subject, msg)
       end
 
+      def assert_pdf_signature(subject, msg = nil, name: nil, valid: true)
+        assert_pdf(Matchers::HaveSignature.new(name:, valid:), subject, msg)
+      end
+
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
       def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
       def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)