zpl_builder/

builder.rs

//! Builder to build a ZPL label

use crate::elements::{
    BarcodeElement, GraphicalBoxElement, GraphicalCircleElement, GraphicalDiagonalLineElement,
    GraphicalEllipseElement, TextElement,
};
use crate::types::{
    AxisPosition, BarcodeHeight, BarcodeWidth, BoxDimension, Font, FontSize, GraphicDimension,
    Rounding, Thickness, WidthRatio, ZplError,
};
use std::fmt::Display;

/// Orientation of a text or barcode field.
///
/// Applies to [`LabelBuilder::add_text`] and [`LabelBuilder::add_barcode`].
/// The rotation is applied clockwise relative to the normal reading direction.
#[derive(Debug, PartialEq, Copy, Clone)]
pub enum Orientation {
    /// No rotation — standard left-to-right reading direction.
    Normal,
    /// Rotated 90 degrees clockwise.
    Rotated,
    /// Rotated 180 degrees — upside down.
    Inverted,
    /// Rotated 270 degrees clockwise (read from bottom to top).
    Bottom,
}

impl Display for Orientation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Orientation::Normal => write!(f, "N"),
            Orientation::Rotated => write!(f, "R"),
            Orientation::Inverted => write!(f, "I"),
            Orientation::Bottom => write!(f, "B"),
        }
    }
}

/// Orientation of a diagonal line.
///
/// Applies to [`LabelBuilder::add_graphical_diagonal_line`].
/// The orientation describes the direction the line runs within its bounding box.
///
/// This is a separate type from [`Orientation`] because the ZPL `^GD` command
/// uses `R` and `L` rather than the `N`/`R`/`I`/`B` values used by other elements.
#[derive(Debug, PartialEq, Copy, Clone)]
pub enum DiagonalOrientation {
    /// Line runs from the top-left corner to the bottom-right corner ( `\` ).
    RightLeaning,
    /// Line runs from the bottom-left corner to the top-right corner ( `/` ).
    LeftLeaning,
}

impl Display for DiagonalOrientation {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DiagonalOrientation::RightLeaning => write!(f, "R"),
            DiagonalOrientation::LeftLeaning => write!(f, "L"),
        }
    }
}

/// Barcode symbology.
///
/// Passed to [`LabelBuilder::add_barcode`] to select the encoding format.
/// The wide-to-narrow bar ratio set via `width_ratio` has no effect on
/// fixed-ratio symbologies such as [`BarcodeType::Code128`] or
/// [`BarcodeType::QrCode`].
#[derive(Debug, PartialEq, Copy, Clone)]
#[allow(missing_docs)]
pub enum BarcodeType {
    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,
}

impl Display for BarcodeType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            BarcodeType::Aztec => write!(f, "^BO"),
            BarcodeType::Code11 => write!(f, "^B1"),
            BarcodeType::Interleaved => write!(f, "^B2"),
            BarcodeType::Code39 => write!(f, "^B3"),
            BarcodeType::Code49 => write!(f, "^B4"),
            BarcodeType::PlanetCode => write!(f, "^B5"),
            BarcodeType::Pdf417 => write!(f, "^B7"),
            BarcodeType::EAN8 => write!(f, "^B8"),
            BarcodeType::UpcE => write!(f, "^B9"),
            BarcodeType::Code93 => write!(f, "^BA"),
            BarcodeType::CodaBlock => write!(f, "^BB"),
            BarcodeType::Code128 => write!(f, "^BC"),
            BarcodeType::UPSMaxiCode => write!(f, "^BD"),
            BarcodeType::EAN13 => write!(f, "^BE"),
            BarcodeType::MicroPDF417 => write!(f, "^BF"),
            BarcodeType::Industrial => write!(f, "^BI"),
            BarcodeType::Standard => write!(f, "^BJ"),
            BarcodeType::ANSICodeBar => write!(f, "^BK"),
            BarcodeType::LogMars => write!(f, "^BL"),
            BarcodeType::MSI => write!(f, "^BM"),
            BarcodeType::Plessey => write!(f, "^BP"),
            BarcodeType::QrCode => write!(f, "^BQ"),
            BarcodeType::Rss => write!(f, "^BR"),
            BarcodeType::UpcEanExtension => write!(f, "^BS"),
            BarcodeType::Tlc39 => write!(f, "^BT"),
            BarcodeType::UpcA => write!(f, "^BU"),
            BarcodeType::DataMatrix => write!(f, "^BX"),
        }
    }
}

