zpl_render 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05e06eca743b13623cd089ca67956463df7ddeccba669ac184028669a1df1367
+  data.tar.gz: d30efa23e8265c64b11a3586cbb547f3dfe57e526eb1dfdaa277f127d65c7942
+SHA512:
+  metadata.gz: 8a2deff01c66b826be88bb43a2fafc457a735911b530b91b3523c349d1b85881947f46afc10807053fb8cdf3bc61c6f9df945d7798c49ef53946ea1a5183bf02
+  data.tar.gz: 0c26655758c3d6e790ad68b886e53c5a3932fe295391108bd6e6d7a7bddd5abb5140a899738e2822fbb3ab57a8f023f911f25809f917750aaa5878da9d498ada

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-31
+
+Initial release.
+
+### Added
+
+- ZPL II parser and renderer producing one 1-bit dot canvas per `^XA..^XZ`
+  format, at true printer resolution (dpmm 6/8/12/24).
+- PNG output (`ZplRender.to_png` / `.to_pngs`, chunky_png) and PDF output
+  (`ZplRender.to_pdf`, prawn) with one page per label at exact physical size.
+- Barcodes, scanner-verified against the zxing-cpp engine in the spec suite:
+  - Code 128 (`^BC`): own ISO/IEC 15417 encoder with ZPL subset invocation
+    codes (`>0`..`>;`), modes N / A (automatic) / U (UCC case) / D (GS1),
+    mod-103 check symbol, mod-10 UCC check digit.
+  - PDF417 (`^B7`): own ISO/IEC 15438 encoder, byte + numeric compaction,
+    Reed-Solomon error correction over GF(929), security levels 0-8,
+    columns/rows/truncated.
+  - QR (`^BQ`) via rqrcode_core, with ZPL `<ECC><mode>,` field-data prefixes.
+  - Code 39 (`^B3`) with optional mod-43 check digit.
+  - Interleaved 2 of 5 (`^B2`) with optional mod-10 check digit.
+- Text rendering through a built-in pure-Ruby TrueType rasterizer using
+  bundled Liberation Sans Bold (scalable font 0) and Liberation Mono Regular
+  (bitmap fonts A-H, with ZPL matrix cells and inter-character gaps),
+  metrics calibrated against Labelary reference renders; embedded
+  public-domain 8x8 bitmap font as fallback.
+- Fields and graphics: `^FO ^FT ^FS ^FD ^FV ^SN`, fonts `^A ^A@ ^CF`,
+  field blocks `^FB`, hex escapes `^FH`, `^CI`, field reverse `^FR`,
+  rotation via `^FW`/per-field orientation (last-wins), `^GB ^GC ^GD`,
+  `^GF` images (ASCII hex, Zebra RLE, B64/Z64), `~DG`/`^XG` stored
+  graphics, `^PW ^LL ^LH` (narrow `^PW` centers, never shrinks),
+  `^CC ~CC ^CT ~CT`, multi-label streams.
+- `zpl_render` CLI (PNG/PDF by output extension, `--strict`, `--quiet`).
+- Error hygiene: all intentional failures raise `ZplRender::Error`;
+  lenient mode collects contextual warnings, `strict: true` raises on the
+  first problem.
+- CI matrix for Ruby 3.0-3.4 (GitHub Actions and GitLab CI) with real
+  scanner round-trip verification.
+
+[Unreleased]: https://github.com/wqsaali/zpl_render/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wqsaali/zpl_render/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waqas Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# zpl_render
+
+A pure-Ruby ZPL II renderer. Converts Zebra label programs (`^XA...^XZ`) to
+**PNG** images and print-size **PDF** documents, rasterizing at true printer
+resolution so barcodes come out module-exact and scanner-readable.
+
+Every barcode symbology in this gem is verified in CI by rendering labels and
+decoding them back with the [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp)
+scanner engine, at every supported rotation and at 203 and 300 dpi.
+
+## Install
+
+```ruby
+gem "zpl_render"
+```
+
+Runtime dependencies are pure Ruby: `chunky_png`, `rqrcode_core`, `prawn`.
+No ImageMagick, no Java, no native extensions. Text is rasterized by a
+built-in pure-Ruby TrueType engine from bundled Liberation fonts (SIL OFL).
+
+## Usage
+
+```ruby
+require "zpl_render"
+
+zpl = File.read("label.zpl")
+
+# PNG (first label). dpmm: 6 = 152 dpi, 8 = 203 dpi, 12 = 300 dpi, 24 = 600 dpi
+png = ZplRender.to_png(zpl, dpmm: 8, width_in: 4, height_in: 6)
+File.binwrite("label.png", png)
+
+# PDF: one page per ^XA..^XZ format, at exact physical label size
+pdf = ZplRender.to_pdf(zpl, dpmm: 8, width_in: 4, height_in: 6)
+File.binwrite("labels.pdf", pdf)
+
+# All labels as PNGs, upscaled 2x for screen display
+pngs = ZplRender.to_pngs(zpl, scale: 2)
+
+# Collect diagnostics about unsupported commands
+warnings = []
+ZplRender.to_png(zpl, warnings: warnings)
+
+# Strict mode: raise on the first problem instead of warning
+ZplRender.to_png(zpl, strict: true)
+```
+
+## Errors
+
+Every intentional failure raises `ZplRender::Error` (invalid input type,
+bad dpmm/dimensions, no `^XA..^XZ` formats, oversized barcode data in
+strict mode). By default rendering is lenient, like a printer: a field
+that cannot render or an unsupported command is recorded in the
+`warnings:` array with its type and position (for example
+`pdf417 barcode field at (21,433) failed: ...`) and rendering continues.
+Pass `strict: true` (CLI: `--strict`) for pipelines that must not
+silently drop label content.
+
+### CLI
+
+```
+zpl_render label.zpl -o label.png          # PNG at 203 dpi, 4x6"
+zpl_render label.zpl -o label.pdf -d 12    # PDF at 300 dpi
+cat label.zpl | zpl_render -o out.png -W 4 -H 2
+```
+
+## Barcode accuracy
+
+Barcodes are generated from the symbology specifications, not drawn
+approximately, and are rendered on a 1-bit dot grid with integer module
+widths (`^BY`), exactly as a Zebra print head would lay them down:
+
+| Symbology | ZPL | Implementation |
+|---|---|---|
+| Code 128 | `^BC` | Own encoder: ISO/IEC 15417 patterns, mod-103 check, ZPL subset invocation codes (`>9 >: >; >5 >6 >7 >8` ...), modes **N**, **A** (automatic packing), **U** (UCC case, SSCC-18 + mod-10) and **D** (GS1 with application identifiers, FNC1) |
+| QR Code | `^BQ` | `rqrcode_core` (full ISO/IEC 18004: Reed-Solomon ECC, mask scoring); ZPL `<ECC><mode>,` field-data prefixes (`QA,` `HM,` ...) |
+| PDF417 | `^B7` | Own encoder: ISO/IEC 15438 cluster patterns, Reed-Solomon over GF(929), security levels 0-8, columns/rows/truncated; verified byte-exact against FedEx ANSI MH10.8.2 payloads incl. GS/RS/EOT control characters |
+| Code 39 | `^B3` | Full pattern table, optional mod-43 check digit |
+| Interleaved 2 of 5 | `^B2` | Interleaved pairs, optional mod-10 check digit |
+
+GS1-128 output is validated down to the application identifier level: a
+scanner decodes the mode-U/D output as `(00)61414100...` etc.
+
+## Supported commands
+
+`^XA ^XZ` formats (multiple per stream), `^FO ^FT ^FS ^FD ^FV ^SN`,
+fonts `^A ^A@ ^CF` with `^FB` field blocks (wrap, `\&` line breaks, L/C/R
+justification), `^FH` hex escapes, `^CI`, field reverse `^FR`,
+default orientation `^FW` and per-field rotation (N/R/I/B),
+barcodes `^BY ^BC ^B3 ^B2 ^B7 ^BQ` (with interpretation lines, above/below),
+graphics `^GB ^GC ^GD`, images `^GF` (ASCII hex, Zebra RLE compression,
+`:B64:`/`:Z64:`) and `~DG`/`^XG` stored graphics,
+layout `^PW ^LL ^LH`, prefix changes `^CC ~CC ^CT ~CT`, comments `^FX`.
+Print-control commands with no visual effect (`^PQ ^MM ^MD ...`) are
+ignored; anything else is reported through the `warnings:` array.
+
+## Fidelity notes
+
+- Scalable font 0 renders with Liberation Sans Bold (metrics match
+  Helvetica/Arial Bold, close to Zebra's CG Triumvirate Bold Condensed),
+  with advances and cap height calibrated against Labelary reference
+  renders. Bitmap fonts A-H render with Liberation Mono Regular at the
+  ZPL matrix cell sizes and inter-character gaps; font B is
+  uppercase-only like the hardware. On a real FedEx Ground label this
+  reproduces the reference render with ~94% pixel agreement, and
+  Code 128 output is pixel-identical. If the bundled fonts cannot be
+  loaded, an embedded public-domain 8x8 bitmap font is the fallback.
+- `^PW` narrower than the label width is centered on the canvas and
+  never shrinks it, matching printer behavior.
+- `^B7` PDF417 uses byte + numeric compaction; a Zebra printer may pick
+  text compaction for the same data, producing a denser but
+  identically-decoding symbol.
+- `^BQ` mask selection is delegated to the encoder's automatic mask
+  scoring (always produces a spec-valid, scannable symbol; the printed
+  pixel pattern may differ from a printer forcing a specific mask).
+- DataMatrix (`^BX`) and template recall (`^FN`/`^XF`) are not yet
+  implemented and are surfaced as warnings.
+
+## Development
+
+```
+bundle install
+bundle exec rspec          # includes scanner round-trip tests when
+                           # python3 + zxing-cpp + pillow are installed
+```
+
+CI runs the suite (with the real zxing-cpp scanner) on Ruby 3.0 through
+3.4 via the version matrix in `.github/workflows/ci.yml` and
+`.gitlab-ci.yml`.
+
+### Releasing
+
+1. Update `ZplRender::VERSION` and move the `[Unreleased]` notes to a new
+   version section in `CHANGELOG.md`.
+2. Commit, then tag and push: `git tag v0.2.0 && git push origin main v0.2.0`.
+
+The `Release` workflow runs the full test matrix, verifies the tag matches
+`ZplRender::VERSION`, builds the gem, and creates a GitHub release with
+the `.gem` attached and notes taken from the changelog. If a
+`RUBYGEMS_API_KEY` repository secret is configured, it also publishes to
+rubygems.org.
+
+## License
+
+MIT. Embedded 8x8 font derived from public-domain IBM VGA fonts
+(via Daniel Hepper's font8x8).

data/exe/zpl_render

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "zpl_render"
+
+options = { dpmm: 8, width: 4.0, height: 6.0, scale: 1, output: nil }
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    Usage: zpl_render [options] [input.zpl]
+
+    Renders ZPL II to PNG or PDF (format chosen by output extension).
+    Reads from stdin when no input file is given.
+  BANNER
+
+  opts.on("-o", "--output FILE", "Output file (.png or .pdf). Default: label.png") { |v| options[:output] = v }
+  opts.on("-d", "--dpmm N", Integer, "Printer density in dots/mm (6, 8, 12, 24). Default: 8 (203 dpi)") { |v| options[:dpmm] = v }
+  opts.on("-W", "--width INCHES", Float, "Label width in inches (default 4)") { |v| options[:width] = v }
+  opts.on("-H", "--height INCHES", Float, "Label height in inches (default 6)") { |v| options[:height] = v }
+  opts.on("-s", "--scale N", Integer, "Integer upscale for PNG output (default 1)") { |v| options[:scale] = v }
+  opts.on("--strict", "Fail on the first problem instead of warning") { options[:strict] = true }
+  opts.on("-q", "--quiet", "Suppress warnings") { options[:quiet] = true }
+  opts.on("-v", "--version", "Print version") do
+    puts ZplRender::VERSION
+    exit
+  end
+end
+parser.parse!
+
+if ARGV[0] && !File.exist?(ARGV[0])
+  warn "error: input file not found: #{ARGV[0]}"
+  exit 1
+end
+
+zpl = ARGV[0] ? File.read(ARGV[0]) : $stdin.read
+output = options[:output] || "label.png"
+warnings = []
+
+begin
+  bytes = if File.extname(output).casecmp(".pdf").zero?
+            ZplRender.to_pdf(zpl, dpmm: options[:dpmm], width_in: options[:width],
+                                  height_in: options[:height], strict: options[:strict],
+                                  warnings: warnings)
+          else
+            ZplRender.to_png(zpl, dpmm: options[:dpmm], width_in: options[:width],
+                                  height_in: options[:height], scale: options[:scale],
+                                  strict: options[:strict], warnings: warnings)
+          end
+rescue ZplRender::Error => e
+  warn "error: #{e.message}"
+  exit 1
+end
+
+begin
+  File.binwrite(output, bytes)
+rescue SystemCallError => e
+  warn "error: cannot write #{output}: #{e.message}"
+  exit 1
+end
+warnings.uniq.each { |w| warn "warning: #{w}" } unless options[:quiet]
+puts "wrote #{output}"

data/lib/zpl_render/barcode/code128.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module ZplRender
+  module Barcode
+    # Code 128 encoder implementing ZPL ^BC semantics, including the Zebra
+    # subset invocation characters (>0 .. >;) and modes N, U, A and D.
+    #
+    # Produces the exact module sequence defined by ISO/IEC 15417: each
+    # symbol is 6 elements (11 modules), the stop pattern is 7 elements
+    # (13 modules), with a mod-103 check symbol before the stop.
+    class Code128
+      # Element widths for symbol values 0..105 (each entry: 3 bars and
+      # 3 spaces, alternating, starting with a bar).
+      PATTERNS = %w[
+        212222 222122 222221 121223 121322 131222 122213 122312 132212 221213
+        221312 231212 112232 122132 122231 113222 123122 123221 223211 221132
+        221231 213212 223112 312131 311222 321122 321221 312212 322112 322211
+        212123 212321 232121 111323 131123 131321 112313 132113 132311 211313
+        231113 231311 112133 112331 132131 113123 113321 133121 313121 211331
+        231131 213113 213311 213131 311123 311321 331121 312113 312311 332111
+        314111 221411 431111 111224 111422 121124 121421 141122 141221 112214
+        112412 122114 122411 142112 142211 241211 221114 413111 241112 134111
+        111242 121142 121241 114212 124112 124211 411212 421112 421211 212141
+        214121 412121 111143 111341 131141 114113 114311 411113 411311 113141
+        114131 311141 411131 211412 211214 211232
+      ].freeze
+      STOP_PATTERN = "2331112"
+
+      CODE_C = 99
+      CODE_B = 100
+      CODE_A = 101
+      SHIFT  = 98
+      FNC1   = 102
+      FNC2   = 97
+      FNC3   = 96
+      FNC4_A = 101 # FNC4 shares values with CODE A/B depending on active subset
+      FNC4_B = 100
+      START_A = 103
+      START_B = 104
+      START_C = 105
+
+      Result = Struct.new(:values, :interpretation, keyword_init: true)
+
+      # data: raw ^FD string. mode: "N", "U", "A", "D". ucc_check: bool (^BC e param)
+      def self.encode(data, mode: "N", ucc_check: false)
+        new(data.to_s, mode: mode.to_s.upcase, ucc_check: ucc_check).encode
+      end
+
+      def initialize(data, mode:, ucc_check: false)
+        @data = data
+        @mode = mode
+        @ucc_check = ucc_check
+      end
+
+      def encode
+        tokens = tokenize(@data)
+        case @mode
+        when "U" then encode_ucc(tokens)
+        when "A" then encode_auto(tokens, gs1: false)
+        when "D" then encode_auto(strip_gs1_decorations(tokens), gs1: true)
+        else          encode_literal(tokens)
+        end
+      end
+
+      # Expand the symbol value list into a module-width string, e.g. "2122..."
+      # alternating bar/space widths, including check symbol and stop.
+      def self.modules(values)
+        sum = values.first
+        values.each_with_index { |v, i| sum += v * i unless i.zero? }
+        check = sum % 103
+        (values + [check]).map { |v| PATTERNS.fetch(v) }.join + STOP_PATTERN
+      end
+
+      private
+
+      # --- ZPL invocation-code tokenizer -------------------------------------
+      # Tokens: {char:}, {fnc: 1..4}, {code: :a/:b/:c}, {shift: true}, {start: :a/:b/:c}
+      INVOCATIONS = {
+        "<" => { char: "^" },  "0" => { char: ">" },  "=" => { char: "~" },
+        "1" => { char: "\x7f" }, # US in subset A / DEL in subset B; both value 95
+        "2" => { fnc: 3 }, "3" => { fnc: 2 }, "4" => { shift: true },
+        "5" => { code: :c }, "6" => { code: :b }, "7" => { code: :a },
+        "8" => { fnc: 1 },
+        "9" => { start: :a }, ":" => { start: :b }, ";" => { start: :c }
+      }.freeze
+
+      def tokenize(str)
+        tokens = []
+        i = 0
+        while i < str.length
+          ch = str[i]
+          if ch == ">" && (tok = INVOCATIONS[str[i + 1]])
+            tokens << tok.dup
+            i += 2
+          else
+            tokens << { char: ch }
+            i += 1
+          end
+        end
+        tokens
+      end
+
+      # --- mode N: literal ZPL subset semantics -------------------------------
+      def encode_literal(tokens)
+        start = tokens.first && tokens.first[:start]
+        subset = start || :b
+        tokens = tokens.drop(1) if start
+        values = [start_value(subset)]
+        interp = +""
+        shift_next = nil
+
+        i = 0
+        while i < tokens.length
+          tok = tokens[i]
+          if tok[:start]
+            subset = tok[:start]
+            values << code_value(subset)
+          elsif tok[:code]
+            values << subset_switch_value(subset, tok[:code])
+            subset = tok[:code]
+          elsif tok[:shift]
+            shift_next = subset == :a ? :b : :a
+            values << SHIFT
+          elsif tok[:fnc]
+            values << fnc_value(subset, tok[:fnc])
+          elsif tok[:char]
+            effective = shift_next || subset
+            shift_next = nil
+            case effective
+            when :b
+              val = tok[:char].ord - 32
+              if val.between?(0, 94) || tok[:char] == "\x7f"
+                values << (tok[:char] == "\x7f" ? 95 : val)
+                interp << tok[:char] unless tok[:char] == "\x7f"
+              end
+            when :a, :c
+              # ZPL: subsets A and C are programmed as pairs of digits 00-99
+              # which map directly to symbol values.
+              nxt = tokens[i + 1]
+              if digit?(tok[:char]) && nxt && nxt[:char] && digit?(nxt[:char])
+                value = tok[:char].to_i * 10 + nxt[:char].to_i
+                values << value
+                interp << (effective == :c ? format("%02d", value) : symbol_to_char(value, :a))
+                i += 1
+              end
+              # non-digit or unpaired digit: ignored, per the ZPL manual
+            end
+          end
+          i += 1
+        end
+        finalize(values, interp)
+      end
+
+      # --- mode A / D: automatic subset optimization ---------------------------
+      def encode_auto(tokens, gs1: false)
+        items = [] # {char:} with control/fnc entries preserved
+        interp = +""
+        tokens.each do |tok|
+          if tok[:char]
+            items << { char: tok[:char] }
+            interp << tok[:char] if tok[:char] >= " " && tok[:char] != "\x7f"
+          elsif tok[:fnc]
+            items << { fnc: tok[:fnc] }
+          end
+          # explicit subset/start controls are ignored: the encoder optimizes
+        end
+        values = optimize(items, gs1: gs1)
+        finalize(values, interp)
+      end
+
+      # UCC case mode: exactly 19 digits (padded/truncated), subset C,
+      # leading FNC1, mod-10 check digit appended.
+      def encode_ucc(tokens)
+        digits = tokens.filter_map { |t| t[:char] }.join.gsub(/\D/, "")
+        digits = digits[0, 19].rjust(19, "0")
+        full = digits + mod10_check(digits).to_s
+        values = [START_C, FNC1]
+        full.chars.each_slice(2) { |pair| values << pair.join.to_i }
+        finalize(values, full)
+      end
+
+      def strip_gs1_decorations(tokens)
+        out = []
+        tokens.each do |tok|
+          next if tok[:char] == "(" || tok[:char] == ")" || tok[:char] == " "
+
+          out << tok
+        end
+        # Mode D always starts with FNC1 (UCC/EAN-128)
+        out.unshift(fnc: 1) unless out.first && out.first[:fnc] == 1
+        out
+      end
+
+      # Greedy subset optimizer (Zebra mode A behavior: a run of 4+ digits,
+      # or an all-digit even-length tail, switches to subset C).
+      def optimize(items, gs1: false)
+        values = []
+        subset = nil
+        i = 0
+
+        while i < items.length
+          item = items[i]
+          if item[:fnc]
+            if subset.nil?
+              subset = digits_ahead(items, i + 1) >= 4 ? :c : :b
+              values << start_value(subset)
+            end
+            values << fnc_value(subset, item[:fnc])
+            i += 1
+            next
+          end
+
+          run = digit_run(items, i)
+          if run >= 4 || (run >= 2 && run == items.length - i && run.even? && i.zero?)
+            run -= 1 if run.odd?
+            if subset.nil?
+              values << START_C
+            elsif subset != :c
+              values << CODE_C
+            end
+            subset = :c
+            (run / 2).times do
+              values << (items[i][:char].to_i * 10 + items[i + 1][:char].to_i)
+              i += 2
+            end
+            next
+          end
+
+          ch = item[:char]
+          target = ch.ord < 32 ? :a : :b
+          if subset.nil?
+            subset = target
+            values << start_value(subset)
+          elsif subset == :c || subset != target
+            # single opposite-subset char inside a run: use SHIFT, else CODE
+            if subset != :c && single_exception?(items, i, subset)
+              values << SHIFT
+              values << char_value(ch, target)
+              i += 1
+              next
+            end
+            values << subset_switch_value(subset, target)
+            subset = target
+          end
+          values << char_value(ch, subset)
+          i += 1
+        end
+
+        values = [START_B] if values.empty?
+        values.unshift(START_B) unless values.first.between?(START_A, START_C)
+        values
+      end
+
+      def digit_run(items, i)
+        run = 0
+        run += 1 while (item = items[i + run]) && item[:char] && digit?(item[:char])
+        run
+      end
+
+      def digits_ahead(items, i)
+        digit_run(items, i)
+      end
+
+      # true when items[i] needs the other subset but items[i+1] fits the current
+      def single_exception?(items, i, subset)
+        nxt = items[i + 1]
+        return false unless nxt && nxt[:char]
+
+        nxt_target = nxt[:char].ord < 32 ? :a : :b
+        nxt_target == subset
+      end
+
+      def char_value(ch, subset)
+        if subset == :a
+          ch.ord < 32 ? ch.ord + 64 : ch.ord - 32
+        else
+          ch == "\x7f" ? 95 : ch.ord - 32
+        end
+      end
+
+      def digit?(ch)
+        ch >= "0" && ch <= "9"
+      end
+
+      def symbol_to_char(value, _subset)
+        value <= 63 ? (value + 32).chr : ""
+      end
+
+      def start_value(subset)
+        { a: START_A, b: START_B, c: START_C }.fetch(subset)
+      end
+
+      def code_value(subset)
+        { a: CODE_A, b: CODE_B, c: CODE_C }.fetch(subset)
+      end
+
+      def subset_switch_value(_from, to)
+        code_value(to)
+      end
+
+      def fnc_value(subset, n)
+        case n
+        when 1 then FNC1
+        when 2 then FNC2
+        when 3 then FNC3
+        when 4 then subset == :a ? FNC4_A : FNC4_B
+        end
+      end
+
+      def mod10_check(digits)
+        sum = 0
+        digits.reverse.each_char.with_index do |c, i|
+          sum += c.to_i * (i.even? ? 3 : 1)
+        end
+        (10 - (sum % 10)) % 10
+      end
+
+      def finalize(values, interp)
+        if @ucc_check && @mode != "U"
+          # ^BC e=Y appends a mod-10 check digit over the interpretation digits
+          digits = interp.gsub(/\D/, "")
+          unless digits.empty?
+            check = mod10_check(digits)
+            interp += check.to_s
+            values << check if values.last && values.last < 100 # only extend subset C data
+          end
+        end
+        Result.new(values: values, interpretation: interp)
+      end
+    end
+  end
+end

data/lib/zpl_render/barcode/code39.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ZplRender
+  module Barcode
+    # Code 39 encoder (ZPL ^B3). Each character is 9 elements (5 bars,
+    # 4 spaces), 3 of them wide. Start/stop character '*' is added
+    # automatically, elements are separated by a narrow inter-character gap.
+    class Code39
+      # n = narrow, w = wide; elements alternate bar/space starting with a bar
+      PATTERNS = {
+        "0" => "nnnwwnwnn", "1" => "wnnwnnnnw", "2" => "nnwwnnnnw",
+        "3" => "wnwwnnnnn", "4" => "nnnwwnnnw", "5" => "wnnwwnnnn",
+        "6" => "nnwwwnnnn", "7" => "nnnwnnwnw", "8" => "wnnwnnwnn",
+        "9" => "nnwwnnwnn", "A" => "wnnnnwnnw", "B" => "nnwnnwnnw",
+        "C" => "wnwnnwnnn", "D" => "nnnnwwnnw", "E" => "wnnnwwnnn",
+        "F" => "nnwnwwnnn", "G" => "nnnnnwwnw", "H" => "wnnnnwwnn",
+        "I" => "nnwnnwwnn", "J" => "nnnnwwwnn", "K" => "wnnnnnnww",
+        "L" => "nnwnnnnww", "M" => "wnwnnnnwn", "N" => "nnnnwnnww",
+        "O" => "wnnnwnnwn", "P" => "nnwnwnnwn", "Q" => "nnnnnnwww",
+        "R" => "wnnnnnwwn", "S" => "nnwnnnwwn", "T" => "nnnnwnwwn",
+        "U" => "wwnnnnnnw", "V" => "nwwnnnnnw", "W" => "wwwnnnnnn",
+        "X" => "nwnnwnnnw", "Y" => "wwnnwnnnn", "Z" => "nwwnwnnnn",
+        "-" => "nwnnnnwnw", "." => "wwnnnnwnn", " " => "nwwnnnwnn",
+        "$" => "nwnwnwnnn", "/" => "nwnwnnnwn", "+" => "nwnnnwnwn",
+        "%" => "nnnwnwnwn", "*" => "nwnnwnwnn"
+      }.freeze
+
+      CHECK_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-. $/+%"
+
+      Result = Struct.new(:elements, :interpretation, keyword_init: true)
+
+      # Returns elements as [[width_units, bar?], ...] where width_units is
+      # 1 (narrow) or the wide ratio, to be multiplied by the module width.
+      def self.encode(data, check_digit: false)
+        text = data.to_s.upcase.gsub(/[^0-9A-Z\-\. $\/+%]/, "")
+        payload = text.dup
+        if check_digit
+          sum = payload.chars.sum { |c| CHECK_CHARS.index(c) || 0 }
+          payload += CHECK_CHARS[sum % 43]
+        end
+        full = "*#{payload}*"
+        elements = []
+        full.each_char.with_index do |ch, idx|
+          PATTERNS.fetch(ch).each_char.with_index do |wide, i|
+            elements << [wide == "w" ? :wide : :narrow, i.even?]
+          end
+          elements << [:narrow, false] unless idx == full.length - 1 # inter-char gap
+        end
+        Result.new(elements: elements, interpretation: text)
+      end
+    end
+  end
+end