zpl-builder 0.1.0

//! A library for building [ZPL II](https://www.zebra.com/us/en/support-downloads/software/zpl-resources.html)
//! label strings to be sent to Zebra thermal printers.
//!
//! # 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.
//!
//! # Quick start
//!
//! ```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"));
//! ```
//!
//! # Elements
//!
//! The builder supports the following ZPL elements:
//!
//! | Method | ZPL command | Description |
//! |---|---|---|
//! | [`LabelBuilder::add_text`] | `^A` / `^FD` | Text field |
//! | [`LabelBuilder::add_barcode`] | `^BY` / `^B*` | Barcode (27 types) |
//! | [`LabelBuilder::add_graphical_box`] | `^GB` | Rectangle |
//! | [`LabelBuilder::add_graphical_circle`] | `^GC` | Circle |
//! | [`LabelBuilder::add_graphical_ellipse`] | `^GE` | Ellipse |
//! | [`LabelBuilder::add_graphical_diagonal_line`] | `^GD` | Diagonal line |
//!
//! # Error handling
//!
//! Every builder method returns `Result<LabelBuilder, ZplError>`. This means
//! you can chain calls with `?` in a function that returns `Result`:
//!
//! ```rust
//! use zpl_builder::{LabelBuilder, Color, Orientation, ZplError};
//!
//! fn build_shipping_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())
//! }
//! ```
//!
//! Or with `.unwrap()` / `.expect()` when the values are known to be valid:
//!
//! ```rust
//! use zpl_builder::{LabelBuilder, Orientation};
//!
//! let zpl = LabelBuilder::new()
//!     .add_text("Fixed label", 10, 10, 'A', 20, Orientation::Normal).unwrap()
//!     .build();
//! ```
//!
//! See [`ZplError`] for the full list of validation errors and their ranges.

#![deny(
    missing_docs,
    missing_debug_implementations,
    missing_copy_implementations,
    trivial_casts,
    trivial_numeric_casts,
    unsafe_code,
    unstable_features,
    unused_import_braces,
    unused_qualifications
)]

mod builder;
mod elements;
mod types;

