gamba 2.0.2 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Gamba
4
+ # What a Rails application gets once Gamba is in its bundle: `render pdf:` in controllers, `.pdf.rb` templates,
5
+ # and Gamba loaded before the server forks. Defined only when Rails is.
6
+ class Railtie < ::Rails::Railtie
7
+ # The bytes of what a controller renders or a template ends with: a Gamba::Document, a Prawn::Document, an
8
+ # object answering to_pdf (a document class of the application), or the bytes themselves.
9
+ def self.pdf(document)
10
+ if document.respond_to?(:to_pdf) then document.to_pdf
11
+ elsif document.is_a?(Gamba::Document) then document.to_s
12
+ elsif document.respond_to?(:render) then document.render
13
+ elsif document.is_a?(String) then document
14
+ else raise ArgumentError, "render pdf: takes a Gamba::Document, a Prawn::Document, an object answering to_pdf or a PDF's bytes, not #{document.class}"
15
+ end.b
16
+ end
17
+
18
+ # A `.pdf.rb` template: its code runs in the view, helpers and translations at hand, with `document`, a
19
+ # Gamba::Document; Prawn's API is at document.prawn. A template that ends with a document of its own (Gamba's
20
+ # or Prawn's) renders that one instead. A PDF is bytes, not text: the response loses the charset Rails adds.
21
+ module TemplateHandler
22
+ def self.call(template, source)
23
+ <<~RUBY
24
+ document = ::Gamba::Document.new
25
+ result = begin
26
+ #{source}
27
+ end
28
+ if respond_to?(:response) && response
29
+ response.content_type = Mime[:pdf].to_s
30
+ response.charset = false
31
+ end
32
+ ::Gamba::Railtie.pdf(result.is_a?(::Gamba::Document) || result.is_a?(::Prawn::Document) ? result : document)
33
+ RUBY
34
+ end
35
+ end
36
+
37
+ # Before the server forks its workers, so they share what Gamba loads instead of each loading its own.
38
+ config.before_eager_load { Gamba.eager_load! }
39
+
40
+ initializer "gamba.renderer" do
41
+ ActiveSupport.on_load(:action_controller) do
42
+ ActionController::Renderers.add(:pdf) do |document, options|
43
+ send_data Gamba::Railtie.pdf(document), {type: Mime[:pdf], disposition: "inline"}.merge(options.slice(:filename, :disposition, :status))
44
+ end
45
+ end
46
+ end
47
+
48
+ initializer "gamba.template_handler" do
49
+ ActiveSupport.on_load(:action_view) { ActionView::Template.register_template_handler(:rb, Gamba::Railtie::TemplateHandler) }
50
+ end
51
+ end
52
+ end
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "gamba/testing"
4
+
5
+ module Gamba
6
+ # require "gamba/rspec": matchers on PDFs, as bytes or a file's path, in every example group.
7
+ module RSpec
8
+ # A matcher whose check returns nil when it passes, or the failure's words.
9
+ class Matcher
10
+ def initialize(description, &check)
11
+ @description = description
12
+ @check = check
13
+ end
14
+
15
+ def matches?(pdf)
16
+ @failure = @check.call(pdf)
17
+ @failure.nil?
18
+ rescue Gamba::PdfCheck::ToolMissing => error
19
+ raise if Gamba::Testing.missing_tools == :fail
20
+
21
+ ::RSpec::Core::Pending.mark_skipped!(::RSpec.current_example, error.message) if defined?(::RSpec::Core::Pending)
22
+ raise ::RSpec::Core::Pending::SkipDeclaredInExample, error.message
23
+ end
24
+
25
+ def does_not_match?(pdf)
26
+ !matches?(pdf)
27
+ end
28
+
29
+ def failure_message
30
+ @failure
31
+ end
32
+
33
+ def failure_message_when_negated
34
+ "expected the PDF not to #{@description}"
35
+ end
36
+
37
+ attr_reader :description
38
+ end
39
+
40
+ def have_pdf_text(text, page: nil, at: nil)
41
+ Matcher.new("have the text #{text.inspect}") { |pdf| Gamba::Testing.text_failure(pdf, text, page:, at:) }
42
+ end
43
+
44
+ def have_same_pages_as(expected)
45
+ Matcher.new("have the same pages") { |actual| Gamba::Testing.pages_failure(expected, actual) }
46
+ end
47
+
48
+ def be_a_valid_pdf
49
+ Matcher.new("be a valid PDF") { |pdf| Gamba::Testing.validity_failure(pdf) }
50
+ end
51
+
52
+ def be_pdf_a(flavour: "3b")
53
+ Matcher.new("be PDF/A-#{flavour}") { |pdf| Gamba::Testing.pdf_a_failure(pdf, flavour:) }
54
+ end
55
+ end
56
+ end
57
+
58
+ RSpec.configure { |config| config.include(Gamba::RSpec) } if defined?(RSpec.configure)
@@ -26,6 +26,15 @@ module Prawn
26
26
  @text_options[:style] = style
