postsvg 0.2.6 → 0.3.0

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-`postsvg` is a pure-Ruby bidirectional converter between PostScript/EPS and SVG. Both directions are implemented in the 0.2.x line; the SVg→PS direction is newer. The PS side uses a hand-written lexer + stack-machine interpreter; the SVG side uses leptris. There is no Ghostscript, Inkscape, or other external renderer.
+`postsvg` is a pure-Ruby bidirectional converter between PostScript/EPS and SVG. Both directions are implemented in the 0.2.x line; the SVg→PS direction is newer. The PS side uses a hand-written lexer + stack-machine interpreter; the SVG side uses Nokogiri. There is no Ghostscript, Inkscape, or other external renderer.
 
 Code architecture mirrors `emfsvg`: a typed `Model::Program` value object is the single source of truth, with a Renderer / Visitor visiting it to emit SVG, and a Serializer walking it to emit PS.
 
@@ -27,30 +27,6 @@ bundle exec ruby exe/postsvg batch     INPUT_DIR         [OUTPUT_DIR]
 bundle exec ruby exe/postsvg version
 ```
 
-## Round-trip contract
-
-The `round_trip` tag selects the model comparison, SVG summary comparison,
-and byte-pinned emitted-PostScript golden checks:
-
-```bash
-bundle exec rspec --tag round_trip
-bundle exec rake round_trip:regenerate_goldens
-```
-
-These specs also run in the normal CI suite. The regeneration task rewrites
-the `.ps.golden` beside every SVG listed in
-`spec/fixtures/round_trip/manifest.yml`. Regenerate only for intentional output
-changes, inspect the diffs, and include them in a reviewed PR; never edit
-goldens by hand.
-
-Manifest `known_gap` and `non_goal` markers are **strict pending**, scoped to
-the `model` or `svg` leg. They do not skip comparisons: an unexpected pass
-fails the suite and requires reviewing/removing the marker. `known_gap`
-identifies a bug requiring follow-up; `non_goal` records intentional loss
-(currently gradient paint flattening). Unmarked legs must pass, and golden
-checks apply even to marked fixtures. See the README Round-trip section for
-the supported subset, comparison precision and parser-callable parity hook.
-
 ## Architecture
 
 ```
@@ -78,7 +54,7 @@ PS/EPS bytes ──▶│ Postsvg::Lexer       │
                 │                 │
                 ▼                 │
         SVG string               │
-                │ leptris        │
+                │ Nokogiri       │
                 ▼                 │
       ┌─────────────────┐         │
       │ Postsvg::       │         │
