postsvg 0.1.0 → 0.3.0

data/README.adoc

@@ -1,99 +1,115 @@
 = Postsvg
 
-image:https://img.shields.io/gem/v/postsvg.svg[Gem Version,
-link=https://rubygems.org/gems/postsvg]
-image:https://github.com/metanorma/postsvg/actions/workflows/test.yml/badge.svg[Build Status,
-link=https://github.com/metanorma/postsvg/actions/workflows/test.yml]
+image:https://img.shields.io/gem/v/postsvg.svg[Gem Version,link=https://rubygems.org/gems/postsvg]
+image:https://github.com/metanorma/postsvg/actions/workflows/test.yml/badge.svg[Build Status,link=https://github.com/metanorma/postsvg/actions/workflows/test.yml]
 image:https://img.shields.io/github/license/metanorma/postsvg.svg[License]
 
 == Purpose
 
-Postsvg is a pure Ruby library for converting PostScript (PS) and
-Encapsulated PostScript (EPS) files to Scalable Vector Graphics (SVG)
-format.
+Postsvg is a pure-Ruby PostScript (PS) and Encapsulated PostScript (EPS)
+transformer. It supports both directions: *PS → SVG* and *SVG → PS* (and
+*SVG → EPS*). No external tools, no Ghostscript, no Inkscape — the
+entire pipeline runs in Ruby.
 
-Unlike traditional approaches that rely on external tools like
-Ghostscript or Inkscape, Postsvg provides a native Ruby implementation
-using Parslet for parsing PostScript commands and generating clean,
-standards-compliant SVG output.
+Postsvg uses Nokogiri for the SVG parse side and a hand-written
+comment-aware lexer / stack-machine interpreter for the PS source side.
+Output is typed: the same `Postsvg::Model::Program` is produced whether
+the source was parsed from PS or built from SVG, so round-trips are
+trivial.
 
 This library is particularly useful for applications that need to:
 
-* Convert legacy PostScript graphics to modern SVG format
+* Convert legacy PostScript or SVG to the other format in pure Ruby
 * Process vector graphics without external dependencies
-* Generate SVG from PostScript programmatically
+* Generate PostScript from SVG programmatically (publishing pipelines)
 * Work with EPS files in pure Ruby environments
 
 == Features
 
-* <<basic-conversion,Basic PostScript to SVG conversion>> - Ruby API
-  for converting PS/EPS content to SVG
-* <<cli,Command-line interface>> - Thor-based CLI for file and batch
-  conversions
-* <<postscript-language,PostScript language support>> - Comprehensive
-  documentation and implementation
-* <<architecture,Pure Ruby architecture>> - No external dependencies,
-  Parslet-based parser
+* <<forward-conversion,PS/EPS → SVG conversion>> — Ruby API for
+  converting PS or EPS source to SVG
+* <<reverse-conversion,SVG → PS/EPS conversion>> — Ruby API for the
+  reverse direction
+* <<cli,Command-line interface>> — Thor-based CLI for file and batch
+  conversions in either direction
+* <<architecture,Pure-Ruby architecture>> — No external dependencies
+  for PS/EPS, only Nokogiri for SVG
+* <<svg-optimization,SVG optimization>> — Automatic deduplication of
+  clipPath elements for efficient output
+* <<round-trip,Round-trip preservation>> — `Postsvg.to_svg(Postsvg.to_ps(svg))`
+  for supported SVG elements preserves geometry
+* <<composability,OCP extensible>> — new operators or SVG elements
+  are plug-ins, not edits to existing dispatch
 
 == Architecture
 
 [[architecture]]
 
-=== General
+Postsvg is layered as a typeless surface → a typed model → an
+emitter/serializer. The same `Postsvg::Model::Program` is produced by
+the forward-direction parser and the reverse-direction translator, so
+the same serializer can write it out in either direction.
 
-Postsvg uses a three-stage architecture for converting PostScript to
-SVG. This design follows separation of concerns principles, with each
-component handling a specific responsibility in the conversion process.
+=== Forward direction (PS/EPS → SVG)
 
-.PostScript to SVG conversion pipeline
 [source]
 ----
