Prawn PDF Generation Library

Prawn is a pure Ruby PDF generation library designed for flexibility. Key capabilities include:

• Vector Drawing: Lines, polygons, curves, ellipses, etc.
• Text Rendering: Flowing text and limited inline formatting.
• Font Support: PDF built-in fonts and embedded TrueType fonts.
• Layout Tools: Basic layout tools including a simple grid system.
• Image Embedding: PNG and JPG support with scaling options.
• Security: Encryption and password protection.
• Repeatable Content: Tools for headers, footers, and page numbers.
• Internationalization: UTF-8 support, right-to-left text rendering, and fallback fonts.
• Navigation: Support for PDF outlines.
• Low-level Access: Ability to manipulate the PDF object tree layer directly.

When to use Prawn

Use Prawn if you need a highly flexible PDF document generation system. It can be used as a foundation for building reporting or publishing toolchains.

When NOT to use Prawn

Prawn is not an HTML to PDF generator. While it has very limited support for basic inline styling, it is not suitable for rendering rich HTML documents. If you need HTML to PDF conversion, consider using Ferrum.

Versioning and Stability

Prawn does not strictly follow Semantic Versioning because it frequently releases experimental APIs that may not be stable. However, the stable portion of the API follows Semantic Versioning. Note that bug fixes may change behavior; always test your application after updating.

Prawn can be installed via RubyGems using the command line, or directly from the git repository. The master branch contains the latest developments and may contain bugs.

gem install prawn

AFM fonts are used for PDF built-in fonts. These fonts do not contain glyph outlines and rely on the target system having the fonts installed. They are space-efficient but do not support Unicode.

Supported Built-in Fonts:

• Courier
• Helvetica
• Times-Roman
• Symbol
• ZapfDingbats
• Courier-Bold
• Courier-Oblique
• Courier-BoldOblique
• Times-Bold
• Times-Italic
• Times-BoldItalic
• Helvetica-Bold
• Helvetica-Oblique
• Helvetica-BoldOblique

Important Limitations:

• They only support WinAnsi (Windows-1252) encoding.
• If you need full UTF-8 support, you must use external fonts instead of these built-in AFM fonts.

To generate a simple PDF file, require prawn and use the Prawn::Document.generate method. This method accepts a filename and a block where you define the document content using Prawn's DSL (e.g., text).

require "prawn"

Prawn::Document.generate("hello.pdf") do
  text "Hello World!"
end

You can control where Prawn looks for .afm files by setting the METRICS environment variable. The variable should contain a colon-separated list of paths.

If ENV['METRICS'] is not set, Prawn searches the following default locations:

• . (current directory)
• /usr/lib/afm
• /usr/local/lib/afm
• /usr/openwin/lib/fonts/afm
• #{Prawn::DATADIR}/fonts

When working with TrueType fonts in Prawn, you may encounter specific error classes. Understanding these can help diagnose issues with your font files:

• Prawn::Fonts::TTF::Error: A general error indicating an issue with the TTF font.
• Prawn::Fonts::TTF::NoUnicodeCMap: Raised when the font lacks a Unicode character map. This is critical for proper character rendering.
• Prawn::Fonts::TTF::NoPostscriptName: Raised when a PostScript name cannot be detected in the font file.

The dash method will raise an ArgumentError in the following cases:

• If all provided lengths in the array are zero: Zero length dashes are invalid. Call #undash to disable dashes.
• If any provided length is negative: Negative numbers are not allowed for dash lengths.

Use stroke_color to manage the color used for drawing lines/outlines.

• To get the current color: Call stroke_color with no arguments.
• To set a color using HTML hex: Provide a single 6-digit hex string (e.g., "f0ffc1").
• To set a color using CMYK: Provide 4 arguments representing CMYK values. Each value must be in the range 0–100.

Note: stroke_color= is an alias for setting the color.