postsvg 0.1.0 → 0.3.0

data/exe/postsvg

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require_relative "../lib/postsvg"
 require_relative "../lib/postsvg/cli"
 
 Postsvg::CLI.start(ARGV)

data/lib/postsvg/cli.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 require "thor"
-require_relative "../postsvg"
 
 module Postsvg
-  # Command-line interface for postsvg
+  # Command-line interface. Thor-based. Auto-detects conversion
+  # direction by file extension in +batch+.
   class CLI < Thor
-    desc "convert INPUT [OUTPUT]", "Convert PostScript/EPS file to SVG"
+    package_name "postsvg"
+
+    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 format.
+      Convert a PostScript (.ps) or Encapsulated PostScript (.eps) file to SVG.
 
-      If OUTPUT is not specified, the output will be written to stdout.
+      If OUTPUT is not specified, SVG is written to stdout.
 
       Examples:
 
@@ -18,43 +20,48 @@ module Postsvg
         $ postsvg convert input.eps > output.svg
     DESC
     def convert(input_path, output_path = nil)
-      unless File.exist?(input_path)
-        say "Error: Input file '#{input_path}' not found", :red
-        exit 1
-      end
+      handle_input(input_path, output_path, method(:read_ps_to_svg), direction: "PS/EPS -> SVG")
+    end
 
-      begin
-        ps_content = File.read(input_path)
-        svg_output = Postsvg.convert(ps_content)
+    desc "to-svg INPUT [OUTPUT]", "Convert PostScript/EPS to SVG"
+    long_desc <<~DESC
+      Alias for `convert`. Reads PS or EPS, writes SVG.
+    DESC
+    def to_svg(input_path, output_path = nil)
+      convert(input_path, output_path)
+    end
 
-        if output_path
-          File.write(output_path, svg_output)
-          say "Successfully converted #{input_path} to #{output_path}", :green
-        else
-          puts svg_output
-        end
-      rescue Postsvg::Error => e
-        say "Conversion error: #{e.message}", :red
-        exit 1
-      rescue StandardError => e
-        say "Unexpected error: #{e.message}", :red
-        say e.backtrace.join("\n"), :red if options[:verbose]
-        exit 1
-      end
+    desc "to-ps INPUT [OUTPUT]", "Convert SVG to PostScript"
+    long_desc <<~DESC
+      Convert an SVG file to PostScript source. If OUTPUT is not specified,
+      PS source is written to stdout.
+
+      Examples:
+
+        $ postsvg to-ps input.svg output.ps
+        $ 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")
     end
 
-    desc "batch INPUT_DIR [OUTPUT_DIR]",
-         "Convert all PS/EPS files in a directory"
+    desc "to-eps INPUT [OUTPUT]", "Convert SVG to Encapsulated PostScript"
     long_desc <<~DESC
-      Convert all .ps and .eps files in INPUT_DIR to SVG format.
+      Like to-ps but emits an EPSF-3.0 header and a single-page program
+      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")
+    end
 
-      If OUTPUT_DIR is specified, SVG files will be written there.
-      Otherwise, SVG files will be written to the same directory as the input files.
+    desc "batch INPUT_DIR [OUTPUT_DIR]", "Convert all PS/EPS/SVG files in a directory"
+    long_desc <<~DESC
+      Auto-detects direction by file extension:
 
-      Examples:
+        .ps, .eps   -> .svg
+        .svg        -> .ps
 
-        $ postsvg batch ps_files/
-        $ postsvg batch ps_files/ svg_files/
+      Output goes to OUTPUT_DIR if given, otherwise to INPUT_DIR.
     DESC
     def batch(input_dir, output_dir = nil)
       unless Dir.exist?(input_dir)
@@ -64,34 +71,15 @@ module Postsvg
 
       Dir.mkdir(output_dir) if output_dir && !Dir.exist?(output_dir)
 
-      pattern = File.join(input_dir, "*.{ps,eps}")
-      files = Dir.glob(pattern, File::FNM_CASEFOLD)
-
+      files = Dir.glob(File.join(input_dir, "*.{ps,eps,svg}"), File::FNM_CASEFOLD)
       if files.empty?
