View Source Mudbrick (mudbrick v0.2.1)

Top-level API for creating documents.

Example

Compression, OTF font with special characters and image placement:

iex> import Mudbrick.TestHelper                 # import some example fonts and images
...> import Mudbrick
...> alias Mudbrick.Page
...> new(
...>   compress: true,                          # flate compression for fonts, text etc.
...>   fonts: %{bodoni: [file: bodoni()]},      # register an OTF font
...>   images: %{flower: [file: flower()]}      # register a JPEG
...> )
...> |> page(size: Page.size(:letter))
...> |> image(                                  # place preregistered JPEG
...>   :flower,
...>   scale: {100, 100},
...>   position: {50, 600}                      # in points (1/72 inch), starts at bottom left
...> )
...> |> text_position(200, 700)                 # set text start position from bottom left
...> |> font(:bodoni, size: 14)                 # choose preregistered font
...> |> colour({1, 0, 0})                       # make text red
...> |> text("CO₂", align: :right)              # write text in current font, with right side
...>                                            # anchored to 200 points from left of page
...> |> render()                                # produces iodata, can go straight to File.write/2
...> |> IO.iodata_to_binary()                   # or turned into a (non-String) binary

Summary

Functions

Set the current fill colour (currently only for text).

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

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

Set the current font using a name previously registered in new/1.

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

Start a new document.

Start a new page upon which future operators should apply.

Produce iodata from the current document.

Write text at the current position. Repeated calls to this do not produce newlines.

Set the position for future calls to text/3, relative to the current page's bottom left corner. Starts a new PDF text object (BT/ET).

Functions

Set the current fill colour (currently only for text).

Takes an {r, g, b} tuple.

Examples

Green text:

iex> Mudbrick.new(fonts: %{my_bodoni: [file: Mudbrick.TestHelper.bodoni()]})
...> |> Mudbrick.page()
...> |> Mudbrick.colour({0, 1, 0})

Invalid:

iex> Mudbrick.new(fonts: %{my_bodoni: [file: Mudbrick.TestHelper.bodoni()]})
...> |> Mudbrick.page()
...> |> Mudbrick.colour({2, 0, 0})
** (Mudbrick.ContentStream.InvalidColour) tuple must be made of floats or integers between 0 and 1

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 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"]
Link to this function

font(context, user_identifier, opts)

View Source

Set the current font using a name previously registered in new/1.

Example

iex> Mudbrick.new(fonts: %{my_bodoni: [file: Mudbrick.TestHelper.bodoni()]})
...> |> Mudbrick.page()
...> |> Mudbrick.font(:my_bodoni, size: 14)

Forgetting to set the font is an error:

iex> Mudbrick.new(fonts: %{my_bodoni: [file: Mudbrick.TestHelper.bodoni()]})
...> |> Mudbrick.page()
...> |> Mudbrick.text("oops!")
** (Mudbrick.Font.NotSet) No font chosen

Forgetting to register the font is an error:

iex> Mudbrick.new()
...> |> Mudbrick.page()
...> |> Mudbrick.font(:helvetica, size: 21)
** (Mudbrick.Font.Unregistered) Unregistered font: helvetica
Link to this function

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

View Source

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.
  • :skew - {x, y}, passed through to PDF cm operator.

All options default to {0, 0}.

Examples

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

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

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

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

Register an OTF font. Pass the file's raw data to the :file option.

iex> Mudbrick.new(fonts: %{bodoni: [file: Mudbrick.TestHelper.bodoni()]})

Or a built-in font. Note that these don't support right-alignment or special characters.

iex> Mudbrick.new(fonts: %{helvetica: [name: :Helvetica, type: :TrueType, encoding: :PDFDocEncoding]})

Register an image.

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

Set document metadata.

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

page(context, opts \\ [])

View Source

Start a new page upon which future operators should apply.

Options

Produce iodata from the current document.

Link to this function

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

View Source

Write text at the current position. Repeated calls to this do not produce newlines.

Options

  • :align - either :left or :right. When :right, text is right-aligned to the current position set with text_position/3. Default: :left.
Link to this function

text_position(context, x, y)

View Source

Set the position for future calls to text/3, relative to the current page's bottom left corner. Starts a new PDF text object (BT/ET).