zpl_renderer 0.1.2

data/lib/zpl_renderer/options.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  # Normalized render options with validation for DPI, dimensions, and format.
+  class Options
+    SUPPORTED_DPI = {
+      203 => 8,
+      300 => 12,
+      600 => 24
+    }.freeze
+
+    SUPPORTED_DPMM = SUPPORTED_DPI.invert.freeze
+    SUPPORTED_FORMATS = %i[png pdf].freeze
+
+    attr_reader :format, :width_in, :height_in, :dpi, :dpmm, :index,
+                :timeout, :max_output_bytes, :strict, :unit, :clip_to_print_width
+
+    def initialize(
+      format: :png,
+      width: 4,
+      height: 6,
+      dpi: 203,
+      dpmm: nil,
+      index: 0,
+      timeout: 30,
+      max_output_bytes: 50 * 1024 * 1024,
+      strict: true,
+      unit: :inches,
+      clip_to_print_width: false
+    )
+      @format = format.to_sym
+      @unit = unit.to_sym
+      @index = Integer(index)
+      @timeout = Float(timeout)
+      @max_output_bytes = Integer(max_output_bytes)
+      @strict = !!strict
+      @clip_to_print_width = !!clip_to_print_width
+
+      validate_format!
+      validate_timeout!
+      validate_index!
+
+      if dpmm
+        @dpmm = Integer(dpmm)
+        raise ConfigurationError, "unsupported dpmm=#{@dpmm}; use 8, 12, or 24" unless SUPPORTED_DPMM.key?(@dpmm)
+
+        @dpi = SUPPORTED_DPMM[@dpmm]
+      else
+        @dpi = Integer(dpi)
+        raise ConfigurationError, "unsupported dpi=#{@dpi}; use 203, 300, or 600" unless SUPPORTED_DPI.key?(@dpi)
+
+        @dpmm = SUPPORTED_DPI[@dpi]
+      end
+
+      @width_in, @height_in = normalize_dimensions(width, height)
+      validate_dimensions!
+    end
+
+    def width_mm
+      width_in * 25.4
+    end
+
+    def height_mm
+      height_in * 25.4
+    end
+
+    # Printer-dot canvas size used by the offline renderer (mm * dpmm, ceiled).
+    def pixel_width
+      (width_mm * dpmm).ceil
+    end
+
+    def pixel_height
+      (height_mm * dpmm).ceil
+    end
+
+    # Canvas width in dots used when widening narrow ^PW values, or nil when
+    # printer-style clipping is requested.
+    def sanitize_canvas_dots
+      clip_to_print_width ? nil : pixel_width
+    end
+
+    def content_type
+      format == :pdf ? "application/pdf" : "image/png"
+    end
+
+    def to_h
+      {
+        format: format,
+        width_in: width_in,
+        height_in: height_in,
+        width_mm: width_mm,
+        height_mm: height_mm,
+        dpi: dpi,
+        dpmm: dpmm,
+        index: index,
+        timeout: timeout,
+        max_output_bytes: max_output_bytes,
+        strict: strict,
+        unit: unit,
+        clip_to_print_width: clip_to_print_width
+      }
+    end
+
+    private
+
+    def normalize_dimensions(width, height)
+      w = Float(width)
+      h = Float(height)
+
+      case unit
+      when :inches, :in
+        [w, h]
+      when :millimeters, :mm
+        [w / 25.4, h / 25.4]
+      else
+        raise ConfigurationError, "unsupported unit=#{unit.inspect}; use :inches or :mm"
+      end
+    end
+
+    def validate_format!
+      return if SUPPORTED_FORMATS.include?(format)
+
+      raise ConfigurationError, "unsupported format=#{format.inspect}; use :png or :pdf"
+    end
+
+    def validate_timeout!
+      raise ConfigurationError, "timeout must be positive" unless timeout.positive?
+    end
+
+    def validate_index!
+      raise ConfigurationError, "index must be >= 0" if index.negative?
+    end
+
+    def validate_dimensions!
+      raise ConfigurationError, "width and height must be positive" if width_in <= 0 || height_in <= 0
+      raise ConfigurationError, "label dimensions exceed 24x24 inches" if width_in > 24 || height_in > 24
+    end
+  end
+end