-        say "No PS or EPS files found in #{input_dir}", :yellow
+        say "No PS, EPS, or SVG files found in #{input_dir}", :yellow
         return
       end
 
       say "Found #{files.size} file(s) to convert", :cyan
-
-      files.each do |input_path|
-        basename = File.basename(input_path, ".*")
-        output_path = if output_dir
-                        File.join(output_dir, "#{basename}.svg")
-                      else
-                        File.join(input_dir, "#{basename}.svg")
-                      end
-
-        begin
-          ps_content = File.read(input_path)
-          svg_output = Postsvg.convert(ps_content)
-          File.write(output_path, svg_output)
-          say "  ✓ #{input_path} → #{output_path}", :green
-        rescue Postsvg::Error => e
-          say "  ✗ #{input_path}: #{e.message}", :red
-        rescue StandardError => e
-          say "  ✗ #{input_path}: Unexpected error: #{e.message}", :red
-        end
+      files.each do |path|
+        convert_in_batch(path, input_dir, output_dir)
       end
     end
 
@@ -99,5 +87,64 @@ module Postsvg
     def version
       say "postsvg version #{Postsvg::VERSION}"
     end
+
+    private
+
+    def handle_input(input_path, output_path, reader, direction:)
+      unless File.exist?(input_path)
+        say "Error: Input file '#{input_path}' not found", :red
+        exit 1
+      end
+
+      output = reader.call(File.read(input_path))
+      if output_path
+        File.write(output_path, output)
+        say "Converted #{input_path} -> #{output_path} (#{direction})", :green
+      else
+        puts output
+      end
+    rescue Postsvg::Error => e
+      say "Conversion error: #{e.message}", :red
+      exit 2
+    rescue StandardError => e
+      say "Unexpected error: #{e.message}", :red
+      say e.backtrace.join("\n"), :red if options[:verbose]
+      exit 2
+    end
+
+    def read_ps_to_svg(content)
+      Postsvg.to_svg(content)
+    end
+
+    def read_svg_to_ps(content)
+      Postsvg.to_ps(content)
+    end
+
+    def read_svg_to_eps(content)
+      Postsvg.to_eps(content)
+    end
+
+    def convert_in_batch(path, input_dir, output_dir)
+      ext = File.extname(path).downcase
+      basename = File.basename(path, ".*")
+      out_ext =
+        case ext
+        when ".svg" then ".ps"
+        else ".svg"
+        end
+      out_dir = output_dir || input_dir
+      out_path = File.join(out_dir, "#{basename}#{out_ext}")
+
+      content = File.read(path)
+      output =
+        case ext
+        when ".svg" then Postsvg.to_ps(content)
+        else Postsvg.to_svg(content)
+        end
+      File.write(out_path, output)
+      say "  #{path} -> #{out_path}", :green
+    rescue Postsvg::Error => e
+      say "  #{path}: #{e.message}", :red
+    end
   end
 end

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/errors.rb

@@ -1,11 +1,76 @@
 # frozen_string_literal: true
 
 module Postsvg
+  # Base class for every Postsvg error. rescue this to catch anything
+  # Postsvg raises.
   class Error < StandardError; end
 
-  class ParseError < Error; end
+  # Lexing or parsing failed. Carries +source_position+ when known.
+  class ParseError < Error
+    attr_reader :source_position
 
-  class ConversionError < Error; end
+    def initialize(message, source_position: nil)
+      @source_position = source_position
+      super(message)
+    end
+  end
 
