postsvg 0.1.0

checksums.yaml

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

data/.rubocop.yml

@@ -0,0 +1,19 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  - .rubocop_todo.yml
+
+inherit_mode:
+  merge:
+    - Exclude
+
+# local repo-specific modifications
+# ...
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0

data/.rubocop_todo.yml

@@ -0,0 +1,141 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-10-19 09:58:29 UTC using RuboCop version 1.81.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 36
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Exclude:
+    - 'lib/postsvg.rb'
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/graphics_state.rb'
+    - 'lib/postsvg/interpreter.rb'
+    - 'lib/postsvg/parser/postscript_parser.rb'
+    - 'lib/postsvg/tokenizer.rb'
+    - 'postsvg.gemspec'
+    - 'scripts/regenerate_fixtures.rb'
+
+# Offense count: 5
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/interpreter.rb'
+
+# Offense count: 1
+Lint/DuplicateCaseCondition:
+  Exclude:
+    - 'lib/postsvg/converter.rb'
+
+# Offense count: 29
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/postsvg.rb'
+    - 'lib/postsvg/cli.rb'
+    - 'lib/postsvg/colors.rb'
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/graphics_state.rb'
+    - 'lib/postsvg/interpreter.rb'
+    - 'lib/postsvg/matrix.rb'
+    - 'lib/postsvg/path_builder.rb'
+    - 'lib/postsvg/svg_generator.rb'
+    - 'lib/postsvg/tokenizer.rb'
+
+# Offense count: 1
+# Configuration parameters: CountBlocks, CountModifierForms.
+Metrics/BlockNesting:
+  Max: 6
+
+# Offense count: 14
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/postsvg/cli.rb'
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/interpreter.rb'
+    - 'lib/postsvg/tokenizer.rb'
+
+# Offense count: 30
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 111
+
+# Offense count: 5
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 7
+
+# Offense count: 13
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/postsvg/cli.rb'
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/interpreter.rb'
+    - 'lib/postsvg/tokenizer.rb'
+
+# Offense count: 67
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/postsvg.rb'
+    - 'lib/postsvg/converter.rb'
+    - 'lib/postsvg/graphics_state.rb'
+    - 'lib/postsvg/interpreter.rb'
+    - 'lib/postsvg/matrix.rb'
+    - 'lib/postsvg/path_builder.rb'
+    - 'lib/postsvg/tokenizer.rb'
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'lib/postsvg/interpreter.rb'
+
+# Offense count: 3
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'lib/postsvg/interpreter.rb'
+
+# Offense count: 1
+# Configuration parameters: IgnoredMetadata.
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/postsvg/integration_spec.rb'
+
+# Offense count: 7
+# Configuration parameters: CountAsOne.
+RSpec/ExampleLength:
+  Max: 16
+
+# Offense count: 3
+RSpec/MultipleExpectations:
+  Max: 4
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, AllowComments.
+# SupportedStyles: empty, nil, both
+Style/EmptyElse:
+  Exclude:
+    - 'lib/postsvg/converter.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
+# SupportedStyles: annotated, template, unannotated
+Style/FormatStringToken:
+  EnforcedStyle: unannotated

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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 "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Ribose Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,473 @@
+= 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/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.
+
+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.
+
+This library is particularly useful for applications that need to:
+
+* Convert legacy PostScript graphics to modern SVG format
+* Process vector graphics without external dependencies
+* Generate SVG from PostScript programmatically
+* 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
+
+== Architecture
+
+[[architecture]]
+
+=== General
+
+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.
+
+.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.
+
+* `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
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem "postsvg"
+----
+
+And then execute:
+
+[source,sh]
+----
+bundle install
+----
+
+Or install it yourself as:
+
+[source,sh]
+----
+gem install postsvg
+----
+
+== Basic PostScript to SVG conversion
+
+[[basic-conversion]]
+
+=== General
+
+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.
+
+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
+
+.Converting PostScript content to SVG
+[example]
+====
+[source,ruby]
+----
+require "postsvg"
+
+ps_content = <<~PS
+  %!PS-Adobe-3.0 EPSF-3.0
+  %%BoundingBox: 0 0 100 100
+  newpath
+  10 10 moveto
+  90 10 lineto
+  90 90 lineto
+  10 90 lineto
+  closepath
+  0.5 0.5 0.5 setrgbcolor
+  fill
+PS
+
+svg = Postsvg.convert(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
+
+Syntax:
+
+[source,ruby]
+----
+Postsvg.convert_file(input_path, output_path) <1>
+svg_content = Postsvg.convert_file(input_path) <2>
+----
+<1> Convert file and save to output path
+<2> Convert file and return SVG content without saving
+
+Where,
+
+`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.
+
+Returns:: When `output_path` is omitted, returns SVG markup as a string.
+When `output_path` is provided, returns the output path.
+
+.Converting a PostScript file to SVG
+[example]
+====
+[source,ruby]
+----
+require "postsvg"
+
+# Convert and save in one step
+Postsvg.convert_file("input.eps", "output.svg")
+
+# Or get SVG content without saving
+svg_content = Postsvg.convert_file("input.ps")
+puts svg_content
+----
+
+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.
+
+The CLI is available through the `postsvg` executable installed with the
+gem.
+
+=== Converting single files
+
+Syntax:
+
+[source,sh]
+----
+postsvg convert INPUT_FILE [OUTPUT_FILE] <1>
+----
+<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.
+
+.Converting a single PostScript file
+[example]
+====
+[source,sh]
+----
+# Convert to stdout
+postsvg convert input.ps
+
+# Convert and save to file
+postsvg convert 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.
+====
+
+=== Batch conversion
+
+Syntax:
+
+[source,sh]
+----
+postsvg batch INPUT_DIR [OUTPUT_DIR] <1>
+----
+<1> Convert all PS/EPS files in INPUT_DIR, optionally saving to
+OUTPUT_DIR
+
+Where,
+
+`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.
+
+.Batch converting PostScript files
+[example]
+====
+[source,sh]
+----
+# Convert all PS/EPS files in a directory
+postsvg batch ps_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:
+
+[source,sh]
+----
+postsvg version <1>
+----
+<1> Display the Postsvg version number
+
+.Getting version information
+[example]
+====
+[source,sh]
+----
+postsvg version
+----
+
+Output:
+----
+postsvg version 0.1.0
+----
+====
+
+== PostScript language support
+
+[[postscript-language]]
+
+=== General
+
+Postsvg provides comprehensive PostScript language support with detailed
+documentation covering fundamentals, operators, and conversion
+strategies.
+
+The implementation supports common PostScript operations including path
+construction, painting, color management, graphics state, and coordinate
+transformations.
+
+=== PostScript documentation
+
+Complete PostScript language documentation is available at
+link:docs/POSTSCRIPT.adoc[docs/POSTSCRIPT.adoc], organized into the
+following topics:
+
+* link:docs/postscript/fundamentals.adoc[Fundamentals] - PostScript
+  language basics, syntax, and data types
+* link:docs/postscript/graphics-model.adoc[Graphics model] - Coordinate
+  systems, paths, and painting model
+* link:docs/postscript/operators/index.adoc[Operators reference] -
+  Detailed documentation for all supported operators:
+** link:docs/postscript/operators/path-construction.adoc[Path
+   construction] - moveto, lineto, curveto, closepath, newpath
+** link:docs/postscript/operators/painting.adoc[Painting] - stroke,
+   fill
+** link:docs/postscript/operators/graphics-state.adoc[Graphics state] -
+   gsave, grestore, setlinewidth
+** link:docs/postscript/operators/transformations.adoc[Transformations]
+   - translate, scale, rotate
+** link:docs/postscript/operators/stack-manipulation.adoc[Stack
+   manipulation] - dup, pop, exch, roll
+** link:docs/postscript/operators/arithmetic.adoc[Arithmetic] - add,
+   sub, mul, div
+** link:docs/postscript/operators/control-flow.adoc[Control flow] - if,
+   ifelse, for, repeat
+** link:docs/postscript/operators/dictionary.adoc[Dictionary] - def,
+   dict, begin, end
+* link:docs/postscript/svg-mapping.adoc[SVG mapping guide] - How
+  PostScript operations map to SVG
+* link:docs/postscript/implementation-notes.adoc[Implementation notes] -
+  Postsvg-specific details and design decisions
+
+=== Supported PostScript operations
+
+==== Path construction
+
+* `moveto` - Begin new subpath at coordinates
+* `lineto` - Append straight line segment
+* `rlineto` - Append relative line segment
+* `curveto` - Append cubic Bézier curve
+* `closepath` - Close current subpath
+* `newpath` - Initialize new path
+
+==== Painting
+
+* `stroke` - Stroke current path with current color and line width
+* `fill` - Fill current path with current color
+
+==== Color
+
+* `setrgbcolor` - Set RGB color (0-1 range for each component)
+* `setgray` - Set grayscale color (0-1 range)
+
+==== Graphics state
+
+* `gsave` - Save current graphics state to stack
+* `grestore` - Restore graphics state from stack
+* `setlinewidth` - Set line width for stroke operations
+
+==== Transformations
+
+* `translate` - Translate coordinate system
+* `scale` - Scale coordinate system
+* `rotate` - Rotate coordinate system (angle in degrees)
+
+== 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.
+
+== Acknowledgments
+
+This project uses test fixtures from
+https://github.com/elalish/ps2svg[ps2svg] by Emmett Lalish, licensed
+under the MIT License. These test files help ensure the correctness of
+our SVG generation against a reference implementation. We are grateful
+for this valuable resource that helps validate PostScript to SVG
+conversion.
+
+== Development
+
+=== Running tests
+
+[source,sh]
+----
+bundle exec rspec
+----
+
+=== Code style
+
+[source,sh]
+----
+bundle exec rubocop
+----
+
+=== Running all checks
+
+[source,sh]
+----
+bundle exec rake
+----
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/metanorma/postsvg.
+
+== Copyright
+
+Copyright Ribose.
+
+== License
+
+The gem is available as open source under the terms of the
+https://opensource.org/licenses/BSD-2-Clause[BSD 2-Clause License].

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/POSTSCRIPT.adoc

@@ -0,0 +1,13 @@
+= PostScript Language Reference
+
+For comprehensive PostScript documentation for the Postsvg library, see:
+
+* link:postscript/index.adoc[PostScript Quick Reference Guide]
+
+== Quick Links
+
+* link:postscript/fundamentals.adoc[Language Fundamentals]
+* link:postscript/graphics-model.adoc[Graphics Model]
+* link:postscript/operators/index.adoc[Operator Reference]
+* link:postscript/svg-mapping.adoc[PostScript to SVG Mapping]
+* link:postscript/implementation-notes.adoc[Postsvg Implementation Notes]