etassia 0.1.0

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

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require_relative "../../../text_measurement"
+require_relative "../../plantuml_data/boxes/table_box"
+require_relative "detour"
+require_relative "frame_ports"
+require_relative "label_fan"
+require_relative "metrics"
+require_relative "packer"
+require_relative "paths"
+require_relative "ranking"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Places a {Graph}: each container lays out its own children in
+        # ranks, outermost container last. Links are cut at the box edges.
+        class Layout
+          MARGIN = 16.0
+          PAD = 16.0
+          TITLE_HEIGHT = 30.0
+          # A cloud's cut, bumped outline needs this much more room on each
+          # side, across and down, before it clears what it holds.
+          CLOUD_ROOM = [5.0, 0.0].freeze
+          # An untitled cloud has no header to take that room, and the JAR
+          # leaves a little more above and below what it holds.
+          UNTITLED_CLOUD_ROOM = [5.0, 2.15].freeze
+
+          # @param graph [Graph]
+          # @return [Scene]
+          def call(graph, **)
+            reset(graph)
+            top = arrange(nil)
+            placed = []
+            place(top, [MARGIN, MARGIN + title_room], 0, placed)
+            scene(top, placed)
+          end
+
+          private
+
+          def reset(graph)
+            @graph = graph
+            @sizes = {}
+            @frame_ports = FramePorts.new(@sizes)
+            @ports = {}
+            @inner = {}
+            @inset = {}
+            @paths = Paths.new(left_to_right? ? 0 : 1)
+          end
+
+          def scene(top, placed)
+            Scene.new(width: [top.width + (2 * MARGIN), title_width].max,
+                      height: top.height + (2 * MARGIN) + title_room,
+                      placed: placed, routes: routes(placed),
+                      title: @graph.title)
+          end
+
+          def title_room
+            @graph.title ? TITLE_HEIGHT : 0.0
+          end
+
+          def title_width
+            return 0.0 unless @graph.title
+
+            Metrics.text_width([@graph.title]) + (2 * MARGIN)
+          end
+
+          # Lays out the children of `scope` and records their sizes.
+          def arrange(scope)
+            ports, children = split_ports(scope)
+            (ports + children).each { |child| measure(child) }
+            ranking = Ranking.new(children, pairs(scope))
+            packed = pack(ranking, scope)
+            scope ? frame(packed, scope, ports) : packed
+          end
+
+          def pack(ranking, scope)
+            packer = Packer.new(@sizes, left_to_right: left_to_right?,
+                                        reach: label_reach(scope))
+            packer.route(packer.pack(ranking.layers), ranking.chains)
+          end
+
+          # How wide the widest label on a link of each item of `scope` is:
+          # neighbours are kept this far apart so the labels fan out.
+          def label_reach(scope)
+            @graph.edges.each_with_object(Hash.new(0.0)) do |edge, reach|
+              width = label_width(edge)
+              ends(edge, scope).each do |item|
+                reach[item] = [reach[item], width].max
+              end
+            end
+          end
+
+          def ends(edge, scope)
+            [edge.from, edge.to].filter_map { |node| lift(node, scope) }
+          end
+
+          def label_width(edge)
+            text = edge.label.to_s
+            return 0.0 if text.empty?
+
+            Drawing::Face.width(text, size: 12).to_f
+          end
+
+          # The children of `scope` on its frame, then the rest.
+          def split_ports(scope)
+            @graph.children_of(scope).partition do |node|
+              FramePorts.on_frame?(node)
+            end.tap { |ports, _| @ports[scope] = ports }
+          end
+
+          def left_to_right?
+            @graph.direction == :left_to_right
+          end
+
+          def frame(packed, scope, ports)
+            packed.width = [packed.width, @frame_ports.width(ports)].max
+            packed.width += 2 * PAD
+            packed.height += top_inset(scope) + bottom_inset(scope)
+            packed
+          end
+
+          def measure(node)
+            return @sizes[node] = Metrics.size(node) unless node.container?
+
+            inner = @inner[node] = arrange(node)
+            @sizes[node] = [[inner.width, Metrics.header_width(node)].max,
+                            inner.height]
+            inflate_cloud(node)
+          end
+
+          def inflate_cloud(node)
+            return @sizes[node] unless node.kind == :cloud
+
+            inset = @inset[node] = cloud_room(node)
+            @sizes[node] = @sizes[node].zip(inset).map do |size, room|
+              size + (2 * room)
+            end
+          end
+
+          def cloud_room(node)
+            Metrics.untitled?(node) ? UNTITLED_CLOUD_ROOM : CLOUD_ROOM
+          end
+
+          # A container with ports on its top keeps its children a rank
+          # below them, as the JAR does; likewise for the bottom.
+          def top_inset(node)
+            return FramePorts::REACH if ports_on?(node, :portin)
+
+            PAD + Metrics.header_height(node)
+          end
+
+          def bottom_inset(node)
+            ports_on?(node, :portout) ? FramePorts::REACH : PAD
+          end
+
+          def ports_on?(node, kind)
+            @ports[node].any? { |port| port.kind == kind }
+          end
+
+          def pairs(scope)
+            @graph.edges.filter_map do |edge|
+              from = lift(edge.from, scope)
+              to = lift(edge.to, scope)
+              ranked(edge, from, to) if inner?(from, to)
+            end
+          end
+
+          # Whether a link is between two items that take part in ranking.
+          def inner?(from, to)
+            return false unless from && to && !from.equal?(to)
+
+            [from, to].none? { |node| FramePorts.on_frame?(node) }
+          end
+
+          # `[from, to, step]`, the ends swapped when the link reads backwards.
+          def ranked(edge, from, to)
+            ends = edge.backwards ? [to, from] : [from, to]
+            [*ends, edge.rank_step]
+          end
+
+          def lift(node, scope)
+            chain = node.ancestors + [node]
+            return chain.first unless scope
+
+            at = chain.index { |entry| entry.equal?(scope) }
+            at && chain[at + 1]
+          end
+
+          def place(packed, origin, depth, placed)
+            @paths.record(packed.paths, origin)
+            packed.offsets.each do |node, (x_pos, y_pos)|
+              width, height = @sizes[node]
+              placed << Placed.new(node: node, x: origin[0] + x_pos,
+                                   y: origin[1] + y_pos, width: width,
+                                   height: height, depth: depth)
+              place_inside(placed.last, depth, placed) if node.container?
+            end
+          end
+
+          def place_inside(box, depth, placed)
+            place(@inner[box.node], inside_origin(box), depth + 1, placed)
+            placed.concat(@frame_ports.place(box, @ports[box.node], depth + 1))
+          end
+
+          def inside_origin(box)
+            room = @inset.fetch(box.node, [0.0, 0.0])
+            [box.x + PAD + room[0], box.y + room[1] + top_inset(box.node)]
+          end
+
+          def routes(placed)
+            boxes = placed.to_h { |box| [box.node, terminal(box)] }
+            detour = Detour.new(placed)
+            found = @graph.edges.filter_map do |edge|
+              route(edge, boxes, detour)
+            end
+            LabelFan.new(axis).call(found)
+            found
+          end
+
+          def axis
+            left_to_right? ? 0 : 1
+          end
+
+          def route(edge, boxes, detour)
+            from, to = boxes.values_at(edge.from, edge.to)
+            return if from.equal?(to)
+
+            points = segment(from, to, edge, @paths.between(edge, center(from)))
+            Route.new(edge: edge, points: bent(detour, edge, points))
+          end
+
+          # A note's pointer and a line to a row stay straight.
+          def bent(detour, edge, points)
+            straight = edge.pointer || edge.from_row || edge.to_row
+            straight ? points : detour.call(edge, points)
+          end
+
+          # What a link ends at: the square of a port on a frame, otherwise
+          # the box itself.
+          def terminal(box)
+            FramePorts.on_frame?(box.node) ? @frame_ports.terminal(box) : box
+          end
+
+          # `between` is where a link across ranks passes the ranks it
+          # skips.
+          def segment(from, to, edge, between)
+            a = center(from)
+            b = center(to)
+            [end_at(from, edge.from_row, a, between.first || b),
+             *between,
+             end_at(to, edge.to_row, b, between.last || a)]
+          end
+
+          def end_at(box, row, inner, toward)
+            row_end(box, row, toward) || clip(box, inner, toward)
+          end
+
+          # The middle of the row of a map or object box that a line ends
+          # at, on the side facing `toward`.
+          def row_end(box, row, toward)
+            return unless row
+
+            side = toward[0] >= center(box)[0] ? box.x + box.width : box.x
+            [side, PlantUMLData::Boxes::TableBox
+              .row_middle(box.node.table, row, box.y)]
+          end
+
+          def center(box)
+            [box.x + (box.width / 2), box.y + (box.height / 2)]
+          end
+
+          # The point where the line from `inner` toward `outer` leaves `box`.
+          def clip(box, inner, outer)
+            delta = [outer[0] - inner[0], outer[1] - inner[1]]
+            return inner if delta.all?(&:zero?)
+
+            scale = exit_scale(box, delta)
+            inner.zip(delta).map { |pos, change| pos + (change * scale) }
+          end
+
+          def exit_scale(box, delta)
+            [box.width, box.height].zip(delta).map do |extent, change|
+              extent / 2 / (change.abs.nonzero? || 1e-9)
+            end.min
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "edge"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # What the arrow of a link says: its line style, colour, thickness
+        # and which end carries a head.
+        class Link
+          LINE_STYLES = %w[dashed dotted].freeze
+
+          attr_reader :color, :color2, :width
+
+          def initialize(arrow)
+            @arrow = arrow
+            @options = arrow[/\[(.*)\]/, 1].to_s.split(/[,;]/).map(&:strip)
+            colours = @options.filter_map { |o| o[/\A#(\w+)\z/, 1] }
+            @color, @color2 = colours
+            @width = @options.filter_map { |o| o[/\Athickness=(\d+)/, 1] }
+              .first.to_i
+            @width = 1 if @width < 1
+          end
+
+          # @return [Edge] the line this arrow draws from `from` to `to`;
+          #   `rest` is the label and the rows it starts and ends at
+          def edge(from, to, **rest)
+            Edge.new(from: from, to: to, style: style, head: head,
+                     color: color, color2: color2, width: width,
+                     rank_step: rank_step, backwards: backwards?, **rest)
+          end
+
+          def bare
+            @arrow.gsub(/\[.*\]/, "")
+          end
+
+          def hidden?
+            @options.include?("hidden")
+          end
+
+          # @return [Symbol] :dashed or :solid
+          def style
+            dashed = bare.include?(".") || @options.intersect?(LINE_STYLES)
+            dashed ? :dashed : :solid
+          end
+
+          # @return [Integer] how many ranks on the target sits: a direction
+          #   word says it (`down` and `up` one, `left` and `right` none),
+          #   otherwise the line is one shorter than it is long, as in the
+          #   PlantUML JAR (`->` none, `-->` one, `--->` two)
+          def rank_step
+            word = bare[/#{References::DIRECTION}/o]
+            return word.match?(/up|down/) ? 1 : 0 if word
+
+            [bare.count("-.=") - 1, 0].max
+          end
+
+          # @return [Boolean] whether `up` or `left` reads the link from the
+          #   target
+          def backwards?
+            bare.match?(/(?:up|left)(?![[:alpha:]])/)
+          end
+
+          # @return [Symbol, nil] :both, :target, :source, :socket or nil
+          def head
+            ends = [bare.start_with?("<"), bare.end_with?(">")]
+            return :both if ends.all?
+            return :target if ends.last
+            return :source if ends.first
+
+            bare.match?(/0\)|\(0|\)/) ? :socket : nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # `!define NAME body`: PlantUML's object-like macro. The definition
+        # is dropped and each later whole-word `NAME` becomes `body`.
+        # A macro with parameters is left alone, so the parser still names
+        # it as a preprocessor line.
+        module Macros
+          DEFINE = /\A!define\s+(?<name>\w+)(?:\s+(?<body>.*))?\z/
+
+          module_function
+
+          # @param entries [Array<Array(String, Integer)>] text and line number
+          # @return [Array<Array(String, Integer)>] the entries with every
+          #   plain definition expanded
+          def expand(entries)
+            table = {}
+            entries.filter_map do |text, number|
+              if (match = text.match(DEFINE))
+                table[match[:name]] = substitute(match[:body].to_s, table)
+                next
+              end
+              [substitute(text, table), number]
+            end
+          end
+
+          def substitute(text, table)
+            table.reduce(text) do |line, (name, body)|
+              line.gsub(/(?<!\w)#{Regexp.escape(name)}(?!\w)/) { body }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../../../text_measurement"
+require_relative "../../plantuml_data/boxes/table_box"
+require_relative "archimate"
+require_relative "entity_metrics"
+require_relative "usecase_ellipse"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The size of each shape, from the text it carries.
+        module Metrics
+          FONT_SIZE = 14
+          LINE_HEIGHT = 16.4883
+          ASCENT = 13.5352
+          HEADER_PAD = 10.0
+
+          module_function
+
+          # @return [Array<String>] the stereotype line, if any, then the
+          #   label lines
+          def text_lines(node)
+            lines = node.lines.reject(&:empty?)
+            node.stereotype ? ["«#{node.stereotype}»"] + lines : lines
+          end
+
+          def text_width(lines)
+            lines.map do |line|
+              Drawing::Face.width(line, size: FONT_SIZE)
+            end.max.to_f
+          end
+
+          def text_height(lines)
+            [lines.size, 1].max * LINE_HEIGHT
+          end
+
+          # @return [Array(Float, Float)] width and height of a leaf node
+          def size(node)
+            case node.kind
+            when :entity then EntityMetrics.size(node)
+            when :data then data_size(node)
+            when :usecase then usecase_size(node)
+            else text_size(node)
+            end
+          end
+
+          def text_size(node)
+            lines = text_lines(node)
+            width = text_width(lines)
+            height = text_height(lines)
+            send(:"size_#{shape(node.kind)}", width, height + sprite_room(node))
+          end
+
+          def usecase_size(node)
+            widths = text_lines(node).map { |line| text_width([line]) }
+            UsecaseEllipse.size(widths, LINE_HEIGHT)
+          end
+
+          def sprite_room(node)
+            node.sprite ? Archimate::SPRITE_ROOM : 0.0
+          end
+
+          def data_size(node)
+            box = PlantUMLData::Boxes::TableBox.size(node.table)
+            [box.width, box.height]
+          end
+
+          def shape(kind)
+            return kind if %i[actor usecase component interface portin
+                              portout note database cloud node
+                              circle].include?(kind)
+
+            :box
+          end
+
+          def size_actor(width, height) = [[width, 26.0].max, 59.5 + height]
+
+          def size_component(width, height)
+            [width + 40, height + 30]
+          end
+
+          def size_interface(width, height) = [[width, 20.0].max, 28.0 + height]
+          def size_portin(width, height) = [[width, 14.0].max, 24.0 + height]
+          def size_portout(width, height) = [[width, 14.0].max, 12.0 + height]
+          def size_circle(width, height) = [[width, 16.0].max, 24.0 + height]
+          def size_note(width, height) = [width + 24, height + 16]
+          def size_database(width, height) = [width + 30, height + 40]
+
+          def size_cloud(width, height) = [width + 34, height + 31]
+
+          def size_node(width, height) = [width + 38, height + 28]
+          def size_box(width, height) = [width + 26, height + 20]
+
+          # @return [Float] the room a container's label takes at its top
+          def header_height(node)
+            lines = text_lines(node).reject(&:empty?)
+            return text_height(lines) + HEADER_PAD unless lines.empty?
+
+            node.kind == :cloud ? 0.0 : HEADER_PAD
+          end
+
+          def untitled?(node) = text_lines(node).empty?
+
+          def header_width(node)
+            text_width(text_lines(node)) + 28
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # One element of a use case, component or deployment diagram: an
+        # actor, a use case, a component, an interface, a deployment node or
+        # a container holding other nodes.
+        class Node
+          CONTAINER_KINDS = %i[package node database cloud rectangle folder
+                               frame storage artifact card namespace
+                               component].freeze
+
+          attr_reader :id, :parent
+          attr_accessor :kind, :lines, :stereotype, :color, :sections, :table,
+                        :sprite
+          attr_writer :container
+
+          # @param parent [Node, nil] the container this node sits in
+          def initialize(id:, kind:, lines: nil, parent: nil)
+            @id = id
+            @kind = kind
+            @lines = lines || [id]
+            @parent = parent
+            @container = false
+          end
+
+          def container?
+            @container
+          end
+
+          # @return [Array<Node>] the containers around this node, outermost
+          #   first
+          def ancestors
+            return [] unless parent
+
+            parent.ancestors + [parent]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../../../svg"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The pointer of a note: a pale triangle with its base on the note
+        # and its tip on the note's target.
+        class NoteTail
+          HALF = 4.0
+          FILL = "#FEFFDD"
+          STROKE = "#181818"
+
+          # @param points [Array<Array(Float, Float)>] the route, from the
+          #   note to its target
+          def initialize(points)
+            @base = points.first
+            @tip = points.last
+          end
+
+          # @return [Svg::Polygon]
+          def element
+            Svg::Polygon.new.tap do |polygon|
+              polygon.points = outline
+              polygon.fill = FILL
+              polygon.stroke = STROKE
+              polygon.stroke_width = "0.5"
+            end
+          end
+
+          private
+
+          def outline
+            across = normal
+            [offset(across, 1), @tip, offset(across, -1)]
+              .map { |point| point.map { |value| value.round(2) }.join(",") }
+              .join(" ")
+          end
+
+          def offset(across, sign)
+            [@base[0] + (sign * across[0]), @base[1] + (sign * across[1])]
+          end
+
+          # @return [Array(Float, Float)] half the base's width, at a right
+          #   angle to the route
+          def normal
+            dx = @tip[0] - @base[0]
+            dy = @tip[1] - @base[1]
+            scale = HALF / [Math.hypot(dx, dy), 1.0].max
+            [-dy * scale, dx * scale]
+          end
+        end
+      end
+    end
+  end
+end