@@ -187,7 +163,7 @@ Errors: `Postsvg::ParseError`, `LexError`, `SyntaxError`, `RenderError`, `StackU
 
 ## Dependencies
 
-- `parslet`, `thor`, `leptris`, `lutaml/canon` (dev only, for XML matcher in integration specs) — see `Gemfile`.
+- `parslet`, `thor`, `nokogiri`, `lutaml/canon` (dev only, for XML matcher in integration specs) — see `Gemfile`.
 
 ## Limitations
 

data/Gemfile

@@ -4,8 +4,8 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "canon"
-gem "leptris", ">= 1.9.399.0"
+gem "canon", github: "lutaml/canon", branch: "main"
+gem "nokogiri"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -225,9 +225,8 @@ equivalent PS `arc` operator.
 
 === Round-trip
 
-The round-trip contract covers a pinned SVG corpus, with per-fixture
-expectations in link:spec/fixtures/round_trip/manifest.yml[manifest.yml].
-The conversion is a function composition:
+The same `Model::Program` value object sits behind both directions, so
+round-trip is a function composition:
 
 [source,ruby]
 ----
@@ -237,67 +236,10 @@ original_svg = File.read("input.svg")
 ps = Postsvg.to_ps(original_svg)
 round_tripped_svg = Postsvg.to_svg(ps)
 
+# round_tripped_svg preserves the geometry of original_svg for the
+# supported subset of SVG elements.
 ----
 
-The gate checks two legs independently:
-
-* *Normalized model diff*: `RoundTrip::Harness` compares the program built
-  from SVG with the program parsed from its serialized PostScript. The
-  normalizer compares operators and operand values, rounding floats to the
-  serializer's four decimal places.
-* *SVG summary diff*: `RoundTrip::SvgSummary` compares the original SVG with
-  the returned SVG as painted geometry in document coordinates. It checks
-  fill, stroke, stroke width, line caps and joins, transforms, and text
-  content, position, font family and size. Numbers are rounded to two decimal
-  places; equivalent shape/path spellings and the renderer's Y-flip wrapper
-  are normalized. This is not a byte-for-byte SVG or pixel-rendering test.
-
-Covered families are shapes (rectangles, polygons, polylines, line and curve
-paths), line strokes, arcs (circles, ellipses and path arcs), gray/RGB fills,
-combined fill and stroke, stroke styles, text, transforms (translation,
-rotation, matrices and nested groups), and gradients. Coverage does not mean
-every family preserves everything: the manifest records known SVG-leg gaps
-for polyline fill, path arcs and matrix shear. Text checks do not promise font
-metrics or glyph fidelity. Features outside the corpus are not guaranteed by
-this gate.
-
-The manifest is authoritative for exceptions on each leg. `known_gap` marks
-a bug; `non_goal` marks intentional loss. Linear and radial gradient `url()`
-paint is intentionally flattened to a plain fill (currently black), so gradient
-preservation is a non-goal even though the model leg passes. Both markers are
-strict pending: the comparison still runs, and an unexpected pass fails so
-the marker must be reviewed and removed when appropriate.
-
-The `round_trip` spec tag selects the contract and emitted-PostScript golden
-checks, which also run in the normal CI spec suite. Every manifest fixture has
-a byte-pinned `.ps.golden`; even marked fixtures must match their golden.
-For an intentional output change, regenerate with:
-
-[source,sh]
-----
-bundle exec rake round_trip:regenerate_goldens
-----
-
-Review the resulting diffs and submit them with the change in a reviewed PR.
-Do not edit goldens by hand or regenerate them merely to silence a regression.
-
-For `postscript#4` parser parity, the test-support hook
-`RoundTrip::Harness.call(svg, parser: candidate_parser)` accepts a callable
-that receives serialized PS source and returns a compatible program. It
-defaults to `Postscript::Source.parse` and returns an empty diff on a match,
-or indexed expected/actual normalized records on a mismatch. This lets a
-candidate parser reuse the same model contract without changing the public
-conversion API.
-
-The model contract also runs every manifest fixture with
-`Postscript::Source.parse(source, engine: :native)`, comparing normalized
-programs against both Ruby parsing and the emitted model. Run it with
-`bundle exec rspec spec/postsvg/round_trip_contract_spec.rb --tag native`.
-When the installed postscript lacks the native API or its optional parsanol
-native engine is unavailable, examples skip with an explicit reason. These
-skips do not establish native parity; see
-`spec/fixtures/round_trip/README.adoc` for prerequisites and marker behavior.
-
 == Command-line interface
 
 [[cli]]

data/Rakefile

@@ -3,29 +3,12 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
-require "yaml"
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
 
-namespace :round_trip do
-  desc "Regenerate pinned PostScript output for the round-trip corpus"
-  task :regenerate_goldens do
-    require "postsvg"
-
-    root = File.expand_path("spec/fixtures/round_trip", __dir__)
-    manifest = YAML.safe_load_file(File.join(root, "manifest.yml"))
-
-    manifest.fetch("fixtures").each do |entry|
-      svg_path = File.join(root, entry.fetch("file"))
-      golden_path = svg_path.sub(/\.svg\z/, ".ps.golden")
-      File.binwrite(golden_path, Postsvg.to_ps(File.read(svg_path)))
-    end
-  end
-end
-
 # Link checking tasks
 namespace :check do
   desc "Check internal documentation links only (recommended for CI)"

