Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 25 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
# Gamba

Gamba is a Ruby library that writes PDF files: invoices, reports, labels, anything you can lay out as text, tables,
images and shapes. It is a faster rewrite of [Prawn](https://github.com/prawnpdf/prawn), the most widely used PDF
library for Ruby, together with its two companion gems, prawn-table and prawn-svg.
images and shapes. You describe the layout, stacks, rows, tables, headers and footers, and Gamba measures it, places
it, breaks pages where a reader expects them, and tags the result for screen readers.

Code written for Prawn 2.5 runs on Gamba unchanged and draws the same pages, down to the pixel. The difference is
speed and size: a one-page invoice renders about four times faster and the file is a quarter lighter (see
[Performance](#performance)).
It also runs code written for [Prawn](https://github.com/prawnpdf/prawn) 2.5, the most widely used PDF library for
Ruby, and for its companions prawn-table and prawn-svg, unchanged and down to the pixel: a one-page invoice renders
about four times faster and the file is a quarter lighter (see [Performance](#performance)). An application moves
from one API to the other one block at a time ([the migration guide](https://levups.github.io/gamba/migration.html)).

Website and guide: https://levups.github.io/gamba/

Expand All @@ -24,6 +25,19 @@ without them.

## A first document

```ruby
require "gamba"

Gamba.document do |document|
document.footer { |footer, page| footer.text "Page #{page.number} of #{page.total}" }
document.text "Hello, World!", role: :h1
document.table([{sku: "A-1", quantity: 2}], columns: {sku: {title: "SKU"}, quantity: {title: "Qty"}})
end.write("hello.pdf")
```

This writes `hello.pdf` with a heading, which also makes the PDF's first bookmark, a two-row table and a footer
numbering the pages. The same document with Prawn's API, which Gamba runs as it is:

```ruby
require "prawn"

Expand All @@ -33,9 +47,9 @@ Prawn::Document.generate("hello.pdf") do
end
```

This writes `hello.pdf` with a line of text and a two-row table. Everything else Prawn documents works the same
way: fonts, colors, images, columns, page numbers, links, encryption. Prawn's manual applies as it is, and
[the guide](https://levups.github.io/gamba/guide.html) covers what Gamba adds.
Everything else Prawn documents works the same way: fonts, colors, images, columns, page numbers, links,
encryption. Prawn's manual applies as it is, and [the guide](https://levups.github.io/gamba/guide.html) covers what
Gamba adds.

The constant is still `Prawn`, so you don't have to rename anything. `Prawn::VERSION` reports `2.5.0`, the
version of the API Gamba reproduces, for code that checks it. Gamba's own version is `Gamba::VERSION`.
Expand Down Expand Up @@ -83,8 +97,9 @@ document.table(lines, columns: {sku: {title: "SKU", width: 60}, description: {},
Pages break where a reader expects them: a paragraph leaves no single line at the bottom or the top of a page
(`widows` and `orphans`, 2 unless told), and a heading with `keep_with_next: true` moves with what follows it.

Text, styles, components, stacks, rows, grids, tables, images, headers, footers and these page breaks are there today;
boxes with a background split across pages come next ([the plan](https://github.com/levups/gamba/issues/69)).
Text, styles, components, stacks, rows, grids, tables, images, codes, headers, footers, these page breaks and
semantic roles are there today; forms, signatures and complex scripts come next
([the plan](https://github.com/levups/gamba/issues/69)).

Ligatures and kerning from OpenType fonts, per font:

Expand Down
2 changes: 1 addition & 1 deletion Rakefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ namespace :corpus do
end
end

desc "Compare Gamba with Prawn on bench/documents, and Gamba's own API untagged and tagged on bench/native, into docs/benchmarks.json"
desc "Compare Gamba with Prawn on bench/documents, one native block on bench/mixed, and Gamba's own API untagged and tagged on bench/native, into docs/benchmarks.json"
task :bench do
ruby "bench/compare.rb"
end
Expand Down
15 changes: 9 additions & 6 deletions bench/compare.rb
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# frozen_string_literal: true

# Renders each document of bench/documents with Prawn and with Gamba, and its bench/native version with Gamba's own
# API untagged then tagged for PDF/UA, in PROCESSES fresh YJIT processes per column, and writes the median of each
# Renders each document of bench/documents with Prawn and with Gamba, its bench/mixed version (Prawn code holding one
# block of Gamba's own API) with Gamba, and its bench/native version with Gamba's own API untagged then tagged for
# PDF/UA, in PROCESSES fresh YJIT processes per column, and writes the median of each
# measure across them (time, allocations, peak memory, file weight) to docs/benchmarks.json. Peak memory varies by 20%
# from one process to the next: one process proves nothing.

Expand Down Expand Up @@ -49,20 +50,22 @@ def median(values)
sorted.all?(Integer) ? mean.round(half: :even) : mean.round(1, half: :even)
end

# What each column of the results renders: the document with Prawn's API on each engine, and with Gamba's own API
# where bench/native has it, untagged then tagged for PDF/UA.
# What each column of the results renders: the document with Prawn's API on each engine, with one native block where
# bench/mixed has it, and with Gamba's own API where bench/native has it, untagged then tagged for PDF/UA.
def candidates(document)
mixed = File.join(__dir__, "mixed", File.basename(document))
native = File.join(NativeBench::DIRECTORY, File.basename(document))
columns = Oracle::ENGINES.keys.to_h { |engine| [engine, [engine, document]] }
columns["gamba_mixed"] = ["gamba", mixed] if File.exist?(mixed)
return columns unless File.exist?(native)

columns.merge("gamba_native" => ["gamba", native], "gamba_tagged" => ["gamba", native, "pdf_ua"])
end

# A Williams design: over as many rounds as columns, each column takes each place once and follows each other column
# once (an even count of columns, as here), so neither a slower moment of the machine nor a heavier neighbour falls
# once (for an even count of columns), so neither a slower moment of the machine nor a heavier neighbour falls
# on one column more than another. Only a multiple of the columns balances all the rounds: 8, the default, balances
# the four columns twice.
# the four columns twice, and gives the invoice's fifth, its native block, each place at least once.
def order(count, round)
first = [0] + (1...count).map { |step| step.odd? ? (step + 1) / 2 : count - (step / 2) }
first.map { |index| (index + round) % count }
Expand Down
10 changes: 10 additions & 0 deletions bench/mixed/invoice.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# The invoice of bench/documents, its table moved to one block of Gamba's own API: the middle step of a migration.
font_families.update("DejaVuSans" => {normal: "#{DATA_DIRECTORY}/fonts/DejaVuSans.ttf", bold: "#{DATA_DIRECTORY}/fonts/DejaVuSans-Bold.ttf"})
font "DejaVuSans", size: 9
image "#{DATA_DIRECTORY}/images/letterhead.jpg", width: 200
text "Invoice INV-2026-0001 — Alice Example", style: :bold, size: 14
move_down 10
lines = Array.new(10) { {sku: "SKU#{_1}", description: "Gadget, deluxe edition, model #{_1} with spare parts toolkit", quantity: "2", unit: "$1,299.00", total: "$2,598.00"} }
gamba do |document|
document.table(lines, columns: {sku: {title: "SKU"}, description: {}, quantity: {title: "Qty"}, unit: {}, total: {}}, header: {weight: :normal}, cell: {padding: 3})
end
5 changes: 3 additions & 2 deletions docs/benchmarks.html
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
<nav class="site-nav" aria-label="Site">
<a class="brand" href="./">Gamba</a>
<a href="guide.html">Guide</a>
<a href="migration.html">Migration</a>
<a href="compatibility.html">Compatibility</a>
<a href="benchmarks.html" aria-current="page">Benchmarks</a>
<a href="https://github.com/levups/gamba">GitHub</a>
Expand All @@ -46,7 +47,7 @@ <h2 id="documents-title">Three documents, two engines, two APIs, tagged or not</
<p class="note" id="bench-note">Loading the latest numbers…</p>
<div id="documents"></div>
<div class="prose">
<p>“Gamba, own API” is the same document written with Gamba’s own API, in <code>bench/native/</code>: boxes measured then placed, ligatures and kerning on, widows and orphans kept. It draws a page as a typesetter would rather than as Prawn does, so its file weight differs a little; Prawn and Gamba draw the same pages. “Gamba, own API, PDF/UA” is that same document with <code>pdf: :ua</code>: what tagging costs, the structure tree and its marked content, the language, the title and the XMP metadata. Prawn compresses its streams only when asked: it is measured with <code>compress: true</code>, at its lightest. Peak memory is the whole process’s maximum resident set size, Ruby included.</p>
<p>“Gamba, one native block” is the invoice’s Prawn code with its table moved to a <code>gamba</code> block, in <code>bench/mixed/</code>: the middle stage of the <a href="migration.html">migration</a>, byte for byte the same PDF. “Gamba, own API” is the same document written with Gamba’s own API, in <code>bench/native/</code>: boxes measured then placed, ligatures and kerning on, widows and orphans kept. It draws a page as a typesetter would rather than as Prawn does, so its file weight differs a little; Prawn and Gamba draw the same pages. “Gamba, own API, PDF/UA” is that same document with <code>pdf: :ua</code>: what tagging costs, the structure tree and its marked content, the language, the title and the XMP metadata. Prawn compresses its streams only when asked: it is measured with <code>compress: true</code>, at its lightest. Peak memory is the whole process’s maximum resident set size, Ruby included.</p>
</div>
</section>

Expand All @@ -66,7 +67,7 @@ <h2 id="reproduce-title">Reproduce</h2>
<pre><code class="language-sh">bundle <span class="nb">install</span> <span class="o">&amp;&amp;</span> <span class="nv">BUNDLE_GEMFILE</span><span class="o">=</span>oracle/Gemfile bundle <span class="nb">install
</span>bundle <span class="nb">exec </span>rake corpus:fetch <span class="c"># Prawn's fonts and images, into corpus/cache</span>
bundle <span class="nb">exec </span>rake bench <span class="c"># BENCH_ITERATIONS=20 by default</span></code></pre>
<p><code>bench/compare.rb</code> renders each document of <code>bench/documents/</code> with Prawn, from its own bundle in <code>oracle/Gemfile</code>, and with Gamba, and each document of <code>bench/native/</code> with Gamba, untagged then tagged for PDF/UA, in fresh YJIT processes per column that take turns, 8 by default so that each order of the four columns comes back as often. Each process measures the median of 20 renders, the objects one render allocates, the file’s weight and its peak memory; the site shows the median of those processes, as <code>docs/benchmarks.json</code> records it. Peak memory varies by about 20% from one process to the next, which one process cannot show. It writes <code>docs/benchmarks.json</code>, which every page of this site reads.</p>
<p><code>bench/compare.rb</code> renders each document of <code>bench/documents/</code> with Prawn, from its own bundle in <code>oracle/Gemfile</code>, and with Gamba, each document of <code>bench/mixed/</code> with Gamba, and each document of <code>bench/native/</code> with Gamba, untagged then tagged for PDF/UA, in fresh YJIT processes per column that take turns, 8 by default so that each order of the four columns comes back as often, and the invoice’s fifth column takes each place at least once. Each process measures the median of 20 renders, the objects one render allocates, the file’s weight and its peak memory; the site shows the median of those processes, as <code>docs/benchmarks.json</code> records it. Peak memory varies by about 20% from one process to the next, which one process cannot show. It writes <code>docs/benchmarks.json</code>, which every page of this site reads.</p>
</div>
</section>
</main>
Expand Down
1 change: 1 addition & 0 deletions docs/compatibility.html
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
<nav class="site-nav" aria-label="Site">
<a class="brand" href="./">Gamba</a>
<a href="guide.html">Guide</a>
<a href="migration.html">Migration</a>
<a href="compatibility.html" aria-current="page">Compatibility</a>
<a href="benchmarks.html">Benchmarks</a>
<a href="https://github.com/levups/gamba">GitHub</a>
Expand Down
3 changes: 2 additions & 1 deletion docs/guide.html
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
<nav class="site-nav" aria-label="Site">
<a class="brand" href="./">Gamba</a>
<a href="guide.html" aria-current="page">Guide</a>
<a href="migration.html">Migration</a>
<a href="compatibility.html">Compatibility</a>
<a href="benchmarks.html">Benchmarks</a>
<a href="https://github.com/levups/gamba">GitHub</a>
Expand All @@ -33,7 +34,7 @@
<main id="main">
<header>
<h1 class="page-title">Guide</h1>
<p class="lede">Gamba answers to Prawn’s API: installing it is swapping gems. This page covers what it brings on top, and its own API, which existing code adopts one block at a time.</p>
<p class="lede">Gamba has an API of its own, and answers to Prawn’s: installing it is swapping gems. This page covers both, and the <a href="migration.html">migration page</a> takes existing Prawn code to the native API one block at a time.</p>
<ul class="toc">
<li><a href="#installation">Installation</a></li>
<li><a href="#usage">Drop-in usage</a></li>
Expand Down
Loading
Loading