postscript 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 657b74cfdae6702c2d5aa7bc8f6fcc4d80c4319f38806b2d1a4c0f48d9d050e9
+  data.tar.gz: f13ac7de23328c6a211cd40e915942ab4228bdb12bd0cda6f565f557547fda20
+SHA512:
+  metadata.gz: ca8e96d0ad7ca8b75f0b41690ed71e9b0e55167f1326db5cce018ae41f49a0e104b5fd77d588d4bfe5aa0ad41ebaa7eccb166b773db5e2b1dd5312a0f90063bd
+  data.tar.gz: 43a30efc33221687d6658e4fd61dbe4b97b9851991a8a345ba14b68f7e01e11c164d9c60c5773d0ae796777e64f4e7998f4884eecd609b9b33aee921a515ad78

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--require spec_helper

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -0,0 +1,72 @@
+= Postscript
+
+Pure-Ruby PostScript (PS) / EPS parser, typed domain model, and
+serializer. The lower layer of the
+https://github.com/claricle/postsvg[postsvg] converter. Independently
+reusable for any tool that needs to read, write, or transform
+PostScript source.
+
+== Installation
+
+[source,sh]
+----
+gem install postscript
+----
+
+== Usage
+
+[source,ruby]
+----
+require "postscript"
+
+# Parse PS source into a typed AST
+program = Postscript::Source.parse(<<~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
+  fill
+  showpage
+PS
+
+# Walk the AST
+program.body.each do |node|
+  puts node.class
+end
+
+# Re-serialize back to PS source
+ps_text = Postscript::Serializer.call(program)
+puts ps_text
+----
+
+== Architecture
+
+Three layers, each with a single responsibility:
+
+[cols="1,4", options="header"]
+|===
+| Layer | Owns
+| `Postscript::Source` | PS source → tokens → `Model::Program`. Lexer is comment-aware.
+| `Postscript::Model` | Typed PS records: `Program`, `Literals::*`, `Operators::*` (one class per PS operator).
+| `Postscript::Serializer` | `Model::Program` → PS source text.
+|===
+
+Adding a new PS operator = writing one subclass + one `visit_*`
+method. No switch edits (OCP).
+
+== Value types
+
+This gem also hosts three general-purpose value types that
+postsvg depends on:
+
+* `Postscript::Matrix` — 2D affine transform.
+* `Postscript::Color` — RGB / Gray / CMYK immutable value.
+* `Postscript::FormatNumber` — float → PS-safe text.
+
+== License
+
+BSD-2-Clause. See `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/lib/postscript/color.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Postscript
+  # 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/postscript/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Postscript
+  # Base class for every Postscript gem error. rescue this to catch
+  # anything the gem raises.
+  class Error < StandardError; end
+
+  # Lexing or parsing failed. Carries +source_position+ when known.
+  class ParseError < Error
+    attr_reader :source_position
+
+    def initialize(message, source_position: nil)
+      @source_position = source_position
+      super(message)
+    end
+  end
+
+  # Lexer hit a character or construct it could not consume.
+  class LexError < ParseError; end
+
+  # Tokens did not form a valid PostScript program (unbalanced braces,
+  # missing operands, malformed literal).
+  class SyntaxError < ParseError; end
+
+  # PS -> SVG / serializer execution failed.
+  class RenderError < Error
+    attr_reader :operator_name
+
+    def initialize(message, operator_name: nil)
+      @operator_name = operator_name
+      super(message)
+    end
+  end
+
+  # An operator tried to pop more values than the stack held.
+  class StackUnderflowError < RenderError; end
+
+  # An operator referenced a name that has no definition in any
+  # active dictionary.
+  class UndefinedOperatorError < RenderError; end
+
+  # A procedure invocation chain exceeded the depth limit.
+  class RecursionLimitError < RenderError; end
+
+  # Output exceeded the configured byte limit.
+  class SizeLimitError < RenderError; end
+
+  # Model -> PS source serialization failed.
+  class SerializeError < Error; end
+
+  # Internal control-flow signals used by visitors to unwind loops
+  # and stop program execution. NOT user-facing errors; caught by
+  # the orchestrator (e.g. Postscript::Renderer).
+  class ExitSignal < StandardError; end
+  class QuitSignal < StandardError; end
+end

data/lib/postscript/format_number.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Postscript
+  # 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/postscript/matrix.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Postscript
+  # 2D affine transformation matrix [a b c d e f].
+  #
+  # Used by both PS-side (CTM, transforms) and SVG-side (transform
+  # attribute parsing). General-purpose; lives here so both postsvg
+  # and a future pdf gem can share it.
+  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/postscript/model/literals/array.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Postscript
+  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/postscript/model/literals/dictionary.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Postscript
+  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/postscript/model/literals/hex.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Postscript
+  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/postscript/model/literals/name.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Postscript
+  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

data/lib/postscript/model/literals/number.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Postscript
+  module Model
+    module Literals
+      # A PostScript numeric literal. Stored as a Ruby Numeric so
+      # arithmetic Just Works; class carries the original source
+      # representation choice (int vs float) when known.
+      class Number
+        attr_reader :value
+
+        def initialize(value)
+          @value = value.is_a?(Numeric) ? value : Float(value)
+          freeze
+        end
+
+        def to_i = value.to_i
+        def to_f = value.to_f
+        def integer? = value.is_a?(Integer)
+
+        def accept(visitor, ctx)
+          visitor.visit_number(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(Number) && other.value == value
+        end
+        alias eql? ==
+
+        def hash
+          value.hash
+        end
+      end
+    end
+  end
+end

data/lib/postscript/model/literals/procedure.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Postscript
+  module Model
+    module Literals
+      # Procedure body: +{ ... }+. Carries the inner token stream as a
+      # list of literal/operator nodes. Procedures are not executed by
+      # the parser; the renderer descends into them on InvokeProcedure.
+      class Procedure
+        include Enumerable
+
+        attr_reader :body
+
+        def initialize(body = [])
+          @body = body.freeze
+          freeze
+        end
+
+        def each(&block)
+          @body.each(&block)
+        end
+
+        def length = @body.length
+        def empty? = @body.empty?
+
+        def accept(visitor, ctx)
+          visitor.visit_procedure(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(Procedure) && other.body == @body
+        end
+        alias eql? ==
+
+        def hash
+          @body.hash
+        end
+      end
+    end
+  end
+end

data/lib/postscript/model/literals/string.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Postscript
+  module Model
+    module Literals
+      # Parenthesized string literal: +(foo bar baz)+.
+      class StringLiteral
+        attr_reader :value
+
+        def initialize(value)
+          @value = value.to_s
+          freeze
+        end
+
+        def accept(visitor, ctx)
+          visitor.visit_string_literal(self, ctx)
+        end
+
+        def ==(other)
+          other.is_a?(StringLiteral) && other.value == value
+        end
+        alias eql? ==
+
+        def hash
+          value.hash
+        end
+      end
+    end
+  end
+end