Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 142 lines (88 sloc) 3.54 KB
= 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:
http://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}[link:classes/Prawn/Document.html]
===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}[link:classes/Prawn/Font.html]
===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}[link:classes/Prawn/Graphics.html]
===Embedding JPEG and PNG Images Natively
Reading an image directly from a file:
prawn_logo = "#{Prawn::BASEDIR}/data/images/prawn_logo.png"
pdf.image prawn_logo, :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}[link:classes/Prawn/Images.html]
===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}[link:classes/Prawn/Measurements.html]
===Document Security, Permissions, and Encryption
See examples/security/ for example code, such as this:
require 'prawn/security'
Prawn::Document.generate("hello_foo.pdf") do
text "Hello, world!"
encrypt_document :user_password => 'foo', :owner_password => 'bar',
:permissions => { :print_document => false }
end
This creates a document that requires the password 'foo' to be opened,
and cannot be printed without entering the owner password 'bar'.
If you want to prohibit most anyone from performing a certain activity, you can
pass :owner_password => :random to generate a probably-unguessable owner
password.
== Resources
=== Examples:
http://github.com/sandal/prawn/tree/stable/examples
=== Bug Tracker:
http://github.com/sandal/prawn/issues
=== Source Code:
http://github.com/sandal/prawn
=== Mailing List:
http://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>
Jonathan Greenberg: <jonsgreen>
== Notes to Developers:
See HACKING file for details on getting set up with a local build.