-┌─────────────┐      ┌───────────┐      ┌──────────────┐
-│ PostScript  │──>   │  Parser   │──>   │  Converter   │
-│   Input     │      │ (Parslet) │      │ (Interpreter)│
-└─────────────┘      └───────────┘      └───────┬──────┘
-                                                │
-                                                ▼
-                                       ┌─────────────────┐
-                                       │ SVG Generator   │
-                                       └────────┬────────┘
-                                                │
-                                                ▼
-                                       ┌─────────────────┐
-                                       │   SVG Output    │
-                                       └─────────────────┘
-----
-
-=== Parser stage
-
-The parser uses Parslet to tokenize and parse PostScript commands into
-an abstract syntax tree (AST). The parser handles PostScript syntax
-including numbers, operators, names, strings, arrays, and procedures.
-
-* `Postsvg::Parser::PostscriptParser` - Parslet grammar for PostScript
-  syntax
-* `Postsvg::Parser::Transform` - Transforms AST into Ruby data
-  structures
-
-=== Converter stage
-
-The converter interprets PostScript commands using a stack-based
-execution model. It maintains an operand stack, dictionary, and graphics
-state while executing PostScript operators.
+PS / EPS source
+       │
+       ▼
+Postsvg::Source::Lexer    (state-machine, comment-aware)
+       │  tokens
+       ▼
+Postsvg::Source::AstBuilder  (tokens → Model::Program)
+       │
+       ▼
+Postsvg::Model::Program  (typed records: Moveto, Stroke, Gsave, …)
+       │
+       ▼
+Postsvg::Renderer  ┐
+Postsvg::Visitors::PsVisitor  ├──  dispatches records, drives
+Postsvg::SvgBuilder          ┘   the SvgBuilder
+       │
+       ▼
+SVG string
+----
+
+=== Reverse direction (SVG → PS/EPS)
 
-* `Postsvg::Converter` - Main orchestrator that executes PostScript
-  commands
-* `Postsvg::GraphicsState` - Manages current path, colors,
-  transformations, and graphics state stack
-
-=== Generator stage
-
-The generator creates SVG output from the interpreted graphics
-operations, handling coordinate system transformations and generating
-standards-compliant SVG markup.
-
-* `Postsvg::SvgGenerator` - Builds SVG document with proper structure
-  and viewBox
+[source]
+----
+SVG string
+       │
+       ▼
+Postsvg::Svg::Parser  (Nokogiri-backed)
+       │  Svg::Document with Element value objects
+       ▼
+Postsvg::Translation::PsRenderer
+Postsvg::Translation::HandlerRegistry
+Postsvg::Translation::Handlers::*  (one per SVG element type)
+       │
+       ▼
+Postsvg::Model::Program  (same model as forward direction)
+       │
+       ▼
+Postsvg::Serializer  ─▶  PS / EPS source
+----
+
+=== MECE responsibility split
+
+| Namespace                          | Owns                              |
+|------------------------------------|-----------------------------------|
+| `Postsvg::Source`                  | Lexer, AstBuilder, OperandStack   |
+| `Postsvg::Model`                   | Typed records, value equality     |
+| `Postsvg::GraphicsContext`/`Stack`| Immutable graphics-state snapshots|
+| `Postsvg::Matrix`/`Color`/`FormatNumber` | Foundational value types    |
+| `Postsvg::SvgBuilder`              | Append-only SVG emission         |
+| `Postsvg::Renderer`                | PS → SVG orchestrator             |
+| `Postsvg::Visitors`                | Per-operator dispatch             |
+| `Postsvg::Svg`                     | SVG domain model                  |
+| `Postsvg::Translation`             | SVG → PS dispatch + context       |
+| `Postsvg::Serializer`              | Model → PS source                 |
+| `Postsvg::CLI`                     | Argument parsing, I/O             |
 
 == Installation
 
@@ -118,40 +134,25 @@ Or install it yourself as:
 gem install postsvg
 ----
 
-== Basic PostScript to SVG conversion
+== Conversion APIs
 
 [[basic-conversion]]
 
-=== General
+Postsvg provides four directional APIs covering both PS/EPS → SVG and
+SVG → PS/EPS. All conversions are pure-Ruby with no external process
+invocation.
 
-The Postsvg library provides a simple Ruby API for converting PostScript
-content to SVG format. The conversion can be performed on in-memory
-content or directly on files.
+=== Forward direction (PS/EPS → SVG)
 