data/lib/zpl_renderer/renderer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  # High-level ZPL rendering entry point used by the public module API.
+  class Renderer
+    def initialize(engine: Engine.new)
+      @engine = engine
+    end
+
+    def render(zpl, **kwargs)
+      options = Options.new(**kwargs)
+      sanitized = Sanitizer.sanitize(zpl, canvas_dots: options.sanitize_canvas_dots)
+      Validation.validate!(sanitized.zpl, options)
+      @engine.render(sanitized.zpl, options)
+    end
+
+    def render_file(zpl, path, **kwargs)
+      bytes = render(zpl, **kwargs)
+      File.binwrite(path, bytes)
+      path
+    end
+  end
+end

data/lib/zpl_renderer/sanitizer.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  # Normalizes carrier ZPL quirks before validation/render.
+  #
+  # Two repairs are applied:
+  #
+  # 1. Invalid field origins such as +^FO464,--^GB2,126,2^FS+ from carrier ZPL.
+  #    Invalid numeric params become 0 on printers; for a vertical rule we reuse
+  #    the last horizontal section-divider Y so the divider lands in the middle
+  #    band instead of y=0.
+  #
+  # 2. Print widths narrower than the requested canvas. The engine draws on a
+  #    +^PW+-wide canvas and centers it, so fields near the right edge (some
+  #    templates put rotated text at +^FO791+ under +^PW800+) are clipped. Widening +^PW+
+  #    to the canvas and shifting +^LH+ by the same centering offset keeps every
+  #    field in its original position while leaving nothing cut off.
+  class Sanitizer
+    Result = Struct.new(:zpl, :repairs, keyword_init: true)
+
+    COMMAND = /\^(FO|FT)([^,\^]*),([^,\^]*)/i
+    PRINT_WIDTH = /\^PW(\d+)/i
+    LABEL_HOME = /\^LH(\d+),(\d+)/i
+    INVERTED_ORIENTATION = /\^POI/i
+
+    def initialize(zpl, canvas_dots: nil)
+      @zpl = zpl.to_s
+      @canvas_dots = canvas_dots
+      @repairs = []
+    end
+
+    def call
+      zpl = repair_field_origins(@zpl)
+      zpl = expand_print_widths(zpl) if @canvas_dots
+      Result.new(zpl: zpl, repairs: @repairs)
+    end
+
+    def self.sanitize(zpl, canvas_dots: nil)
+      new(zpl, canvas_dots: canvas_dots).call
+    end
+
+    private
+
+    def repair_field_origins(source)
+      last_horizontal_y = nil
+      output = +""
+      index = 0
+
+      source.scan(COMMAND) do
+        match = Regexp.last_match
+        output << source[index...match.begin(0)]
+
+        cmd = match[1].upcase
+        raw_x = match[2]
+        raw_y = match[3]
+        x = parse_coord(raw_x)
+        y = parse_coord(raw_y)
+        repaired = false
+
+        if x.nil?
+          x = 0
+          repaired = true
+        end
+
+        trailing = source[match.end(0)..]
+
+        if y.nil?
+          y = vertical_rule?(trailing) && last_horizontal_y ? last_horizontal_y : 0
+          repaired = true
+        end
+
+        if repaired
+          @repairs << {
+            command: "^#{cmd}",
+            from: "^#{cmd}#{raw_x},#{raw_y}",
+            to: "^#{cmd}#{x},#{y}",
+            reason: "non-numeric field origin coordinates"
+          }
+        end
+
+        if (box = trailing.match(/\A\s*\^GB(\d+),(\d+),(\d+)/i))
+          last_horizontal_y = y if horizontal_rule?(box[1].to_i, box[2].to_i)
+        end
+
+        output << "^#{cmd}#{x},#{y}"
+        index = match.end(0)
+      end
+
+      output << source[index..]
+      output
+    end
+
+    def expand_print_widths(source)
+      source.split(/(?=\^XA)/i).map { |block| expand_block(block) }.join
+    end
+
+    def expand_block(block)
+      return block if block.match?(INVERTED_ORIENTATION)
+
+      match = block.match(PRINT_WIDTH)
+      return block unless match
+
+      print_width = match[1].to_i
+      return block unless print_width.positive? && print_width < @canvas_dots
+
+      offset = (@canvas_dots - print_width) / 2
+      expanded = block.sub(PRINT_WIDTH, "^PW#{@canvas_dots}")
+      expanded = shift_label_home(expanded, offset, match)
+
+      @repairs << {
+        command: "^PW",
+        from: "^PW#{print_width}",
+        to: "^PW#{@canvas_dots}",
+        reason: "print width narrower than #{@canvas_dots}-dot canvas would clip right-edge fields " \
+                "(label home shifted by #{offset} dots to preserve placement)"
+      }
+
+      expanded
+    end
+
+    def shift_label_home(block, offset, print_width_match)
+      return block if offset.zero?
+
+      if (home = block.match(LABEL_HOME))
+        block.sub(LABEL_HOME, "^LH#{home[1].to_i + offset},#{home[2].to_i}")
+      else
+        insert_at = print_width_match.begin(0) + "^PW#{@canvas_dots}".length
+        block.dup.insert(insert_at, "^LH#{offset},0")
+      end
+    end
+
+    def parse_coord(raw)
+      token = raw.to_s.strip
+      return nil if token.empty?
+      return nil if token.match?(/\A-+\z/)
+      return nil unless token.match?(/\A-?\d+(\.\d+)?\z/)
+
+      token.to_i.abs
+    end
+
+    def vertical_rule?(trailing)
+      box = trailing.match(/\A\s*\^GB(\d+),(\d+),(\d+)/i)
+      return false unless box
+
+      gw = box[1].to_i
+      gh = box[2].to_i
+      # Thin tall boxes are vertical dividers (e.g. ^GB2,126,2).
+      gh >= 20 && gh >= gw * 4
+    end
+
+    def horizontal_rule?(width, height)
+      # Full-width section rules (e.g. ^GB755,2,2 / ^GB777,2,2), not H-box edges.
+      height <= 4 && width >= 200
+    end
+  end
+end

