etassia 0.1.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Whether a line segment passes through a box (Liang-Barsky): the part
+      # of the segment inside the box, if any, is a range of its length
+      # narrowed axis by axis.
+      module SegmentBox
+        extend self
+
+        # @param box [Array<Float>] left, top, right, bottom
+        # @param from [Array(Float, Float)] one end of the segment
+        # @param to [Array(Float, Float)] the other end
+        def crosses?(box, from, to)
+          span = [0.0, 1.0]
+          [0, 1].all? do |axis|
+            inside?(span, from[axis], to[axis], box[axis], box[axis + 2])
+          end
+        end
+
+        # Whether the segment lies within `gap` of the box, measured straight
+        # between them rather than along each axis, so a corner of the box is
+        # no further off than its sides.
+        # @param gap [Float] the farthest the segment may be from the box
+        def within?(box, from, to, gap)
+          distance(box, from, to) <= gap
+        end
+
+        private
+
+        # Zero when the segment crosses the box; otherwise the shortest
+        # reach is between a corner of the box and the segment, or between an
+        # end of the segment and the box.
+        def distance(box, from, to)
+          return 0.0 if crosses?(box, from, to)
+
+          corners = [box.values_at(0, 1), box.values_at(2, 1),
+                     box.values_at(2, 3), box.values_at(0, 3)]
+          [*corners.map { |corner| to_segment(corner, from, to) },
+           *[from, to].map { |end_point| to_box(end_point, box) }].min
+        end
+
+        def to_box(point, box)
+          Math.hypot([box[0] - point[0], 0, point[0] - box[2]].max,
+                     [box[1] - point[1], 0, point[1] - box[3]].max)
+        end
+
+        def to_segment(point, from, to)
+          near = nearest_on(point, from, to)
+          Math.hypot(point[0] - near[0], point[1] - near[1])
+        end
+
+        def nearest_on(point, from, to)
+          run = to.zip(from).map { |end_at, start| end_at - start }
+          share = share_of(point.zip(from).map { |at, start| at - start }, run)
+          from.zip(run).map { |start, part| start + (share * part) }
+        end
+
+        # How far along `run` the point `gone` from its start lies, kept
+        # within the segment.
+        def share_of(gone, run)
+          length = run.sum { |part| part * part }
+          return 0.0 if length.zero?
+
+          (gone.zip(run).sum { |at, part| at * part } / length).clamp(0.0, 1.0)
+        end
+
+        def inside?(span, start, finish, low, high)
+          delta = finish - start
+          return start.between?(low, high) if delta.zero?
+
+          overlaps?(span, [(low - start) / delta, (high - start) / delta])
+        end
+
+        def overlaps?(span, bounds)
+          first, last = bounds.minmax
+          span[0] = [span[0], first].max
+          span[1] = [span[1], last].min
+          span[0] <= span[1]
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/activation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # `activate X` or `deactivate X`, or the `++` and `--` that end a
+        # message line: a bar on the lifeline of `participant` opens or
+        # closes at this point. `color` is the fill of the bar it opens.
+        class Activation
+          attr_reader :participant, :phase, :color
+
+          # @param phase [Symbol] :on or :off
+          def initialize(participant:, phase:, color: nil)
+            @participant = participant
+            @phase = phase
+            @color = color
+            freeze
+          end
+
+          def on?
+            phase == :on
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/appearance.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "head_style"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # What skinparam and `<style>` set for a sequence diagram: the
+        # narrowest participant head, how a head's lines sit against each
+        # other, the {HeadStyle} of the heads, and the fill, text colour and
+        # text size of a fragment's keyword tab, and the widest line a message
+        # wraps at.
+        # A setting the source never made is nil, except `alignment` and
+        # `head_style`.
+        class Appearance
+          KEYS = %i[min_width alignment tab_fill tab_colour tab_size
+                    head_style max_message paint arrow_width].freeze
+          private_constant :KEYS
+
+          attr_reader :min_width, :tab_fill, :tab_colour, :tab_size,
+                      :max_message, :arrow_width
+
+          def initialize(**settings)
+            unknown = settings.keys - KEYS
+            raise ArgumentError, "unknown: #{unknown}" if unknown.any?
+
+            @settings = settings.freeze
+            @min_width, @tab_fill, @tab_colour, @tab_size, @max_message,
+              @arrow_width =
+              settings.values_at(:min_width, :tab_fill, :tab_colour, :tab_size,
+                                 :max_message, :arrow_width)
+            freeze
+          end
+
+          # @return [Symbol] :left, :center or :right
+          def alignment
+            @settings[:alignment] || :center
+          end
+
+          # @return [Hash{Symbol => String}] the colour each {Paint} role was
+          #   given
+          def paint
+            @settings[:paint] || {}
+          end
+
+          # @return [HeadStyle]
+          def head_style
+            @settings[:head_style] || HeadStyle.new
+          end
+
+          # @return [Appearance] this one with each setting `other` made
+          def merge(other)
+            Appearance.new(
+              **@settings.merge(other.made) { |_, mine, new| new || mine },
+              head_style: head_style.merge(other.head_style),
+              paint: paint.merge(other.paint),
+            )
+          end
+
+          protected
+
+          # The settings the source made, without the defaults.
+          def made
+            @settings.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/arrow_end.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # What is drawn at one end of an arrow. `glyph` is nil, :filled,
+        # :open, :upper, :lower, :upper_open, :lower_open or :cross; the
+        # half and cross glyphs are the ones written `\`, `/` and `x`.
+        # `circle` adds the ring written `o`.
+        class ArrowEnd
+          attr_reader :glyph, :circle
+
+          def initialize(glyph: nil, circle: false)
+            @glyph = glyph
+            @circle = circle
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/arrow_marks.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # The shapes drawn at one end of an arrow, measured against PlantUML.
+        # `inward` is +1 or -1: the side of the lifeline the shaft lies on.
+        class ArrowMarks
+          LENGTH = 10.0
+          HALF_WIDTH = 4.0
+          CROSS_CENTRE = 11.5
+          CROSS_HALF = 5.0
+          RING_RADIUS = 4.0
+          RING_SHIFT = 5.5
+          RING_LIFT = 0.75
+
+          # @return [Array(Array<Scene::Mark>, Float)] the shapes and the x
+          #   the shaft stops at
+          def self.for(arrow_end, at_x, at_y, inward)
+            new(arrow_end, at_x, at_y, inward).build
+          end
+
+          def initialize(arrow_end, x_pos, y_pos, inward)
+            @end = arrow_end
+            @x = x_pos
+            @y = y_pos
+            @inward = inward
+          end
+
+          def build
+            marks = []
+            shaft = @x
+            shaft = glyph_marks(marks) if @end.glyph
+            marks << ring if @end.circle
+            shaft = @x + (@inward * RING_RADIUS) if ring_alone?
+            [marks, shaft]
+          end
+
+          private
+
+          def ring_alone?
+            @end.circle && @end.glyph.nil?
+          end
+
+          def glyph_marks(marks)
+            return cross(marks) if @end.glyph == :cross
+
+            tip = @end.circle ? @x + (@inward * RING_SHIFT) : @x
+            marks.concat(half_or_head(tip))
+            tip
+          end
+
+          def half_or_head(tip)
+            back = tip + (@inward * LENGTH)
+            case @end.glyph
+            when :filled then [triangle(tip, back)]
+            when :open then open_head(tip, back)
+            when :upper then [half(tip, back, -HALF_WIDTH)]
+            when :lower then [half(tip, back, HALF_WIDTH)]
+            when :upper_open then [stroke([tip, @y], [back, @y - HALF_WIDTH])]
+            else [stroke([tip, @y], [back, @y + HALF_WIDTH])]
+            end
+          end
+
+          def open_head(tip, back)
+            [stroke([tip, @y], [back, @y - HALF_WIDTH]),
+             stroke([tip, @y], [back, @y + HALF_WIDTH])]
+          end
+
+          def triangle(tip, back)
+            notch = tip + (@inward * 6.0)
+            polygon([[back, @y - HALF_WIDTH], [tip, @y],
+                     [back, @y + HALF_WIDTH], [notch, @y]])
+          end
+
+          def half(tip, back, side)
+            polygon([[tip, @y], [back, @y + side], [back, @y]])
+          end
+
+          def cross(marks)
+            centre = @x + (@inward * CROSS_CENTRE)
+            [-CROSS_HALF, CROSS_HALF].each do |slant|
+              marks << stroke([centre - CROSS_HALF, @y - slant],
+                              [centre + CROSS_HALF, @y + slant], heavy: true)
+            end
+            centre
+          end
+
+          def polygon(points)
+            list = points.map { |px, py| "#{px},#{py}" }.join(" ")
+            Scene::Mark.new(kind: "polygon", filled: @end.glyph != :open,
+                            points: list)
+          end
+
+          def stroke(from, to, heavy: false)
+            Scene::Mark.new(kind: "line", x1: from[0], y1: from[1],
+                            x2: to[0], y2: to[1], heavy: heavy)
+          end
+
+          def ring
+            Scene::Mark.new(kind: "circle", cx: @x, cy: @y - RING_LIFT,
+                            r: RING_RADIUS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/arrow_style.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "arrow_end"
+require_relative "keyword_defaults"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # How a message is drawn: the two ends, a dashed or solid shaft, and
+        # which side a message to its own sender loops out on.
+        class ArrowStyle
+          DRAWN = { leftward: false, hidden: false, colour: nil }.freeze
+          private_constant :DRAWN
+
+          attr_reader :head, :tail, :dashed, :leftward, :hidden, :colour
+
+          # @param head [ArrowEnd] the end at the receiver
+          # @param tail [ArrowEnd] the end at the sender
+          # @param leftward [Boolean] written `<-`; only a message to its own
+          #   sender draws differently for it
+          # @param hidden [Boolean] written `-[hidden]>`: laid out, not drawn
+          # @param colour [String, nil] written `-[#22A722]>`
+          def initialize(head:, tail: ArrowEnd.new, dashed: false, **drawn)
+            drawn = KeywordDefaults.resolve(drawn, DRAWN)
+            @head = head
+            @tail = tail
+            @dashed = dashed
+            @leftward = drawn[:leftward]
+            @hidden = drawn[:hidden]
+            @colour = drawn[:colour]
+            freeze
+          end
+
+          def self.plain(glyph, dashed: false)
+            new(head: ArrowEnd.new(glyph: glyph), dashed: dashed)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/arrow_syntax.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "arrow_style"
+require_relative "fill"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # Reads the arrow between two participant names: `->`, `<<--`, `o->x`,
+        # `-\\`, `<->`. Returns nil for a token outside the forms checked
+        # against PlantUML, so the parser refuses the line by name.
+        module ArrowSyntax
+          extend self
+
+          # The arrow as a part of a longer pattern. A leading or trailing
+          # o/x is a decoration only when blanks, or a `[` or `]` or `?` edge,
+          # separate it from the names.
+          EXTRA = "(?:(?i:hidden|bold|dashed|dotted)|" \
+                  '\#(?:\h{3}(?:\h{3})?|[a-zA-Z]+))'
+          BRACKET = "\\[#{EXTRA}(?:,#{EXTRA})*\\]".freeze
+          SOURCE =
+            '(?:(?<=[ \t\[])[oxOX])?(?:<<|<|//|/|\\\\\\\\|\\\\)?' \
+            "-(?:#{BRACKET})?-?" \
+            '(?:>>|>|\\\\\\\\|\\\\|//|/)?(?:[oxOX](?=[ \t\]?]|\z))?'.freeze
+          TOKEN = /\A([oxOX])?(<<|<|\/\/|\/|\\\\|\\)?(--?)
+                   (>>|>|\\\\|\\|\/\/|\/)?([oxOX])?\z/x
+          EXTRAS = /\[([^\]]*)\]/
+          HIDDEN = /\bhidden\b/i
+          DASHED = /\b(?:dashed|dotted)\b/i
+          COLOUR = /(\#(?:\h{6}|\h{3}|[a-z]+))/i
+          LEFT = { "<<" => :open, "<" => :filled, "//" => :upper_open,
+                   "/" => :upper, "\\\\" => :lower_open,
+                   "\\" => :lower }.freeze
+          RIGHT = { ">>" => :open, ">" => :filled, "\\\\" => :upper_open,
+                    "\\" => :upper, "//" => :lower_open,
+                    "/" => :lower }.freeze
+
+          # `-[hidden]>` takes its row and its label's room but draws nothing.
+          # `-[#22A722]>` and `-[#red]>` draw the shaft and head in that
+          # colour; `dashed` and `dotted` draw the shaft dashed; `bold` is
+          # read and, as in PlantUML 1.2026.6, changes nothing.
+          #
+          # @return [Array(ArrowStyle, Boolean), nil] the style and whether
+          #   the arrow is written pointing at the sender's name
+          def read(token)
+            match = TOKEN.match(plain(token)) or return
+
+            from_parts(match.captures, token)
+          end
+
+          private
+
+          def from_parts(parts, token)
+            lead, left, shaft, right, trail = parts
+            return unless fits?(lead, left, right, trail) && colour?(token)
+
+            build(ends(lead, left, LEFT), ends(trail, right, RIGHT),
+                  shaft.length == 2 || dashed?(token),
+                  !left.nil? && right.nil?, looks(token))
+          end
+
+          def plain(token)
+            token.sub(EXTRAS, "")
+          end
+
+          def extras(token)
+            token[EXTRAS, 1].to_s
+          end
+
+          def dashed?(token)
+            DASHED.match?(extras(token))
+          end
+
+          # A colour in the brackets must be one PlantUML is known to draw.
+          def colour?(token)
+            written = extras(token)[COLOUR, 1]
+            written.nil? || !Fill.read(written).nil?
+          end
+
+          def looks(token)
+            written = extras(token)
+            { hidden: HIDDEN.match?(written),
+              colour: Fill.read(written[COLOUR, 1])&.colour }
+          end
+
+          # Pairs of glyph and decoration for one side; `x` beside a head
+          # replaces it, `x` alone and `o` are decorations.
+          def ends(mark, glyph, table)
+            cross = mark&.downcase == "x"
+            kind = cross && glyph ? :cross : table[glyph]
+            ArrowEnd.new(glyph: kind || (:cross if cross),
+                         circle: mark&.downcase == "o")
+          end
+
+          def build(left, right, dashed, reversed, looks)
+            head, tail = reversed ? [left, right] : [right, left]
+            [ArrowStyle.new(head: head, tail: tail, dashed: dashed,
+                            leftward: reversed, **looks), reversed]
+          end
+
+          # Only the combinations measured against PlantUML.
+          def fits?(lead, left, right, trail)
+            return false unless left || right
+
+            paired?(left, right) && crossable?(lead, left, "<") &&
+              crossable?(trail, right, ">")
+          end
+
+          def paired?(left, right)
+            !(left && right) || (left == "<" && right == ">")
+          end
+
+          # `x` replaces a plain head only.
+          def crossable?(mark, glyph, plain)
+            mark&.downcase != "x" || glyph.nil? || glyph == plain
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/bar_tracker.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # Pairs each activation with its deactivation into a bar on the
+        # lifeline. Bars still open when {#finish} is called end there; a
+        # bar opened inside another is drawn half a bar width to the right.
+        class BarTracker
+          WIDTH = 10.0
+
+          attr_reader :bars
+
+          # @param centre [#call] x of a participant's lifeline, by id
+          def initialize(centre)
+            @centre = centre
+            @bars = []
+            @open = Hash.new { |hash, id| hash[id] = [] }
+          end
+
+          def depth(id)
+            @open[id].size
+          end
+
+          # @param at [Float] the y where the bar starts or ends
+          def apply(activation, at)
+            id = activation.participant
+            return @open[id] << [at, activation.color] if activation.on?
+
+            emit(id, *@open[id].pop, at)
+          end
+
+          def finish(bottom)
+            @open.each do |id, tops|
+              emit(id, *tops.pop, bottom) until tops.empty?
+            end
+          end
+
+          def destroy(id, bottom)
+            tops = @open[id]
+            emit(id, *tops.pop, bottom) until tops.empty?
+          end
+
+          private
+
+          def emit(id, top, color, bottom)
+            shift = @open[id].size * (WIDTH / 2)
+            @bars << Scene::Bar.new(x: (@centre.call(id) - (WIDTH / 2)) + shift,
+                                    y: top, width: WIDTH, fill: color,
+                                    height: [bottom - top, 0.0].max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/box.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # A `box "title" ... endbox` grouping of neighbouring participants.
+        # `members` are participant ids; `title` is the source text; `fill` is
+        # the {Fill} written after the title, or nil.
+        class Box
+          attr_reader :title, :members, :fill
+
+          def initialize(title:, members:, fill: nil)
+            @title = title
+            @members = members.freeze
+            @fill = fill
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/chrome.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # The header, footer, caption and legend written around a sequence
+        # diagram. Each text is its lines joined by "\n"; `legend_place` is
+        # "<top|bottom> <left|center|right>".
+        class Chrome
+          DEFAULT_PLACE = "bottom center"
+          KINDS = %i[header footer caption legend].freeze
+
+          # @param texts [Hash{Symbol => String}] a text per kind in KINDS
+          # @param legend_place [String, nil]
+          def initialize(texts = {}, legend_place: nil)
+            @texts = texts.slice(*KINDS).freeze
+            @legend_place = legend_place || DEFAULT_PLACE
+            freeze
+          end
+
+          NONE = new
+
+          attr_reader :legend_place
+
+          # @return [String, nil]
+          def text(kind)
+            @texts[kind]
+          end
+
+          # @return [Array<String>] the lines of one kind, empty if unset
+          def lines(kind)
+            @texts.fetch(kind, "").split("\n")
+          end
+
+          # @return [Hash{Symbol => String}]
+          def to_h
+            @texts
+          end
+
+          # @return [Symbol] :top or :bottom
+          def legend_edge
+            legend_place.split.first.to_sym
+          end
+
+          # @return [Symbol] :left, :center or :right
+          def legend_side
+            legend_place.split.last.to_sym
+          end
+
+          # @param kind [Symbol] one of KINDS
+          # @return [Chrome] this chrome with one more text
+          def with(kind, text, place = legend_place)
+            Chrome.new(@texts.merge(kind => text), legend_place: place)
+          end
+        end
+      end
+    end
+  end
+end