-The library automatically handles BoundingBox extraction, coordinate
-system transformations, and SVG generation while preserving the visual
-appearance of the original PostScript graphics.
-
-=== Converting PostScript content
-
-Syntax:
-
-[source,ruby]
-----
-svg_output = Postsvg.convert(ps_content) <1>
-----
-<1> Convert PostScript string to SVG string
-
-Where,
-
-`ps_content`:: PostScript or EPS content as a string. Should include
-proper PostScript header and BoundingBox comment for best results.
-
-Returns:: SVG markup as a string
+[cols="1,4", options="header"]
+|===
+| Method | Description
+| `Postsvg.to_svg(source, **opts)` | Convert PS/EPS source string to SVG.
+| `Postsvg.to_svg_file(input_path, output_path=nil, **opts)` | Read PS/EPS file, optionally write SVG.
+| `Postsvg.convert(...)` / `Postsvg.convert_file(...)` | Backwards-compatible aliases for `to_svg` / `to_svg_file`.
+|===
 
 .Converting PostScript content to SVG
-[example]
-====
 [source,ruby]
 ----
 require "postsvg"
@@ -169,102 +170,136 @@ ps_content = <<~PS
   fill
 PS
 
-svg = Postsvg.convert(ps_content)
+svg = Postsvg.to_svg(ps_content)
 File.write("output.svg", svg)
 ----
 
 This converts a PostScript square with gray fill to SVG format and saves
 it to a file.
-====
 
-=== Converting PostScript files
+.Converting a PostScript file to SVG
+[source,ruby]
+----
+require "postsvg"
+
+# Convert and save in one step
+Postsvg.to_svg_file("input.eps", "output.svg")
 
-Syntax:
+# Or get SVG content without saving
+svg_content = Postsvg.to_svg_file("input.ps")
+puts svg_content
+----
 
+=== Reverse direction (SVG → PS / EPS)
+
+[cols="1,4", options="header"]
+|===
+| Method | Description
+| `Postsvg.to_ps(svg_string, eps: false, **opts)` | Convert SVG to PostScript source.
+| `Postsvg.to_eps(svg_string, **opts)` | Convert SVG to Encapsulated PostScript (EPSF-3.0 header).
+| `Postsvg.to_ps_file(input_path, output_path=nil, eps: false, **opts)` | Read SVG file, optionally write PS.
+|===
+
+.Converting SVG to PostScript
 [source,ruby]
 ----
-Postsvg.convert_file(input_path, output_path) <1>
-svg_content = Postsvg.convert_file(input_path) <2>
+require "postsvg"
+
+svg_content = File.read("input.svg")
+
+# Produce PostScript
+ps = Postsvg.to_ps(svg_content)
+File.write("output.ps", ps)
+
+# Produce Encapsulated PostScript for embedding
+eps = Postsvg.to_eps(svg_content)
+File.write("output.eps", eps)
 ----
-<1> Convert file and save to output path
-<2> Convert file and return SVG content without saving
 
-Where,
+The SVG→PS pipeline supports `<svg>`, `<g>`, `<path>` (full M/L/H/V/C/S/Q/T/A/Z
+command set), `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<polyline>`,
+`<polygon>`, `<text>` (emits `findfont`/`scalefont`/`setfont`/`show`),
+`<image>` (stubbed), `<defs>`, and `<clipPath>`. Arc paths use the W3C
+endpoint-to-center conversion algorithm (SVG 1.1 §F.6.5) to emit the
+equivalent PS `arc` operator.
 
-`input_path`:: Path to input PostScript (.ps) or EPS (.eps) file
-`output_path`:: (Optional) Path where SVG file should be saved. If
-omitted, SVG content is returned without saving.
+=== Round-trip
 
-Returns:: When `output_path` is omitted, returns SVG markup as a string.
-When `output_path` is provided, returns the output path.
+The same `Model::Program` value object sits behind both directions, so
+round-trip is a function composition:
 
-.Converting a PostScript file to SVG
-[example]
-====
 [source,ruby]
 ----
 require "postsvg"
 
-# Convert and save in one step
-Postsvg.convert_file("input.eps", "output.svg")
+original_svg = File.read("input.svg")
+ps = Postsvg.to_ps(original_svg)
+round_tripped_svg = Postsvg.to_svg(ps)
 
