flutter_zpl_builder 1.0.0

A CLI tool to statically extract ZPL strings from Dart source files using analyzer.

ZPL Builder CLI (flutter_zpl_builder)

A standalone Dart command-line interface (CLI) tool designed to generate Zebra Programming Language (ZPL) strings directly from Dart code.

By leveraging Dart's official analyzer package, ZPL Builder uses static analysis to parse ZplGenerator objects without needing to run Flutter or depend on dart:ui. It is built to run natively in pure Dart VM environments, making it ideal for backend services, CI/CD pipelines, and server-side ZPL generation.

Features

• Pure Dart Execution: Run safely without the Flutter SDK. Completely independent of RootBundle and graphical capabilities like dart:ui.
• Static Syntax Tree Parsing: Maps your Dart file's Abstract Syntax Tree (AST) into runtime ZPL objects in-memory.
• Support for Core Primitives: Maps the majority of flutter_zpl_generator's visual nodes perfectly. Supported primitives include:
  • Text & Barcodes: ZplText, ZplBarcode
  • Graphics & Shapes: ZplBox, ZplSeparator, ZplGraphicCircle, ZplGraphicEllipse, ZplGraphicDiagonalLine
  • Layout Constraints: ZplColumn, ZplGridRow, ZplGridCol
  • Injection: ZplRaw
• Output to stdout: Returns ZPL strings straight to standard output, making it highly chainable for shell scripts.

Getting Started

Global Installation (recommended)

Install once and use anywhere:

dart pub global activate --source path .

Then run from any directory:

zpl_builder -i <path/to/file.dart>

Local Development

If working within the project itself:

dart pub get
dart run bin/zpl_builder.dart -i <path/to/file.dart>

Usage

Define a layout using ZplGenerator inside a standalone .dart file.

Note: Since the parser uses static analysis, the layout structure must be statically analyzable. Avoid using execution semantics like dynamic arrays, loops, or complex runtime variable interpolations directly inside the configuration array.

Options

Option	Alias	Description
--input	-i	Path to the Dart file containing the ZplGenerator instance.
--help	-h	Show the help message.

Example

Included in the example/ directory are pure Dart examples of flutter_zpl_generator layouts.

# Global install
zpl_builder -i example/text_demo.dart

# Or local development
dart run bin/zpl_builder.dart -i example/text_demo.dart

Output:

Starting ZPL static analysis on: example/text_demo.dart

Analysis complete. Found 1 ZplGenerator instance(s).
Mapping AST literal values to Dart memory constructs...

================ ZPL OUTPUT ================
^XA
^LL1100
^PW812
^JMA
^FO0,20
^A0N,40,36
^FB812,1,0,C,0
^FDTEXT CAPABILITIES^FS
...
^XZ
============================================

Advanced Examples

To see how advanced components such as barcodes, grids, columns, and geometric shapes are translated, refer to the files within the example/ directory:

• example/text_demo.dart - Font sizes, orientations, alignment, text wrapping
• example/barcode_demo.dart - Code128, Code39, QR, DataMatrix, EAN-13, UPC-A
• example/graphics_demo.dart - Boxes, circles, ellipses, diagonal lines, ZplRaw
• example/layout_demo.dart - ZplColumn, ZplGridRow, ZplGridCol

Architecture Limitations

• Images: Components like ZplImage are not natively supported statically as they require converting byte streams or images (such as Uint8List) into rendered monochrome memory blobs at runtime, which is beyond the scope of a static AST processor.
• Variables / Complex Control Flow: Variables referenced outside the ZplGenerator tree and dynamic structural loops cannot currently be executed via the static analyzer. Use templating (ZplText with literal template brackets e.g. {{name}}) or code generation loops instead.

Additional Information

This tool serves as an extension payload of the larger flutter_zpl_generator ecosystem.