Versatile PDF creation and manipulation for Ruby
HexaPDF is a pure Ruby library with an accompanying application for working with PDF files. It was
designed with ease of use and performance in mind. It uses lazy loading and lazy computing when
possible and tries to produce small PDF files by default.
In short, it allows
HexaPDF is available under two license, the AGPL and a commercial license, see the License
section for details.
hexapdf binary, ‘geom2d’ for document layout)hexapdf binary for most common PDF manipulation tasksThe HexaPDF distribution provides the library as well as the hexapdf application. The application
can be used to perform common tasks like merging PDF files, decrypting or encrypting PDF files and
so on.
When HexaPDF is used as a library, it can be used to do all the task that the command line
application does and much more. Here is a “Hello World” example that shows how to create a simple
PDF file:
require 'hexapdf'
doc = HexaPDF::Document.new
canvas = doc.pages.add.canvas
canvas.font('Helvetica', size: 100)
canvas.text("Hello World!", at: [20, 400])
doc.write("hello-world.pdf")
For detailed information have a look at the HexaPDF website where you will the API
documentation, example code and more.
It is recommend to use the HTML API documentation provided by the HexaPDF website as it is enhanced
with example graphics and PDF files and tightly integrated into the rest of the website.
Since HexaPDF is written in Ruby, a working Ruby installation is needed - see the
official installation documentation for details. Note that you need Ruby version 2.6 or
higher as prior versions are not supported!
HexaPDF works on all Ruby implementations that are CRuby compatible, e.g. TruffleRuby, and on any
platform supported by Ruby (Linux, macOS, Windows, …).
Apart from Ruby itself the HexaPDF library has only one external dependency geom2d which is
written and provided by the HexaPDF authors. The hexapdf application has an additional dependency
on cmdparse, a command line parsing library.
HexaPDF itself is distributed via Rubygems and therefore easily installable via gem install hexapdf.
The main difference between HexaPDF and Prawn is that HexaPDF is a full PDF library whereas
Prawn is a library for generating content.
To be more specific, it is easily possible to read an existing PDF with HexaPDF and modify parts of
it before writing it out again. The modifications can be to the PDF object structure like removing
superfluous annotations or the the content itself.
Prawn has no such functionality. There is basic support for using a PDF as a template using the
pdf-reader and prawn-template gems but support is very limited. However, Prawn has a very
featureful API when it comes to creating content, for individual pages as well as across pages.
If you want to migrate from Prawn to HexaPDF, there is the migration guide with detailed
information and examples, comparing the Prawn API to HexaPDF’s equivalents.
Why use HexaPDF?
It has many more features beside content creation that might come in handy (e.g. PDF
form creation, encryption, digital signatures, …).
The architecture of HexaPDF is based on the object model of the PDF standard. This makes extending
HexaPDF very easy and allows for reading PDF files for templating purposes.
HexaPDF provides a high level API for composing a document of individual elements that are
automatically layouted. Such elements can be headers, paragraphs, code blocks, … or links,
emphasized text and so on. These elements can be customized and additional element types easily
added.
In addition to being usable as a library, HexaPDF also comes with a command line tool for
manipulating PDFs. This tool is intended to be a replacement for tools like pdftk and the
various Poppler-based tools like pdfinfo, pdfimages, …
Clone the repository and then run rake dev:setup. This will install the needed Rubygem
dependencies as well as make sure that all applications needed for the tests are available.
AGPL - see the LICENSE file for licensing details. Commercial licenses are available at
https://gettalong.at/hexapdf/.
A commercial license is needed as soon as HexaPDF is distributed with your software or remotely
accessed via a network and you don’t provide the source code of your application under the AGPL. For
example, if you serve PDFs on the fly in a web application.
Contact [email protected] for more information!
Some included files have a different license:
For the license of the included AFM files in the data/hexapdf/afm directory, see the file
data/hexapdf/afm/MustRead.html.
The files test/data/encoding/{glyphlist.txt,zapfdingbats.txt} are licensed under the Apache
License V2.0.
The file test/data/fonts/Ubuntu-Title.ttf is licensed under the SIL Open Font License.
The AES test vector files in test/data/aes-test-vectors have been created using the test vector
file available from http://csrc.nist.gov/groups/STM/cavp/block-ciphers.html#test-vectors.
The license of the file data/hexapdf/sRGB2014.icc is available in the
data/hexapdf/sRGB2014.icc.LICENSE file.
See https://hexapdf.gettalong.org/contributing.html for more information.
Thomas Leitner, https://gettalong.org