-# Or get SVG content without saving
-svg_content = Postsvg.convert_file("input.ps")
-puts svg_content
+# round_tripped_svg preserves the geometry of original_svg for the
+# supported subset of SVG elements.
 ----
 
-The first example converts an EPS file and saves the result as SVG. The
-second example reads a PostScript file and returns the SVG content for
-further processing.
-====
-
 == Command-line interface
 
 [[cli]]
 
 === General
 
-Postsvg provides a Thor-based command-line interface for converting
-PostScript and EPS files to SVG format. The CLI supports single file
-conversion, batch processing, and version information.
+Postsvg provides a Thor-based command-line interface covering both
+directions (PS/EPS → SVG and SVG → PS/EPS), plus batch processing and
+version information.
 
 The CLI is available through the `postsvg` executable installed with the
 gem.
 
-=== Converting single files
+=== Converting PS/EPS to SVG
 
 Syntax:
 
 [source,sh]
 ----
-postsvg convert INPUT_FILE [OUTPUT_FILE] <1>
+postsvg convert INPUT_FILE [OUTPUT_FILE]
+postsvg to-svg INPUT_FILE [OUTPUT_FILE]   # explicit alias
 ----
-<1> Convert INPUT_FILE to SVG, optionally saving to OUTPUT_FILE
 
-Where,
-
-`INPUT_FILE`:: Path to input PostScript (.ps) or EPS (.eps) file
-`OUTPUT_FILE`:: (Optional) Path where SVG file should be saved. If
-omitted, SVG is written to stdout.
+`INPUT_FILE` is a PostScript (.ps) or EPS (.eps) file. If `OUTPUT_FILE`
+is omitted, SVG is written to stdout.
 
-.Converting a single PostScript file
-[example]
-====
+.Converting PS/EPS to SVG
 [source,sh]
 ----
 # Convert to stdout
 postsvg convert input.ps
 
 # Convert and save to file
-postsvg convert input.eps output.svg
+postsvg to-svg input.eps output.svg
 
 # Redirect stdout to file
 postsvg convert input.ps > output.svg
 ----
 
-The first command prints SVG to stdout. The second saves directly to
-output.svg. The third uses shell redirection to save the output.
-====
+=== Converting SVG to PS/EPS
+
+Syntax:
+
+[source,sh]
+----
+postsvg to-ps  INPUT.svg [OUTPUT.ps]   # SVG → PostScript
+postsvg to-eps INPUT.svg [OUTPUT.eps]  # SVG → Encapsulated PostScript
+----
+
+If `OUTPUT` is omitted, PS/EPS source is written to stdout.
+
+.Converting SVG to PostScript
+[source,sh]
+----
+# Save to file
+postsvg to-ps input.svg output.ps
+
+# Pipe through stdout
+postsvg to-eps input.svg > output.eps
+----
 
 === Batch conversion
 
@@ -272,36 +307,27 @@ Syntax:
 
 [source,sh]
 ----
-postsvg batch INPUT_DIR [OUTPUT_DIR] <1>
+postsvg batch INPUT_DIR [OUTPUT_DIR]
 ----
-<1> Convert all PS/EPS files in INPUT_DIR, optionally saving to
-OUTPUT_DIR
 
-Where,
+`batch` auto-detects the direction by file extension:
 
-`INPUT_DIR`:: Directory containing PostScript (.ps) and/or EPS (.eps)
-files to convert
-`OUTPUT_DIR`:: (Optional) Directory where SVG files should be saved. If
-omitted, SVG files are saved in the same directory as input files with
-.svg extension.
+* `.ps` / `.eps` → `.svg`
+* `.svg` → `.ps`
 
-.Batch converting PostScript files
-[example]
-====
+If `OUTPUT_DIR` is omitted, output files land in `INPUT_DIR` with the
+converted extension.
+
+.Batch converting files
 [source,sh]
 ----
-# Convert all PS/EPS files in a directory
-postsvg batch ps_files/
+# Convert all PS/EPS/SVG files in a directory
+postsvg batch mixed_files/
 
 # Convert to a different directory
 postsvg batch ps_files/ svg_files/
 ----
 
