View Source Mudbrick (mudbrick v0.8.1)

API for creating and exporting PDF documents.

General example

Compression, OTF font with special characters, JPEG and line drawing:

iex> import Mudbrick.TestHelper                     # import some example fonts and images
...> import Mudbrick
...> new(
...>   compress: true,                              # flate compression for fonts, text etc.
...>   fonts: %{bodoni: bodoni_regular()},          # register an OTF font
...>   images: %{flower: flower()}                  # register a JPEG
...> )
...> |> page(size: {100, 100})
...> |> image(                                      # place preregistered JPEG
...>   :flower,
...>   scale: {100, 100},                           # full page size
...>   position: {0, 0}                             # in points (1/72 inch), starts at bottom left
...> )
...> |> path(fn path ->                             # draw a line
...>   import Mudbrick.Path
...>   path
...>   |> move(to: {55, 40})                        # starting near the middle of the page
...>   |> line(
...>     to: {95, 5},                               # ending near the bottom right
...>     width: 6.0,                                # make it fat
...>     colour: {1, 0, 0}                          # make it red
...>   )
...> end)
...> |> text(
...>   {"CO₂", colour: {0, 0, 1}},                  # write blue text
...>   font: :bodoni,                               # in the bodoni font
...>   font_size: 14,                               # size 14 points
...>   position: {35, 45}                           # 60 points from left, 45 from bottom of page
...> )
...> |> render()                                    # produce iodata, ready for File.write/2
...> |> then(&File.write("examples/compression_font_special_chars.pdf", &1))

Produces this.

Auto-kerning

iex> import Mudbrick.TestHelper
...> import Mudbrick
...> new(fonts: %{bodoni: bodoni_bold()})
...> |> page(size: {400, 100})
...> |> text(
...>   [{"Warning\n", underline: [width: 0.5]}],
...>   font: :bodoni,
...>   font_size: 70,
...>   position: {7, 30}
...> )
...> |> render()
...> |> then(&File.write("examples/auto_kerning.pdf", &1))

Produces this. Notice how the 'a' is underneath the 'W' in 'Warning'.

It's on by default, but we can turn it off:

iex> import Mudbrick.TestHelper
...> import Mudbrick
...> new(fonts: %{bodoni: bodoni_bold()})
...> |> page(size: {400, 100})
...> |> text(
...>   [{"Warning\n", underline: [width: 0.5]}],
...>   font: :bodoni,
...>   font_size: 70,
...>   position: {7, 30},
...>   auto_kern: false
...> )
...> |> render()
...> |> then(&File.write("examples/auto_kerning_disabled.pdf", &1))

Produces this.

Summary

Types

colour()

context()

coords()

Functions

compress(data)

Compress data with the same method that PDF generation does. Useful for testing.

decompress(data)

Decompress data with the same method that PDF generation does. Useful for testing.

image(context, user_identifier, opts \\ [])

Insert image previously registered in new/1 at the given coordinates.

new(opts \\ [])

Start a new document.

page(context, opts \\ [])

Start a new page upon which future operators should apply.

path(context, f)

Vector drawing. f is a function that takes a Mudbrick.Path and returns a Mudbrick.Path. See the functions in that module.

render(doc)

Produce iodata from the current document.

text(context, write_or_writes, opts \\ [])

Write text at the given coordinates.

Types

colour()

@type colour() :: {number(), number(), number()}

context()

@type context() :: {Mudbrick.Document.t(), Mudbrick.Indirect.Object.t()}

coords()

@type coords() :: {number(), number()}

Functions

compress(data)

@spec compress(iodata()) :: iodata()

Compress data with the same method that PDF generation does. Useful for testing.

Example

iex> Mudbrick.compress(["hi", "there", ["you"]])
[<<120, 156, 203, 200, 44, 201, 72, 45, 74, 173, 204, 47, 5, 0, 23, 45, 4, 71>>]

decompress(data)

@spec decompress(iodata()) :: iodata()