/// Line and fill color for graphical elements.
///
/// Passed to box, circle, ellipse and diagonal line methods.
/// `White` prints white on a black background, which is useful for
/// inverting areas of a label.
#[derive(Debug, PartialEq, Copy, Clone)]
#[allow(missing_docs)]
pub enum Color {
    /// Solid black.
    Black,
    /// Solid white (transparent on a white label background).
    White,
}

impl Display for Color {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Color::Black => write!(f, "B"),
            Color::White => write!(f, "W"),
        }
    }
}

/// Builder for ZPL II label strings.
///
/// Elements are added in order; the final ZPL string is produced by calling
/// [`build`](LabelBuilder::build). Every method that adds an element validates
/// its arguments and returns a [`ZplError`] if any value is out of range.
///
/// # Example
///
/// ```rust
/// use zpl_builder::{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();
///
/// assert!(zpl.starts_with("^XA"));
/// assert!(zpl.ends_with("^XZ"));
/// ```
#[derive(Debug, PartialEq)]
pub struct LabelBuilder {
    elements: Vec<String>,
    x_origin: AxisPosition,
    y_origin: AxisPosition,
}

fn get_axis_position(x: u16, y: u16) -> Result<(AxisPosition, AxisPosition), ZplError> {
    let x_position = AxisPosition::try_from(x)?;
    let y_position = AxisPosition::try_from(y)?;
    Ok((x_position, y_position))
}

impl LabelBuilder {
    /// Create a new, empty label builder.
    ///
    /// The home position defaults to `(0, 0)`. Call
    /// [`set_home_position`](LabelBuilder::set_home_position) to change it.
    #[must_use]
    pub fn new() -> Self {
        Self {
            elements: Vec::new(),
            x_origin: AxisPosition(0),
            y_origin: AxisPosition(0),
        }
    }

    /// Set the label home position (`^LH`).
    ///
    /// The home position is the axis reference point for the label. Any area
    /// below and to the right of this point is available for printing. It is
    /// recommended to call this before adding any elements.
    ///
    /// # Arguments
    ///
    /// * `x_origin` — x-axis offset in dots. Range: `0–32000`. Default: `0`.
    /// * `y_origin` — y-axis offset in dots. Range: `0–32000`. Default: `0`.
    ///
    /// # Errors
    ///
    /// Returns [`ZplError::InvalidPosition`] if either value exceeds `32000`.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::LabelBuilder;
    /// let zpl = LabelBuilder::new()
    ///     .set_home_position(50, 10).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^LH50,10"));
    /// ```
    pub fn set_home_position(mut self, x_origin: u16, y_origin: u16) -> Result<Self, ZplError> {
        let (x_origin, y_origin) = get_axis_position(x_origin, y_origin)?;
        self.x_origin = x_origin;
        self.y_origin = y_origin;
        Ok(self)
    }

    /// Add a text field (`^A` / `^FD`).
    ///
    /// # Arguments
    ///
    /// * `text` — the string to print.
    /// * `x` — x-axis position in dots. Range: `0–32000`.
    /// * `y` — y-axis position in dots. Range: `0–32000`.
    /// * `font` — ZPL font name: a single ASCII uppercase letter (`A`–`Z`)
    ///   or a digit (`1`–`9`). The digit `0` (zero) is not valid.
    /// * `font_size` — font height in dots. Range: `10–32000`.
    /// * `orientation` — field rotation. See [`Orientation`].
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidFont`] | `font` is not `A`–`Z` or `1`–`9` |
    /// | [`ZplError::InvalidFontSize`] | `font_size` < 10 or > 32000 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{LabelBuilder, Orientation};
    /// let zpl = LabelBuilder::new()
    ///     .add_text("Hello", 10, 10, 'A', 30, Orientation::Normal).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^FDHello^FS"));
    /// ```
    pub fn add_text(
        mut self,
        text: &str,
        x: u16,
        y: u16,
        font: char,
        font_size: u16,
        orientation: Orientation,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let font_size = FontSize::try_from(font_size)?;
        let font = Font::try_from(font)?;
        let zpl_text = TextElement::new(text, x, y, font, font_size, orientation).to_zpl();
        self.elements.push(zpl_text);
        Ok(self)
    }