-The first example converts all PS and EPS files in the `ps_files/`
-directory, saving the SVG files in the same directory. The second
-example saves the converted files to the `svg_files/` directory.
-====
-
 === Displaying version information
 
 Syntax:
@@ -326,6 +352,258 @@ postsvg version 0.1.0
 ----
 ====
 
+== File validation
+
+[[file-validation]]
+
+=== General
+
+Postsvg includes a comprehensive validation tool for checking PostScript
+and EPS files. The validator performs syntax checking, semantic
+validation, and optional full conversion testing to ensure files are
+well-formed and can be successfully converted.
+
+The validator is particularly useful for:
+
+* Verifying PostScript/EPS file integrity before conversion
+* Identifying syntax errors and structural issues
+* Validating compliance with PostScript standards
+* Integrating quality checks into CI/CD pipelines
+
+=== Basic validation
+
+Syntax:
+
+[source,sh]
+----
+postsvg check FILE... <1>
+----
+<1> Validate one or more PostScript or EPS files
+
+Where,
+
+`FILE`:: Path to PostScript (.ps) or EPS (.eps) file(s) to validate.
+Multiple files can be specified.
+
+Returns:: Exit code 0 if all files are valid, 1 if any file has errors.
+
+.Validating PostScript files
+[example]
+[source,sh]
+----
+# Validate a single file
+postsvg check document.ps
+
+# Validate multiple files
+postsvg check file1.ps file2.eps file3.ps
+
+# Validate all PS files in directory
+postsvg check *.ps
+----
+
+The validator performs semantic-level validation by default, checking
+syntax, stack balance, and graphics state management.
+
+=== Validation levels
+
+Syntax:
+
+[source,sh]
+----
+postsvg check --level=LEVEL FILE... <1>
+----
+<1> Validate with specified level: syntax, semantic, or full
+
+Where,
+
+`LEVEL`:: One of:
+* `syntax` - Fast syntax-only validation (header, delimiters,
+  tokenization)
+* `semantic` - Default level (syntax + stack/state checking)
+* `full` - Strictest validation (semantic + complete conversion test)
+
+.Using different validation levels
+[example]
+[source,sh]
+----
+# Fast syntax-only check
+postsvg check --level=syntax document.ps
+
+# Default semantic validation
+postsvg check --level=semantic document.ps
+
+# Full validation with conversion test
+postsvg check --level=full document.ps
+----
+
+Syntax validation is fastest but only checks basic file structure.
+Semantic validation adds stack and state checking. Full validation
+attempts complete conversion and is most thorough.
+
+=== Output formats
+
+Syntax:
+
+[source,sh]
+----
+postsvg check --format=FORMAT FILE... <1>
+----
+<1> Output validation results in specified format
+
+Where,
+
+`FORMAT`:: One of:
+* `text` - Human-readable colored console output (default)
+* `yaml` - YAML structured format
+* `json` - JSON structured format
+
+.Output format examples
+[example]
+[source,sh]
+----
+# Default text output with colors
+postsvg check document.ps
+
+# YAML output
+postsvg check --format=yaml document.ps
+
+# JSON output for programmatic parsing
+postsvg check --format=json document.ps
+
+# JSON output without colors (for CI)
+postsvg check --format=json --no-color document.ps
+----
+
+Text format provides human-readable output with color-coded status
+indicators. YAML and JSON formats are useful for programmatic processing
+or integration with other tools.
+
+=== Validation options
+
+The validator supports additional options for controlling behavior and
+output:
+
+`--verbose`:: Show warnings and info messages in addition to errors
+`--quiet`:: Suppress output for valid files (only show errors)
+`--no-color`:: Disable colored output
+`--fail-fast`:: Stop validation at first error
+`--eps-version=VERSION`:: Validate EPS version (e.g., `3.0`)
+
+.Using validation options
+[example]
+[source,sh]
+----
+# Verbose output with all details
+postsvg check --verbose document.eps
+
+# Quiet mode - only show errors
+postsvg check --quiet *.ps
+
+# Stop at first error
+postsvg check --fail-fast file1.ps file2.ps file3.ps
+
+# Validate specific EPS version
+postsvg check --eps-version=3.0 diagram.eps
+----
+
+== SVG optimization
+
+[[svg-optimization]]
+
+=== General
+
+Postsvg automatically optimizes SVG output to produce smaller, more
+efficient files while maintaining visual fidelity to the original
+PostScript graphics.
+
+=== ClipPath deduplication
+
+PostScript files often contain repeated clipping operations with
+identical paths. Postsvg automatically detects and deduplicates these
+clipPath definitions, significantly reducing SVG file size for documents
+with repeated clipping operations.
+
+.ClipPath deduplication example
+[example]
+Instead of generating multiple identical clipPath definitions:
+
+[source,xml]
+----
+<defs>
+  <clipPath id="clipPath2">
+    <path d="M 0 0 L 100 100"/>
+  </clipPath>
+  <clipPath id="clipPath3">
+    <path d="M 0 0 L 100 100"/>
+  </clipPath>
+  <clipPath id="clipPath4">
+    <path d="M 0 0 L 100 100"/>
+  </clipPath>
+</defs>
+----
+
+Postsvg generates a single definition and reuses it:
+
+[source,xml]
+----
+<defs>
+  <clipPath id="clipPath2">
+    <path d="M 0 0 L 100 100"/>
+  </clipPath>
+</defs>
+<path clip-path="url(#clipPath2)" .../>
+<path clip-path="url(#clipPath2)" .../>
+<path clip-path="url(#clipPath2)" .../>
+----
+
+This optimization is automatic and requires no configuration.
+
+== Test coverage
+
+[[test-coverage]]
+
+=== General
+
+Postsvg maintains comprehensive test coverage to ensure reliability and
+correctness of PostScript to SVG conversion.
+
+=== Core test suite
+
+The core test suite consists of 90+ tests covering execution context and
+integration testing:
+
+* **Execution context tests (84 tests)** - Unit tests for stack
+  operations, graphics state management, dictionary operations, path
+  operations, helper methods, SVG generation, and clipPath deduplication
+* **Integration tests (6 tests)** - End-to-end tests using real
+  PostScript files from ps2svg and vectory test suites
+
+All core tests maintain 100% pass rate, ensuring critical functionality
+remains stable.
+
+=== Running tests
+
+Run the full test suite:
+
+[source,sh]
+----
+bundle exec rspec
+----
+
+Run only core tests:
+
+[source,sh]
+----
+bundle exec rspec spec/postsvg/execution_context_spec.rb spec/postsvg/integration_spec.rb
+----
+
+Run with documentation format:
+
+[source,sh]
+----
+bundle exec rspec --format documentation
+----
+
 == PostScript language support
 
 [[postscript-language]]