-  class UnsupportedOperatorError < Error; 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 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
+
+  # SVG -> PS translation failed.
+  class TranslationError < Error
+    attr_reader :element_name
+
+    def initialize(message, element_name: nil)
+      @element_name = element_name
+      super(message)
+    end
+  end
+
+  # Encountered an SVG element type with no registered handler.
+  class UnsupportedElementError < TranslationError; end
+
+  # A reference (clip-path, gradient, pattern) could not be resolved.
+  class UnresolvedReferenceError < TranslationError; end
+
+  # Model -> PS source serialization failed.
+  class SerializeError < Error; end
+
+  # Legacy aliases kept so older rescue clauses still match.
+  ConversionError = RenderError
+  UnsupportedOperatorError = UndefinedOperatorError
+
+  # Internal control-flow signals used by the visitor to unwind
+  # loops and stop program execution. These are NOT user-facing
+  # errors — they are caught by the Renderer.
+  class ExitSignal < StandardError; end
+  class QuitSignal < StandardError; 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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # Immutable graphics state snapshot. Mutations return new instances
+  # via +with(...)+. The GraphicsStack pushes/pops these.
+  #
+  # Fields mirror PLRM §7.2 graphics state operators. Optional fields
+  # are +nil+ meaning "not set in this state"; the renderer falls back
+  # to defaults at emit time.
+  class GraphicsContext
+    attr_reader :ctm, :fill_color, :stroke_color, :stroke_width,
+                :line_cap, :line_join, :miter_limit, :dash,
+                :font_name, :font_size, :clip_paths, :last_text_position,
+                :fill_rule
+
+    DEFAULTS = {
+      ctm: Matrix.new,
+      fill_color: Color::BLACK,
+      stroke_color: Color::BLACK,
+      stroke_width: 1.0,
+      line_cap: :butt,
+      line_join: :miter,
+      miter_limit: 10.0,
+      dash: nil,
+      font_name: "Helvetica",
+      font_size: 12.0,
+      clip_paths: [],
+      last_text_position: nil,
+      fill_rule: :nonzero,
+    }.freeze
+
+    def initialize(**fields)
+      merged = DEFAULTS.merge(fields)
+      @ctm = merged[:ctm]
+      @fill_color = merged[:fill_color]
+      @stroke_color = merged[:stroke_color]
+      @stroke_width = merged[:stroke_width]
+      @line_cap = merged[:line_cap]
+      @line_join = merged[:line_join]
+      @miter_limit = merged[:miter_limit]
+      @dash = merged[:dash]
+      @font_name = merged[:font_name]
+      @font_size = merged[:font_size]
+      @clip_paths = merged[:clip_paths].freeze
+      @last_text_position = merged[:last_text_position]
+      @fill_rule = merged[:fill_rule]
+      freeze
+    end
+
+    def with(**overrides)
+      GraphicsContext.new(
+        ctm: overrides.fetch(:ctm, @ctm),
+        fill_color: overrides.fetch(:fill_color, @fill_color),
+        stroke_color: overrides.fetch(:stroke_color, @stroke_color),
+        stroke_width: overrides.fetch(:stroke_width, @stroke_width),
+        line_cap: overrides.fetch(:line_cap, @line_cap),
+        line_join: overrides.fetch(:line_join, @line_join),
+        miter_limit: overrides.fetch(:miter_limit, @miter_limit),
+        dash: overrides.fetch(:dash, @dash),
+        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),
+        fill_rule: overrides.fetch(:fill_rule, @fill_rule),
+      )
+    end
+
+    def push_clip_path(path_d)
+      with(clip_paths: @clip_paths + [path_d])
+    end
+
+    def identity_ctm?
+      @ctm.identity?
+    end
+
+    def clipped?
+      !@clip_paths.empty?
+    end
+  end
+end

data/lib/postsvg/graphics_stack.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # LIFO stack of immutable GraphicsContext snapshots. +gsave+ pushes
+  # a duplicate of the current top; +grestore+ pops. Popping an empty
+  # stack is a no-op (mirrors PLRM §7.2.2).
+  class GraphicsStack
+    def initialize(initial: GraphicsContext.new)
+      @stack = [initial]
+    end
+
+    def current
+      @stack.last
+    end
+
+    def push
+      @stack.push(current)
+      self
+    end
+    alias gsave push
+
+    def pop
+      return current if @stack.size == 1
+
+      @stack.pop
+      current
+    end
+    alias grestore pop
+
+    def depth
+      @stack.size
+    end
+
+    def replace(new_state)
+      @stack[-1] = new_state
+      new_state
+    end
+
+    def update(**overrides)
+      replace(current.with(**overrides))
+    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