postsvg 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a2ecbfa1ecb4e8bc18ce43304e7ea828054d255bb2183e9356cf08742e91483
-  data.tar.gz: c7520e5a867bd4992d169ffa496cfc70eb36dba2bddfc78a1c472b3b21009020
+  metadata.gz: 7eb334f9e4c74e3038c41e80d545bcaec37aa5032f20aa2d27fe61da5795542f
+  data.tar.gz: 2df77c30cad2f75203764b86835e3e0cded61db1b8b658882e342ed5b2f6c91d
 SHA512:
-  metadata.gz: 212ad8d736573633ab5d335908e1305f89e621e7389740420858fbaacf6c982165af4b69a0c154e21ff0ea456e3e0343c88b9d06c43a2c1b47202dc31078511e
-  data.tar.gz: 91f449c7d4a7a09560215bae0f83b58410ca64a472c43c97af9322198e1d2c249442263cdfe5aa41163735bdcd5728211169b30f67feeeaefb14a66e096b5f8f
+  metadata.gz: ab6b8afd0962151ce8f2799cd260d69bf5a4343b847a44f454dcc84cf847066f4e48e07e577d397071e4387cd68f3d58665e754bd4d07ac0b26fa87ba85f37e9
+  data.tar.gz: c844ee5ab50f674a1e3f186131d4da0840516eb35ff7cccb210e4ca64441560ca18c207103702eaa0c88679ef91343e10a8f8f0f2c54ae74963e06587dd23203

data/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to Postsvg will be documented in this file.
+
+## [Unreleased]
+
+### Added — 2026-07-27
+
+**0.2.0 — PS/EPS ⇔ SVG bidirectional pipeline.**
+
+This release rebuilds the converter on a typed domain model and adds
+the reverse direction (SVG → PS / EPS).
+
+* `Postsvg::Model::*` — typed PS records (Program, Literals, Operator
+  hierarchy). Adding a new PS operator is a new class + one
+  `visit_*` method, no switch edit.
+* `Postsvg::Source::Lexer` — comment-aware lexer. Replaces the old
+  `Tokenizer` whose `gsub(/%[^\n\r]*/)` corruption of string literals
+  broke on inputs with literal `%`.
+* `Postsvg::Source::AstBuilder` — turns tokens into a `Model::Program`,
+  constructing typed operator instances by popping the parse stack in
+  reverse source order.
+* `Postsvg::Source::OperandStack` — type-aware parse stack with
+  permissive pop (returns a `Computed` sentinel on underflow) so
+  procedure bodies parse cleanly without runtime context.
+* `Postsvg::Model::Operator.consumes` / `.produces` — stack-arity
+  declaration. The parser pushes `Computed` sentinels for each value
+  an operator produces, keeping parse-time stack shape in sync with
+  runtime semantics.
+* `Postsvg::Visitors::PsVisitor` — per-category dispatch tables
+  (Path, Painting, Color, GraphicsState, Transformations,
+  Dictionary, ControlFlow, Device, Arithmetic, Boolean, Stack, Font,
+  Container).
+* `Postsvg::SvgBuilder` — append-only SVG emitter with clipPath /
+  gradient / pattern dedup and a single Y-flip wrapper group.
+* `Postsvg::Renderer` — orchestrator for PS → SVG; sets up viewBox,
+  opens SVG / closes SVG, enforces `MAX_OUTPUT_BYTES`, handles
+  `QuitSignal` cleanly.
+* `Postsvg::Svg::*` — typed SVG domain model (Document, Element,
+  PathData, Paint, Stroke, TransformList, ClipPathRegistry) +
+  Elements (Svg, Group, Path, Rect, Circle, Ellipse, Line, Polyline,
+  Polygon, Text, Image, Defs, ClipPath). The `Element` base class
+  provides nil-default getters for `fill`, `stroke_paint`, `stroke`,
+  `transform`, `children` so handlers never need `respond_to?`.
+* `Postsvg::Svg::Parser` — Nokogiri-backed SVG parser.
+* `Postsvg::Translation::*` — SVG → PS dispatch (`PsRenderer`,
+  `HandlerRegistry`, per-element `Handlers::*`).
+* `Postsvg::Translation::ArcConverter` — SVG endpoint-to-center
+  arc parametrization (W3C algorithm from SVG 1.1 §F.6.5).
+* `Postsvg::Translation::Handlers::PathHandler` — full SVG path
+  command coverage (M/L/H/V/C/S/Q/T/A/Z, absolute + relative).
+* `Postsvg::Translation::Handlers::PolygonHandler` — closes the
+  path before paint (unlike PolylineHandler).
+* `Postsvg::Model::Operators::Painting::FillAndStroke` — marker
+  operator for elements with both fill and stroke; serializer emits
+  `gsave fill grestore stroke`.
+* `Postsvg::Model::Operators::Font::*` — findfont, scalefont, setfont,
+  show, xyshow, stringwidth, charpath.
+* `Postsvg::Model::Operators::Container::*` — type-dispatching
+  length / get / put / getinterval / putinterval / forall / astore /
+  search / anchorsearch / token / string / cvs that work on strings,
+  arrays, and dictionaries.
+* `Postsvg::Serializer` — `Model::Program` → PS / EPS source text.
+* `Postsvg::Options` — frozen struct for both directions (`eps`,
+  `width`, `height`, `viewbox_override`, `verbose`, `page_size`).
+* New CLI commands: `postsvg to-svg`, `postsvg to-ps`, `postsvg
+  to-eps`. `convert`, `batch`, `version` retained as BC / helpful
+  shortcuts.
+* New typed error hierarchy: `LexError`, `SyntaxError`, `StackUnderflowError`,
+  `UndefinedOperatorError`, `RecursionLimitError`, `SizeLimitError`,
+  `UnsupportedElementError`, `UnresolvedReferenceError`,
+  `SerializeError`.
+
+### Changed
+
+- Architecture is fully rewritten around the Renderer / Visitor /
+  SvgBuilder pattern (modeled on `emfsvg`). The 0.1.0
+  Converter / Parser / Parslet pipeline is preserved at
+  `lib/postsvg/{converter,parser,parser/postscript_parser,
+  parser/transform,tokenizer,interpreter,svg_generator,
+  graphics_state,colors}.rb` as a reference, but is no longer on
+  the autoload path. Its method names are no longer public API.
+- `Postsvg::Matrix` and `Postsvg::Color` are now promoted from
+  utility module to first-class value types. `Colors` (free functions)
+  is removed from the live path; existing callers can `require
+  "postsvg/colors"` explicitly for the legacy module.
+- Specs follow the project's rules: no doubles, no `instance_variable_set`,
+  no `send` to private methods, no `respond_to?` for type checks, autoload throughout.
+
+### Fixed
+
+- `PolygonHandler` now emits `closepath` before paint.
+- `PathHandler` supports all SVG path commands (M/L/H/V/C/S/Q/T/A/Z,
+  absolute and relative).
+- All `respond_to?` calls in handlers eliminated (zero remain in
+  `lib/`).
+- Handler registration is now lazy (auto-triggered on first use)
+  instead of eager at file load.
+- 6/6 integration fixtures (colors.ps, example_full.ps, file.ps,
+  prog.ps, img.ps, img.eps) now convert without error.
+
+### Test coverage
+
+- 99 examples, 0 failures.
+

