postsvg 0.1.0 → 0.3.0

data/lib/postsvg/svg/paint.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    # Paint value object: resolves a CSS-style paint value to either
+    # a Color instance, a paint-server URL reference (gradient /
+    # pattern id), or :none.
+    Paint = Struct.new(:kind, :value, keyword_init: true) do
+      def self.parse(text)
+        return Paint.new(kind: :none) if text.nil? || text.strip == "none"
+
+        if text&.start_with?("url(")
+          id = text.match(/url\(\s*["']?#([^)\s"']+)/)
+          return Paint.new(kind: :reference, value: id && id[1])
+        end
+
+        color = begin
+          ::Postsvg::Color.parse(text.to_s)
+        rescue ArgumentError
+          nil
+        end
+        if color
+          Paint.new(kind: :color, value: color)
+        else
+          Paint.new(kind: :none)
+        end
+      end
+
+      def none? = kind == :none
+      def reference? = kind == :reference
+      def color? = kind == :color
+    end
+  end
+end

data/lib/postsvg/svg/parser.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Postsvg
+  module Svg
+    # Parses an SVG document via Nokogiri and produces an Svg::Document.
+    # Pure: no I/O, no global state.
+    class Parser
+      def self.call(svg_string)
+        doc = Nokogiri::XML(svg_string, &:noblanks)
+        root = doc.root
+        raise TranslationError, "no root element in SVG" unless root
+
+        Elements.load_all! # populate Element.registry with all known tag handlers
+        root_element = Element.from_node(root)
+        viewbox, width, height = extract_root_dimensions(root)
+        clip_paths = ClipPathRegistry.from_node(root)
+        Document.new(root_element: root_element,
+                     viewbox: viewbox,
+                     width: width,
+                     height: height,
+                     clip_paths: clip_paths)
+      end
+
+      def self.extract_root_dimensions(root)
+        vb = root["viewBox"]
+        width = root["width"]
+        height = root["height"]
+        parsed_vb =
+          if vb
+            nums = vb.split(/\s+|,/).map(&:to_f)
+            nums if nums.length == 4
+          end
+        [parsed_vb, width&.to_f, height&.to_f]
+      end
+    end
+  end
+end

data/lib/postsvg/svg/path_data/command.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    module PathData
+      # Single SVG path command. Opcode is upper-case (absolute) or
+      # lower-case (relative). +args+ is the raw numeric arguments.
+      Command = Struct.new(:opcode, :args, keyword_init: true) do
+        def absolute? = opcode == opcode.upcase
+
+        def relative? = opcode == opcode.downcase
+
+        def arity
+          case opcode.upcase
+          when "M", "L", "T" then 2
+          when "H", "V" then 1
+          when "C" then 6
+          when "S", "Q" then 4
+          when "A" then 7
+          when "Z" then 0
+          else 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/postsvg/svg/path_data/parser.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    module PathData
+      # Tokenizer + parser for SVG path data. Handles the standard
+      # grammar from SVG 1.1 §8.3. Output is a list of Command value
+      # objects with normalized argument counts.
+      module Parser
+        module_function
+
+        COMMAND_RE = /([MmLlHhVvCcSsQqTtAaZz])/
+        ARG_RE = /(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)/.freeze
+
+        def parse(text)
+          return [] if text.nil? || text.empty?
+
+          commands = []
+          tokens = tokenize(text)
+          i = 0
+          while i < tokens.length
+            opcode = tokens[i]
+            i += 1
+            arity = arity_for(opcode)
+            if arity.zero?
+              commands << Command.new(opcode: opcode, args: [])
+              next
+            end
+
+            # Repeat: M / L / C etc. can have multiple coordinate
+            # tuples after a single opcode. Consume in groups of arity.
+            loop do
+              args, consumed = take_args(tokens, i, arity)
+              break unless consumed == arity
+
+              commands << Command.new(opcode: opcode, args: args)
+              i += consumed
+              # After moveto, implicit lineto for subsequent tuples.
+              opcode = (opcode == "M") ? "L" : (opcode == "m" ? "l" : opcode)
+              # For H/V/Z, no implicit repetition.
+              break if %w[H V Z h v z].include?(opcode)
+            end
+          end
+          commands
+        end
+
+        def arity_for(opcode)
+          case opcode.upcase
+          when "M", "L", "T" then 2
+          when "H", "V" then 1
+          when "C" then 6
+          when "S", "Q" then 4
+          when "A" then 7
+          when "Z" then 0
+          else 0
+          end
+        end
+
+        def tokenize(text)
+          text.to_s.gsub(/-/, " -")
+               .scan(/([MmLlHhVvCcSsQqTtAaZz])|(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)/)
+               .flatten.compact
+        end
+
+        NUMBER_ONLY_RE = /\A-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?\z/.freeze
+
+        def take_args(tokens, start, count)
+          args = []
+          consumed = 0
+          while consumed < count && start + consumed < tokens.length
+            tok = tokens[start + consumed]
+            break unless NUMBER_ONLY_RE.match?(tok.to_s)
+
+            args << tok.to_f
+            consumed += 1
+          end
+          [args, consumed]
+        end
+      end
+    end
+  end
+end

data/lib/postsvg/svg/path_data.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    # Parses the SVG path "d" attribute into a list of Command value
+    # objects. Each Command carries its opcode (M, L, C, Z, A, etc.)
+    # and its numeric arguments.
+    module PathData
+      autoload :Command, "postsvg/svg/path_data/command"
+      autoload :Parser, "postsvg/svg/path_data/parser"
+
+      def self.parse(text)
+        Parser.parse(text)
+      end
+    end
+  end
+end

data/lib/postsvg/svg/stroke.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    # Stroke style value object. Width is a Float (default 1.0),
+    # dasharray is an Array of Floats, dashoffset is a Float, linecap
+    # / linejoin are Symbols.
+    Stroke = Struct.new(:width, :dasharray, :dashoffset, :linecap, :linejoin,
+                        :miterlimit, keyword_init: true) do
+      def self.parse(node)
+        width = AttributeParser.number(node["stroke-width"], default: 1.0)
+        dasharray_raw = node["stroke-dasharray"]
+        dasharray =
+          if dasharray_raw && dasharray_raw != "none"
+            AttributeParser.number_list(dasharray_raw)
+          end
+        dashoffset = AttributeParser.number(node["stroke-dashoffset"], default: 0.0)
+        linecap = (node["stroke-linecap"] || "butt").to_sym
+        linejoin = (node["stroke-linejoin"] || "miter").to_sym
+        miterlimit = AttributeParser.number(node["stroke-miterlimit"], default: 10.0)
+        new(width: width, dasharray: dasharray, dashoffset: dashoffset,
+            linecap: linecap, linejoin: linejoin, miterlimit: miterlimit)
+      end
+
+      def default?
+        width == 1.0 && dasharray.nil? && dashoffset.zero? &&
+          linecap == :butt && linejoin == :miter && miterlimit == 10.0
+      end
+    end
+  end
+end

data/lib/postsvg/svg/transform_list.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Svg
+    # Parsed SVG transform attribute. Produces a list of
+    # Postsvg::Matrix instances that, multiplied in order, give the
+    # composite CTM for the element.
+    class TransformList
+      attr_reader :matrices
+
+      def initialize(matrices = [])
+        @matrices = matrices.freeze
+        freeze
+      end
+
+      def empty?
+        @matrices.empty?
+      end
+
+      def composite
+        return Matrix.new if @matrices.empty?
+
+        @matrices.reduce(Matrix.new) { |acc, m| acc.multiply(m) }
+      end
+
+      def self.parse(text)
+        return new if text.nil? || text.strip.empty?
+
+        matrices = []
+        text.scan(/(\w+)\s*\(([^)]*)\)/).each do |name, args|
+          nums = args.split(/[\s,]+/).map(&:to_f)
+          case name
+          when "matrix"
+            next unless nums.length == 6
+
+            matrices << Matrix.new(a: nums[0], b: nums[1], c: nums[2],
+                                   d: nums[3], e: nums[4], f: nums[5])
+          when "translate"
+            tx = nums[0] || 0
+            ty = nums[1] || 0
+            matrices << Matrix.new(e: tx, f: ty)
+          when "scale"
+            sx = nums[0] || 1
+            sy = nums.length > 1 ? nums[1] : sx
+            matrices << Matrix.new(a: sx, d: sy)
+          when "rotate"
+            angle = nums[0] || 0
+            matrices << Matrix.new.rotate(angle)
+          when "skewX"
+            matrices << Matrix.new.skew_x(nums[0] || 0)
+          when "skewY"
+            matrices << Matrix.new.skew_y(nums[0] || 0)
+          end
+        end
+        new(matrices)
+      end
+    end
+  end
+end

data/lib/postsvg/svg.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # SVG domain model. Built once from a Nokogiri-parsed document;
+  # consumed by the Translation layer (SVG -> PS).
+  #
+  # Svg::* value objects know nothing about PostScript. Their job is
+  # to present SVG semantics in a typed, immutable form.
+  module Svg
+    autoload :Element, "postsvg/svg/element"
+    autoload :OpenElement, "postsvg/svg/element"
+    autoload :Document, "postsvg/svg/document"
+    autoload :Parser, "postsvg/svg/parser"
+    autoload :AttributeParser, "postsvg/svg/attribute_parser"
+    autoload :Paint, "postsvg/svg/paint"
+    autoload :Stroke, "postsvg/svg/stroke"
+    autoload :TransformList, "postsvg/svg/transform_list"
+    autoload :PathData, "postsvg/svg/path_data"
+    autoload :ClipPathRegistry, "postsvg/svg/clip_path_registry"
+    autoload :Elements, "postsvg/svg/elements"
+  end
+end

data/lib/postsvg/svg_builder.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Postsvg
+  # Append-only SVG emitter. The Renderer / Visitors call methods on a
+  # builder instance; #to_s finalizes and returns the SVG string.
+  #
+  # Determinism invariants:
+  # - Two runs of the same input produce byte-equal output.
+  # - IDs (clip1, grad1, pattern1) start at 1 on every SvgBuilder.new.
+  # - Floats formatted through FormatNumber.
+  # - <defs> block orders clipPaths, gradients, then patterns by
+  #   registration order so output is reproducible.
+  class SvgBuilder
+    CLIP_PREFIX = "clip".freeze
+    GRADIENT_PREFIX = "grad".freeze
+    PATTERN_PREFIX = "pattern".freeze
+
+    def initialize
+      @buffer = String.new(capacity: 4096)
+      @defs_buffer = String.new(capacity: 1024)
+      @body_buffer = String.new(capacity: 4096)
+      @clip_paths = {}     # path_d -> id
+      @gradients = {}      # signature -> id
+      @patterns = {}       # signature -> id
+      @next_clip_id = 1
+      @next_gradient_id = 1
+      @next_pattern_id = 1
+      @svg_open = false
+      @group_depth = 0
+      @header_height = nil
+    end
+
+    def open_svg(viewbox:, width:, height:)
+      raise RenderError, "svg already open" if @svg_open
+
+      @svg_open = true
+      @header_height = height
+      @buffer << %(<?xml version="1.0" encoding="UTF-8"?>\n)
+      @buffer << %(<svg xmlns="http://www.w3.org/2000/svg" )
+      @buffer << %(viewBox="#{viewbox}" )
+      @buffer << %(width="#{num(width)}" height="#{num(height)}">\n)
+      self
+    end
+
+    def open_y_flip_group
+      open_group(transform: "translate(0 #{num(@header_height)}) scale(1 -1)")
+    end
+
+    def open_group(transform: nil, clip_path_id: nil)
+      attrs = +""
+      attrs << %( transform="#{transform}") if transform
+      attrs << %( clip-path="url(##{clip_path_id})") if clip_path_id
+      @body_buffer << %(<g#{attrs}>\n)
+      @group_depth += 1
+      self
+    end
+
+    def close_group
+      raise RenderError, "no open group" if @group_depth.zero?
+
+      @body_buffer << %(</g>\n)
+      @group_depth -= 1
+      self
+    end
+
+    # Register a clip path. Returns the id used. If +path_d+ was
+    # previously registered, returns the existing id (dedup).
+    def register_clip_path(path_d)
+      return @clip_paths[path_d] if @clip_paths.key?(path_d)
+
+      id = "#{CLIP_PREFIX}#{@next_clip_id}"
+      @next_clip_id += 1
+      @clip_paths[path_d] = id
+      @defs_buffer << %(<clipPath id="#{id}"><path d="#{path_d}" /></clipPath>\n)
+      id
+    end
+
+    def register_linear_gradient(stops:, x1:, y1:, x2:, y2:)
+      sig = gradient_signature("linear", stops, [x1, y1, x2, y2])
+      return @gradients[sig] if @gradients.key?(sig)
+
+      id = "#{GRADIENT_PREFIX}#{@next_gradient_id}"
+      @next_gradient_id += 1
+      @gradients[sig] = id
+      @defs_buffer << %(<linearGradient id="#{id}" )
+      @defs_buffer << %(x1="#{num(x1)}" y1="#{num(y1)}" )
+      @defs_buffer << %(x2="#{num(x2)}" y2="#{num(y2)}">\n)
+      stops.each do |stop|
+        @defs_buffer << %(<stop offset="#{num(stop[:offset])}" )
+        @defs_buffer << %(stop-color="#{stop[:color].to_svg}" />\n)
+      end
+      @defs_buffer << %(</linearGradient>\n)
+      id
+    end
+
+    def register_radial_gradient(stops:, cx:, cy:, r:, fx: nil, fy: nil)
+      fx ||= cx
+      fy ||= cy
+      sig = gradient_signature("radial", stops, [cx, cy, r, fx, fy])
+      return @gradients[sig] if @gradients.key?(sig)
+
+      id = "#{GRADIENT_PREFIX}#{@next_gradient_id}"
+      @next_gradient_id += 1
+      @gradients[sig] = id
+      @defs_buffer << %(<radialGradient id="#{id}" )
+      @defs_buffer << %(cx="#{num(cx)}" cy="#{num(cy)}" r="#{num(r)}" )
+      @defs_buffer << %(fx="#{num(fx)}" fy="#{num(fy)}">\n)
+      stops.each do |stop|
+        @defs_buffer << %(<stop offset="#{num(stop[:offset])}" )
+        @defs_buffer << %(stop-color="#{stop[:color].to_svg}" />\n)
+      end
+      @defs_buffer << %(</radialGradient>\n)
+      id
+    end
+
+    def register_pattern(width:, height:, body_blocks:)
+      sig = "pattern:#{width}:#{height}:#{body_blocks.join('|')}"
+      return @patterns[sig] if @patterns.key?(sig)
+
+      id = "#{PATTERN_PREFIX}#{@next_pattern_id}"
+      @next_pattern_id += 1
+      @patterns[sig] = id
+      @defs_buffer << %(<pattern id="#{id}" )
+      @defs_buffer << %(width="#{num(width)}" height="#{num(height)}" )
+      @defs_buffer << %(patternUnits="userSpaceOnUse">\n)
+      body_blocks.each { |b| @defs_buffer << b }
+      @defs_buffer << %(</pattern>\n)
+      id
+    end
+
+    # Emit a <path>. +mode+ is one of :fill, :stroke, :fill_and_stroke.
+    def path(d:, mode:, color: nil, stroke_color: nil,
+             stroke_width: nil, line_cap: nil, line_join: nil,
+             dash: nil, clip_path_id: nil, fill_id: nil)
+      attrs = +"d=\"#{d}\""
+
+      attrs << case mode
+               when :fill
+                 fill_attr(color, fill_id)
+               when :stroke
+                 %( fill="none" stroke="#{color_attr(stroke_color || color)}")
+               when :fill_and_stroke
+                 "#{fill_attr(color, fill_id)} stroke=\"#{color_attr(stroke_color || color)}\""
+               else
+                 %( fill="none" stroke="none")
+               end
+
+      attrs << %( stroke-width="#{num(stroke_width)}") if stroke_width && stroke_width != 1.0
+      attrs << %( stroke-linecap="#{line_cap}") if line_cap && line_cap != :butt
+      attrs << %( stroke-linejoin="#{line_join}") if line_join && line_join != :miter
+      attrs << %( stroke-dasharray="#{dash}") if dash
+      attrs << %( clip-path="url(##{clip_path_id})") if clip_path_id
+
+      @body_buffer << %(<path #{attrs} />\n)
+      self
+    end
+
+    def text(content:, x:, y:, font_family:, font_size:, color:,
+             transform: nil)
+      attrs = +""
+      attrs << %( transform="#{transform}") if transform
+      attrs << %( x="#{num(x)}" y="#{num(y)}")
+      attrs << %( font-family="#{escape(font_family)}")
+      attrs << %( font-size="#{num(font_size)}")
+      attrs << %( fill="#{color_attr(color)}")
+      @body_buffer << %(<text#{attrs}>#{escape(content)}</text>\n)
+      self
+    end
+
+    def image(href:, x:, y:, width:, height:, transform: nil)
+      attrs = +""
+      attrs << %( transform="#{transform}") if transform
+      attrs << %( x="#{num(x)}" y="#{num(y)}")
+      attrs << %( width="#{num(width)}" height="#{num(height)}")
+      attrs << %( href="#{escape(href)}")
+      @body_buffer << %(<image#{attrs} />\n)
+      self
+    end
+
+    def comment(text)
+      @body_buffer << %(<!-- #{escape(text)} -->\n)
+      self
+    end
+
+    def close_svg
+      raise RenderError, "svg not open" unless @svg_open
+      raise RenderError, "unclosed groups: #{@group_depth}" if @group_depth.positive?
+
+      @buffer << "<defs>\n" unless @clip_paths.empty? && @gradients.empty? && @patterns.empty?
+      @buffer << @defs_buffer
+      @buffer << "</defs>\n" unless @clip_paths.empty? && @gradients.empty? && @patterns.empty?
+      @buffer << @body_buffer
+      @buffer << "</svg>\n"
+      @svg_open = false
+      self
+    end
+
+    def to_s
+      raise RenderError, "svg not closed" if @svg_open
+
+      @buffer.dup
+    end
+
+    # Expose internal buffers for testing only.
+    def buffer_size
+      @buffer.bytesize + @defs_buffer.bytesize + @body_buffer.bytesize
+    end
+
+    def registered_clip_count
+      @clip_paths.size
+    end
+
+    def registered_gradient_count
+      @gradients.size
+    end
+
+    private
+
+    def num(value)
+      FormatNumber.call(value)
+    end
+
+    def color_attr(color)
+      return "none" if color.nil?
+
+      color.is_a?(Color) ? color.to_svg : color.to_s
+    end
+
+    def fill_attr(color, fill_id)
+      return %( fill="url(##{fill_id})") if fill_id
+
+      %( fill="#{color_attr(color)}")
+    end
+
+    def gradient_signature(kind, stops, coords)
+      stops_str = stops.map { |s| "#{s[:offset]}:#{s[:color]}" }.join(",")
+      "#{kind}|#{stops_str}|#{coords.map { |c| num(c) }.join(',')}"
+    end
+
+    def escape(text)
+      text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+          .gsub("'", "&#39;")
+    end
+  end
+end

data/lib/postsvg/translation/arc_converter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Postsvg
+  module Translation
+    # SVG endpoint-to-center arc parametrization converter. Implements
+    # the algorithm documented in the SVG 1.1 implementation notes
+    # (appendix F.6.5). Returns the PS-style center parametrization:
+    # center x/y, normalized radii, rotation, and start/end angles.
+    module ArcConverter
+      EPSILON = 1e-12
+
+      module_function
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+      def endpoint_to_center(x1:, y1:, rx:, ry:, x_axis_rotation:,
+                             large_arc:, sweep:, x2:, y2:)
+        rx = rx.abs
+        ry = ry.abs
+        # If the endpoints coincide, the arc is degenerate.
+        return [x1, y1, 0.0, 0.0, 0.0, 0.0, 0.0] if rx < EPSILON || ry < EPSILON
+
+        phi = x_axis_rotation * Math::PI / 180.0
+        cos_phi = Math.cos(phi)
+        sin_phi = Math.sin(phi)
+
+        # Step 1: rotate and scale (x1,y1) into the unit-circle frame.
+        dx = (x1 - x2) / 2.0
+        dy = (y1 - y2) / 2.0
+        x1p =  cos_phi * dx + sin_phi * dy
+        y1p = -sin_phi * dx + cos_phi * dy
+
+        # Ensure radii are large enough; if not, scale them up.
+        rx_sq = rx * rx
+        ry_sq = ry * ry
+        x1p_sq = x1p * x1p
+        y1p_sq = y1p * y1p
+        lambda = (x1p_sq / rx_sq) + (y1p_sq / ry_sq)
+        if lambda > 1.0
+          sqrt_lambda = Math.sqrt(lambda)
+          rx *= sqrt_lambda
+          ry *= sqrt_lambda
+          rx_sq = rx * rx
+          ry_sq = ry * ry
+        end
+
+        # Step 2: compute center (cx', cy') in the rotated frame.
+        sign = (large_arc == sweep) ? -1 : 1
+        num = rx_sq * ry_sq - rx_sq * y1p_sq - ry_sq * x1p_sq
+        den = rx_sq * y1p_sq + ry_sq * x1p_sq
+        den = EPSILON if den.abs < EPSILON
+        coef = sign * Math.sqrt([num / den, 0.0].max)
+        cxp =  coef * (rx * y1p) / ry
+        cyp = -coef * (ry * x1p) / rx
+
+        # Step 3: rotate (cx', cy') back into original frame.
+        cx = cos_phi * cxp - sin_phi * cyp + (x1 + x2) / 2.0
+        cy = sin_phi * cxp + cos_phi * cyp + (y1 + y2) / 2.0
+
+        # Step 4: compute angles.
+        ux = (x1p - cxp) / rx
+        uy = (y1p - cyp) / ry
+        vx = (-x1p - cxp) / rx
+        vy = (-y1p - cyp) / ry
+
+        theta1 = angle_between(1.0, 0.0, ux, uy)
+        delta_theta = angle_between(ux, uy, vx, vy) % (2 * Math::PI)
+        delta_theta -= 2 * Math::PI if !sweep && delta_theta.positive?
+
+        theta2 = theta1 + delta_theta
+
+        [cx, cy, rx, ry, phi, theta1 * 180.0 / Math::PI, theta2 * 180.0 / Math::PI]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+
+      def angle_between(ux, uy, vx, vy)
+        dot = ux * vx + uy * vy
+        len = Math.sqrt((ux * ux + uy * uy) * (vx * vx + vy * vy))
+        return 0.0 if len < EPSILON
+
+        cos_val = (dot / len).clamp(-1.0, 1.0)
+        sign = (ux * vy - uy * vx).negative? ? -1.0 : 1.0
+        sign * Math.acos(cos_val)
+      end
+    end
+  end
+end