etassia 0.1.0

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../../plantuml_data/boxes/json_reader"
+require_relative "../../plantuml_data/boxes/highlights"
+require_relative "../../plantuml_data/boxes/tree_builder"
+require_relative "box_reader"
+require_relative "edge"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # What the node parser needs for a `json` element mixed into a use
+        # case, component or deployment diagram, which PlantUML allows after
+        # `allowmixing`. The element is drawn as the boxes of a JSON
+        # diagram; a nested value is a box of its own, joined to its parent
+        # by a dashed line. A `map` or `object` element is a box of its own,
+        # read by {BoxReader}.
+        module DataReader
+          include BoxReader
+
+          MIXING = /\Aallow_?mixing\z/i
+          JSON_OPEN = /\Ajson\s+(?:"(?<label>[^"]+)"\s+as\s+)?
+                       (?<id>\w[\w.]*)\s*\{(?<body>.*)\z/mx
+
+          private
+
+          def take_data(text)
+            return unless @mixing
+
+            take_json(text) || take_map(text) || take_object(text)
+          end
+
+          def take_json(text)
+            return unless (match = text.match(JSON_OPEN))
+
+            root = tree(json_text(match[:body]))
+            data_node(match[:id], match[:label],
+                      Boxes::Table.new(id: match[:id], title: root_title(match),
+                                       rows: root.rows, kind: :inline))
+          end
+
+          def json_text(first)
+            text = "{#{first}"
+            while unbalanced?(text) && @index < @entries.size
+              text += "\n#{@entries[@index].first}"
+              @index += 1
+            end
+            text
+          end
+
+          def unbalanced?(text)
+            text.count("{") > text.count("}")
+          end
+
+          def tree(text)
+            value = PlantUMLData::Boxes::JsonReader.new.call(text)
+            PlantUMLData::Boxes::TreeBuilder
+              .new(PlantUMLData::Boxes::Highlights.new, inline: true)
+              .call(value)
+          end
+
+          def root_title(match)
+            match[:label] || match[:id]
+          end
+
+          def data_node(id, label, table)
+            node = @graph.node(id, :data, parent: @stack.last)
+            node.lines = [label || id]
+            node.table = table
+            node
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../../plantuml_data/boxes/renderer"
+require_relative "../../plantuml_data/boxes/scene"
+require_relative "../../plantuml_data/boxes/table_box"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Draws a `json` element placed in a use case, component or
+        # deployment diagram: the box a JSON diagram draws, with its corner
+        # where the layout put the node.
+        class DataShape
+          Boxes = PlantUMLData::Boxes
+
+          # @param placed [Placed]
+          def initialize(placed)
+            @placed = placed
+          end
+
+          # @return [Array<Svg::Element>]
+          def elements
+            Boxes::Renderer.new.render(scene).children
+          end
+
+          private
+
+          def scene
+            marks = Boxes::TableBox.draw(@placed.node.table, @placed.x,
+                                         @placed.y)
+            Boxes::Scene.new(width: @placed.x + @placed.width,
+                             height: @placed.y + @placed.height, marks: marks)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Bends a link around a box that its straight line would cross, as
+        # the PlantUML JAR routes a spline past what is in the way.
+        class Detour
+          CLEARANCE = 14.0
+          MAX_BENDS = 3
+          # How far apart the points tested along a line are.
+          STEP = 4.0
+          EDGE_MARGIN = 4.0
+          PORTS = %i[portin portout].freeze
+
+          # @param placed [Array<Placed>] every placed node
+          def initialize(placed)
+            @placed = placed.reject do |box|
+              PORTS.include?(box.node.kind)
+            end
+          end
+
+          # @return [Array<Array(Float, Float)>] `points` with the bends
+          #   needed to clear the boxes between its ends
+          def call(edge, points)
+            route = points.dup
+            boxes = obstacles(edge)
+            MAX_BENDS.times do
+              index, box = blocked(route, boxes)
+              break unless box
+
+              route.insert(index + 1,
+                           around(route[index], route[index + 1], box))
+            end
+            route
+          end
+
+          private
+
+          # The boxes the link has no business with: not its ends, what
+          # holds them, or what they hold.
+          def obstacles(edge)
+            @placed.reject do |box|
+              chain = box.node.ancestors + [box.node]
+              [edge.from, edge.to].any? do |node|
+                (node.ancestors + [node]).include?(box.node) ||
+                  chain.include?(node)
+              end
+            end
+          end
+
+          def blocked(route, boxes)
+            route.each_cons(2).with_index do |(from, to), index|
+              box = boxes.find { |candidate| crosses?(from, to, candidate) }
+              return [index, box] if box
+            end
+            nil
+          end
+
+          def crosses?(from, to, box)
+            steps = (Math.hypot(to[0] - from[0], to[1] - from[1]) / STEP).ceil
+            (1...steps).any? do |step|
+              inside?(box, *lerp(from, to, step.to_f / steps))
+            end
+          end
+
+          def lerp(from, to, ratio)
+            from.zip(to).map do |start, finish|
+              start + ((finish - start) * ratio)
+            end
+          end
+
+          def inside?(box, x_pos, y_pos)
+            x_pos.between?(box.x, box.x + box.width) &&
+              y_pos.between?(box.y, box.y + box.height)
+          end
+
+          # A point beside the box, on the side the line passes nearer.
+          def around(from, to, box)
+            middle = box.y + (box.height / 2)
+            [nearer_side(box, crossing_x(from, to, middle)), middle]
+          end
+
+          def crossing_x(from, to, y_pos)
+            rise = (to[1] - from[1]).nonzero? || 1e-9
+            lerp(from, to, (y_pos - from[1]) / rise)[0]
+          end
+
+          def nearer_side(box, x_pos)
+            [[box.x - CLEARANCE, EDGE_MARGIN].max,
+             box.x + box.width + CLEARANCE].min_by { |side| (side - x_pos).abs }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # A link between two nodes.
+        #
+        # `head` is `:target`, `:source`, `:socket` or `nil`; `style` is
+        # `:solid` or `:dashed`. `from_row` and `to_row` are the index of the
+        # row of a map or object box the line starts or ends at, or nil. `ends`
+        # is nil, or for an entity link the crow's foot markers of its two
+        # ends, `[from, to]`, each listed from the box outward (see
+        # {CrowsFoot}). `rank_step` is how many ranks the layout puts `to`
+        # after `from` (0 keeps them in one rank); `backwards` reads the link
+        # from `to`. `pointer` marks the tail of a note written beside its
+        # target (`note right of X`); a link to or from a named note is a
+        # plain line. `color2` is the second colour of `-[#red;#blue]->`,
+        # drawn as a copy of the line two units right and down.
+        Edge = Struct.new(:from, :to, :label, :style, :head, :color, :color2,
+                          :width, :ends, :from_row, :to_row, :rank_step,
+                          :backwards, :pointer, keyword_init: true)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../../text_measurement"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The size of an entity box, from its name and field sections.
+        module EntityMetrics
+          FONT_SIZE = 12
+          HEADER = 32.0
+          ROW = 16.5
+          SECTION_PAD = 8.0
+          SPOT = 11.0
+          SPOT_ROOM = (2 * SPOT) + 4
+          INDENT = 20.0
+          MIN_WIDTH = 60.0
+
+          module_function
+
+          # @return [Array(Float, Float)] width and height of the entity
+          def size(node)
+            sections = node.sections || []
+            [[header_width(node), fields_width(sections), MIN_WIDTH].max,
+             HEADER + sections.sum { |rows| section_height(rows) }]
+          end
+
+          def header_width(node)
+            SPOT_ROOM + 12 + text_width(node.lines.join(" "))
+          end
+
+          def fields_width(sections)
+            widths = sections.flatten.map { |f| text_width(f.text) }
+            widths.max.to_f + INDENT + 8
+          end
+
+          def section_height(rows)
+            SECTION_PAD + (rows.size * ROW)
+          end
+
+          def text_width(text)
+            Drawing::Face.width(text, size: FONT_SIZE).to_f
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "crows_foot"
+require_relative "references"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # What the node parser needs for entity diagrams: the
+        # `entity Name { fields }` block and the cardinality links between
+        # entities.
+        module EntityReader
+          Field = Struct.new(:text, :key)
+
+          ENTITY = /\Aentity\s+(?<rest>.+?)(?:\s*(?<open>\{))?\z/im
+          DIVIDER = /\A([-=._])\1(?:.*\1\1)?\z/
+
+          private
+
+          def take_entity(text)
+            return unless (match = text.match(ENTITY))
+
+            node = declare(:entity, match[:rest])
+            node.sections = match[:open] ? read_sections : []
+            node
+          end
+
+          def take_er_edge(text)
+            return unless (match = text.match(References::ER_EDGE))
+
+            add_edge(match, Link.new(match[:line]))
+            @graph.edges.last.ends = CrowsFoot.parse(match[:l], match[:r])
+          end
+
+          # Reads field lines up to the closing brace into sections that a
+          # divider line (`--`, `==`, `..`, `__`) separates.
+          def read_sections
+            sections = [[]]
+            block_lines.each do |line|
+              next sections << [] if line.match?(DIVIDER)
+
+              sections.last << field(line)
+            end
+            sections.reject(&:empty?)
+          end
+
+          def block_lines
+            from = @index
+            @index += 1 until @index >= @entries.size ||
+                @entries[@index].first == "}"
+            @index += 1
+            @entries[from...(@index - 1)].map(&:first)
+          end
+
+          def field(line)
+            key = line.start_with?("*")
+            text = line.delete_prefix("*").strip
+            Field.new(text.gsub(/<<\s*(.*?)\s*>>/, "«\\1»"), key)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "../../../svg"
+require_relative "entity_metrics"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Draws an entity: a header with the "E" spot and the name, then
+        # one compartment per field section. A key field (`*name`) carries a
+        # bullet.
+        class EntityShape
+          STROKE = "#181818"
+          # The reference draws the frame of an entity with a hairline and
+          # rounds its corners.
+          FRAME_WIDTH = "0.5"
+          CORNER = 2.5
+          Metrics = EntityMetrics
+
+          # @param placed [Placed]
+          def initialize(placed)
+            @p = placed
+            @sections = placed.node.sections || []
+          end
+
+          # @return [Array<Svg::Element>]
+          def elements
+            [shape(Svg::Rect, x: @p.x, y: @p.y, width: @p.width,
+                              height: @p.height, fill: "#F1F1F1",
+                              rx: CORNER, ry: CORNER,
+                              stroke_width: FRAME_WIDTH),
+             *header, *compartments]
+          end
+
+          private
+
+          def header
+            left = @p.x + ((@p.width - span) / 2)
+            [*spot(left + Metrics::SPOT, mid),
+             label(left + Metrics::SPOT_ROOM, mid + 4, name)]
+          end
+
+          def name
+            @p.node.lines.join(" ")
+          end
+
+          def mid
+            @p.y + (Metrics::HEADER / 2)
+          end
+
+          def span
+            Metrics::SPOT_ROOM + Metrics.text_width(name)
+          end
+
+          def spot(across, down)
+            [shape(Svg::Circle, cx: across, cy: down, r: Metrics::SPOT,
+                                fill: "#ADD1B2"),
+             label(across, down + 4, "E", anchor: "middle", weight: "bold")]
+          end
+
+          def compartments
+            top = @p.y + Metrics::HEADER
+            @sections.each_with_index.flat_map do |rows, index|
+              parts = [rule(top, index.zero? ? "0.5" : "1"), *fields(rows, top)]
+              top += Metrics.section_height(rows)
+              parts
+            end
+          end
+
+          def fields(rows, top)
+            rows.each_with_index.flat_map do |field, row|
+              base = top + Metrics::SECTION_PAD + (row * Metrics::ROW)
+              [*bullet(field, base),
+               label(@p.x + Metrics::INDENT, base + 11, field.text)]
+            end
+          end
+
+          def bullet(field, base)
+            return [] unless field.key
+
+            [shape(Svg::Circle, cx: @p.x + 10, cy: base + 5, r: 3,
+                                fill: "#000000")]
+          end
+
+          def rule(down, width)
+            shape(Svg::Line, x1: @p.x, x2: @p.x + @p.width, y1: down,
+                             y2: down, stroke_width: width)
+          end
+
+          def shape(type, **attrs)
+            build(type, { stroke: STROKE, stroke_width: "1" }.merge(attrs))
+          end
+
+          def label(across, down, content, anchor: "start", weight: nil)
+            build(Svg::Text, x: across, y: down, content: content,
+                             text_anchor: anchor, font_family: "sans-serif",
+                             font_size: Metrics::FONT_SIZE.to_s,
+                             font_weight: weight, fill: "#000000")
+          end
+
+          def build(type, attrs)
+            type.new.tap do |node|
+              attrs.each { |key, value| node.public_send(:"#{key}=", value) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The outlines of each shape as data. A point is `[fx, fy, dx, dy]`:
+        # `fx` of the width plus `dx`, `fy` of the height plus `dy`, from the
+        # box's top left. A size reads the same way.
+        module Figures
+          ORIGIN = [0, 0, 0, 0].freeze
+          FULL = [1, 1, 0, 0].freeze
+          CORNERS = [[0, 0, 0, 0], [1, 0, 0, 0], [1, 1, 0, 0],
+                     [0, 1, 0, 0]].freeze
+
+          BOX = [[:rect, ORIGIN, FULL, 2.5]].freeze
+          FILE = [[:rect, ORIGIN, FULL],
+                  [:polygon, [[1, 0, -8, 0], [1, 0, 0, 8], [1, 0, -8, 8]],
+                   "#FFFFFF"]].freeze
+          # The box is rounded; its glyph is a small component icon at the top
+          # right, a body with two tabs on its left.
+          COMPONENT = [[:rect, ORIGIN, FULL, 2.5],
+                       [:rect, [1, 0, -20, 5], [0, 0, 15, 10]],
+                       [:rect, [1, 0, -22, 7], [0, 0, 4, 2]],
+                       [:rect, [1, 0, -22, 11], [0, 0, 4, 2]]].freeze
+          NOTE = [[:polygon, [[0, 0, 0, 0], [1, 0, -10, 0], [1, 0, 0, 10],
+                              [1, 1, 0, 0], [0, 1, 0, 0]], "#FEFFDD"]].freeze
+          ACTOR = [[:circle, [0.5, 0, 0, 8], 8],
+                   [:line, [0.5, 0, 0, 16], [0.5, 0, 0, 43]],
+                   [:line, [0.5, 0, -13, 24], [0.5, 0, 13, 24]],
+                   [:line, [0.5, 0, 0, 43], [0.5, 0, -13, 58]],
+                   [:line, [0.5, 0, 0, 43], [0.5, 0, 13, 58]]].freeze
+          PORT = [[:rect, [0.5, 0, -6, 0], [0, 0, 12, 12]]].freeze
+          PORT_IN = [[:rect, [0.5, 1, -6, -12], [0, 0, 12, 12]]].freeze
+          DATABASE = [[:path, [[:M, [0, 0, 0, 8]],
+                               [:A, [0.5, 0, 0, 8], 1, [1, 0, 0, 8]],
+                               [:L, [1, 1, 0, -8]],
+                               [:A, [0.5, 0, 0, 8], 1, [0, 1, 0, -8]], [:Z]]],
+                      [:path, [[:M, [0, 0, 0, 8]],
+                               [:A, [0.5, 0, 0, 8], 0, [1, 0, 0, 8]]], "none"]]
+            .freeze
+          NODE = [[:polygon, [[0, 0, 0, 8], [0, 0, 8, 0], [1, 0, 0, 0],
+                              [1, 0, -8, 8]]],
+                  [:polygon, [[1, 0, -8, 8], [1, 0, 0, 0], [1, 1, 0, -8],
+                              [1, 1, -8, 0]]],
+                  [:rect, [0, 0, 0, 8], [1, 1, -8, -8]]].freeze
+          # The containers that wear a tab over the top left edge, which
+          # holds their name.
+          TABBED = %i[package folder frame].freeze
+          USECASE = [[:ellipse]].freeze
+          CLOUD = [[:cloud]].freeze
+          INTERFACE = [[:circle, [0.5, 0, 0, 10], 8]].freeze
+          CIRCLE = [[:circle, [0.5, 0, 0, 8], 8]].freeze
+
+          # What a container is drawn as; any other kind is a plain frame.
+          CONTAINERS = { node: NODE, database: DATABASE, cloud: CLOUD }.freeze
+
+          BY_KIND = { actor: ACTOR, usecase: USECASE, component: COMPONENT,
+                      interface: INTERFACE, portin: PORT_IN, portout: PORT,
+                      note: NOTE, database: DATABASE, node: NODE, cloud: CLOUD,
+                      file: FILE, circle: CIRCLE }.freeze
+
+          # Where the label goes, by kind: `top` from the box top, else
+          # centred; `dy` moves a centred label, `shift` and `shrink` its
+          # horizontal middle and width, `left` pins it to the left.
+          LABELS = { actor: { top: 59.5 }, interface: { top: 22 },
+                     circle: { top: 20 },
+                     portin: { top: 0 }, portout: { top: 12 },
+                     note: { top: 4, left: 8 }, database: { dy: 6 },
+                     component: { dy: 4 },
+                     node: { dy: 4, shrink: 8 } }.freeze
+
+          module_function
+
+          def for(kind)
+            BY_KIND.fetch(kind, BOX)
+          end
+
+          # @return [Array, nil] the outline of a container of `kind`, nil
+          #   for a plain rectangle
+          def container(kind)
+            CONTAINERS[kind]
+          end
+
+          def label(kind)
+            LABELS.fetch(kind, {})
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # Ports on a container's frame: `portin` along the top edge,
+        # `portout` along the bottom, each square straddling the edge, as
+        # the PlantUML JAR draws them.
+        class FramePorts
+          KINDS = %i[portin portout].freeze
+          SIDE = 12.0
+          GAP = 12.0
+          # From a container's border to the children inside it, when ports
+          # sit on that side: the JAR ranks the children a full rank gap
+          # below the port row.
+          REACH = 66.0
+
+          # @return [Boolean] whether `node` sits on the frame of its container
+          def self.on_frame?(node)
+            !node.parent.nil? && KINDS.include?(node.kind)
+          end
+
+          # @param sizes [Hash{Node => Array(Float, Float)}] width, height
+          def initialize(sizes)
+            @sizes = sizes
+          end
+
+          # @return [Float] the frame width the busier side needs
+          def width(ports)
+            ports.group_by(&:kind).values.map do |side|
+              side.sum { |port| @sizes[port][0] + GAP }
+            end.max.to_f
+          end
+
+          # @param frame [Placed] the container
+          # @return [Array<Placed>] the ports, spread along their edge
+          def place(frame, ports, depth)
+            ports.group_by(&:kind).flat_map do |kind, side|
+              side.each_with_index.map do |port, index|
+                at = frame.x + (frame.width * (index + 0.5) / side.size)
+                put(port, [at, edge(frame, kind)], depth)
+              end
+            end
+          end
+
+          # @return [Placed] the square a link to `box` ends at
+          def terminal(box)
+            top = box.node.kind == :portin ? box.height - SIDE : 0.0
+            Placed.new(node: box.node, x: box.x + ((box.width - SIDE) / 2),
+                       y: box.y + top, width: SIDE, height: SIDE,
+                       depth: box.depth)
+          end
+
+          private
+
+          def edge(frame, kind)
+            kind == :portin ? frame.y : frame.y + frame.height
+          end
+
+          def put(port, (centre, edge_y), depth)
+            width, height = @sizes[port]
+            reach = port.kind == :portin ? height - (SIDE / 2) : SIDE / 2
+            Placed.new(node: port, x: centre - (width / 2), y: edge_y - reach,
+                       width: width, height: height, depth: depth)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "node"
+require_relative "edge"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module NodeGraph
+        # The nodes and links of one diagram, in source order.
+        class Graph
+          attr_reader :nodes, :edges
+          attr_accessor :title, :direction
+
+          # @param direction [Symbol] :left_to_right or :top_to_bottom
+          def initialize(direction:)
+            @direction = direction
+            @nodes = {}
+            @edges = []
+            @title = nil
+          end
+
+          # @return [Node] the node for `id`, made with `kind` if new
+          def node(id, kind, parent: nil)
+            @nodes[id] ||= Node.new(id: id, kind: kind, parent: parent)
+          end
+
+          def find(name)
+            @nodes[name] || @nodes.values.find { |n| n.lines == [name] }
+          end
+
+          # @return [Array<Node>] the nodes directly inside `parent`
+          def children_of(parent)
+            @nodes.values.select { |n| n.parent.equal?(parent) }
+          end
+        end
+      end
+    end
+  end
+end