Prawn: Fast, Nimble PDF Generation For Ruby

Prawn is a PDF writing library for Ruby designed to be tiny, fast, and nimble, just like the majestic sea creature.

Development on this library was initially made possible thanks to the many people who donated to the Ruby Mendicant project: rubymendicant.wikidot.com

The project is currently maintained by Gregory Brown, with lots of help from Prawn’s core developers and the community.

Quick Start

Getting started with Prawn can be as simple as:

require 'prawn'
pdf = Prawn::Document.new
pdf.text("Prawn Rocks")
pdf.render_file('prawn.pdf')

But prawn can do a lot more:

Any page size you can think of

Prawn::Document.new('A0')

…gives you an really big page.

Prawn::Document.new(:page_size   => [11.32, 8.49],
                    :page_layout => :portrait)

…giving you a postage stamp.

Learn more

Multiple Font Handling with UTF-8 Support

pdf.text("Prawn Rocks")
pdf.font("/myfont.ttf")
pdf.text("Prawn still rocks in a different font")

…allowing you to use any font you want.

Learn more

Drawing graphics directly into the page

Simple shapes:

pdf.stroke do
  pdf.circle_at [100,100], :radius => 25
  pdf.rectangle [300,300], 100, 200
end

(note, you need to stroke the path to put “ink” there)

Learn more

Embedding JPEG and PNG Images Natively

Reading an image directly from a file:

 = "#{Prawn::BASEDIR}/data/images/prawn_logo.png"
pdf.image , :at => [50,450], :width => 450

Or reading it from an IO stream:

require "open-uri"
pdf.image open("http://prawn.majesticseacreature.com/media/prawn_logo.png")

Learn more

Measurement Conversion Tools for Your Sanity

Prawn deals exclusively in PDF points… which work out to about 2.83464567mm… don’t try and do it in your head, instead, let Prawn help you:

require "prawn/measurement_extensions"

Prawn::Document.generate(:page_layout => :portrait, 
                    :left_margin => 10.mm,    # different
                    :right_margin => 1.cm,    # units
                    :top_margin => 0.1.dm,    # work
                    :bottom_margin => 0.01.m, # well 
                    :page_size => 'A4') do
  text "Prawn Rocks"
end

Learn more

Resources

Website:

prawn.majesticseacreature.com

Examples:

github.com/sandal/prawn/tree/stable/examples

For tables and grid based layout:

github.com/sandal/prawn-layout/tree/stable/examples

For encryption, password protection, and permissions:

github.com/madriska/prawn-security/tree/stable/examples

(or gem unpack prawn-core, prawn-security and prawn-layout if you want to run them locally)

Bug Tracker / Wiki:

github.com/sandal/prawn/issues github.com/sandal/prawn-layout/issues github.com/madriska/prawn-security/issues

Source Code:

github.com/sandal/prawn github.com/sandal/prawn-layout github.com/madriska/prawn-security

Mailing List:

groups.google.com/group/prawn-ruby

IRC:

Find us in #prawn on irc.freenode.net

Gregory Brown: <sandal>
James Healy: <yob>               
Brad Ediger: <bradediger>
Daniel Nelson: <bluejade>

Notes to Developers:

See HACKING file for details on getting set up with a local build.