@@ -408,23 +686,22 @@ following topics:
 
 == Limitations
 
-Current version has the following limitations:
-
-* Text rendering: Text operations (show, findfont, setfont, etc.) are
-  not yet supported. Convert text to outlines before processing.
-* Complex clipping: Clipping paths (clip, eoclip) are not fully
-  implemented
-* Gradients and patterns: Pattern fills and gradient operations are not
-  yet supported
-* CMYK colors: Only RGB and grayscale colors are supported. CMYK color
-  operations will need conversion.
-* Image embedding: Raster images within PostScript (image, imagemask)
-  are not supported
-* Advanced operators: Some PostScript Level 2 and 3 operators are not
-  yet implemented
-
-For files with these features, consider preprocessing with external
-tools or contributing implementations of these features.
+* **Text rendering** is stubbed: `show` maps to SVG `<text>` but no
+  font metrics. Convert text to outlines for fidelity.
+* **Real raster images** (`image`, `imagemask`): emit SVG `<image>`
+  with a placeholder when decoded; PNG round-trip is planned but not
+  yet wired.
+* **Real Level 3 shading** (types 4–7) and forms are stubbed.
+* **User-defined procedures** invoked at runtime: parsed via the AST,
+  but only first-order ones execute.
+* **Procedures inside arrays** (`[...]`) keep literals only; operators
+  inside `[...]` are an unusual construct in EPS drawing programs
+  and not handled.
+* **Document-level DSC** comments other than `%%BoundingBox` and
+  `%%HiResBoundingBox` are captured but not re-emitted.
+
+For these gaps, see link:../TODO.roadmap/[TODO.roadmap] for the
+planned work.
 
 == Acknowledgments