Decompress data with the same method that PDF generation does. Useful for testing.

Example

iex> Mudbrick.decompress([<<120, 156, 203, 200, 44, 201, 72, 45, 74, 173, 204, 47, 5, 0, 23, 45, 4, 71>>])
["hithereyou"]

image(context, user_identifier, opts \\ [])

@spec image(context(), atom(), Mudbrick.Image.image_options()) :: context()

Insert image previously registered in new/1 at the given coordinates.

Options

:position - {x, y} in points, relative to bottom-left corner.
:scale - {w, h} in points. To preserve aspect ratio, set either, but not both, to :auto.
:skew - {x, y}, passed through to PDF cm operator.

All options default to {0, 0}.

Examples

iex> Mudbrick.new(images: %{lovely_flower: Mudbrick.TestHelper.flower()})
...> |> Mudbrick.page()
...> |> Mudbrick.image(:lovely_flower, position: {100, 100}, scale: {100, 100})

Forgetting to register the image:

iex> Mudbrick.new()
...> |> Mudbrick.page()
...> |> Mudbrick.image(:my_face, position: {100, 100}, scale: {100, 100})
** (Mudbrick.Image.Unregistered) Unregistered image: my_face

Auto height:

iex> Mudbrick.new(images: %{lovely_flower: Mudbrick.TestHelper.flower()})
...> |> Mudbrick.page(size: {50, 50})
...> |> Mudbrick.image(:lovely_flower, position: {0, 0}, scale: {50, :auto})
...> |> Mudbrick.render()
...> |> then(&File.write("examples/image_auto_aspect_scale.pdf", &1))

Attempting to set both width and height to :auto:

iex> Mudbrick.new(images: %{lovely_flower: Mudbrick.TestHelper.flower()})
...> |> Mudbrick.page()
...> |> Mudbrick.image(:lovely_flower, position: {100, 100}, scale: {:auto, :auto})
** (Mudbrick.Image.AutoScalingError) Auto scaling works with width or height, but not both.

Tip: to make the image fit the page, pass e.g. Page.size(:a4) as the scale and {0, 0} as the position.

new(opts \\ [])

@spec new(opts :: Mudbrick.Document.options()) :: Mudbrick.Document.t()

Start a new document.

Options

:compress - when set to true, apply deflate compression to streams (if compression saves space). Default: false
:fonts - register OTF or built-in fonts for later use.
:images - register images for later use.

The following options define metadata for the document:

:producer - software used to create the document, default: "Mudbrick"
:creator_tool - tool used to create the document, default: "Mudbrick"
:create_date - DateTime representing the document's creation time
:modify_date - DateTime representing the document's last update time
:title - title (can change e.g. browser window title), default: nil
:creators - list of names of the creators of the document, default: []

Examples

iex> Mudbrick.new(fonts: %{bodoni: Mudbrick.TestHelper.bodoni_regular()})

iex> Mudbrick.new(images: %{flower: Mudbrick.TestHelper.flower()})

Set document metadata.

iex> Mudbrick.new(title: "The best PDF", producer: "My cool software")

page(context, opts \\ [])

@spec page(Mudbrick.Document.t() | context(), Keyword.t()) :: context()

Start a new page upon which future operators should apply.

Options

:size - a tuple of {width, height}. Some standard sizes available in Mudbrick.Page.size/1.

path(context, f)

@spec path(context(), (Mudbrick.Path.t() -> Mudbrick.Path.t())) :: context()

Vector drawing. f is a function that takes a Mudbrick.Path and returns a Mudbrick.Path. See the functions in that module.

Example

A thick diagonal red line and a black rectangle with a thinner (default) line on top.

iex> import Mudbrick
...> new()
...> |> page(size: {100, 100})
...> |> path(fn path ->
...>   import Mudbrick.Path
...>   path
...>   |> move(to: {0, 0})
...>   |> line(to: {50, 50}, colour: {1, 0, 0}, width: 9)
...>   |> rectangle(lower_left: {0, 0}, dimensions: {50, 60})
...> end)
...> |> render()
...> |> then(&File.write("examples/drawing.pdf", &1))

