diff --git a/README.md b/README.md index 65b1217..706cdb4 100644 --- a/README.md +++ b/README.md @@ -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/ @@ -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" @@ -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`. @@ -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: diff --git a/Rakefile b/Rakefile index 40817b1..82b2839 100644 --- a/Rakefile +++ b/Rakefile @@ -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 diff --git a/bench/compare.rb b/bench/compare.rb index afb3366..7c9f9ab 100644 --- a/bench/compare.rb +++ b/bench/compare.rb @@ -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. @@ -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 } diff --git a/bench/mixed/invoice.rb b/bench/mixed/invoice.rb new file mode 100644 index 0000000..486e8da --- /dev/null +++ b/bench/mixed/invoice.rb @@ -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 diff --git a/docs/benchmarks.html b/docs/benchmarks.html index 206517a..12ab216 100644 --- a/docs/benchmarks.html +++ b/docs/benchmarks.html @@ -25,6 +25,7 @@