    /// Add a barcode field (`^BY` / `^B*`).
    ///
    /// # Arguments
    ///
    /// * `_type` — barcode symbology. See [`BarcodeType`].
    /// * `data` — the string to encode.
    /// * `x` — x-axis position in dots. Range: `0–32000`.
    /// * `y` — y-axis position in dots. Range: `0–32000`.
    /// * `width` — width of the narrowest bar in dots. Range: `1–10`.
    /// * `width_ratio` — wide bar to narrow bar ratio. Range: `2.0–3.0`,
    ///   step `0.1`. Has no effect on fixed-ratio symbologies.
    /// * `height` — barcode height in dots. Range: `1–32000`.
    /// * `orientation` — field rotation. See [`Orientation`].
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidBarcodeWidth`] | `width` < 1 or > 10 |
    /// | [`ZplError::InvalidWidthRatio`] | `width_ratio` outside `2.0–3.0` |
    /// | [`ZplError::InvalidBarcodeHeight`] | `height` < 1 or > 32000 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{BarcodeType, LabelBuilder, Orientation};
    /// let zpl = LabelBuilder::new()
    ///     .add_barcode(BarcodeType::Code128, "ABC-123", 10, 10, 2, 2.5, 80, Orientation::Normal).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^FDABC-123^FS"));
    /// ```
    pub fn add_barcode(
        mut self,
        _type: BarcodeType,
        data: &str,
        x: u16,
        y: u16,
        width: u8,
        width_ratio: f32,
        height: u16,
        orientation: Orientation,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let width = BarcodeWidth::try_from(width)?;
        let width_ratio = WidthRatio::try_from(width_ratio)?;
        let height = BarcodeHeight::try_from(height)?;
        let zpl_barcode =
            BarcodeElement::new(_type, data, x, y, width, width_ratio, height, orientation)
                .to_zpl();
        self.elements.push(zpl_barcode);
        Ok(self)
    }

    /// Add a graphical box (`^GB`).
    ///
    /// Draws a rectangle outline. Setting `width` and `height` equal to
    /// `thickness` produces a filled square. Set `rounding` to `0` for sharp
    /// corners.
    ///
    /// # Arguments
    ///
    /// * `x` — x-axis position in dots. Range: `0–32000`.
    /// * `y` — y-axis position in dots. Range: `0–32000`.
    /// * `width` — box width in dots. Must be ≥ `thickness`. Range: `thickness–32000`.
    /// * `height` — box height in dots. Must be ≥ `thickness`. Range: `thickness–32000`.
    /// * `thickness` — line thickness in dots. Range: `1–32000`.
    /// * `color` — line color. See [`Color`].
    /// * `rounding` — corner rounding amount. Range: `0–8` (`0` = sharp, `8` = most rounded).
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidThickness`] | `thickness` < 1 or > 32000 |
    /// | [`ZplError::InvalidBoxDimension`] | `width` or `height` < `thickness` or > 32000 |
    /// | [`ZplError::InvalidRounding`] | `rounding` > 8 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{LabelBuilder, Color};
    /// let zpl = LabelBuilder::new()
    ///     .add_graphical_box(10, 10, 200, 100, 3, Color::Black, 0).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^GB200,100,3,B,0"));
    /// ```
    pub fn add_graphical_box(
        mut self,
        x: u16,
        y: u16,
        width: u16,
        height: u16,
        thickness: u16,
        color: Color,
        rounding: u8,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let rounding = Rounding::try_from(rounding)?;
        let thickness = Thickness::try_from(thickness)?;
        let width = BoxDimension::try_new(width, thickness)?;
        let height = BoxDimension::try_new(height, thickness)?;
        let zpl_box =
            GraphicalBoxElement::new(x, y, width, height, thickness, color, rounding).to_zpl();
        self.elements.push(zpl_box);
        Ok(self)
    }

    /// Add a graphical circle (`^GC`).
    ///
    /// # Arguments
    ///
    /// * `x` — x-axis position in dots. Range: `0–32000`.
    /// * `y` — y-axis position in dots. Range: `0–32000`.
    /// * `diameter` — outer diameter in dots. Range: `3–4095`.
    /// * `thickness` — line thickness in dots. Range: `1–32000`.
    ///   Set equal to `diameter` to produce a filled circle.
    /// * `color` — line color. See [`Color`].
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidThickness`] | `thickness` < 1 or > 32000 |
    /// | [`ZplError::InvalidGraphicDimension`] | `diameter` < 3 or > 4095 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{LabelBuilder, Color};
    /// let zpl = LabelBuilder::new()
    ///     .add_graphical_circle(50, 50, 100, 3, Color::Black).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^GC100,3,B"));
    /// ```
    pub fn add_graphical_circle(
        mut self,
        x: u16,
        y: u16,
        diameter: u16,
        thickness: u16,
        color: Color,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let thickness = Thickness::try_from(thickness)?;
        let diameter = GraphicDimension::try_from(diameter)?;
        let zpl_circle = GraphicalCircleElement::new(x, y, diameter, thickness, color).to_zpl();
        self.elements.push(zpl_circle);
        Ok(self)
    }