data/lib/postsvg/cli.rb

@@ -8,8 +8,7 @@ module Postsvg
   class CLI < Thor
     package_name "postsvg"
 
-    desc "convert INPUT [OUTPUT]",
-         "Convert PostScript/EPS file to SVG (legacy alias for to-svg)"
+    desc "convert INPUT [OUTPUT]", "Convert PostScript/EPS file to SVG (legacy alias for to-svg)"
     long_desc <<~DESC
       Convert a PostScript (.ps) or Encapsulated PostScript (.eps) file to SVG.
 
@@ -21,8 +20,7 @@ module Postsvg
         $ postsvg convert input.eps > output.svg
     DESC
     def convert(input_path, output_path = nil)
-      handle_input(input_path, output_path, method(:read_ps_to_svg),
-                   direction: "PS/EPS -> SVG")
+      handle_input(input_path, output_path, method(:read_ps_to_svg), direction: "PS/EPS -> SVG")
     end
 
     desc "to-svg INPUT [OUTPUT]", "Convert PostScript/EPS to SVG"
@@ -44,8 +42,7 @@ module Postsvg
         $ postsvg to-ps input.svg > output.ps
     DESC
     def to_ps(input_path, output_path = nil)
-      handle_input(input_path, output_path, method(:read_svg_to_ps),
-                   direction: "SVG -> PS")
+      handle_input(input_path, output_path, method(:read_svg_to_ps), direction: "SVG -> PS")
     end
 
     desc "to-eps INPUT [OUTPUT]", "Convert SVG to Encapsulated PostScript"
@@ -54,12 +51,10 @@ module Postsvg
       suitable for embedding.
     DESC
     def to_eps(input_path, output_path = nil)
-      handle_input(input_path, output_path, method(:read_svg_to_eps),
-                   direction: "SVG -> EPS")
+      handle_input(input_path, output_path, method(:read_svg_to_eps), direction: "SVG -> EPS")
     end
 
-    desc "batch INPUT_DIR [OUTPUT_DIR]",
-         "Convert all PS/EPS/SVG files in a directory"
+    desc "batch INPUT_DIR [OUTPUT_DIR]", "Convert all PS/EPS/SVG files in a directory"
     long_desc <<~DESC
       Auto-detects direction by file extension:
 

