etassia 0.1.0

data/lib/etassia/notation/plantuml/node_graph/ranking.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require_relative "skipped_ranks"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Puts the items of one scope into ranks and orders each rank, from
+        # the links between them. Source order breaks every tie, so the
+        # result is deterministic.
+        class Ranking
+          SWEEPS = 4
+
+          # @return [Array<Array<Object>>] the items of each rank, in order,
+          #   with a {Waypoint} in each rank a link skips
+          attr_reader :layers
+
+          # @return [Hash{Array => Array<Waypoint>}] for each `[from, to]`
+          #   that spans more than one rank, its waypoints from the rank
+          #   after `from`
+          attr_reader :chains
+
+          # @param items [Array<Object>] in source order
+          # @param pairs [Array<Array>] links between items, each
+          #   `[from, to, step]`: `to` sits `step` ranks after `from` (0 puts
+          #   them in one rank, with `from` first; 1 when omitted)
+          def initialize(items, pairs)
+            @items = items
+            @pairs = merged(pairs)
+            @forward = acyclic(@pairs)
+            @rank = items.to_h { |item| [item, 0] }
+            settle_ranks
+            sink_sources
+            @tie_order = tie_order
+            lay_out
+            order
+          end
+
+          private
+
+          def lay_out
+            @layers = @pairs.empty? ? grid : group
+            skips = SkippedRanks.new(@layers, @rank, @pairs, @forward)
+            @chains = skips.chains
+            @bound = skips.links
+          end
+
+          # Each pair once, with the longest step asked of it.
+          def merged(pairs)
+            pairs.reject { |a, b| a.equal?(b) }
+              .group_by { |a, b, _| [a.object_id, b.object_id] }
+              .values.map { |group| group.max_by { |_, _, step| step || 1 } }
+          end
+
+          # The links that remain once every link closing a cycle, found
+          # depth first in source order, is dropped.
+          def acyclic(pairs)
+            @adjacency = pairs.group_by(&:first)
+            @state = {}
+            @kept = []
+            @items.each { |item| descend(item) unless @state[item] }
+            @kept
+          end
+
+          def descend(item)
+            @state[item] = :open
+            @adjacency.fetch(item, []).each { |pair| follow(pair) }
+            @state[item] = :done
+          end
+
+          def follow(pair)
+            return if @state[pair[1]] == :open
+
+            @kept << pair
+            descend(pair[1]) unless @state[pair[1]]
+          end
+
+          # Longest path ranks: a link of step n puts its target n ranks
+          # after its source, a step of 0 puts both in one rank. Stops after
+          # a bounded number of sweeps, so links that cannot all hold (a
+          # one-rank link across a pair held in one rank) cannot loop.
+          def settle_ranks
+            (@items.size + 1).times do
+              break unless @forward.map { |link| hold?(*link) }.any?
+            end
+          end
+
+          # A group of items with no link in (items tied by a link of step 0
+          # move together) drops to the rank just before its nearest target,
+          # which shortens every link it has, as the JAR's ranking does.
+          def sink_sources
+            groups = same_rank_groups
+            groups.sort_by { |group| -@rank[group.first] }.each do |group|
+              target = sink_rank(group)
+              next unless target && target > @rank[group.first]
+
+              group.each { |item| @rank[item] = target }
+            end
+          end
+
+          # @return [Integer, nil] the rank before the nearest target of
+          #   `group`, when no link feeds it
+          def sink_rank(group)
+            return if fed?(group)
+
+            @forward.filter_map do |from, to, step|
+              next unless group.include?(from) && !group.include?(to)
+
+              @rank[to] - (step || 1)
+            end.min
+          end
+
+          # Whether a link from outside `group` ends in it.
+          def fed?(group)
+            @forward.any? do |from, to, _|
+              group.include?(to) && !group.include?(from)
+            end
+          end
+
+          def same_rank_groups
+            groups = @items.to_h { |item| [item, [item]] }
+            @forward.each do |from, to, step|
+              next unless step&.zero?
+
+              merged = groups[from] | groups[to]
+              merged.each { |item| groups[item] = merged }
+            end
+            groups.values.uniq
+          end
+
+          # @return [Boolean] whether the link moved a rank
+          def hold?(from, to, step)
+            step ||= 1
+            want = @rank[from] + step
+            ends = step.zero? ? [from, to] : [to]
+            want = ends.map { |item| @rank[item] }.push(want).max
+            ends.map { |item| @rank[item] < want && @rank[item] = want }.any?
+          end
+
+          # Items with no links between them are packed into the squarest
+          # grid, `ceil(sqrt(n))` to a rank, in source order, as the
+          # PlantUML JAR does.
+          def grid
+            @items.each_slice([Math.sqrt(@items.size).ceil, 1].max).to_a
+          end
+
+          def group
+            by_rank = @items.group_by { |item| @rank[item] }
+            (0..(by_rank.keys.max || -1)).map do |rank|
+              tied_first(by_rank.fetch(rank, []))
+            end
+          end
+
+          # A rank with its tied items (links of step 0) first, in the order
+          # their first tie was written; the JAR places the actor of the
+          # first `A -> (B)` left of an actor declared earlier but untied.
+          def tied_first(layer)
+            layer.sort_by.with_index do |item, at|
+              tie = @tie_order[item]
+              [tie ? 0 : 1, tie || 0, at]
+            end
+          end
+
+          # @return [Hash] each item tied to another by a step-0 link, to
+          #   the position of its first such link
+          def tie_order
+            order = {}
+            @pairs.each_with_index do |(from, to, step), at|
+              next unless step&.zero?
+
+              order[from] ||= at
+              order[to] ||= at
+            end
+            order
+          end
+
+          def order
+            SWEEPS.times do |pass|
+              down = pass.even?
+              sweep = down ? 1...@layers.size : (@layers.size - 2).downto(0)
+              sweep.each { |index| sort_layer(index, down ? -1 : 1) }
+            end
+          end
+
+          def sort_layer(index, step)
+            neighbour = @layers[index + step]
+            @layers[index] = @layers[index].sort_by.with_index do |item, at|
+              [barycentre(item, neighbour) || at, at]
+            end
+            @layers[index] = settled(@layers[index])
+          end
+
+          # The layer with every item after the items that must come first
+          # in its rank (links of step 0); an item goes right after the one
+          # it is tied to, otherwise the layer keeps its order.
+          def settled(layer)
+            rest = layer.dup
+            last = nil
+            Array.new(layer.size) do
+              last = pick_next(rest, last)
+              rest.delete_if { |item| item.equal?(last) }
+              last
+            end
+          end
+
+          def pick_next(rest, last)
+            ready = rest.reject { |item| before(item).intersect?(rest) }
+            ready.find { |item| before(item).include?(last) } ||
+              ready.first || rest.first
+          end
+
+          # The items a link of step 0 puts ahead of `item`.
+          def before(item)
+            @forward.filter_map do |from, to, step|
+              from if step&.zero? && to.equal?(item)
+            end
+          end
+
+          def barycentre(item, layer)
+            linked = @bound.filter_map do |a, b, _|
+              other = if a.equal?(item) then b elsif b.equal?(item) then a end
+              layer.index { |entry| entry.equal?(other) } if other
+            end
+            linked.sum.fdiv(linked.size) unless linked.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/node_graph/reader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "macros"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Splits PlantUML source into significant lines: the first diagram
+        # only, comments dropped and a label that runs over several lines
+        # joined into one.
+        module Reader
+          OPEN_QUOTE = /\A[[:alpha:]]+\s.*"[^"]*\z/
+          OPEN_BRACKET = /\A[[:alpha:]]+\s+\S+\s+\[[^\]]*\z/
+
+          module_function
+
+          # @return [Array<Array(String, Integer)>] stripped text and its
+          #   1-based line number
+          def entries(source)
+            lines = source.dup.force_encoding(Encoding::UTF_8).scrub.lines
+            numbered = lines.each_with_index.map { |l, i| [l.strip, i + 1] }
+            Macros.expand(merge(first_diagram(numbered)))
+          end
+
+          def first_diagram(numbered)
+            from = numbered.index { |text, _| text.start_with?("@start") }
+            body = numbered.drop(from ? from + 1 : 0)
+            body.take_while { |text, _| !text.start_with?("@end") }
+              .reject { |text, _| text.empty? || text.start_with?("'") }
+          end
+
+          def merge(entries)
+            queue = entries.dup
+            result = []
+            until queue.empty?
+              text, number = queue.shift
+              text = "#{text}\n#{queue.shift.first}" while open?(text) &&
+                  !queue.empty?
+              result << [text, number]
+            end
+            result
+          end
+
+          def open?(text)
+            text.match?(OPEN_BRACKET) ||
+              (text.match?(OPEN_QUOTE) && text.count('"').odd?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/node_graph/references.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The patterns that name a node in a link or a declaration.
+        module References
+          IDENT = /[\p{L}\p{N}_$]+/
+          BRACKET = /\[[^\]]+\]|\([^()]*\)|:[^:\n]+:/
+          REF = /#{BRACKET}|"[^"]+"|#{IDENT}/
+          DIRECTION = /(?:up|down|left|right)(?![[:alpha:]])/
+          ARROW = /<?<?[-.=]+(?:\[[^\]]*\]|#{DIRECTION})?
+                   [-.=]*(?:\(0\)|\(0|0\)|\))?[-.=]*>?>?/x
+          EDGE = /\A(?<a>#{REF})(?:::(?<aport>#{IDENT}))?\s*(?<arrow>#{ARROW})
+                  \s*(?<b>#{REF})(?:::(?<bport>#{IDENT}))?
+                  (?:\s*:\s*(?<label>.*))?\z/x
+          ER_LEFT = /\|o|\|\||\}o|\}\|/
+          ER_RIGHT = /o\||\|\||o\{|\|\{/
+          ER_EDGE = /\A(?<a>#{REF})\s+(?<l>#{ER_LEFT})(?<line>[-.]+)
+                     (?<r>#{ER_RIGHT})\s+(?<b>#{REF})
+                     (?:\s*:\s*(?<label>.*))?\z/x
+          STEREOTYPE = /<<\s*(?<st>.*?)\s*>>/
+          LEADING_COLOR = /\A\#(?<color>[0-9A-Fa-f]{3,8}|[A-Za-z]+)\s+/
+          COLOR = /\s+#(?<color>[0-9A-Fa-f]{3,8}|[A-Za-z]+)\z/
+
+          module_function
+
+          # @return [Array<String>] the lines of a label
+          def lines_of(text)
+            lines = text.to_s.split(/\\n|\n/).map(&:strip)
+            lines.empty? ? [""] : lines
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/node_graph/renderer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "../../../renderer/base"
+require_relative "../../../svg"
+require_relative "curve"
+require_relative "heads"
+require_relative "label_placer"
+require_relative "../creole"
+require_relative "layout"
+require_relative "note_tail"
+require_relative "shapes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Draws a {Scene}: containers, then links, then nodes, then labels.
+        class Renderer < Etassia::Renderer::Base
+          INK = "#181818"
+          DASH = "5,4"
+          TITLE_SIZE = 13
+          SECOND_OFFSET = "translate(2,2)"
+          NAMED = /\A[A-Za-z]+\z/
+
+          # @param scene [Scene]
+          # @return [Svg::Document]
+          def render(scene)
+            placements = LabelPlacer.new.call(scene.routes,
+                                              [*scene.placed,
+                                               *title_area(scene)])
+            document(scene, placements).tap do |document|
+              elements(scene, placements).each { |item| document << item }
+            end
+          end
+
+          private
+
+          # Wide and tall enough for the labels as well as the scene.
+          def document(scene, placements)
+            width = [scene.width, *placements.map(&:right)].max
+            height = [scene.height, *placements.map(&:bottom)].max
+            Svg::Document.new(width: width, height: height,
+                              view_box: "0 0 #{width} #{height}")
+          end
+
+          def elements(scene, placements)
+            containers, leaves = scene.placed.partition do |box|
+              box.node.container?
+            end
+            [*drawn(containers.sort_by(&:depth)), *scene.routes.flat_map do |r|
+              link(r)
+            end, *drawn(leaves), *labels(placements), *title(scene)]
+          end
+
+          def drawn(boxes)
+            shapes = Shapes.new
+            boxes.flat_map { |box| shapes.draw(box) }
+          end
+
+          def labels(placements)
+            placements.map do |placed|
+              text(placed.x, placed.y, placed.route.edge.label)
+            end
+          end
+
+          # The room the title takes, which no label covers.
+          def title_area(scene)
+            return [] unless scene.title
+
+            width = Drawing::Face.width(scene.title, size: TITLE_SIZE)
+            [Placed.new(x: (scene.width - width) / 2, y: 8.0, width: width,
+                        height: 18.0)]
+          end
+
+          def title(scene)
+            return [] unless scene.title
+
+            [text(scene.width / 2, 22, scene.title, "bold")]
+          end
+
+          # A note's pointer is a pale triangle from the note to its target.
+          def link(route)
+            edge = route.edge
+            return [NoteTail.new(route.points).element] if note?(edge)
+
+            points = route.points
+            [line(points, edge, ink(edge.color)), *heads(points, edge),
+             *second_stroke(points, edge)]
+          end
+
+          def heads(points, edge)
+            Heads.for(edge, points.first, points.last, ink(edge.color),
+                      [points[1], points[-2]])
+          end
+
+          # PlantUML draws `-[#blue;#green]->` as the line in each colour, the
+          # second two units right and down (measured on 1.2026.6).
+          def second_stroke(points, edge)
+            return [] unless edge.color2
+
+            [line(points, edge, ink(edge.color2)).tap do |copy|
+              copy.transform = SECOND_OFFSET
+            end]
+          end
+
+          def note?(edge)
+            edge.pointer
+          end
+
+          def line(points, edge, color)
+            return bent(points, edge, color) if points.size > 2
+
+            Svg::Line.new.tap do |line|
+              line.x1, line.y1 = points.first
+              line.x2, line.y2 = points.last
+              stroke(line, edge, color)
+            end
+          end
+
+          def bent(points, edge, color)
+            Svg::Path.new.tap do |path|
+              path.d = Curve.path(points)
+              path.fill = "none"
+              stroke(path, edge, color)
+            end
+          end
+
+          def stroke(line, edge, color)
+            line.stroke = color
+            line.stroke_width = edge.width.to_s
+            line.stroke_dasharray = DASH if edge.style == :dashed
+          end
+
+          def ink(color)
+            return INK unless color
+
+            color.match?(NAMED) ? color : "##{color}"
+          end
+
+          def text(x_pos, y_pos, content, weight = nil)
+            Svg::Text.new.tap do |node|
+              node.x = x_pos
+              node.y = y_pos
+              style_text(node, weight)
+              Creole.assign(node, content)
+            end
+          end
+
+          def style_text(node, weight)
+            node.text_anchor = "middle"
+            node.font_family = "sans-serif"
+            node.font_size = "12"
+            node.font_weight = weight
+            node.fill = "#000000"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/node_graph/scene.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # A node placed at final coordinates.
+        Placed = Struct.new(:node, :x, :y, :width, :height, :depth,
+                            keyword_init: true)
+
+        # A link routed between two placed nodes, as a list of points.
+        # `label_at` is the point the line passes through at its label, or
+        # nil.
+        Route = Struct.new(:edge, :points, :label_at, keyword_init: true)
+
+        # A laid-out diagram.
+        Scene = Struct.new(:width, :height, :placed, :routes, :title,
+                           keyword_init: true)
+      end
+    end
+  end
+end