zpl-builder 0.1.0

A builder for ZPL II label strings, for use with Zebra thermal printers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# zpl-builder

A Rust library for building [ZPL II](https://www.zebra.com/us/en/support-downloads/software/zpl-resources.html) label
strings to send to Zebra thermal printers.

[![Crates.io](https://img.shields.io/crates/v/zpl-builder)](https://crates.io/crates/zpl-builder)
[![docs.rs](https://img.shields.io/docsrs/zpl-builder)](https://docs.rs/zpl-builder)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Overview

ZPL (Zebra Programming Language) is a label description language interpreted by Zebra printers. This library lets you
build valid ZPL strings in Rust without constructing raw strings by hand.

All field values are validated against the ZPL II specification at construction time. An invalid value returns a
`ZplError` rather than silently producing a malformed command string.

## Installation

```toml
[dependencies]
zpl-builder = "0.1"
```

## Quick start

```rust
use zpl_rs::{LabelBuilder, BarcodeType, Color, Orientation};

let zpl = LabelBuilder::new()
.set_home_position(10, 10).unwrap()
.add_text("Hello, printer!", 50, 50, 'A', 30, Orientation::Normal).unwrap()
.add_graphical_box(10, 10, 500, 300, 3, Color::Black, 0).unwrap()
.add_barcode(BarcodeType::Code128, "ABC-123", 50, 120, 2, 2.5, 80, Orientation::Normal).unwrap()
.build();

// Send `zpl` to your printer over TCP, USB, or serial.
```

## Error handling

Every builder method returns `Result<LabelBuilder, ZplError>`, so you can chain with `?`:

```rust
use zpl_rs::{LabelBuilder, Color, Orientation, ZplError};

fn build_label(tracking: &str) -> Result<String, ZplError> {
    Ok(LabelBuilder::new()
        .set_home_position(0, 0)?
        .add_text("SHIP TO:", 10, 10, 'B', 20, Orientation::Normal)?
        .add_graphical_box(5, 5, 400, 200, 2, Color::Black, 0)?
        .build())
}
```

## Supported elements

| Method                        | ZPL command   | Description                             |
|-------------------------------|---------------|-----------------------------------------|
| `add_text`                    | `^A` / `^FD`  | Text field                              |
| `add_barcode`                 | `^BY` / `^B*` | Barcode (27 types supported)            |
| `add_graphical_box`           | `^GB`         | Rectangle with optional rounded corners |
| `add_graphical_circle`        | `^GC`         | Circle                                  |
| `add_graphical_ellipse`       | `^GE`         | Ellipse                                 |
| `add_graphical_diagonal_line` | `^GD`         | Diagonal line                           |

## Supported barcode types

`Aztec`, `Code11`, `Interleaved`, `Code39`, `Code49`, `PlanetCode`, `Pdf417`, `EAN8`, `UpcE`, `Code93`, `CodaBlock`,
`Code128`, `UPSMaxiCode`, `EAN13`, `MicroPDF417`, `Industrial`, `Standard`, `ANSICodeBar`, `LogMars`, `MSI`, `Plessey`,
`QrCode`, `Rss`, `UpcEanExtension`, `Tlc39`, `UpcA`, `DataMatrix`.

## Validation ranges

| Parameter                  | Range                         |
|----------------------------|-------------------------------|
| x / y position             | 0 – 32 000 dots               |
| Font size                  | 10 – 32 000 dots              |
| Barcode bar width          | 1 – 10 dots                   |
| Barcode width ratio        | 2.0 – 3.0 (step 0.1)          |
| Barcode height             | 1 – 32 000 dots               |
| Line thickness             | 1 – 32 000 dots               |
| Circle / ellipse dimension | 3 – 4 095 dots                |
| Box corner rounding        | 0 – 8                         |
| Box width / height         | ≥ thickness, ≤ 32 000 dots    |
| Font name                  | A–Z or 1–9 (single character) |

## License

MIT — see [LICENSE](LICENSE).