#label API reference

Describe and print labels for industrial label printers. One module, one way to describe a label, with the printer language as a selectable backend (a Device dialect), not a module per printer. A three-stage pipeline keeps the stages independent: build a device-independent Label in millimetres, render it to a chosen dialect string, then emit that string anywhere (a file, a database, or the thin send convenience over net to a printer's :9100 raw port). Dialects: "zpl" (Zebra Programming Language, raster - needs the target dpi) and "cab" (cab JScript, millimetre-native); each dialect encoder lives in its own file (label_zpl.inc.j / label_cab.inc.j) spliced in via include, so a new dialect is a new file plus a branch in render. Build and render are pure and run on both binaries; only send needs the default jennifer binary.

Import with import "label.j" as label;. See the label guide for prose and examples.

#Functions

#label.barcode(label as Label, x as float, y as float, type as string, opts as BarcodeOptions, data as string)

Place a barcode field, returning a new Label. type is a linear symbology - "code128", "ean13", "ean8", "itf" (Interleaved 2 of 5), "code39", "gs1-128" - or a 2D symbology - "datamatrix", "qr". opts refines it (size, check digit, 2D error level, human-readable line); pass a zero-value BarcodeOptions for the defaults. ITF is numeric-only and even-length (its digits are paired): non-numeric data is rejected and odd-length data is padded with a leading zero (so a 13-digit body becomes ITF-14). GS1-128 data uses the parenthesised Application Identifier form, e.g. (00)3006....

Parameters

• label {Label} - the label to extend
• x {float} - the x origin in millimetres
• y {float} - the y origin in millimetres
• type {string} - the barcode symbology ("code128"/"ean13"/"ean8"/"itf"/"code39"/"gs1-128"/"datamatrix"/"qr")
• opts {BarcodeOptions} - size / check-digit / error-level / text refinements
• data {string} - the barcode data

Returns {Label} - a new Label with the barcode field added

Throws

• {Error} - kind "label" for an unknown type or invalid ITF data

#label.box(label as Label, x as float, y as float, w as float, h as float, thickness as float)

Place a rectangular box (outline), returning a new Label.

Parameters

• label {Label} - the label to extend
• x {float} - the x origin in millimetres
• y {float} - the y origin in millimetres
• w {float} - the box width in millimetres
• h {float} - the box height in millimetres
• thickness {float} - the line thickness in millimetres

Returns {Label} - a new Label with the box added

#label.cab()

Build a cab JScript render target with default print-setup.

Returns {Device} - a cab device

#label.cabWith(setup as CabSetup)

Build a cab JScript render target carrying explicit cab print-setup.

Parameters

• setup {CabSetup} - the cab-only print-setup (job name, heat, orientation, sensor, geometry)

Returns {Device} - a cab device

#label.image(label as Label, x as float, y as float, name as string)

Place an image referenced by name, returning a new Label. The image must be pre-stored on the printer (cab: the images/ folder; ZPL: a stored graphic); name is the stored name in that dialect's convention. Printed at native size. (Embedding a bitmap in the job is a planned follow-on.)

Parameters

• label {Label} - the label to extend
• x {float} - the x origin in millimetres
• y {float} - the y origin in millimetres
• name {string} - the stored image name

Returns {Label} - a new Label with the image field added

#label.new(width as float, height as float)

Start a new, empty label of the given size in millimetres (quantity 1).

Parameters

• width {float} - the label width in millimetres
• height {float} - the label height in millimetres

Returns {Label} - a fresh, empty label

#label.quantity(label as Label, n as int)

Set the number of copies to print, returning a new Label.

Parameters

• label {Label} - the label to update
• n {int} - the number of copies

Returns {Label} - a new Label with the quantity set

#label.render(label as Label, device as Device)

Render a label to a dialect command string.

Parameters

• label {Label} - the label to render
• device {Device} - the target dialect (and dpi for raster dialects)

Returns {string} - the printer command stream

Throws

• {Error} - kind "label" for an unknown dialect

#label.send(host as string, port as int, rendered as string)

Send a rendered command stream to a printer's raw :9100 port over TCP.

Parameters

• host {string} - the printer host or IP
• port {int} - the raw print port (usually 9100)
• rendered {string} - the rendered command stream from render

Throws

• {Error} - on a network failure (a positioned net error)

#label.text(label as Label, x as float, y as float, opts as TextOptions, content as string)

Place a text field, returning a new Label.

Parameters

• label {Label} - the label to extend
• x {float} - the x origin in millimetres
• y {float} - the y origin in millimetres
• opts {TextOptions} - the text options (font height)
• content {string} - the text to print

Returns {Label} - a new Label with the text field added

#label.zpl(dpi as int)

Build a ZPL render target for a printer of the given resolution.

Parameters

• dpi {int} - the printer dots-per-inch

Returns {Device} - a ZPL device

#Structs

#label.BarcodeOptions

Optional refinements for a barcode. A zero-value struct (def o as label.BarcodeOptions;) means no options: default size, no added check digit, default error correction, human-readable line shown.

#label.CabSetup

cab-only print-setup that has no ZPL equivalent, carried on the render target so it can be reproduced without leaking into the device-independent Label. A zero-value struct emits none of it (a bare J, no H/O line, and an S line derived from the label size). Every field is optional; the cab encoder emits a command only when the corresponding field is set. ZPL ignores it all.

#label.Device

The render target: which dialect to emit and, for raster dialects, the printer resolution. Build one with label.zpl(dpi), label.cab(), or label.cabWith(setup) rather than a raw literal.

#label.Field

One field on a label. kind selects which attributes matter: "text" uses h as the font height and data as the content; "barcode" uses barcodeType, h (bar height, or module size for a 2D code), and data; "box" uses w, h, thickness; "image" uses data as the stored name.

#label.Label

A device-independent label: its physical size in millimetres, the number of copies to print, and its fields. Value-semantic - every builder returns a new Label.

#label.TextOptions

Options for a text field. A zero-value struct (def o as label.TextOptions;) means an unrotated, non-bold field sized by height. Set points for a point-sized font (it wins over height).