data/lib/postsvg/color.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # Immutable RGB color value object. Use the constructors (+.rgb+,
+  # +.gray+, +.cmyk+, +.parse+) instead of +new+ when constructing from
+  # other color models; they normalize to integer [0, 255] channels.
+  class Color
+    include Comparable
+
+    attr_reader :red, :green, :blue
+
+    def self.clamp_byte(value)
+      Integer === value ? value.clamp(0, 255) : value.to_i.clamp(0, 255)
+    end
+
+    def self.scale_unit_to_byte(value)
+      (value.clamp(0.0, 1.0) * 255.0).round
+    end
+
+    def initialize(red, green, blue)
+      @red = Color.clamp_byte(red)
+      @green = Color.clamp_byte(green)
+      @blue = Color.clamp_byte(blue)
+      freeze
+    end
+
+    # RGB triple in PS-native [0.0, 1.0] floats.
+    def self.rgb(r, g, b)
+      new(scale_unit_to_byte(r), scale_unit_to_byte(g), scale_unit_to_byte(b))
+    end
+
+    # Gray in [0.0, 1.0].
+    def self.gray(level)
+      v = scale_unit_to_byte(level)
+      new(v, v, v)
+    end
+
+    # CMYK in [0.0, 1.0]. Conversion matches PLRM §8.2.4 simplified
+    # formula; not colorimetrically exact.
+    def self.cmyk(c, m, y, k)
+      new(
+        scale_unit_to_byte((1 - c) * (1 - k)),
+        scale_unit_to_byte((1 - m) * (1 - k)),
+        scale_unit_to_byte((1 - y) * (1 - k)),
+      )
+    end
+
+    # Parse CSS / SVG color notations: #rgb, #rrggbb, rgb(r, g, b),
+    # rgb(r g b / a), named colors (X11 subset).
+    def self.parse(text)
+      return text if text.is_a?(Color)
+
+      case text.to_s.downcase
+      when /\A#([0-9a-f]{6})\z/
+        hex = ::Regexp.last_match(1)
+        new(hex[0, 2].to_i(16), hex[2, 2].to_i(16), hex[4, 2].to_i(16))
+      when /\A#([0-9a-f]{3})\z/
+        hex = ::Regexp.last_match(1)
+        new((hex[0] * 2).to_i(16), (hex[1] * 2).to_i(16), (hex[2] * 2).to_i(16))
+      when /\argb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/
+        new(::Regexp.last_match(1).to_i, ::Regexp.last_match(2).to_i, ::Regexp.last_match(3).to_i)
+      when /\argb\(\s*(\d+)\s+(\d+)\s+(\d+)/
+        new(::Regexp.last_match(1).to_i, ::Regexp.last_match(2).to_i, ::Regexp.last_match(3).to_i)
+      when "none", "transparent"
+        nil
+      else
+        rgb = NAMED_COLORS[text.to_s]
+        return new(*rgb) if rgb
+
+        raise ArgumentError, "unrecognized color: #{text.inspect}"
+      end
+    end
+
+    def gray?
+      red == green && green == blue
+    end
+
+    def gray_level
+      (red + green + blue) / 765.0
+    end
+
+    def to_rgb_unit
+      [red / 255.0, green / 255.0, blue / 255.0]
+    end
+
+    def to_svg
+      format("#%02x%02x%02x", red, green, blue)
+    end
+
+    def to_ps_rgb
+      to_rgb_unit.map { |c| FormatNumber.call(c) }.join(" ")
+    end
+
+    def to_ps_gray
+      raise ArgumentError, "color is not gray" unless gray?
+
+      FormatNumber.call(gray_level)
+    end
+
+    def <=>(other)
+      return nil unless other.is_a?(Color)
+
+      [red, green, blue] <=> [other.red, other.green, other.blue]
+    end
+
+    def hash
+      [red, green, blue].hash
+    end
+
+    def eql?(other)
+      other.is_a?(Color) && other.red == red && other.green == green && other.blue == blue
+    end
+    alias == eql?
+
+    NAMED_COLORS = {
+      "black" => [0, 0, 0], "white" => [255, 255, 255],
+      "red" => [255, 0, 0], "green" => [0, 128, 0], "blue" => [0, 0, 255],
+      "yellow" => [255, 255, 0], "cyan" => [0, 255, 255],
+      "magenta" => [255, 0, 255], "gray" => [128, 128, 128],
+      "grey" => [128, 128, 128], "silver" => [192, 192, 192],
+      "maroon" => [128, 0, 0], "olive" => [128, 128, 0],
+      "navy" => [0, 0, 128], "purple" => [128, 0, 128],
+      "teal" => [0, 128, 128], "lime" => [0, 255, 0],
+      "aqua" => [0, 255, 255], "fuchsia" => [255, 0, 255],
+      "orange" => [255, 165, 0], "pink" => [255, 192, 203],
+      "brown" => [165, 42, 42],
+    }.freeze
+
+    BLACK = Color.new(0, 0, 0).freeze
+    WHITE = Color.new(255, 255, 255).freeze
+  end
+end

data/lib/postsvg/format_number.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # Single source of truth for formatting numbers in both directions.
+  #
+  # - Integers print without a trailing ".0".
+  # - Floats print to 4 decimals, trailing zeros stripped.
+  # - -0 normalizes to 0 (so viewBoxes don't read "0 -0 100 100").
+  # - +Inf / -Inf / NaN raise ArgumentError; callers should validate.
+  module FormatNumber
+    module_function
+
+    def call(value)
+      raise ArgumentError, "non-finite number: #{value.inspect}" unless value.finite?
+
+      normalized = value.zero? ? 0.0 : value
+      return normalized.to_i.to_s if normalized == normalized.to_i
+
+      format("%.4f", normalized).sub(/\.?0+$/, "")
+    end
+  end
+end

data/lib/postsvg/graphics_context.rb

@@ -60,8 +60,7 @@ module Postsvg
         font_name: overrides.fetch(:font_name, @font_name),
         font_size: overrides.fetch(:font_size, @font_size),
         clip_paths: overrides.fetch(:clip_paths, @clip_paths),
-        last_text_position: overrides.fetch(:last_text_position,
-                                            @last_text_position),
+        last_text_position: overrides.fetch(:last_text_position, @last_text_position),
         fill_rule: overrides.fetch(:fill_rule, @fill_rule),
       )
     end