    /// Add a graphical ellipse (`^GE`).
    ///
    /// # Arguments
    ///
    /// * `x` — x-axis position in dots. Range: `0–32000`.
    /// * `y` — y-axis position in dots. Range: `0–32000`.
    /// * `width` — ellipse width in dots. Range: `3–4095`.
    /// * `height` — ellipse height in dots. Range: `3–4095`.
    /// * `thickness` — line thickness in dots. Range: `1–32000`.
    /// * `color` — line color. See [`Color`].
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidThickness`] | `thickness` < 1 or > 32000 |
    /// | [`ZplError::InvalidGraphicDimension`] | `width` or `height` < 3 or > 4095 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{LabelBuilder, Color};
    /// let zpl = LabelBuilder::new()
    ///     .add_graphical_ellipse(20, 20, 200, 100, 2, Color::Black).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^GE200,100,2,B"));
    /// ```
    pub fn add_graphical_ellipse(
        mut self,
        x: u16,
        y: u16,
        width: u16,
        height: u16,
        thickness: u16,
        color: Color,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let thickness = Thickness::try_from(thickness)?;
        let width = GraphicDimension::try_from(width)?;
        let height = GraphicDimension::try_from(height)?;
        let zpl_ellipse =
            GraphicalEllipseElement::new(x, y, width, height, thickness, color).to_zpl();
        self.elements.push(zpl_ellipse);
        Ok(self)
    }

    /// Add a diagonal line (`^GD`).
    ///
    /// The line is drawn within a bounding box of size `box_width × box_height`.
    /// A square bounding box (`box_width == box_height`) produces a 45° angle.
    ///
    /// # Arguments
    ///
    /// * `x` — x-axis position of the bounding box in dots. Range: `0–32000`.
    /// * `y` — y-axis position of the bounding box in dots. Range: `0–32000`.
    /// * `box_width` — width of the bounding box in dots. Must be ≥ `thickness`.
    ///   Range: `thickness–32000`.
    /// * `box_height` — height of the bounding box in dots. Must be ≥ `thickness`.
    ///   Range: `thickness–32000`.
    /// * `thickness` — line thickness in dots. Range: `1–32000`.
    /// * `color` — line color. See [`Color`].
    /// * `orientation` — direction of the line. See [`DiagonalOrientation`].
    ///
    /// # Errors
    ///
    /// | Error | Condition |
    /// |---|---|
    /// | [`ZplError::InvalidPosition`] | `x` or `y` > 32000 |
    /// | [`ZplError::InvalidThickness`] | `thickness` < 1 or > 32000 |
    /// | [`ZplError::InvalidBoxDimension`] | `box_width` or `box_height` < `thickness` or > 32000 |
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::{LabelBuilder, Color, DiagonalOrientation};
    /// let zpl = LabelBuilder::new()
    ///     .add_graphical_diagonal_line(10, 10, 100, 100, 2, Color::Black, DiagonalOrientation::RightLeaning).unwrap()
    ///     .build();
    ///
    /// assert!(zpl.contains("^GD100,100,2,B,R"));
    /// ```
    pub fn add_graphical_diagonal_line(
        mut self,
        x: u16,
        y: u16,
        box_width: u16,
        box_height: u16,
        thickness: u16,
        color: Color,
        orientation: DiagonalOrientation,
    ) -> Result<Self, ZplError> {
        let (x, y) = get_axis_position(x, y)?;
        let thickness = Thickness::try_from(thickness)?;
        let box_width = BoxDimension::try_new(box_width, thickness)?;
        let box_height = BoxDimension::try_new(box_height, thickness)?;
        let zpl_diagonal = GraphicalDiagonalLineElement::new(
            x,
            y,
            box_width,
            box_height,
            thickness,
            color,
            orientation,
        )
        .to_zpl();
        self.elements.push(zpl_diagonal);
        Ok(self)
    }

    /// Assemble and return the complete ZPL string.
    ///
    /// The string starts with `^XA` and ends with `^XZ`. It can be sent
    /// directly to a Zebra printer over TCP, USB, or serial.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use zpl_builder::LabelBuilder;
    /// let zpl = LabelBuilder::new().build();
    /// assert_eq!(zpl, "^XA\n^LH0,0\n^XZ");
    /// ```
    #[must_use]
    pub fn build(&self) -> String {
        let mut zpl = String::new();
        zpl.push_str("^XA\n");
        zpl.push_str(format!("^LH{},{}\n", self.x_origin, self.y_origin).as_str());
        for element in &self.elements {
            zpl.push_str(element);
        }
        zpl.push_str("^XZ");
        zpl
    }
}

impl Default for LabelBuilder {
    fn default() -> Self {
        Self::new()
    }
}