Produces this drawing.

render(doc)

@spec render(Mudbrick.Document.t() | context()) :: iodata()

Produce iodata from the current document.

text(context, write_or_writes, opts \\ [])

@spec text(context(), Mudbrick.TextBlock.write(), Mudbrick.TextBlock.options()) ::
  context()

Write text at the given coordinates.

Top-level options

:colour - {r, g, b} tuple. Each element is a number between 0 and 1. Default: {0, 0, 0}.
:font - Name of a font previously registered with new/1. Required unless you've only registered one font.
:position - Coordinates from bottom-left of page in points. Default: {0, 0}.
:font_size - Size in points. Default: 12.
:leading - Leading in points. Default is 120% of :font_size.
:align - :left, :right or :centre. Default: :left. Note that the rightmost point of right-aligned text is the horizontal offset provided to :position. The same position defines the centre point of centre-aligned text.

Individual write options

When passing a {text, opts} tuple or list of tuples to this function, opts are:

:colour - {r, g, b} tuple. Each element is a number between 0 and 1. Overrides the top-level option.
:font - Name of a font previously registered with new/1. Overrides the top-level option.
:font_size - Size in points. Overrides the top-level option.
:leading - The number of points to move down the page on the following linebreak. Overrides the top-level option.
:underline - A list of options: :width in points, :colour as an {r, g, b} struct.

Examples

Write "CO₂" in the bottom-left corner of a default-sized page.

iex> import Mudbrick.TestHelper
...> import Mudbrick
...> new(fonts: %{bodoni: bodoni_regular()})
...> |> page()
...> |> text("CO₂")

Write "I am red" at 200, 200, where "red" is in red.

iex> import Mudbrick.TestHelper
...> import Mudbrick
...> new(fonts: %{bodoni: bodoni_regular()})
...> |> page()
...> |> text(["I am ", {"red", colour: {1, 0, 0}}], position: {200, 200})

Write "I am bold" at 200, 200, where "bold" is in bold.

iex> import Mudbrick.TestHelper
...> import Mudbrick
...> new(fonts: %{regular: bodoni_regular(), bold: bodoni_bold()})
...> |> page()
...> |> text(["I am ", {"bold", font: :bold}], font: :regular, position: {200, 200})

Underlined text.

iex> import Mudbrick
...> new(fonts: %{bodoni: Mudbrick.TestHelper.bodoni_regular()})
...> |> page(size: {100, 50})
...> |> text([
...>      {"the\n", leading: 20},
...>      "quick\n",
...>      "brown fox ",
...>      {"jumps", underline: [width: 1]},
...>      " over"
...>    ], position: {8, 40}, font_size: 8)
...> |> render()
...> |> then(&File.write("examples/underlined_text.pdf", &1))

Underlined, right-aligned text.

iex> import Mudbrick
...> new(fonts: %{bodoni: Mudbrick.TestHelper.bodoni_regular()})
...> |> page(size: {100, 50})
...> |> text([
...>      {"the\n", leading: 20},
...>      "quick\n",
...>      "brown fox ",
...>      {"jumps", underline: [width: 1]},
...>      " over"
...>    ], position: {90, 40}, font_size: 8, align: :right)
...> |> render()
...> |> then(&File.write("examples/underlined_text_right_align.pdf", &1))

Underlined, centre-aligned text.

iex> import Mudbrick
...> new(fonts: %{bodoni: Mudbrick.TestHelper.bodoni_regular()})
...> |> page(size: {100, 50})
...> |> text([
...>      {"the\n", leading: 20},
...>      "quick\n",
...>      "brown fox ",
...>      {"jumps", underline: [width: 1]},
...>      " over"
...>    ], position: {50, 40}, font_size: 8, align: :centre)
...> |> render()
...> |> then(&File.write("examples/underlined_text_centre_align.pdf", &1))