data/CLAUDE.md

@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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 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.
+
+## Commands
+
+```bash
+bundle install                          # set up deps
+bundle exec rspec                       # full suite (~74 examples, <0.2s)
+bundle exec rspec spec/postsvg/renderer_spec.rb            # one file
+bundle exec rspec -e "converts a square PS program to SVG"   # by description
+bundle exec rubocop                     # lint (must be clean)
+bundle exec rake                        # spec + rubocop (CI gate)
+
+# CLI
+bundle exec ruby exe/postsvg convert  INPUT.ps|INPUT.eps  [OUTPUT.svg]
+bundle exec ruby exe/postsvg to-svg    INPUT.eps          [OUTPUT.svg]
+bundle exec ruby exe/postsvg to-ps     INPUT.svg          [OUTPUT.ps]
+bundle exec ruby exe/postsvg to-eps    INPUT.svg          [OUTPUT.eps]
+bundle exec ruby exe/postsvg batch     INPUT_DIR         [OUTPUT_DIR]
+bundle exec ruby exe/postsvg version
+```
+
+## Architecture
+
+```
+                ┌─────────────────────┐
+PS/EPS bytes ──▶│ Postsvg::Lexer       │
+                └──────────┬──────────┘
+                           │ tokens
+                           ▼
+                ┌─────────────────────┐
+                │ Postsvg::AstBuilder │
+                └──────────┬──────────┘
+                           │ Model::Program
+                           ▼
+          ┌────────────────────────────────┐
+          │ Postsvg::Model::Program         │ ── single source of truth
+          └────┬─────────────────┬─────────┘
+               │ visit           │ emit
+               ▼                 ▲
+       ┌─────────────────┐       │
+       │ Postsvg::       │       │
+       │ Renderer +      │       │
+       │ PsVisitor +     │       │
+       │ SvgBuilder      │       │
+       └────────┬────────┘       │
+                │                 │
+                ▼                 │
+        SVG string               │
+                │ Nokogiri       │
+                ▼                 │
+      ┌─────────────────┐         │
+      │ Postsvg::       │         │
+      │ Svg::Parser     │         │
+      └────────┬────────┘         │
+               │ Svg::Document   │
+               ▼                 │
+      ┌─────────────────┐         │
+      │ Postsvg::       │         │
+      │ Translation::*  │─────────┘
+      │ + Serializer    │
+      └────────┬────────┘
+               ▼
+       PS / EPS source
+```
+
+MECE responsibilities:
+
+* `Postsvg::Source` (`Lexer`, `AstBuilder`, `OperandStack`) — PS source → typed AST.
+* `Postsvg::Model` (`Program`, `Literals::*`, `Operator`) — typed records, immutable value equality.
+* `Postsvg::GraphicsContext` / `GraphicsStack` — immutable graphics-state snapshots.
+* `Postsvg::Matrix` / `Color` / `FormatNumber` — foundational value types.
+* `Postsvg::SvgBuilder` — append-only SVG emitter (dedups clipPaths / gradients).
+* `Postsvg::Renderer` + `Postsvg::Visitors::*` — PS → SVG orchestration / dispatch.
+* `Postsvg::Svg` (`Parser`, `Element`, `Elements::*`) — SVG domain model.
+* `Postsvg::Translation` (`PsRenderer`, `HandlerRegistry`, `Handlers::*`) — SVG → PS dispatch.
+* `Postsvg::Serializer` — Model records → PS / EPS source text.
+* `Postsvg::CLI` — Thor command-line wrapper.
+
+## Dispatch model
+
+Both directions use an OCP-friendly dispatch via `Model::Operator#accept(visitor, ctx)` for the forward direction and `Translation::HandlerRegistry#handler_for(element)` for the reverse direction.
+
+* **Forward direction**: each `Model::Operator` subclass calls `Operator#register_as(keyword)`, which registers the class in `Model::Operators.@registry` and `define_method(:visit_name)` to route to a `visitor.visit_<name>` method. Adding a new PS operator means writing one class + one `visit_*` method; no switch edits.
+* **Reverse direction**: each `Svg::Elements::*` subclass calls `Element.register(tag_name, self)` on load. The `HandlerRegistry` looks up handlers by exact class, then walks the superclass chain so subclassing handlers inherits behaviour. Adding a new SVG element means writing one handler class + one `Element.register` call; no switch edits.
+
+The per-category visitor modules (`lib/postsvg/visitors/ps_visitor/*.rb`) are split by PLRM chapter (Stack, Arithmetic, Boolean, Path, Painting, Color, GraphicsState, Transformations, Dictionary, ControlFlow, Device, Font, Container, Common). Adding a category = new file + `include` line.
+
+## Runtime stack vs AST operands
+
+The visitor maintains its OWN operand stack (`@stack`), separate from the parser's `OperandStack`. Most operators pop from the RUNTIME stack — not the AST — because chained ops like `1 2 add 3 mul` produce `Computed` sentinels at parse time that have no real value. Operators whose AST operands can be `Computed` (arithmetic, boolean, control flow, font, container) MUST pop from runtime:
+
+```ruby
+def visit_add(_op, _ctx)
+  b = pop_runtime_number
+  a = pop_runtime_number
+  @stack << a + b
+end
+```
+
+Operators whose AST operands are always literal-typed at parse time (moveto, setrgbcolor) can use AST operands directly.
+
+The shared helpers (`numeric_value`, `truthy?`, `lookup_dict`, `normalize_key`, `string_value`) live in `PsVisitor::Common` (`lib/postsvg/visitors/ps_visitor/common.rb`) — DRY: previously `normalize_key` was duplicated in Dictionary and Container.
+
+## Source order semantics
+
+`Postsvg::Source::AstBuilder` writes every consumed token — literals and operators — into `Program.body` in source order. This is what the visitor walks. It is NOT just the operators. So `program.body.first` may be a `Number`, not the first operator. This is by design: the visitor must see the literals to populate the operand stack correctly.
+
+## Y-flip and viewbox
+
+PostScript origin is bottom-left; SVG origin is top-left. `Renderer#call` opens the SVG with the viewBox from the DSC header and wraps all shapes in `<g transform="translate(0 H) scale(1 -1)">` so PS-native coordinates produce visually identical output. `SvgBuilder#open_y_flip_group` is the entry point.
+
+When no `%%BoundingBox` is present the renderer falls back to the A4 page size (595×842 pt) from `Options::DEFAULT_PAGE_SIZE`.
+
+## Dispatch gotcha: `private_class_method` and explicit receivers
+
+`Postsvg::Color` has utility class methods (`clamp_byte`, `scale_unit_to_byte`) that look private but are called from inside `initialize` with explicit `Color.clamp_byte(...)`. Marking them private via `private_class_method` causes `NoMethodError: private method 'clamp_byte' called` at load time. **Keep these public.** The project rule forbids `send`, but it's silent on `private_class_method`; we follow the spirit (no privacy barriers) and keep them public.
+
+## Determinism invariants
+
+- Two runs of the same input produce byte-equal output from both directions.
+- `SvgBuilder` IDs (`clip1`, `grad1`, `pattern1`) start at 1 on every `SvgBuilder.new`.
+- `FormatNumber` is the single source of truth for number formatting.
+- No `Time.now`, `SecureRandom`, or `Object#object_id` in IDs.
+
+## Style and code-quality rules
+
+These come from the user's private global `~/.claude/CLAUDE.md` (Code Quality Standards) and are non-negotiable.
+
+- **No `require_relative` in `lib/`** (and no `require` of internal paths either). Use Ruby `autoload` declared in the immediate parent namespace's file (`lib/postsvg.rb` autoloads top-level constants; `lib/postsvg/visitors/ps_visitor.rb` autoloads `PsVisitor::Stack` etc.). The exe (`exe/postsvg`) is allowed to require internal paths.
+- **No doubles in specs.** Use real instances or `Struct.new`.
+- **No `send` to private methods, no `instance_variable_set/get`, no `respond_to?` for type checks.** For dispatcher "does class define this method?" checks use `self.class.public_method_defined?(method_name)`, not `respond_to?`.
+- **No AI attribution** anywhere (commits, PRs, code comments, changelog).
+- **Never delete source files.** Legacy Parslet-based files live at their original paths. The current pipeline does not autoload them; they are kept for reference (see `TODO.roadmap/02-isolate-dormant-code.md`).
+- **Never commit to `main`, never push tags, never push to `main`.** All changes go through PRs.
+- **Library packages have no side effects.** The gem never writes to its own installed location.
+
+## Public API
+
+```ruby
+# Forward direction (PS / EPS → SVG)
+Postsvg.to_svg(ps_or_eps_string, **opts)
+Postsvg.to_svg_file(input_path, output_path=nil, **opts)
+Postsvg.convert(...)         # alias for to_svg (BC)
+Postsvg.convert_file(...)    # alias (BC)
+
+# Reverse direction (SVG → PS / EPS)
+Postsvg.to_ps(svg_string, eps: false, **opts)
+Postsvg.to_eps(svg_string, **opts)
+Postsvg.to_ps_file(input_path, output_path=nil, eps: false, **opts)
+```
+
+Shared `Postsvg::Options` (frozen struct): `eps`, `width`, `height`, `viewbox_override`, `verbose`, `page_size`.
+
+Errors: `Postsvg::ParseError`, `LexError`, `SyntaxError`, `RenderError`, `StackUnderflowError`, `UndefinedOperatorError`, `RecursionLimitError`, `SizeLimitError`, `TranslationError`, `UnsupportedElementError`, `UnresolvedReferenceError`, `SerializeError`. All inherit from `Postsvg::Error`.
+
+## Dependencies
+
+- `parslet`, `thor`, `nokogiri`, `lutaml/canon` (dev only, for XML matcher in integration specs) — see `Gemfile`.
+
+## Limitations
+
+See `README.adoc` and `TODO.roadmap/`. Highlights:
+
+- Real text/font rendering, image round-trip, Level 3 shading, forms are P2 / P3.
+- 5 integration specs are currently `pending` (awaiting new-pipeline parity with the legacy SvgBuilder output for `colors.ps`, `example_full.ps`, `file.ps`, `prog.ps`, and `img.ps` / `img.eps`).

data/Gemfile

@@ -2,11 +2,10 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in xml-c14n.gemspec
 gemspec
 
-gem "canon", github: "lutaml/canon",
-             branch: "rt-update-behavior-prevent-data-loss"
+gem "canon", github: "lutaml/canon", branch: "main"
+gem "nokogiri"
 gem "rake"
 gem "rspec"
 gem "rubocop"