PrawnEx

CIHex.pmHex.pmHex.pmElixir

Version 0.3.0 · Elixir ~> 1.16

Prawn-style declarative PDF generation for Elixir. Pure Elixir, no Chrome or HTML: build a document spec and emit PDF 1.4.

Features

Getting started

Add the dependency and build your first PDF:

# mix.exs

def deps do

  [{:prawn_ex, "~> 0.3.0"}]

end

PrawnEx.build("output.pdf", fn doc ->

  doc

  |> PrawnEx.add_page()

  |> PrawnEx.set_font("Helvetica", 12)

  |> PrawnEx.text_at({72, 700}, "Hello, PDF!")

end)

See Demo for a full tour, or try the invoice or report with chart examples.

Usage

PrawnEx.build("output.pdf", fn doc ->

  doc

  |> PrawnEx.set_font("Helvetica", 12)

  |> PrawnEx.text_at({100, 700}, "Hello, PDF!")

  |> PrawnEx.rectangle(100, 600, 200, 50)

  |> PrawnEx.stroke()

end)

Or build a document and get binary:

binary =

  PrawnEx.Document.new()

  |> PrawnEx.add_page()

  |> PrawnEx.set_font("Helvetica", 12)

  |> PrawnEx.text_at({72, 72}, "Hello")

  |> PrawnEx.to_binary()

Coordinates use PDF points (72 pt = 1 inch); origin is bottom-left.

Tables

Draw tables with an optional header row (Phase 2):

rows = [["Product", "Qty", "Price"], ["Widget", "2", "$10"], ["Gadget", "1", "$25"]]

doc

|> PrawnEx.table(rows, at: {50, 650}, column_widths: [200, 80, 80], header: true)

Options: :at, :column_widths (list or :auto), :row_height, :cell_padding, :header, :border, :align (:left / :center / :right or list per column), :font_size, :header_font_size.

Headers and footers

Use build(path, opts, fun) with :header and/or :footer callbacks (receiving doc and page number). Ideal for "Page N" and repeating titles:

PrawnEx.build("out.pdf", [

  footer: fn doc, page_num ->

    doc

    |> PrawnEx.set_font("Helvetica", 9)

    |> PrawnEx.text_at({50, 30}, "Page \#{page_num}")

  end

], fn doc ->

  # your content; footer is injected on every page

  doc |> PrawnEx.add_page() |> ...

end)

Charts

Bar and line charts (Phase 3), built from drawing primitives:

# Bar chart: list of {label, value}

PrawnEx.bar_chart(doc, [{"Jan", 40}, {"Feb", 55}, {"Mar", 70}],

  at: {50, 500}, width: 400, height: 200, bar_color: 0.4)



# Line chart: list of y-values (x = index) or [{x, y}, ...]

PrawnEx.line_chart(doc, [10, 25, 15, 40, 35], at: {50, 400}, width: 400, height: 150)

Options: :at, :width, :height, :bar_color / :stroke_color, :axis, :labels, :padding.

Flow layout (PrawnEx.Layout)

For documents that are mostly stacked blocks (title, paragraphs, table), a positional API forces you to repeat page_h - N math. PrawnEx.Layout tracks a baseline cursor inside a margin box and emits the same PrawnEx ops (text_at, text_box, table).

Markup (Phase D) — PrawnEx.Layout.Markup.parse/1 and apply(layout, string, vstack_opts): lines starting with # / ## for headings, - bullets (rendered as ASCII * lines for built-in font encodings), blank lines separate paragraphs. Not a full Markdown engine.

See mix run scripts/invoice.exs for layout without markup.

Images

Embed JPEG or PNG via PrawnEx.image/3 (file path or raw bytes). Use :at (required), and optionally :width / :height in pt; default size is the image’s pixel dimensions treated as pt.

FormatNotes
JPEGStream is embedded as-is with /DCTDecode.
PNG8-bit truecolor RGB or RGBA only, no interlacing. Decoded in pure Elixir; pixels are written as /DeviceRGB with /FlateDecode. RGBA is composited on white (simple transparency handling). Indexed-palette, grayscale-only, or interlaced PNGs are not supported and return {:error, ...}.

Image / asset path: Set config :prawn_ex, image_dir: "priv/images" (or any directory) in your application config. Relative paths passed to PrawnEx.image/3 are resolved from that directory. Absolute paths and raw JPEG or PNG binaries are used as-is.

# In your config/config.exs:

config :prawn_ex, image_dir: "priv/images"



# In your code — paths are under image_dir:

doc

|> PrawnEx.image("photo.jpg", at: {50, 400})

|> PrawnEx.image("logo.png", at: {400, 700}, width: 80, height: 40)

Other image types produce {:error, :unsupported_image_format}.

Colors

Gray: PrawnEx.set_stroking_gray(doc, 0.8), PrawnEx.set_non_stroking_gray(doc, 0.2) (0 = black, 1 = white).
RGB: PrawnEx.set_non_stroking_rgb(doc, r, g, b), PrawnEx.set_stroking_rgb(doc, r, g, b) (0–1).

Demo

Generate the main tour PDF:

mix run scripts/gen_demo.exs

Output: output/prawn_ex_demo.pdf (5 pages: hero, table, charts, images, Layout). Page 4 shows JPEG / PNG; page 5 uses PrawnEx.Layout (Phase A + hstack teaser). Full Phase A–D walk-through (vstack, hstack, region + new page, Markup):

mix run scripts/layout_phases_demo.exs

→ output/layout_phases_demo.pdf (expect at least two pages so Phase C is visible). Set config :prawn_ex, image_dir: "path/to/images" in config/config.exs if you keep assets elsewhere.

Examples

Installation

If available in Hex, the package can be installed by adding prawn_ex to your list of dependencies in mix.exs:

def deps do

  [

    {:prawn_ex, "~> 0.3.0"}

  ]

end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/prawn_ex.