zpl-forge 0.3.2

A fast, memory-safe ZPL (Zebra Programming Language) parser and renderer.
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! # ZPL-Forge
//!
//! `zpl-forge` is a high-performance engine for parsing, processing, and rendering Zebra Programming Language (ZPL) labels.
//! It transforms raw ZPL strings into an optimized Intermediate Representation (IR), which can then be exported to various
//! formats like PNG images or PDF documents.
//!
//! ## Core Features
//! - **Robust Parsing**: Uses `nom` for fast and safe ZPL command parsing.
//! - **State Machine**: Maintains label state (fonts, positions, barcodes) across commands.
//! - **Multiple Backends**: Native support for PNG (via `imageproc`) and PDF (via `lopdf`).
//! - **Extensible**: Includes custom commands for color support and Base64 image loading.
//! - **Security**: Built-in OOM protection and safe arithmetic for coordinate calculations.
//!
//! ## Quick Start
//!
//! Rendering a simple label to a PNG image:
//!
//! ```rust
//! use zpl_forge::{ZplEngine, Unit, Resolution};
//! use zpl_forge::forge::png::PngBackend;
//! use std::collections::HashMap;
//!
//! # fn main() -> zpl_forge::ZplResult<()> {
//! let zpl_input = "^XA^FO50,50^A0N,50,50^FDZPL Forge^FS^XZ";
//!
//! // Create the engine by parsing ZPL data
//! let engine = ZplEngine::new(
//!     zpl_input,
//!     Unit::Inches(4.0),
//!     Unit::Inches(2.0),
//!     Resolution::Dpi203
//! )?;
//!
//! // Render using the PNG backend
//! let backend = PngBackend::new();
//! let png_bytes = engine.render(backend, &HashMap::new())?;
//!
//! // png_bytes now contains the raw PNG data
//! # Ok(())
//! # }
//! ```
//!
//! ## Security and Limits
//!
//! To ensure stability and prevent Denial of Service (DoS) attacks via malformed input, `zpl-forge` implements the following restrictions:
//! - **Canvas Size**: Rendering is limited to a maximum of **8192 x 8192 pixels**.
//! - **Image Data**: Decoded bitmap data (`^GF`) cannot exceed **10 MB** per command.
//! - **Safe Calculations**: Saturating arithmetic is used for all coordinate and dimension calculations to prevent integer overflows.
//! - **Unit Normalization**: Input values for physical dimensions are validated to prevent negative sizes.

#![forbid(unsafe_code)]

mod ast;
mod engine;
pub mod error;
pub mod forge;
pub mod tools;

pub use engine::*;
pub use error::{ZplError, ZplResult};

#[cfg(feature = "tracing")]
pub(crate) const TARGET: &str = "zpl-forge";

/// Renders a ZPL string directly to native vector PDF bytes using default label dimensions (4x6 inches at 203 DPI).
///
/// # Arguments
/// * `zpl` - The raw ZPL string to render.
///
/// # Returns
/// A `ZplResult<Vec<u8>>` containing the raw PDF document bytes.
///
/// # Errors
/// Returns [`ZplError::ParseError`] if the ZPL string contains malformed syntax, or [`ZplError::EmptyInput`] if input is empty.
#[cfg(feature = "pdf")]
pub fn render_pdf(zpl: &str) -> ZplResult<Vec<u8>> {
    let engine = ZplEngine::new(
        zpl,
        Unit::Inches(4.0),
        Unit::Inches(6.0),
        Resolution::Dpi203,
    )?;
    engine.to_pdf()
}

/// Renders a ZPL string directly to PNG image bytes using default label dimensions (4x6 inches at 203 DPI).
///
/// # Arguments
/// * `zpl` - The raw ZPL string to render.
///
/// # Returns
/// A `ZplResult<Vec<u8>>` containing the raw PNG image bytes.
///
/// # Errors
/// Returns [`ZplError::ParseError`] if the ZPL string contains malformed syntax, or [`ZplError::EmptyInput`] if input is empty.
#[cfg(feature = "png")]
pub fn render_png(zpl: &str) -> ZplResult<Vec<u8>> {
    let engine = ZplEngine::new(
        zpl,
        Unit::Inches(4.0),
        Unit::Inches(6.0),
        Resolution::Dpi203,
    )?;
    engine.to_png()
}