escpos/document

A high-level API for building ESC/POS printer documents.

Documents are built by composing commands and modifiers, then compiled into a binary command buffer that can be sent to a printer.

Example

import escpos/document.{bold, cut, justify, line, styled, text, Center}

document.render([
  styled([justify(Center), bold()], [
    line([text("Receipt")]),
  ]),
  line([text("Item 1 ... $5.00")]),
  cut(),
])

Types

Command

opaque </>

A command representing a print operation or content.

pub opaque type Command

Font

</>

Printer font. Re-exported from escpos/protocol.

pub type Font =
  protocol.Font

Justify

</>

Text justification. Re-exported from escpos/protocol.

pub type Justify =
  protocol.Justify

Modifier

opaque </>

A style modifier that affects how text is rendered.

pub opaque type Modifier

Values

bold

</>

pub fn bold() -> Modifier

Bold text modifier.

cut

</>

pub fn cut() -> Command

Performs a full paper cut.

double_strike

</>

pub fn double_strike() -> Modifier

Double-strike (heavier print) modifier.

flip

</>

pub fn flip() -> Modifier

Flips text 180 degrees.

font

</>

pub fn font(f: protocol.Font) -> Modifier

Sets the font.

image

</>

pub fn image(image: image.PrintableImage) -> Command

Prints an image.

Example

let assert Ok(pgm) = simplifile.read_bits(from: "./lucy.pgm")
let assert Ok(img) = image.from_pgm(raw_pgm)
let img = image.dither_bayer4x4(img, 0)

document.render([
  image(img),
  cut(),
])

image_raster

</>

pub fn image_raster(image: image.PrintableImage) -> Command

Prints a monochrome image prepared by the image module. This is using an older method to print images, useful for some printers that do not understand graphic buffer commands.

Example

let assert Ok(pgm) = simplifile.read_bits(from: "./lucy.pgm")
let assert Ok(img) = image.from_pgm(raw_pgm)
let img = image.dither_bayer4x4(img, 0)

document.render([
  raster_image(img),
  cut(),
])

justify

</>

pub fn justify(j: protocol.Justify) -> Modifier

Sets text justification.

line

</>

pub fn line(commands: List(Command)) -> Command

Groups commands into a single line, with a newline at the end. Useful for combining styled and unstyled text on one line.

Example

line([
  styled([bold()], [text("Total:")]),
  text(" $12.99"),
])

line_feed

</>

pub fn line_feed(lines: Int) -> Command

Advances the paper by the specified number of lines.

new_line

</>

pub fn new_line() -> Command

Advances the paper by one line.

partial_cut

</>

pub fn partial_cut() -> Command

Performs a partial paper cut, leaving a small portion connected.

raw

</>

pub fn raw(bytes: BitArray) -> Command

Sends raw ESC/POS bytes to the printer.

render

</>

pub fn render(document: List(Command)) -> printer.CommandBuffer

Compiles a list of commands into a binary command buffer ready for printing.

reverse

</>

pub fn reverse() -> Modifier

Reverse (white on black) text modifier.

styled

</>

pub fn styled(
  modifiers: List(Modifier),
  commands: List(Command),
) -> Command

Applies style modifiers to a group of commands. Styles are automatically reverted after the nested commands.

text

</>

pub fn text(t: String) -> Command

Prints text without a trailing newline.

text_height

</>

pub fn text_height(size: Int) -> Modifier

Sets text height scaling (0-7).

text_size

</>

pub fn text_size(size: Int) -> Modifier

Sets both text width and height scaling (0-7).

text_width

</>

pub fn text_width(size: Int) -> Modifier

Sets text width scaling (0-7).

underline

</>

pub fn underline() -> Modifier

Underlined text modifier.

upside_down

</>

pub fn upside_down() -> Modifier

Prints text upside down (requires newline before and after).