data/lib/postsvg/interpreter.rb

@@ -334,8 +334,9 @@ module Postsvg
     end
 
     def flush_path(mode)
-      # rubocop:disable-next Style/ZeroLengthPredicate
+      # rubocop:disable Style/ZeroLengthPredicate
       return if @path.length.zero?
+      # rubocop:enable Style/ZeroLengthPredicate
 
       d = @path.to_path
       path_str = emit_svg_path(d, @g_state, mode)

data/lib/postsvg/matrix.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # Matrix transformation class for PostScript coordinate transformations
+  # Implements affine transformation matrix [a b c d e f]
+  class Matrix
+    attr_accessor :a, :b, :c, :d, :e, :f
+
+    def initialize(a: 1, b: 0, c: 0, d: 1, e: 0, f: 0)
+      @a = a
+      @b = b
+      @c = c
+      @d = d
+      @e = e
+      @f = f
+    end
+
+    def multiply(matrix)
+      result = Matrix.new
+      result.a = (@a * matrix.a) + (@c * matrix.b)
+      result.b = (@b * matrix.a) + (@d * matrix.b)
+      result.c = (@a * matrix.c) + (@c * matrix.d)
+      result.d = (@b * matrix.c) + (@d * matrix.d)
+      result.e = (@a * matrix.e) + (@c * matrix.f) + @e
+      result.f = (@b * matrix.e) + (@d * matrix.f) + @f
+      result
+    end
+
+    def translate(tx, ty)
+      multiply(Matrix.new(e: tx, f: ty))
+    end
+
+    def scale(sx, sy)
+      multiply(Matrix.new(a: sx, d: sy))
+    end
+
+    def rotate(degrees)
+      radians = degrees * Math::PI / 180.0
+      m = Matrix.new
+      m.a = Math.cos(radians)
+      m.b = Math.sin(radians)
+      m.c = -Math.sin(radians)
+      m.d = Math.cos(radians)
+      multiply(m)
+    end
+
+    def skew_x(angle)
+      radians = angle * Math::PI / 180.0
+      multiply(Matrix.new(c: Math.tan(radians)))
+    end
+
+    def skew_y(angle)
+      radians = angle * Math::PI / 180.0
+      multiply(Matrix.new(b: Math.tan(radians)))
+    end
+
+    def to_transform_string
+      "matrix(#{@a} #{@b} #{@c} #{@d} #{@e} #{@f})"
+    end
+
+    def apply_point(x, y)
+      {
+        x: (x * @a) + (y * @c) + @e,
+        y: (x * @b) + (y * @d) + @f,
+      }
+    end
+
+    def decompose
+      scale_x = Math.hypot(@a, @b)
+      scale_y = ((@a * @d) - (@b * @c)) / scale_x
+
+      rotation = Math.atan2(@b, @a) * (180.0 / Math::PI)
+
+      skew_x = Math.atan2((@a * @c) + (@b * @d), scale_x * scale_x)
+      skew_y = Math.atan2((@a * @b) + (@c * @d), scale_y * scale_y)
+
+      {
+        translate: { x: @e, y: @f },
+        scale: { x: scale_x, y: scale_y },
+        rotate: rotation,
+        skew: {
+          x: skew_x * (180.0 / Math::PI),
+          y: skew_y * (180.0 / Math::PI),
+        },
+      }
+    end
+
+    def invert
+      det = (@a * @d) - (@b * @c)
+      return Matrix.new if det.abs < 1e-10
+
+      inv = Matrix.new
+      inv.a = @d / det
+      inv.b = -@b / det
+      inv.c = -@c / det
+      inv.d = @a / det
+      inv.e = ((@c * @f) - (@d * @e)) / det
+      inv.f = ((@b * @e) - (@a * @f)) / det
+      inv
+    end
+
+    def identity?
+      @a == 1 && @b.zero? && @c.zero? && @d == 1 && @e.zero? && @f.zero?
+    end
+  end
+end