pub use crate::builder::{BarcodeType, Color, DiagonalOrientation, LabelBuilder, Orientation};
pub use crate::types::ZplError;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{AxisPosition, BoxDimension, GraphicDimension, Thickness, WidthRatio};

    // ── AxisPosition ──────────────────────────────────────────────────────────

    #[test]
    fn axis_position_valid_bounds() {
        assert_eq!(AxisPosition::try_from(0), Ok(AxisPosition(0)));
        assert_eq!(AxisPosition::try_from(32000), Ok(AxisPosition(32000)));
        assert_eq!(AxisPosition::try_from(1000), Ok(AxisPosition(1000)));
    }

    #[test]
    fn axis_position_out_of_range() {
        assert_eq!(
            AxisPosition::try_from(32001),
            Err(ZplError::InvalidPosition(32001))
        );
        assert_eq!(
            AxisPosition::try_from(u16::MAX),
            Err(ZplError::InvalidPosition(u16::MAX))
        );
    }

    // ── WidthRatio ────────────────────────────────────────────────────────────

    #[test]
    fn width_ratio_valid_values() {
        assert_eq!(WidthRatio::try_from(2.0).unwrap().to_string(), "2.0");
        assert_eq!(WidthRatio::try_from(2.5).unwrap().to_string(), "2.5");
        assert_eq!(WidthRatio::try_from(3.0).unwrap().to_string(), "3.0");
    }

    #[test]
    fn width_ratio_out_of_range() {
        assert_eq!(
            WidthRatio::try_from(1.9),
            Err(ZplError::InvalidWidthRatio(1.9))
        );
        assert_eq!(
            WidthRatio::try_from(3.1),
            Err(ZplError::InvalidWidthRatio(3.1))
        );
    }

    // ── GraphicDimension ──────────────────────────────────────────────────────

    #[test]
    fn graphic_dimension_valid_bounds() {
        assert_eq!(GraphicDimension::try_from(3), Ok(GraphicDimension(3)));
        assert_eq!(GraphicDimension::try_from(4095), Ok(GraphicDimension(4095)));
    }

    #[test]
    fn graphic_dimension_out_of_range() {
        assert_eq!(
            GraphicDimension::try_from(2),
            Err(ZplError::InvalidGraphicDimension(2))
        );
        assert_eq!(
            GraphicDimension::try_from(4096),
            Err(ZplError::InvalidGraphicDimension(4096))
        );
    }

    // ── BoxDimension ──────────────────────────────────────────────────────────

    #[test]
    fn box_dimension_equal_to_thickness() {
        let t = Thickness::try_from(10).unwrap();
        assert_eq!(BoxDimension::try_new(10, t), Ok(BoxDimension(10)));
    }

    #[test]
    fn box_dimension_greater_than_thickness() {
        let t = Thickness::try_from(10).unwrap();
        assert_eq!(BoxDimension::try_new(200, t), Ok(BoxDimension(200)));
    }

    #[test]
    fn box_dimension_less_than_thickness() {
        let t = Thickness::try_from(10).unwrap();
        assert_eq!(
            BoxDimension::try_new(9, t),
            Err(ZplError::InvalidBoxDimension {
                value: 9,
                thickness: 10
            })
        );
    }

    #[test]
    fn box_dimension_at_maximum() {
        let t = Thickness::try_from(1).unwrap();
        assert_eq!(BoxDimension::try_new(32000, t), Ok(BoxDimension(32000)));
        assert_eq!(
            BoxDimension::try_new(32001, t),
            Err(ZplError::InvalidBoxDimension {
                value: 32001,
                thickness: 1
            })
        );
    }

    // ── add_text ──────────────────────────────────────────────────────────────

    #[test]
    fn add_text_normal_orientation() {
        let label = LabelBuilder::new()
            .add_text("Text to print.", 10, 10, 'B', 15, Orientation::Normal)
            .unwrap()
            .build();
        assert_eq!(
            label,
            "^XA\n^LH0,0\n^AB,15^FO10,10^FDText to print.^FS\n^XZ"
        );
    }

    #[test]
    fn add_text_inverted_orientation() {
        let label = LabelBuilder::new()
            .add_text("Text to print.", 10, 10, '1', 15, Orientation::Inverted)
            .unwrap()
            .build();
        assert_eq!(
            label,
            "^XA\n^LH0,0\n^A1,15^FWI^FO10,10^FDText to print.^FS\n^XZ"
        );
    }

    #[test]
    fn add_text_rotated_orientation() {
        let label = LabelBuilder::new()
            .add_text("Hello", 0, 0, 'A', 10, Orientation::Rotated)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^AA,10^FWR^FO0,0^FDHello^FS\n^XZ");
    }

    #[test]
    fn add_text_bottom_orientation() {
        let label = LabelBuilder::new()
            .add_text("Hello", 0, 0, 'A', 10, Orientation::Bottom)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^AA,10^FWB^FO0,0^FDHello^FS\n^XZ");
    }

    #[test]
    fn add_text_invalid_font() {
        assert_eq!(
            LabelBuilder::new().add_text("x", 10, 10, '0', 15, Orientation::Normal),
            Err(ZplError::InvalidFont('0'))
        );
        assert_eq!(
            LabelBuilder::new().add_text("x", 10, 10, 'a', 15, Orientation::Normal),
            Err(ZplError::InvalidFont('a'))
        );
        assert_eq!(
            LabelBuilder::new().add_text("x", 10, 10, ' ', 15, Orientation::Normal),
            Err(ZplError::InvalidFont(' '))
        );
    }

    #[test]
    fn add_text_invalid_position() {
        assert_eq!(
            LabelBuilder::new().add_text("x", 32001, 0, 'A', 15, Orientation::Normal),
            Err(ZplError::InvalidPosition(32001))
        );
        assert_eq!(
            LabelBuilder::new().add_text("x", 0, 32001, 'A', 15, Orientation::Normal),
            Err(ZplError::InvalidPosition(32001))
        );
    }

    #[test]
    fn add_text_invalid_font_size() {
        assert_eq!(
            LabelBuilder::new().add_text("x", 0, 0, 'A', 9, Orientation::Normal),
            Err(ZplError::InvalidFontSize(9))
        );
    }

    // ── add_barcode ───────────────────────────────────────────────────────────

    #[test]
    fn add_barcode_normal_orientation() {
        let label = LabelBuilder::new()
            .add_barcode(
                BarcodeType::Code128,
                "Text to encode.",
                10,
                10,
                2,
                3.0,
                10,
                Orientation::Normal,
            )
            .unwrap()
            .build();
        assert_eq!(
            label,
            "^XA\n^LH0,0\n^BY2,3.0,10\n^FO10,10^BC^FDText to encode.^FS\n^XZ"
        );
    }

    #[test]
    fn add_barcode_inverted_orientation() {
        let label = LabelBuilder::new()
            .add_barcode(
                BarcodeType::Code128,
                "Text to encode.",
                10,
                10,
                2,
                2.5,
                10,
                Orientation::Inverted,
            )
            .unwrap()
            .build();
        assert_eq!(
            label,
            "^XA\n^LH0,0\n^BY2,2.5,10\n^FO10,10^BC,I^FDText to encode.^FS\n^XZ"
        );
    }

    #[test]
    fn add_barcode_invalid_width() {
        assert_eq!(
            LabelBuilder::new().add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                0,
                2.5,
                10,
                Orientation::Normal
            ),
            Err(ZplError::InvalidBarcodeWidth(0))
        );
        assert_eq!(
            LabelBuilder::new().add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                11,
                2.5,
                10,
                Orientation::Normal
            ),
            Err(ZplError::InvalidBarcodeWidth(11))
        );
    }

    #[test]
    fn add_barcode_invalid_width_ratio() {
        assert_eq!(
            LabelBuilder::new().add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                2,
                1.9,
                10,
                Orientation::Normal
            ),
            Err(ZplError::InvalidWidthRatio(1.9))
        );
        assert_eq!(
            LabelBuilder::new().add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                2,
                3.1,
                10,
                Orientation::Normal
            ),
            Err(ZplError::InvalidWidthRatio(3.1))
        );
    }

    #[test]
    fn add_barcode_invalid_height() {
        assert_eq!(
            LabelBuilder::new().add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                2,
                2.5,
                0,
                Orientation::Normal
            ),
            Err(ZplError::InvalidBarcodeHeight(0))
        );
    }

    // ── add_graphical_box ─────────────────────────────────────────────────────

    #[test]
    fn add_graphical_box_valid() {
        let label = LabelBuilder::new()
            .add_graphical_box(10, 10, 100, 200, 3, Color::Black, 0)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO10,10^GB100,200,3,B,0^FS\n^XZ");
    }

    #[test]
    fn add_graphical_box_white() {
        let label = LabelBuilder::new()
            .add_graphical_box(0, 0, 50, 50, 1, Color::White, 0)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO0,0^GB50,50,1,W,0^FS\n^XZ");
    }

    #[test]
    fn add_graphical_box_width_less_than_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_box(0, 0, 2, 100, 5, Color::Black, 0),
            Err(ZplError::InvalidBoxDimension {
                value: 2,
                thickness: 5
            })
        );
    }

    #[test]
    fn add_graphical_box_height_less_than_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_box(0, 0, 100, 2, 5, Color::Black, 0),
            Err(ZplError::InvalidBoxDimension {
                value: 2,
                thickness: 5
            })
        );
    }

    #[test]
    fn add_graphical_box_invalid_rounding() {
        assert_eq!(
            LabelBuilder::new().add_graphical_box(0, 0, 100, 100, 1, Color::Black, 9),
            Err(ZplError::InvalidRounding(9))
        );
    }

    #[test]
    fn add_graphical_box_invalid_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_box(0, 0, 100, 100, 0, Color::Black, 0),
            Err(ZplError::InvalidThickness(0))
        );
    }

    // ── add_graphical_circle ──────────────────────────────────────────────────

    #[test]
    fn add_graphical_circle_valid() {
        let label = LabelBuilder::new()
            .add_graphical_circle(10, 10, 100, 2, Color::Black)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO10,10^GC100,2,B^FS\n^XZ");
    }

    #[test]
    fn add_graphical_circle_invalid_diameter() {
        assert_eq!(
            LabelBuilder::new().add_graphical_circle(0, 0, 2, 1, Color::Black),
            Err(ZplError::InvalidGraphicDimension(2))
        );
        assert_eq!(
            LabelBuilder::new().add_graphical_circle(0, 0, 4096, 1, Color::Black),
            Err(ZplError::InvalidGraphicDimension(4096))
        );
    }

    #[test]
    fn add_graphical_circle_invalid_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_circle(0, 0, 100, 0, Color::Black),
            Err(ZplError::InvalidThickness(0))
        );
    }

    // ── add_graphical_ellipse ─────────────────────────────────────────────────

    #[test]
    fn add_graphical_ellipse_valid() {
        let label = LabelBuilder::new()
            .add_graphical_ellipse(10, 10, 100, 150, 2, Color::Black)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO10,10^GE100,150,2,B^FS\n^XZ");
    }

    #[test]
    fn add_graphical_ellipse_invalid_width() {
        assert_eq!(
            LabelBuilder::new().add_graphical_ellipse(0, 0, 2, 100, 1, Color::Black),
            Err(ZplError::InvalidGraphicDimension(2))
        );
    }

    #[test]
    fn add_graphical_ellipse_invalid_height() {
        assert_eq!(
            LabelBuilder::new().add_graphical_ellipse(0, 0, 100, 4096, 1, Color::Black),
            Err(ZplError::InvalidGraphicDimension(4096))
        );
    }

    // ── add_graphical_diagonal_line ───────────────────────────────────────────────

    #[test]
    fn add_graphical_diagonal_line_right_leaning() {
        let label = LabelBuilder::new()
            .add_graphical_diagonal_line(
                10,
                10,
                100,
                50,
                2,
                Color::Black,
                DiagonalOrientation::RightLeaning,
            )
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO10,10^GD100,50,2,B,R^FS\n^XZ");
    }

    #[test]
    fn add_graphical_diagonal_line_left_leaning() {
        let label = LabelBuilder::new()
            .add_graphical_diagonal_line(
                10,
                10,
                100,
                50,
                2,
                Color::Black,
                DiagonalOrientation::LeftLeaning,
            )
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO10,10^GD100,50,2,B,L^FS\n^XZ");
    }

    #[test]
    fn add_graphical_diagonal_line_white() {
        let label = LabelBuilder::new()
            .add_graphical_diagonal_line(
                0,
                0,
                200,
                100,
                3,
                Color::White,
                DiagonalOrientation::RightLeaning,
            )
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO0,0^GD200,100,3,W,R^FS\n^XZ");
    }

    #[test]
    fn add_graphical_diagonal_line_square_box() {
        // box_width == box_height → 45° angle
        let label = LabelBuilder::new()
            .add_graphical_diagonal_line(
                0,
                0,
                100,
                100,
                1,
                Color::Black,
                DiagonalOrientation::LeftLeaning,
            )
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO0,0^GD100,100,1,B,L^FS\n^XZ");
    }

    #[test]
    fn add_graphical_diagonal_line_width_equal_to_thickness() {
        // minimum valid width: exactly equal to thickness
        let label = LabelBuilder::new()
            .add_graphical_diagonal_line(
                0,
                0,
                5,
                50,
                5,
                Color::Black,
                DiagonalOrientation::RightLeaning,
            )
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH0,0\n^FO0,0^GD5,50,5,B,R^FS\n^XZ");
    }

    #[test]
    fn add_graphical_diagonal_line_invalid_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_diagonal_line(
                0,
                0,
                100,
                100,
                0,
                Color::Black,
                DiagonalOrientation::RightLeaning
            ),
            Err(ZplError::InvalidThickness(0))
        );
    }

    #[test]
    fn add_graphical_diagonal_line_width_less_than_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_diagonal_line(
                0,
                0,
                4,
                100,
                5,
                Color::Black,
                DiagonalOrientation::RightLeaning
            ),
            Err(ZplError::InvalidBoxDimension {
                value: 4,
                thickness: 5
            })
        );
    }

    #[test]
    fn add_graphical_diagonal_line_height_less_than_thickness() {
        assert_eq!(
            LabelBuilder::new().add_graphical_diagonal_line(
                0,
                0,
                100,
                4,
                5,
                Color::Black,
                DiagonalOrientation::LeftLeaning
            ),
            Err(ZplError::InvalidBoxDimension {
                value: 4,
                thickness: 5
            })
        );
    }

    #[test]
    fn add_graphical_diagonal_line_invalid_position() {
        assert_eq!(
            LabelBuilder::new().add_graphical_diagonal_line(
                32001,
                0,
                100,
                100,
                1,
                Color::Black,
                DiagonalOrientation::RightLeaning
            ),
            Err(ZplError::InvalidPosition(32001))
        );
    }

    // ── set_home_position ─────────────────────────────────────────────────────

    #[test]
    fn set_home_position_valid() {
        let label = LabelBuilder::new()
            .set_home_position(50, 100)
            .unwrap()
            .build();
        assert_eq!(label, "^XA\n^LH50,100\n^XZ");
    }

    #[test]
    fn set_home_position_invalid() {
        assert_eq!(
            LabelBuilder::new().set_home_position(32001, 0),
            Err(ZplError::InvalidPosition(32001))
        );
        assert_eq!(
            LabelBuilder::new().set_home_position(0, 32001),
            Err(ZplError::InvalidPosition(32001))
        );
    }

    // ── Full label ────────────────────────────────────────────────────────────

    #[test]
    fn create_full_label() {
        let label = LabelBuilder::new()
            .set_home_position(10, 10)
            .unwrap()
            .add_text("Test label", 200, 50, '2', 50, Orientation::Normal)
            .unwrap()
            .add_graphical_box(50, 200, 500, 300, 3, Color::Black, 5)
            .unwrap()
            .add_barcode(
                BarcodeType::Code128,
                "Test barcode",
                130,
                270,
                2,
                2.5,
                150,
                Orientation::Normal,
            )
            .unwrap()
            .add_graphical_ellipse(200, 700, 250, 150, 3, Color::Black)
            .unwrap()
            .add_graphical_circle(300, 750, 50, 3, Color::Black)
            .unwrap()
            .build();
        let expected = concat!(
            "^XA\n",
            "^LH10,10\n",
            "^A2,50^FO200,50^FDTest label^FS\n",
            "^FO50,200^GB500,300,3,B,5^FS\n",
            "^BY2,2.5,150\n^FO130,270^BC^FDTest barcode^FS\n",
            "^FO200,700^GE250,150,3,B^FS\n",
            "^FO300,750^GC50,3,B^FS\n",
            "^XZ",
        );
        assert_eq!(label, expected);
    }

    #[test]
    fn empty_label() {
        let label = LabelBuilder::new().build();
        assert_eq!(label, "^XA\n^LH0,0\n^XZ");
    }

    #[test]
    fn error_stops_chain_early() {
        // An invalid barcode width should prevent the label from being built,
        // even if later elements had been valid.
        let result = LabelBuilder::new()
            .add_barcode(
                BarcodeType::Code128,
                "x",
                0,
                0,
                11,
                2.5,
                10,
                Orientation::Normal,
            )
            .and_then(|b| b.add_text("y", 0, 0, 'A', 10, Orientation::Normal));
        assert_eq!(result, Err(ZplError::InvalidBarcodeWidth(11)));
    }
}