data/lib/zpl_renderer/validation.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  # Static ZPL compatibility checks before rendering.
+  #
+  # Reports unsupported commands, missing label boundaries, and barcode
+  # scanability risks without mutating the source ZPL.
+  class Validation
+    Result = Struct.new(:ok?, :errors, :warnings, keyword_init: true) do
+      def raise_if_strict!(strict:)
+        return self if ok? || !strict
+        return self if errors.empty?
+
+        raise ValidationError, errors.join("; ")
+      end
+    end
+
+    SUPPORTED_COMMANDS = %w[
+      XA XZ FO FT FD FS A CF FB FR FH FN FW FV
+      BC BE B2 B3 B7 BO BX BQ BD BY
+      GB GC GD GF GS IL XG
+      PW PO LH LR CI MU DF XF
+      PR PQ JM MD MN MT PM LL
+    ].freeze
+
+    UNSUPPORTED_COMMANDS = %w[
+      RF IS ID JB KD KL KM KP
+      WC WD WQ WR WS WT WV WW
+      SN SF
+    ].freeze
+
+    BARCODE_COMMANDS = %w[BC BE B2 B3 B7 BO BX BQ BD].freeze
+
+    KNOWN_COMMANDS = (
+      SUPPORTED_COMMANDS + UNSUPPORTED_COMMANDS +
+      %w[DG] # ~DG download graphic
+    ).uniq.sort_by { |c| -c.length }.freeze
+
+    # Minimum module width in dots for reliable scanning at each DPI.
+    MIN_MODULE_WIDTH = {
+      203 => 2,
+      300 => 3,
+      600 => 4
+    }.freeze
+
+    def initialize(zpl, options)
+      @zpl = zpl.to_s
+      @options = options
+      @errors = []
+      @warnings = []
+    end
+
+    def call
+      check_not_empty!
+      check_label_bounds!
+      check_malformed_origins!
+      check_commands!
+      check_barcode_module_width!
+      check_qr_params!
+      check_code128_data!
+
+      Result.new(ok?: @errors.empty?, errors: @errors.dup, warnings: @warnings.dup)
+    end
+
+    def self.validate!(zpl, options)
+      new(zpl, options).call.raise_if_strict!(strict: options.strict)
+    end
+
+    private
+
+    def check_not_empty!
+      return unless @zpl.strip.empty?
+
+      @errors << "ZPL input is empty"
+    end
+
+    def check_label_bounds!
+      return if @zpl.strip.empty?
+
+      has_xa = @zpl.match?(/\^XA/i)
+      has_xz = @zpl.match?(/\^XZ/i)
+
+      @errors << "missing ^XA label start" unless has_xa
+      @errors << "missing ^XZ label end" unless has_xz
+    end
+
+    def check_malformed_origins!
+      @zpl.scan(/\^(FO|FT)([^,\^]*),([^,\^]*)/i) do |cmd, x, y|
+        bad_x = !numeric_coord?(x)
+        bad_y = !numeric_coord?(y)
+        next unless bad_x || bad_y
+
+        @warnings << "malformed ^#{cmd.upcase} coordinates (#{x},#{y}); sanitizer should rewrite before render"
+      end
+    end
+
+    def numeric_coord?(raw)
+      token = raw.to_s.strip
+      return false if token.empty?
+      return false if token.match?(/\A-+\z/)
+
+      token.match?(/\A-?\d+(\.\d+)?\z/)
+    end
+
+    def check_commands!
+      extract_commands.each do |cmd|
+        next if SUPPORTED_COMMANDS.include?(cmd)
+        next if cmd.match?(/\AA\z/)
+
+        if UNSUPPORTED_COMMANDS.include?(cmd)
+          message = "unsupported command ^#{cmd} (outside first-release compatibility matrix)"
+          if @options.strict
+            @errors << message
+          else
+            @warnings << message
+          end
+        else
+          @warnings << "command ^#{cmd} is not in the documented support matrix; rendering may be incomplete"
+        end
+      end
+    end
+
+    def extract_commands
+      commands = []
+      @zpl.scan(/[\^~]([A-Za-z0-9]+)/) do |match|
+        token = match[0].upcase
+        known = KNOWN_COMMANDS.find { |cmd| token.start_with?(cmd) }
+        commands << (known || token[0, 3])
+      end
+      commands.uniq
+    end
+
+    def check_barcode_module_width!
+      return unless barcode_commands_present?
+
+      min = MIN_MODULE_WIDTH.fetch(@options.dpi, 2)
+      defaults = @zpl.scan(/\^BY(\d+)/i).flatten.map(&:to_i)
+      narrow = defaults.min
+
+      if narrow && narrow.positive? && narrow < min
+        @warnings << "barcode module width ^BY#{narrow} may be hard to scan at #{@options.dpi} DPI " \
+                     "(recommended >= #{min} dots)"
+      end
+
+      return if defaults.any?
+
+      @warnings << "no ^BY module width set; default module width may be too narrow for scanners"
+    end
+
+    def check_qr_params!
+      @zpl.scan(/\^BQ[^\^]*/i).each do |match|
+        parts = match.sub(/\^BQ/i, "").split(",")
+        magnification = (parts[2] || "").to_s.strip
+        mag = magnification.empty? ? default_qr_magnification : magnification.to_i
+
+        if mag < 2
+          @warnings << "QR magnification #{mag} may produce unscannable modules at #{@options.dpi} DPI"
+        end
+      end
+    end
+
+    def check_code128_data!
+      fields = @zpl.split(/\^FS/i)
+      fields.each do |field|
+        next unless field.match?(/\^B(?:C|E|2|3|7|O|X|Q|D)/i)
+        next if field.match?(/\^FD.+/i)
+
+        @errors << "barcode field is missing ^FD data"
+      end
+    end
+
+    def barcode_commands_present?
+      BARCODE_COMMANDS.any? { |cmd| @zpl.match?(/\^#{cmd}/i) }
+    end
+
+    def default_qr_magnification
+      case @options.dpi
+      when 203 then 2
+      when 300 then 3
+      when 600 then 6
+      else 2
+      end
+    end
+  end
+end

data/lib/zpl_renderer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  VERSION = "0.1.2"
+end

data/lib/zpl_renderer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "zpl_renderer/version"
+require_relative "zpl_renderer/errors"
+require_relative "zpl_renderer/options"
+require_relative "zpl_renderer/binary"
+require_relative "zpl_renderer/validation"
+require_relative "zpl_renderer/sanitizer"
+require_relative "zpl_renderer/engine"
+require_relative "zpl_renderer/decoder"
+require_relative "zpl_renderer/renderer"
+
+# Offline ZPL to PNG/PDF converter for Ruby and Rails applications.
+#
+#   png = ZplRenderer.render(zpl, format: :png, width: 4, height: 6, dpi: 203)
+#   ZplRenderer.render_file(zpl, "label.pdf", format: :pdf, dpi: 300)
+#
+module ZplRenderer
+  class << self
+    # Render ZPL to binary PNG or PDF bytes.
+    #
+    # @param zpl [String] raw ZPL label data
+    # @param format [Symbol] :png or :pdf
+    # @param width [Numeric] label width (inches by default)
+    # @param height [Numeric] label height (inches by default)
+    # @param dpi [Integer] 203, 300, or 600
+    # @param dpmm [Integer, nil] 8, 12, or 24 (overrides dpi when set)
+    # @param index [Integer] label index when multiple ^XA...^XZ blocks exist
+    # @param timeout [Numeric] render timeout in seconds
+    # @param max_output_bytes [Integer] hard cap on output size
+    # @param strict [Boolean] raise on unsupported commands
+    # @param unit [Symbol] :inches or :mm
+    # @param clip_to_print_width [Boolean] retain clipping from a narrow ^PW
+    # @return [String] binary PNG or PDF data
+    def render(zpl, **kwargs)
+      default_renderer.render(zpl, **kwargs)
+    end
+
+    # Render ZPL and write the result to +path+.
+    #
+    # @return [String] the output path
+    def render_file(zpl, path, **kwargs)
+      default_renderer.render_file(zpl, path, **kwargs)
+    end
+
+    # Validate ZPL without rendering.
+    #
+    # @return [ZplRenderer::Validation::Result]
+    def validate(zpl, **kwargs)
+      options = Options.new(**kwargs)
+      sanitized = Sanitizer.sanitize(zpl, canvas_dots: options.sanitize_canvas_dots)
+      result = Validation.new(sanitized.zpl, options).call
+      sanitized.repairs.each do |repair|
+        result.warnings << "sanitized #{repair[:from]} -> #{repair[:to]} (#{repair[:reason]})"
+      end
+      result
+    end
+
+    # Sanitize carrier ZPL quirks (e.g. ^FO464,-- and narrow ^PW).
+    #
+    # @param canvas_dots [Integer, nil] widen ^PW up to this canvas width
+    # @return [ZplRenderer::Sanitizer::Result]
+    def sanitize(zpl, canvas_dots: nil)
+      Sanitizer.sanitize(zpl, canvas_dots: canvas_dots)
+    end
+
+    # Content-Type helper for Rails send_data responses.
+    def content_type(format)
+      Options.new(format: format).content_type
+    end
+
+    # Decode barcodes/QR codes from a rendered PNG using an independent ZXing engine.
+    #
+    # @return [Array<ZplRenderer::Decoder::Hit>]
+    def decode_png(png_bytes)
+      Decoder.new.decode_png(png_bytes)
+    end
+
+    private
+
+    def default_renderer
+      @default_renderer ||= Renderer.new
+    end
+  end
+end