etassia 0.1.0

data/lib/etassia/notation/plantuml/style_reader.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "caption"
+require_relative "package_color"
+require_relative "style_sheet"
+require_relative "unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Reads the lines between `<style>` and `</style>` one at a time.
+      #
+      # Only `document { <kind> { ... } }` is read, with BackGroundColor on
+      # the document and BackGroundColor, FontColor and FontSize on a Caption
+      # kind. Any other selector or property raises {UnsupportedConstructError}
+      # by name, so a style is never half applied.
+      class StyleReader
+        DOCUMENT = "document"
+        PROPERTIES = { "backgroundcolor" => :background,
+                       "fontcolor" => :colour, "fontsize" => :size }.freeze
+        OPENING = /\A(\.?\w+)[ \t]*\{\z/
+        # Element rules (`state { ... }`, `.hot { ... }`) belong to
+        # {Style::Reader}; this reader steps over them.
+        ELEMENTS = %w[classdiagram statediagram activitydiagram class state
+                      activity note arrow].freeze
+        PROPERTY = /\A(\w+)[ \t]+(\S+)\z/
+        CLOSING_TAG = %r{\A</style>\z}i
+        private_constant :DOCUMENT, :PROPERTIES, :ELEMENTS, :OPENING, :PROPERTY,
+                         :CLOSING_TAG
+
+        def initialize
+          @path = []
+          @skipped = 0
+          @background = nil
+          @rules = {}
+        end
+
+        # @param text [String] one stripped line inside the block
+        # @param number [Integer] its line in the source
+        # @return [Symbol] :closed when the line ended the block, else :open
+        # @raise [UnsupportedConstructError] on a selector or property not read
+        # @raise [Etassia::Parser::ParseError] when the block closes with a
+        #   selector still open
+        def feed(text, number)
+          if CLOSING_TAG.match?(text)
+            refuse_open_selector(number)
+            return :closed
+          end
+
+          read_rule(text, number)
+          :open
+        end
+
+        # @return [StyleSheet]
+        def sheet
+          StyleSheet.new(background: @background, rules: @rules.freeze)
+        end
+
+        private
+
+        def read_rule(text, number)
+          return skip_element_rule(text) if skipping?(text)
+
+          if (match = OPENING.match(text))
+            open_selector(match[1], text, number)
+          elsif text == "}" && !@path.empty?
+            @path.pop
+          else
+            read_property(text, number)
+          end
+        end
+
+        def read_property(text, number)
+          match = PROPERTY.match(text)
+          return refuse("style rule form", text, number) unless match
+
+          set(match[1].downcase, match[2], text, number)
+        end
+
+        def skipping?(text)
+          @skipped.positive? || element_rule?(text)
+        end
+
+        def element_rule?(text)
+          match = OPENING.match(text)
+          return false unless match && @path.empty?
+
+          match[1].start_with?(".") || ELEMENTS.include?(match[1].downcase)
+        end
+
+        def skip_element_rule(text)
+          if OPENING.match?(text) || text.end_with?("{")
+            @skipped += 1
+          elsif text == "}"
+            @skipped -= 1
+          end
+        end
+
+        def refuse_open_selector(number)
+          return if @path.empty? && @skipped.zero?
+
+          raise Etassia::Parser::ParseError,
+                "Parse error: line #{number} closes the style block " \
+                "with #{@path.last || 'a rule'} still open"
+        end
+
+        def open_selector(name, text, number)
+          word = name.downcase
+          allowed = @path.empty? ? [DOCUMENT] : caption_kinds_at_document
+          unless allowed.include?(word)
+            refuse("style selector #{name}", text, number)
+          end
+
+          @path << word
+        end
+
+        def caption_kinds_at_document
+          return [] unless @path == [DOCUMENT]
+
+          Caption::KINDS.map(&:to_s)
+        end
+
+        def set(property, value, text, number)
+          name = PROPERTIES[property]
+          unless settable?(name)
+            refuse("style property #{property}", text, number)
+          end
+
+          parsed = parse(name, value, text, number)
+          return @background = parsed if @path.size == 1
+
+          (@rules[@path.last.to_sym] ||= {})[name] = parsed
+        end
+
+        # A document sets only its background; a caption kind sets any.
+        def settable?(name)
+          scope = @path.size
+          name && (scope == 2 || (scope == 1 && name == :background))
+        end
+
+        def parse(name, value, text, number)
+          return font_size(value, text, number) if name == :size
+
+          PackageColor.hex(value) || refuse("style colour", text, number)
+        end
+
+        def font_size(value, text, number)
+          return value.to_i if value.match?(/\A[1-9]\d{0,2}\z/)
+
+          refuse("style font size", text, number)
+        end
+
+        def refuse(construct, text, number)
+          raise UnsupportedConstructError.new(construct: construct,
+                                              line: number, text: text)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style_sheet.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # What a `<style>` block sets: the canvas `background` and, for each
+      # Caption kind, a Hash with any of :background, :colour and :size.
+      class StyleSheet
+        EMPTY_RULE = {}.freeze
+
+        attr_reader :background, :rules
+
+        def initialize(background: nil, rules: {})
+          @background = background
+          @rules = rules
+          freeze
+        end
+
+        # @param kind [Symbol] a Caption kind
+        # @return [Hash] the properties the block set, possibly none
+        def rule(kind)
+          @rules.fetch(kind, EMPTY_RULE)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/styled_relation_curve.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # PlantUML routes a link written with a bracketed style such as
+      # `-[#blue,thickness=8]->` as a spline, not a chord. Across one rank a
+      # shallow link leaves its box flatter than the chord and arrives
+      # steeper (measured on 1.2026.6: a link 468 wide and 95 deep starts at
+      # about 0.8 of the chord slope and ends at about 1.75 of it). A steep
+      # link stays on its chord.
+      module StyledRelationCurve
+        extend self
+
+        SHALLOW_SLOPE = 0.5
+        REACH = 0.4
+        DEPARTURE = 0.3
+        ARRIVAL = 0.6
+        LABEL_AT = 0.65
+        LABEL_WEIGHTS = [(1 - LABEL_AT)**3,
+                         3 * ((1 - LABEL_AT)**2) * LABEL_AT,
+                         3 * (1 - LABEL_AT) * (LABEL_AT**2),
+                         LABEL_AT**3].freeze
+        private_constant :SHALLOW_SLOPE, :REACH, :DEPARTURE, :ARRIVAL,
+                         :LABEL_AT, :LABEL_WEIGHTS
+
+        # @param relation [Relation]
+        # @param from [Array(Float, Float)] the left end
+        # @param to [Array(Float, Float)] the right end
+        # @return [Array(Array, Array), nil] the two cubic control points, or
+        #   nil when the link is not a styled, shallow one
+        def controls(relation, from, to)
+          return unless styled?(relation)
+
+          run = to[0] - from[0]
+          rise = to[1] - from[1]
+          return unless shallow?(run, rise)
+
+          [point(from, run, rise, REACH, DEPARTURE),
+           point(to, -run, -rise, REACH, ARRIVAL)]
+        end
+
+        # @return [Array(Float, Float), nil] the curve's point at LABEL_AT,
+        #   which {#controls} puts off the chord; nil when the link stays on
+        #   its chord
+        def label_point(relation, from, to)
+          points = controls(relation, from, to)
+          return unless points
+
+          [from, *points, to].transpose.map do |axis|
+            axis.zip(LABEL_WEIGHTS).sum { |value, weight| value * weight }
+          end
+        end
+
+        private
+
+        def shallow?(run, rise)
+          run.abs * SHALLOW_SLOPE > rise.abs && rise != 0
+        end
+
+        def point(origin, run, rise, reach, share)
+          [origin[0] + (run * reach), origin[1] + (rise * share)]
+        end
+
+        def styled?(relation)
+          relation.color || relation.width || relation.dotted?
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/timing/arrows.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Timing
+        # Draws a message as an arrow from one track to another, with its
+        # text beside it.
+        class Arrows
+          BLUE = "#00008B"
+          HEAD = 7.5
+          WING = 2.74
+          STROKE = "1.5"
+          LABEL_SIZE = 14
+          # Where the JAR sets a message's text from the tip: pulled back
+          # along the arrow, then below the tip of a rising arrow and above
+          # that of a falling one.
+          PULL = 7.518
+          BELOW = 7.98
+          ABOVE = -8.11
+          private_constant :BLUE, :HEAD, :WING, :STROKE, :LABEL_SIZE,
+                           :PULL, :BELOW, :ABOVE
+
+          # @param pen [Drawing::Pen]
+          # @param axis [Axis]
+          # @param lookup [#call] `(participant id, time)` to the [x, y] of
+          #   that participant's signal at that time
+          def initialize(pen, axis, lookup)
+            @pen = pen
+            @axis = axis
+            @lookup = lookup
+          end
+
+          def draw(message)
+            tail = point(message.from, message.time)
+            tip = point(message.to, message.arrives || message.time)
+            @pen.line(*tail, *tip, stroke: BLUE, stroke_width: STROKE)
+            head(tail, tip)
+            label(message.text, tail, tip)
+          end
+
+          private
+
+          def point(id, time)
+            [@axis.x(time), @lookup.call(id, time)]
+          end
+
+          # PlantUML sets the message in serif, just under the arrow's tip.
+          def label(text, tail, tip)
+            dir = tail == tip ? [0.0, -1.0] : unit(tail, tip)
+            drop = dir.last.positive? ? ABOVE : BELOW
+            @pen.text(text, tip[0] - (PULL * dir.first),
+                      tip[1] + drop - (PULL * dir.last), fill: BLUE,
+                                                         family: "Serif",
+                                                         size: LABEL_SIZE)
+          end
+
+          def head(tail, tip)
+            return if tail == tip
+
+            dir = unit(tail, tip)
+            base = [tip[0] - (HEAD * dir[0]), tip[1] - (HEAD * dir[1])]
+            @pen.polygon([tip, wing(base, dir, WING), wing(base, dir, -WING)],
+                         fill: BLUE, stroke: BLUE, stroke_width: STROKE)
+          end
+
+          def unit(tail, tip)
+            delta = tip.zip(tail).map { |to, from| to - from }
+            length = Math.hypot(*delta)
+            delta.map { |part| part / length }
+          end
+
+          # A point `side` away from `base`, across the arrow.
+          def wing(base, dir, side)
+            [base[0] - (side * dir[1]), base[1] + (side * dir[0])]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/timing/axis.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Timing
+        # Maps times to x positions. The span runs from the first time to a
+        # little past the last. Ticks fall on a regular step: the `scale`
+        # unit, or else the greatest common divisor of the change times and
+        # clock periods, each step drawn 50 pixels wide as PlantUML does.
+        # Where no step exists (fractional or dated times without a scale),
+        # the span fills `plot` pixels and ticks fall on every time.
+        class Axis
+          TAIL = 0.25
+          FALLBACK_SPAN = 100.0
+          STEP_PIXELS = 50.0
+
+          attr_reader :start, :finish
+
+          # @param diagram [Diagram]
+          # @param left [Float] x of the first time
+          # @param plot [Float] width in pixels when the source gives no scale
+          def initialize(diagram, left, plot)
+            @diagram = diagram
+            @left = left
+            times = moments
+            @start = times.min || 0.0
+            last = times.max || @start
+            span = last > @start ? last - @start : FALLBACK_SPAN
+            @step = tick_step
+            @finish = last + (@step || (span * TAIL))
+            @pixels = diagram.pixels_per_unit || pixels_for(plot)
+          end
+
+          # @return [Float]
+          def x(time)
+            @left + ((time - @start) * @pixels)
+          end
+
+          # @return [Array<Float>] the times worth a tick, ascending
+          def ticks
+            return moments.uniq.sort unless @step
+
+            count = ((@finish - @start) / @step).floor
+            Array.new(count + 1) { |index| @start + (index * @step) }
+          end
+
+          # @return [Boolean] whether the tick at `time` carries its label
+          def labelled?(time)
+            return true unless @step && !@diagram.pixels_per_unit
+
+            named_times.any? { |named| (named - time).abs < 1e-9 }
+          end
+
+          # @return [String] the tick's label
+          def label(time)
+            return Time.at(time).utc.strftime("%m/%d") if @diagram.dated
+
+            time == time.floor ? time.to_i.to_s : time.to_s
+          end
+
+          private
+
+          def pixels_for(plot)
+            return STEP_PIXELS / @step if @step
+
+            plot / (@finish - @start)
+          end
+
+          def tick_step
+            return @diagram.scale_units.to_f if @diagram.scale_units
+            return if @diagram.dated
+
+            common_divisor
+          end
+
+          def common_divisor
+            times = named_times
+            return unless times.all? { |time| time == time.floor }
+
+            step = times.map(&:to_i).reduce(0, :gcd)
+            step.to_f if step.positive?
+          end
+
+          def named_times
+            periods = @diagram.participants.values.filter_map(&:period)
+            @diagram.changes.map(&:time) + periods
+          end
+
+          def moments
+            d = @diagram
+            d.changes.map(&:time) +
+              d.messages.flat_map { |m| [m.time, m.arrives] }.compact +
+              d.highlights.flat_map { |h| [h.from, h.to] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/timing/layout.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../drawing"
+require_relative "arrows"
+require_relative "axis"
+require_relative "signals"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Timing
+        # Stacks one track per participant over a shared time axis, then
+        # lays highlights behind, messages across and the axis beneath.
+        class Layout
+          include Drawing::Pen
+
+          TOP = 20.0
+          MARGIN = 20.0
+          # Past the last tick the lanes' frame runs this far; below the
+          # axis the canvas keeps this much (tick, label and margin).
+          REACH = 5.0
+          FOOT = 33.0
+          PLOT = 420.0
+          MIN_LEFT = 25.0
+          RULE = "#333333"
+          TAB_HEIGHT = 17.5
+          TAB_SLANT = 10.0
+          GRID = "3,5"
+          private_constant :TOP, :PLOT, :MIN_LEFT, :RULE, :GRID,
+                           :TAB_HEIGHT, :TAB_SLANT, :MARGIN, :REACH, :FOOT
+
+          # @param diagram [Diagram]
+          # @return [Drawing::Scene]
+          def call(diagram, **)
+            @diagram = diagram
+            prepare
+            draw_backdrop
+            draw_foreground
+            scene(canvas_width, @bottom + FOOT)
+          end
+
+          private
+
+          def prepare
+            @left = left_width
+            @axis = Axis.new(@diagram, @left, PLOT)
+            @signals = Signals.new(self, @diagram, @axis, @left)
+            @tracks = stack
+            @bottom = @tracks.values.map { |top, size| top + size }.max || TOP
+            @right = @axis.x(@axis.finish) + REACH
+          end
+
+          # PlantUML counts a whole pixel past the right margin, and makes
+          # room for the widest lane name's tab.
+          def canvas_width
+            tabs = @diagram.participants.values.map { |p| tab_edge(p.title) }
+            ([@right, tabs.max.to_f + TAB_SLANT].max + MARGIN).floor + 1
+          end
+
+          def left_width
+            signals = Signals.new(self, @diagram, nil, 0)
+            leads = @diagram.participants.values.map { |p| signals.lead(p) }
+            [leads.max.to_f, MIN_LEFT].max
+          end
+
+          def stack
+            top = TOP
+            @diagram.participants.to_h do |id, participant|
+              size = @signals.height(participant)
+              entry = [id, [top, size]]
+              top += size
+              entry
+            end
+          end
+
+          def draw_backdrop
+            @diagram.highlights.each { |highlight| shade(highlight) }
+            @axis.ticks.each { |time| grid(@axis.x(time)) }
+          end
+
+          def draw_foreground
+            @diagram.participants.each_value { |p| track(p) }
+            sides
+            arrows = Arrows.new(self, @axis, method(:signal_point))
+            @diagram.messages.each { |message| arrows.draw(message) }
+            axis_line
+            @diagram.highlights.each { |highlight| caption(highlight) }
+          end
+
+          def sides
+            [MARGIN, @right].each do |x|
+              line(x, TOP, x, @bottom, stroke: RULE, stroke_width: "0.5")
+            end
+          end
+
+          def signal_point(id, time)
+            top, = @tracks.fetch(id)
+            @signals.y_at(@diagram.participants.fetch(id), top, time)
+          end
+
+          def shade(highlight)
+            left = @axis.x(highlight.from)
+            right = @axis.x(highlight.to)
+            rect(left, TOP, right - left, @bottom - TOP,
+                 fill: highlight.fill || "#EEEEEE", stroke: "none")
+            [left, right].each do |x|
+              line(x, TOP, x, @bottom, stroke: highlight.stroke || "#555555",
+                                       stroke_dasharray: "5,3",
+                                       stroke_width: "1.5")
+            end
+          end
+
+          def caption(highlight)
+            highlight.caption.to_s.split("\\n").each_with_index do |entry, row|
+              text(entry, @axis.x(highlight.from) + 4, TOP + 10 + (row * 14))
+            end
+          end
+
+          def grid(across)
+            line(across, TOP, across, @bottom, stroke: RULE,
+                                               stroke_width: "0.5",
+                                               stroke_dasharray: GRID)
+          end
+
+          def track(participant)
+            top, = @tracks.fetch(participant.id)
+            frame(participant.title, top)
+            @signals.draw_labels(participant, top)
+            @signals.draw(participant, top)
+          end
+
+          def frame(title, top)
+            line(MARGIN, top, @right, top, stroke: RULE, stroke_width: "0.5")
+            text(title, MARGIN + 5, top + 8.75, size: 14, bold: true,
+                                                fill: RULE)
+            tab(title, top)
+          end
+
+          # The outline PlantUML draws round a lane's name: a rule under the
+          # text that slants up to the lane's top edge.
+          def tab(title, top)
+            edge = tab_edge(title)
+            low = top + TAB_HEIGHT
+            line(MARGIN, low, edge, low, stroke: RULE, stroke_width: "0.5")
+            line(edge, low, edge + TAB_SLANT, top, stroke: RULE,
+                                                   stroke_width: "0.5")
+          end
+
+          def tab_edge(title)
+            MARGIN + 6 + Drawing::Face.width(title, size: 14, bold: true)
+          end
+
+          def axis_line
+            line(@axis.x(@axis.start), @bottom, @axis.x(@axis.finish),
+                 @bottom, stroke_width: "2", stroke: RULE)
+            @axis.ticks.each { |time| tick(time) }
+          end
+
+          def tick(time)
+            x = @axis.x(time)
+            line(x, @bottom, x, @bottom + 5)
+            return unless @axis.labelled?(time)
+
+            text(@axis.label(time), x, @bottom + 12.87, size: 11,
+                                                        anchor: "middle",
+                                                        fill: RULE)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/timing/model.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Timing
+        # A signal. `kind` is robust, concise, clock, binary or analog; a
+        # clock also has its period, pulse width and offset.
+        Participant = Struct.new(:id, :title, :kind, :period, :pulse, :offset,
+                                 keyword_init: true)
+
+        # A participant taking a state at a time. `fill` and `stroke` are
+        # CSS colours for a concise segment, or nil.
+        Change = Struct.new(:id, :time, :state, :fill, :stroke,
+                            keyword_init: true)
+
+        # An arrow from one participant to another.
+        Message = Struct.new(:from, :to, :time, :arrives, :text,
+                             keyword_init: true)
+
+        # A shaded band over every track, with an optional caption.
+        Highlight = Struct.new(:from, :to, :fill, :stroke, :caption,
+                               keyword_init: true)
+
+        # Everything the source says. `pixels_per_unit` and `scale_units` are
+        # nil unless a `scale` line set them; `dated` is true when times
+        # are dates.
+        Diagram = Struct.new(:participants, :changes, :messages, :highlights,
+                             :pixels_per_unit, :dated, :scale_units,
+                             keyword_init: true)
+      end
+    end
+  end
+end