data/lib/postsvg/model/literals/array.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Model
+    module Literals
+      # Bracketed array literal: +[1 2 3]+. Elements may be any
+      # literal or operator.
+      class ArrayLiteral
+        include Enumerable
+
+        attr_reader :elements
+
+        def initialize(elements = [])
+          @elements = elements.freeze
+          freeze
+        end
+
+        def each(&block)
+          @elements.each(&block)
+        end
+
+        def length = @elements.length
+        def empty? = @elements.empty?
+        def [](idx) = @elements[idx]
+
+        def accept(visitor, ctx)
+          visitor.visit_array(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(ArrayLiteral) && other.elements == @elements
+        end
+        alias eql? ==
+
+        def hash
+          @elements.hash
+        end
+      end
+    end
+  end
+end

data/lib/postsvg/model/literals/dictionary.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Model
+    module Literals
+      # Inline dictionary literal: +<< /Key (value) /Num 42 >>+.
+      class Dictionary
+        attr_reader :entries
+
+        def initialize(entries = {})
+          @entries = entries.dup.freeze
+          freeze
+        end
+
+        def [](key) = @entries[key]
+        def key?(key) = @entries.key?(key)
+        def each(&block) = @entries.each(&block)
+
+        def accept(visitor, ctx)
+          visitor.visit_dictionary(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(Dictionary) && other.entries == @entries
+        end
+        alias eql? ==
+
+        def hash
+          @entries.hash
+        end
+      end
+    end
+  end
+end

data/lib/postsvg/model/literals/hex.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Model
+    module Literals
+      # Hex-string literal: +<DEADBEEF>+.
+      class HexLiteral
+        attr_reader :value
+
+        def initialize(value)
+          @value = value.to_s
+          freeze
+        end
+
+        # Raw bytes encoded by the hex literal.
+        def bytes
+          hex = value.delete("^0-9a-fA-F")
+          hex << "0" if hex.length.odd?
+          hex.chars.each_slice(2).map { |pair| pair.join.to_i(16) }.pack("C*")
+        end
+
+        def accept(visitor, ctx)
+          visitor.visit_hex(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(HexLiteral) && other.value == value
+        end
+        alias eql? ==
+
+        def hash
+          value.hash
+        end
+      end
+    end
+  end
+end

data/lib/postsvg/model/literals/name.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Model
+    module Literals
+      # A PostScript name. +literal:+ distinguishes +/foo+ (literal,
+      # pushed onto the stack) from +foo+ (executable, looked up and
+      # executed).
+      class Name
+        attr_reader :value, :literal
+
+        def initialize(value, literal: false)
+          @value = value.to_s
+          @literal = literal
+          freeze
+        end
+
+        def literal? = literal
+        def executable? = !literal
+
+        def to_s
+          @value
+        end
+
+        def accept(visitor, ctx)
+          visitor.visit_name(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(Name) && other.value == value && other.literal == literal
+        end
+        alias eql? ==
+
+        def hash
+          [value, literal].hash
+        end
+      end
+    end
+  end
+end