Migration
From Prawn to Gamba’s own API in three stages. Each one is worth doing alone, and you can stop after any of them: an application with fifty Prawn documents moves one block, then one document, at a time.
1. Switch the gem
Replace prawn, prawn-table and prawn-svg with gem "gamba" in the Gemfile, and change nothing else. Your documents draw the same pages, pixel for pixel, in less time and in lighter files. This page follows one document through the three stages, the invoice of the benchmarks; here it is as Prawn code, which Gamba runs unchanged:
Prawn::Document.generate("invoice.pdf") do
font_families.update("DejaVuSans" => {normal: "DejaVuSans.ttf", bold: "DejaVuSans-Bold.ttf"})
font "DejaVuSans", size: 9
image "letterhead.jpg", width: 200
text "Invoice INV-2026-0001 — Alice Example", style: :bold, size: 14
move_down 10
lines = Array.new(10) { ["SKU#{_1}", "Gadget, deluxe edition, model #{_1} with spare parts toolkit", "2", "$1,299.00", "$2,598.00"] }
table([%w[SKU Description Qty Unit Total], *lines], header: true, width: bounds.width, cell_style: {padding: 3})
end
What you gain: the speed and weight of the benchmarks, one gem instead of three, and Prawn’s bugs fixed, each declared. What can break: not Prawn’s public API, which a contract guards; an extension that patches Prawn’s internals may need a look.
2. Native blocks in existing documents
In any Prawn document, gamba opens a block of the native API at the cursor, and leaves the cursor below what it drew. Move the part of a document that costs you the most code first: usually a table counted by position, or columns placed by hand. Here the invoice’s table becomes a table with named columns, over rows that are hashes:
Prawn::Document.generate("invoice.pdf") do
font_families.update("DejaVuSans" => {normal: "DejaVuSans.ttf", bold: "DejaVuSans-Bold.ttf"})
font "DejaVuSans", size: 9
image "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
end
The PDF is the same, byte for byte: the native table starts from the font Prawn’s code set, at the cursor Prawn’s code left. Nothing else in the document changes, so each block can be reviewed and released on its own. What you gain: rows taken from your models as they are, options that raise when mistyped instead of being ignored, and boxes measured before they are drawn.
Inside the block, document.prawn is the Prawn document itself, for what the native API does not cover yet.
3. New documents in the native API
Write new documents with Gamba.document, and move an existing one when you next rework it. The block receives the document instead of running inside it, so your own methods and instance variables stay in reach, and the document can be split into small classes that draw takes:
Gamba.document do |document|
document.register_font "DejaVuSans", normal: "DejaVuSans.ttf", bold: "DejaVuSans-Bold.ttf"
document.style :default, font: "DejaVuSans", size: 9
document.image "letterhead.jpg", width: 200, alt: "Example Inc. letterhead"
document.text "Invoice INV-2026-0001 — Alice Example", weight: :bold, size: 14
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"} }
document.stack(padding: [10, 0, 0, 0]) do |stack|
stack.table(lines, columns: {sku: {title: "SKU"}, description: {}, quantity: {title: "Qty"}, unit: {}, total: {}}, header: {weight: :normal}, cell: {padding: 3})
end
end.write("invoice.pdf")
The pages are no longer Prawn’s: fonts use their ligatures and kerning, and paragraphs keep their widows and orphans, as a typesetter would. What you gain on top of stage 2: headers and footers that know their page number, headings that make the PDF’s bookmarks, and a tagged PDF for screen readers from one option, since every box already says what it is:
Gamba.document(pdf: :ua, lang: "en", info: {Title: "Invoice INV-2026-0001"}) do |document|
# the same body: the letterhead's alt text is all PDF/UA asks of this invoice
end
The invoice at each stage
Loading the latest numbers…
| Stage | Time to render | File weight |
|---|
The code of each stage is bench/documents/invoice.rb, bench/mixed/invoice.rb and bench/native/invoice.rb, which rake bench measures before each release; a test checks that this page shows that code, and that each stage draws the same text.
Prawn idioms, side by side
What Prawn code computes by hand, the native API describes. Each pair draws the same text; a test runs both.
Columns placed with bounding_box
A row is as high as its tallest child, and what follows starts below it.
Prawn
Prawn::Document.generate("address.pdf") do
top = cursor
bounding_box([0, top], width: 250) do
text "Alice Martin", size: 14, style: :bold
text "1 Example Street, 75001 Paris"
end
left_bottom = cursor
bounding_box([bounds.width - 150, top], width: 150) do
text "Due on 1 December 2026", align: :right
end
move_cursor_to [left_bottom, cursor].min
move_down 20
text "This starts below the taller column."
end
Gamba
Gamba.document do |document|
document.stack(gap: 20) do |page|
page.row(gap: 24) do |row|
row.stack do |address|
address.text "Alice Martin", size: 14, weight: :bold
address.text "1 Example Street, 75001 Paris"
end
row.text "Due on 1 December 2026", width: 150, align: :right
end
page.text "This starts below the taller column."
end
end.write("address.pdf")
Fonts and colours set, then reset, with move_down between
Styles name text attributes once; a call passes only what differs. Space is a container’s gap or padding, not a cursor moved by hand.
Prawn
Prawn::Document.generate("terms.pdf") do
font_families.update("DejaVuSans" => {normal: "DejaVuSans.ttf", bold: "DejaVuSans-Bold.ttf"})
font "DejaVuSans", size: 10
font_size(16) { text "Payment terms", style: :bold }
move_down 6
text "Payment is due within 30 days."
fill_color "666666"
text "Late payments bear interest at three times the legal rate."
fill_color "000000"
end
Gamba
Gamba.document do |document|
document.register_font "DejaVuSans", normal: "DejaVuSans.ttf", bold: "DejaVuSans-Bold.ttf"
document.style :default, font: "DejaVuSans", size: 10
document.style :heading, size: 16, weight: :bold
document.stack(gap: 6) do |terms|
terms.text "Payment terms", style: :heading
terms.stack do |body|
body.text "Payment is due within 30 days."
body.text "Late payments bear interest at three times the legal rate.", color: "666666"
end
end
end.write("terms.pdf")
Tables counted by position
Columns are named, rows are hashes or objects answering those names, and a column’s alignment sits with its title.
Prawn
lines = [{sku: "A-1", description: "Gadget", quantity: 2}, {sku: "B-2", description: "Gizmo", quantity: 1}]
Prawn::Document.generate("lines.pdf") do
rows = lines.map { |line| [line[:sku], line[:description], line[:quantity]] }
table([%w[SKU Description Qty], *rows], header: true) do
row(0).font_style = :bold
column(2).align = :right
end
end
Gamba
lines = [{sku: "A-1", description: "Gadget", quantity: 2}, {sku: "B-2", description: "Gizmo", quantity: 1}]
Gamba.document do |document|
document.table(lines, columns: {
sku: {title: "SKU"},
description: {},
quantity: {title: "Qty", align: :right}
})
end.write("lines.pdf")
repeat and number_pages
A header and a footer are declared once and run for every page once the pages are counted; the body breaks pages around them without a bounding box of its own.
Prawn
Prawn::Document.generate("report.pdf") do
repeat(:all) do
bounding_box([0, bounds.top], width: bounds.width, height: 20) { text "Example SAS", style: :bold }
end
bounding_box([0, bounds.top - 30], width: bounds.width, height: bounds.height - 60) do
60.times { |index| text "Paragraph #{index + 1} of the report." }
end
number_pages "Page <page> of <total>", at: [0, 10], width: bounds.width, align: :center, size: 8
end
Gamba
Gamba.document do |document|
document.header(gap: 10) { |header, _page| header.text "Example SAS", weight: :bold }
document.footer(gap: 10) do |footer, page|
footer.text "Page #{page.number} of #{page.total}", align: :center, size: 8
end
60.times { |index| document.text "Paragraph #{index + 1} of the report." }
end.write("report.pdf")
Room left on the page, measured by hand
A heading with keep_with_next moves to the next page with the start of what follows it, whatever their size.
Prawn
Prawn::Document.generate("totals.pdf") do
50.times { |index| text "Line #{index + 1} of the invoice" }
# Room for the heading and the lines under it, measured by hand.
start_new_page if cursor < 50
text "Totals", size: 16, style: :bold
text "Subtotal: $2,598.00"
text "Total: $3,117.60"
end
Gamba
Gamba.document do |document|
document.style :heading, size: 16, weight: :bold, keep_with_next: true
50.times { |index| document.text "Line #{index + 1} of the invoice" }
document.text "Totals", style: :heading
document.stack do |totals|
totals.text "Subtotal: $2,598.00"
totals.text "Total: $3,117.60"
end
end.write("totals.pdf")
What still goes through Prawn
SVG, vector graphics, text boxes at fixed positions, links and encryption have no native call yet: document.prawn gives a native document all of Prawn’s API, and what it draws takes its place in the flow. Prawn’s table of arrays stays at document.prawn.table, and a native table’s block receives the Prawn::Table for spans and single cells.
The guide describes every native call, and test/contract/gamba.yml lists each public method with its signature: a change there is a decision, never an accident.