27
27
  end
28
28
 
29
+ # What the cell was given, before the document's font fills in: Gamba's own tables check the faces with them.
30
+ def font_style
31
+ @text_options[:style]
32
+ end
33
+
34
+ def font_name
35
+ @font
36
+ end
37
+
29
38
  def natural_content_width
30
39
  @natural_content_width ||= [styled_width_of(@content), @pdf.bounds.width].min
31
40
  end
@@ -64,8 +73,8 @@ module Prawn
64
73
  def with_font
65
74
  @pdf.save_font do
66
75
  options = {}
67
- options[:style] = @text_options[:style] if @text_options[:style]
68
- options[:style] ||= @pdf.font.options[:style] if @pdf.font.options[:style]
76
+ options[:style] = drawn_style if drawn_style
77
+ options[:style] ||= @pdf.font.options[:style] if @pdf.font.options[:style] && !in_its_regular?
69
78
  @pdf.font(@font || @pdf.font.family, options)
70
79
  yield
71
80
  end
@@ -86,20 +95,46 @@ module Prawn
86
95
  def text_box(extra_options = {})
87
96
  inline_format = @text_options[:inline_format]
88
97
  if inline_format
89
- options = @text_options.except(:inline_format).merge(extra_options).merge(document: @pdf)
98
+ options = drawn_text_options.except(:inline_format).merge(extra_options).merge(document: @pdf)
90
99
  array = @pdf.text_formatter.format(@content, *(inline_format.is_a?(Array) ? inline_format : []))
91
100
  Prawn::Text::Formatted::Box.new(array, options)
92
101
  else
93
- Prawn::Text::Box.new(@content, @text_options.merge(extra_options).merge(document: @pdf))
102
+ Prawn::Text::Box.new(@content, drawn_text_options.merge(extra_options).merge(document: @pdf))
94
103
  end
95
104
  end
96
105
 
97
106
  def styled_width_of(text)
98
- @pdf.width_of(text, @text_options)
107
+ return @pdf.width_of(text, @text_options) unless @sized_in_its_font
108
+
109
+ with_font { @pdf.width_of(text, drawn_text_options) }
99
110
  end
100
111
 
101
112
  private
102
113
 
114
+ # A font of one face, given by its file or by a standard face's name, its own or the document's, is its own
115
+ # regular: asked by name, Prawn would look it up in a family it does not have.
116
+ def drawn_style
117
+ style = @text_options[:style]
118
+ (style == :normal && @sized_in_its_font && one_face?) ? nil : style
119
+ end
120
+
121
+ def one_face?
122
+ @font ? !@pdf.font_families.key?(@font.to_s) : @pdf.font.family.nil?
123
+ end
124
+
125
+ def drawn_text_options
126
+ (drawn_style == @text_options[:style]) ? @text_options : @text_options.except(:style)
127
+ end
128
+
129
+ # A cell of Gamba's own tables in a font of its own is in its regular unless it names a style, as a text is:
130
+ # the style of the document around is not its own. A family without a regular takes it still, as in Prawn.
131
+ def in_its_regular?
132
+ return false unless @sized_in_its_font && @font
133
+
134
+ faces = @pdf.font_families[@font.to_s]
135
+ faces.nil? || faces.key?(:normal)
136
+ end
137
+
103
138
  # A cell is laid out while the table is sized, then drawn: the layout is drawn again unless
