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…

StageTime to renderFile 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.