104
139
  # before_rendering_page, the document or a truncating height changed what the cell would wrap.
105
140
  def laid_out_box_reusable?
@@ -203,6 +238,11 @@ module Prawn
203
238
  def draw_bounded_content(_point)
204
239
  end
205
240
 
241
+ # The spanning cell is the table cell element; its stand-ins make none.
242
+ def tag_content
243
+ yield
244
+ end
245
+
206
246
  def padding_right=(value)
207
247
  @master_cell.padding_right = value if rightmost?
208
248
  end
@@ -31,6 +31,11 @@ module Prawn
31
31
  attr_reader :padding, :colspan, :rowspan, :dummy_cells, :border_widths, :border_colors, :border_lines
32
32
  attr_writer :height
33
33
  attr_accessor :borders, :content, :background_color
34
+ # In a tagged document, :header for a cell of the table header, :repeated for its copy atop a later page.
35
+ attr_writer :tag_role
36
+ # Set by Gamba's own tables: a text cell is measured in the font it is drawn in. prawn-table measures it in the
37
+ # document's, and Prawn's tables keep that.
38
+ attr_writer :sized_in_its_font
34
39
 
35
40
  def self.make(pdf, content, options = {})
36
41
  at = options.delete(:at) || [0, pdf.cursor]
@@ -55,6 +60,8 @@ module Prawn
55
60
  end
56
61
 
57
62
  def self.draw_cells(cells)
63
+ return draw_tagged_cells(cells) if cells.first&.first&.tagged?
64
+
58
65
  cells.each do |cell, point|
59
66
  cell.set_width_constraints
60
67
  cell.draw_background(point)
@@ -65,6 +72,36 @@ module Prawn
65
72
  end
66
73
  end
67
74
 
75
+ # Backgrounds and borders only decorate; the content of each cell goes into its own table cell element.
76
+ def self.draw_tagged_cells(cells)
77
+ cells.each do |cell, point|
78
+ cell.set_width_constraints
79
+ cell.tag_decoration { cell.draw_background(point) }
80
+ end
81
+ cells.each do |cell, point|
82
+ cell.tag_decoration { cell.draw_borders(point) }
83
+ cell.tag_content { cell.draw_bounded_content(point) }
84
+ end
85
+ end
86
+ private_class_method :draw_tagged_cells
87
+
88
+ def tagged?
89
+ @pdf.tagged?
90
+ end
91
+
92
+ def tag_decoration(&)
93
+ @pdf.tag_decoration(&)
94
+ end
95
+
96
+ # A copy of the header atop a later page is an artifact: the table has its header once. A cell drawn outside
97
+ # a table has no row, and no table cell element.
98
+ def tag_content(&)
99
+ return @pdf.tag_artifact(&) if @tag_role == :repeated
100
+ return yield unless respond_to?(:row)
101
+
102
+ @pdf.tag_table_cell(row, header: @tag_role == :header, colspan:, rowspan:, &)
103
+ end
104
+
68
105
  def initialize(pdf, point, options = {})
69
106
  @pdf = pdf
70
107
  @point = point
data/lib/gamba/table.rb CHANGED
@@ -85,6 +85,7 @@ module Prawn
85
85
  started_new_page_at_row = initial_row_on_initial_page
86
86
  offset = @pdf.y
87
87
  @header_row = header_rows if @header
88
+ mark_header_cells if @header && @pdf.tagged?
88
89
  cells_this_page = []
89
90
  @cells.each do |cell|
90
91
  if start_new_page?(cell, offset, reference_bounds)
@@ -149,6 +150,12 @@ module Prawn
149
150
  cell
150
151
  end
151
152
 
153
+ # Tagged, the header is made of header cells, and its copies atop later pages are artifacts.
154
+ def mark_header_cells
155
+ row(0..(number_of_header_rows - 1)).each { _1.tag_role = :header }
156
+ @header_row.each { _1.tag_role = :repeated }
157
+ end
158
+
152
159
  def number_of_header_rows
153
160
  return @header if @header.is_a?(Integer)
154
161
 
@@ -0,0 +1,302 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Prawn
4
+ module Errors
5
+ PdfUaViolation = Class.new(StandardError)
6
+ end
7
+ end
8
+
9
+ module Gamba
10
+ # Tagged PDF (ISO 32000-1 §14.7 and §14.8), switched on with pdf: :ua (PDF/UA-1, ISO 14289-1) or pdf_a: :a
11
+ # (PDF/A-3a): a structure tree that says what the content is and in which order it reads, each piece of content
12
+ # drawn in a marked-content sequence naming its element, and what only decorates the page marked as an artifact.
13
+ # Content drawn outside both raises: a reader would never see it.
14
+ module Tagging
15
+ # A node of the structure tree: a standard structure type (P, H1, Table…), its attributes (Alt, Lang, A), and
16
+ # its kids, other elements or the marked-content sequences that hold its content, as [page, MCID].
17
+ class Element
18
+ attr_reader :type, :attributes, :kids
19
+
20
+ def initialize(type, parent, attributes = {})
21
+ @type = type
22
+ @attributes = attributes
23
+ @kids = []
24
+ parent&.kids&.push(self)
25
+ end
26
+
27
+ # A figure is read as one: its alternative text, not what it is drawn with.
28
+ def whole?
29
+ @type == :Figure
30
+ end
31
+
32
+ # The table row of this table element at a row index of Prawn's table, made when its first cell is drawn.
33
+ def row(index)
34
+ (@rows ||= {})[index] ||= Element.new(:TR, self)
35
+ end
36
+ end
37
+
38
+ # A marked-content sequence: around an element's content, or an artifact when element is nil. page is the page
39
+ # it is open on, nil once a page break closed it there: it opens again on the next page, when something is drawn.
40
+ Mark = Struct.new(:element, :properties, :page)
41
+
42
+ # Operators starting what paints the page: a text object, a path, an image, a shading (ISO 32000-1 §8.2). A
43
+ # marked-content sequence goes around them, never inside a text or a path object.
44
+ BEGINS_GRAPHICS_OBJECT = /(?:\A|\s)(?:BT|BI|Do|m|re|sh)$/
45
+ DOCUMENT_TYPE = :Document
46
+ # A BCP 47 language tag, as /Lang takes it: fr, en-GB, zh-Hant-TW.
47
+ LANGUAGE_TAG = /\A[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*\z/
48
+ HEADING_LEVELS = {H1: 1, H2: 2, H3: 3, H4: 4, H5: 5, H6: 6}.freeze
49
+ # Something besides spaces and invisible format characters (zero-width space, byte order mark…).
50
+ VISIBLE = /[^[:space:]\p{Cf}]/
51
+
52
+ # Text a reader sees or hears: a title, an alt. A string in another encoding counts if it converts to UTF-8.
53
+ def self.visible_text?(value)
54
+ value.is_a?(String) && value.valid_encoding? && value.encode(Encoding::UTF_8).match?(VISIBLE)
55
+ rescue EncodingError
56
+ false
57
+ end
58
+
59
+ # Binary bytes that are UTF-8, as File.binread returns them, read as the text they hold; anything else as given.
60
+ def self.text(value)
61
+ return value unless value.is_a?(String) && value.encoding == Encoding::BINARY
62
+
63
+ utf8 = value.dup.force_encoding(Encoding::UTF_8)
64
+ utf8.valid_encoding? ? utf8 : value
65
+ end
66
+
67
+ def tagged?
68
+ !@tagging.nil?
69
+ end
70
+
71
+ def pdf_ua?
72
+ @pdf_ua == true
73
+ end
74
+
75
+ # An element of the structure tree under the current one, which the block's elements and content go into.
76
+ # Nothing is made untagged, or within an artifact.
77
+ def tag_structure(type, **attributes, &)
78
+ return yield unless tagging_structure? && !@tagging.last.whole?
79
+
80
+ attributes.compact!
81
+ check_text_attributes(type, attributes)
82
+ check_list_nesting(type)
83
+ check_heading_level(type) if pdf_ua?
84
+
85
+ within_element(Tagging::Element.new(type, @tagging.last, attributes), &)
86
+ end
87
+
88
+ # A cell of the table element being drawn, in the row element of its row index: a header cell for a column,
89
+ # or a data cell. In a figure, the cell is part of it; outside a table element, nothing is made.
90
+ def tag_table_cell(row, header:, colspan:, rowspan:, &)
91
+ return yield unless tagging_structure?
92
+ return tag_content(&) if @tagging.last.whole?
93
+ return yield unless (table = @tagging.last).type == :Table
94
+
95
+ attributes = {}
96
+ attributes[:Scope] = :Column if header
97
+ attributes[:ColSpan] = colspan if colspan > 1
98
+ attributes[:RowSpan] = rowspan if rowspan > 1
99
+ cell = Tagging::Element.new(header ? :TH : :TD, table.row(row), attributes.empty? ? {} : {A: {O: :Table, **attributes}})
100
+ within_element(cell) { within_mark(Tagging::Mark.new(cell), &) }
101
+ end
102
+
103
+ # What the block draws is the content of the current element.
104
+ def tag_content(&)
105
+ return yield unless tagging_structure?
106
+
107
+ check_list_nesting(nil)
108
+ within_mark(Tagging::Mark.new(@tagging.last), &)
109
+ end
110
+
111
+ # What the block draws only decorates the page, as a header or a footer of type :Pagination and subtype
112
+ # :Header or :Footer: readers skip it. Elements and content within it are neither made nor marked.
113
+ def tag_artifact(type = nil, subtype = nil, &)
114
+ return yield unless tagged?
115
+
116
+ properties = type && "<</Type /#{type}#{" /Subtype /#{subtype}" if subtype}>>"
117
+ within_mark(Tagging::Mark.new(nil, properties), &)
118
+ end
119
+
120
+ # What only decorates a part of the content, a table cell's background or border: an artifact, unless it is
121
+ # drawn within tagged content, a table nested in a cell, where an artifact cannot be (ISO 14289-1 §7.1).
122
+ def tag_decoration(&)
123
+ return yield if tagged? && @marks.any?(&:element)
124
+
125
+ tag_artifact(&)
126
+ end
127
+
128
+ private
129
+
130
+ def initialize_tagging(options)
131
+ pdf = options.delete(:pdf)
132
+ raise ArgumentError, "pdf is #{pdf.inspect}: :ua is the only conformance level, PDF/UA-1" unless [nil, false, :ua].include?(pdf)
133
+
134
+ @pdf_ua = pdf == :ua
135
+ return unless @pdf_ua || @pdf_a_conformance == "A"
136
+
137
+ check_tagging_options(options)
138
+ # The open elements, the document's own first, then the marks open on the page, the innermost last.
139
+ @tagging = [Tagging::Element.new(DOCUMENT_TYPE, nil)]
140
+ @marks = []
141
+ # By page, the element of each marked-content sequence, at its MCID.
142
+ @elements_by_page = {}.compare_by_identity
143
+ end
144
+
145
+ def check_tagging_options(options)
146
+ lang = options[:lang]
147
+ if lang && !(lang.is_a?(String) && lang.match?(Tagging::LANGUAGE_TAG))
148
+ raise ArgumentError, "lang is #{lang.inspect}: give a language tag, \"fr\" or \"en-GB\""
149
+ end
150
+ return unless @pdf_ua
151
+
152
+ unless lang
153
+ raise Prawn::Errors::PdfUaViolation, 'PDF/UA documents say their language, for screen readers to speak it: lang: "en"'
154
+ end
155
+ title = options.dig(:info, :Title)
156
+ return if Tagging.visible_text?(title)
157
+
158
+ raise Prawn::Errors::PdfUaViolation, "PDF/UA documents have a title, shown in the window bar: info: {Title: \"…\"}, not #{title.inspect}"
159
+ end
160
+
161
+ def tagging_structure?
162
+ tagged? && @marks.none? { _1.element.nil? }
163
+ end
164
+
165
+ # Boxes check their alt and lang when made (Gamba::Layout::Node): here a figure must have an alt.
166
+ def check_text_attributes(type, attributes)
167
+ alt = attributes[:Alt]
168
+ if type == :Figure && !Tagging.visible_text?(alt)
169
+ raise tagging_violation, "#{tagging_standard} gives every figure an alternative text: alt: \"…\", not #{alt.inspect}"
170
+ end
171
+ end
172
+
173
+ # A list holds list items only, and a list item sits in a list. type is nil for content marked in the current
174
+ # element.
175
+ def check_list_nesting(type)
176
+ parent = @tagging.last.type
177
+ return unless (type == :LI) ? parent != :L : (parent == :L && type != :LI)
178
+
179
+ raise tagging_violation, (type == :LI) ? "#{tagging_standard} puts a list item in a list: role: :list on its container" :
180
+ "#{tagging_standard} puts only list items in a list: role: :list_item on each of its boxes"
181
+ end
182
+
183
+ # PDF/UA reads headings as an outline: the first is an h1, and each goes at most one level below the last.
184
+ def check_heading_level(type)
185
+ level = HEADING_LEVELS[type]
186
+ return unless level
187
+
188
+ last = @heading_level || 0
189
+ if level > last + 1
190
+ raise Prawn::Errors::PdfUaViolation, "PDF/UA does not skip heading levels: an h#{level} " \
191
+ "#{last.zero? ? "comes first, before any h1" : "follows an h#{last}"}"
192
+ end
193
+ @heading_level = level
194
+ end
195
+
196
+ def tagging_standard
197
+ pdf_ua? ? "PDF/UA" : "PDF/A-3a"
198
+ end
199
+
200
+ def tagging_violation
201
+ pdf_ua? ? Prawn::Errors::PdfUaViolation : Prawn::Errors::PdfAViolation
202
+ end
203
+
204
+ def within_element(element)
205
+ @tagging << element
206
+ yield
207
+ ensure
208
+ @tagging.pop
209
+ end
210
+
211
+ # The sequence is written when something is drawn in it: a box that moves to the next page before drawing
212
+ # leaves no empty sequence behind, and its decoration sees nothing drawn on the page it leaves.
213
+ def within_mark(mark)
214
+ @marks << mark
215
+ begin
216
+ yield
217
+ ensure
218
+ @marks.pop
219
+ add_content("EMC") if mark.page
220
+ end
221
+ end
222
+
223
+ def write_mark(mark)
224
+ mark.page = page
225
+ if mark.element
226
+ elements = (@elements_by_page[page] ||= [])
227
+ mark.element.kids << [page, elements.size]
228
+ add_content("/#{mark.element.type} <</MCID #{elements.size}>> BDC")
229
+ elements << mark.element
230
+ else
231
+ add_content(mark.properties ? "/Artifact #{mark.properties} BDC" : "/Artifact BMC")
232
+ end
233
+ end
234
+
235
+ # Called before the content goes to the page: what paints opens the sequences not written on this page yet, or
236
+ # raises when it is in none. Within an artifact, only the outermost one is: what it holds is part of it, and
237
+ # the elements around it wait for content of their own.
238
+ def check_tagged_content(string)
239
+ innermost = @marks.last
240
+ return if innermost&.page || !string.match?(Tagging::BEGINS_GRAPHICS_OBJECT)
241
+
242
+ unless innermost
243
+ raise tagging_violation, "#{tagging_standard} tags all content, and this is drawn outside any tagged box or artifact: " \
244
+ "draw it with Gamba's boxes, or leave it out (#{string.strip.lines.last.strip.inspect})"
245
+ end
246
+
247
+ artifact = @marks.index { _1.element.nil? }
248
+ if artifact
249
+ # Artifacts within one, a decoration moved beneath what it holds, are written too: they leave it.
250
+ @marks[artifact..].each { |mark| write_mark(mark) unless mark.element || mark.page }
251
+ else
252
+ @marks.each { |mark| write_mark(mark) unless mark.page }
253
+ end
254
+ end
255
+
256
+ # Before leaving a page, the sequences open on it are closed there.
257
+ def close_marks_on_page
258
+ @marks&.reverse_each do |mark|
259
+ next unless mark.page
260
+
261
+ add_content("EMC")
262
+ mark.page = nil
263
+ end
264
+ end
265
+
266
+ # The structure tree, the parent tree that maps each page's marked content back to its elements, and the
267
+ # catalog entries a tagged PDF and PDF/UA ask for.
268
+ def finalize_tagging
269
+ raise ArgumentError, "a marked-content sequence is still open" unless @marks.empty?
270
+
271
+ min_version(1.7)
272
+ references = {}.compare_by_identity
273
+ tree = ref!(Type: :StructTreeRoot)
274
+ tree.data[:K] = [structure_reference(@tagging.first, tree, references)]
275
+ nums = []
276
+ pages.each do |page|
277
+ elements = @elements_by_page[page]
278
+ next unless elements
279
+
280
+ page.dictionary.data[:StructParents] = nums.size / 2
281
+ nums << (nums.size / 2) << elements.map { references.fetch(_1) }
282
+ end
283
+ tree.data[:ParentTree] = ref!(Nums: nums)
284
+ tree.data[:ParentTreeNextKey] = nums.size / 2
285
+ @root.data[:StructTreeRoot] = tree
286
+ @root.data[:MarkInfo] = {Marked: true}
287
+ @root.data[:ViewerPreferences] = {**(@root.data[:ViewerPreferences] || {}), DisplayDocTitle: true}
288
+ end
289
+
290
+ def structure_reference(element, parent, references)
291
+ reference = ref!(Type: :StructElem, S: element.type, P: parent, **element.attributes)
292
+ references[element] = reference
293
+ reference.data[:K] = element.kids.map do |kid|
294
+ next structure_reference(kid, reference, references) if kid.is_a?(Tagging::Element)
295
+
296
+ page, mcid = kid
297
+ {Type: :MCR, Pg: page.dictionary, MCID: mcid}
298
+ end
299
+ reference
300
+ end
301
+ end
302
+ end
@@ -0,0 +1,79 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "pdf_check"
4
+
5
+ module Gamba
6
+ # What an application's tests ask of its PDFs, in words of the test frameworks: Gamba::Minitest and Gamba::RSpec
7
+ # put it in their own forms. A check whose tool is missing fails with the install command, or is skipped when
8
+ # Gamba::Testing.missing_tools is :skip; it never passes unchecked.
9
+ module Testing
10
+ MISSING_TOOLS = %i[fail skip].freeze
11
+ # Text found this many points from where it was expected is where it was expected.
12
+ POSITION_TOLERANCE = 1
13
+
14
+ class << self
15
+ attr_reader :missing_tools
16
+
17
+ def missing_tools=(choice)
18
+ raise ArgumentError, "missing_tools is #{choice.inspect}: give :fail or :skip" unless MISSING_TOOLS.include?(choice)
19
+
20
+ @missing_tools = choice
21
+ end
22
+
23
+ # nil when the text is on the page (any page unless told), else what was there instead. text: a String, whose
24
+ # spaces match any run of them, or a Regexp; at: [x, y] of its first character's baseline, in points from the page's
25
+ # top left, as MuPDF reads it.
26
+ def text_failure(pdf, text, page: nil, at: nil)
27
+ pages = PdfCheck.text_layout(pdf)
28
+ candidates = page ? [pages[page - 1]].compact : pages
29
+ return "the PDF has #{pages.size} pages, not #{page}" if candidates.empty?
30
+
31
+ pattern = text.is_a?(Regexp) ? text : Regexp.new(text.split.map { Regexp.escape(_1) }.join("\\s+"))
32
+ found = candidates.any? { |candidate| lines(candidate).any? { |glyphs| occurs?(glyphs, pattern, at) } }
33
+ return nil if found
34
+
35
+ place = page ? "page #{page}" : "the PDF"
36
+ "#{text.inspect} is not on #{place}#{" at #{at.inspect}" if at}: it reads\n#{candidates.map { |candidate| lines(candidate).map { _1.map(&:first).join }.join("\n") }.join("\n---\n")}"
37
+ end
38
+
39
+ def pages_failure(expected, actual)
40
+ differences = PdfCheck.page_differences(expected, actual)
41
+ differences.empty? ? nil : "the pages differ:\n#{differences.join("\n")}"
42
+ end
43
+
44
+ def validity_failure(pdf)
45
+ problem = PdfCheck.invalidity(pdf)
46
+ problem && "the PDF is not valid: #{problem}"
47
+ end
48
+
49
+ def pdf_a_failure(pdf, flavour: "3b")
50
+ report = PdfCheck.pdf_a_failure(pdf, flavour:)
51
+ report && "the PDF is not PDF/A-#{flavour}:\n#{report}"
52
+ end
53
+
54
+ private
55
+
56
+ def lines(page)
57
+ page.glyphs.group_by(&:last).sort.map!(&:last)
58
+ end
59
+
60
+ # Whether the pattern matches the line, from a glyph near `at` when told.
61
+ def occurs?(glyphs, pattern, at)
62
+ line = glyphs.map(&:first).join
63
+ position = 0
64
+ while (match = pattern.match(line, position))
65
+ return true if at.nil? || near?(glyphs[match.begin(0)], at)
66
+
67
+ position = match.begin(0) + 1
68
+ end
69
+ false
70
+ end
71
+
72
+ def near?(glyph, (x, y))
73
+ glyph && (glyph[3] - x).abs <= POSITION_TOLERANCE && (glyph[4] - y).abs <= POSITION_TOLERANCE
74
+ end
75
+ end
76
+
77
+ self.missing_tools = :fail
78
+ end
79
+ end
@@ -93,6 +93,11 @@ module Prawn
93
93
  @overflow != :shrink_to_fit && self.class.extensions.empty? && @original_array.none? { _1[:color] }
94
94
  end
95
95
 
96
+ # How far below the box's top each line of the last kept layout ends, its descender included.
97
+ def line_bottoms
98
+ @laid_out_lines.map { |baseline_y, _drawn_fragments, descender| descender - baseline_y }
99
+ end
100
+
96
101
  # Draws, with its top left corner at `at`, the lines the last kept layout wrapped, without wrapping them again.
97
102
  def render_laid_out(at)
98
103
  @at = at.dup
@@ -55,7 +55,7 @@ module Prawn
55
55
  drawn_fragments << drawn_fragment if @laid_out_lines
56
56
  accumulated_width += fragment.width
57
57
  end
58
- @laid_out_lines << [@baseline_y, drawn_fragments] if @laid_out_lines
58
+ @laid_out_lines << [@baseline_y, drawn_fragments, @descender] if @laid_out_lines
59
59
  @printed_lines << printed_fragments.map { _1.dup.force_encoding(::Encoding::UTF_8) }.join
60
60
  end
61
61