etassia 0.1.0

data/lib/etassia/notation/plantuml/activity/router.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require_relative "exits"
+require_relative "placement"
+require_relative "route"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Draws every edge as straight and right-angled segments between the
+        # placed nodes. Loops go round the left, forward edges that skip
+        # rows round the right.
+        class Router
+          DETOUR = 16.0
+          DETOUR_STEP = 7.0
+          JOG = 11.97
+          RUN_LIFT = 2.32
+          private_constant :DETOUR, :DETOUR_STEP, :JOG, :RUN_LIFT
+
+          # @param boxes [Hash{Node => Box}]
+          # @param ranking [Ranking]
+          # @param bottoms [Array<Float>] bottom of each row
+          # @param gaps [Array<Float>] space above each row
+          # @param label_drop [Float] how far below a node a label's
+          #   baseline sits
+          def initialize(boxes:, ranking:, bottoms:, gaps:, label_drop: 13.0)
+            @label_drop = label_drop
+            @boxes = boxes
+            @ranking = ranking
+            @bottoms = bottoms
+            @gaps = gaps
+            @detours = Hash.new(0)
+          end
+
+          # @return [Route]
+          def call(edge)
+            from = @boxes.fetch(edge.from)
+            to = @boxes.fetch(edge.to)
+            return level(edge, from, to) if level?(edge)
+
+            side = detour_side(edge, from, to)
+            return detour(edge, from, to, side) if side
+
+            forward(edge, from, to)
+          end
+
+          private
+
+          def level?(edge)
+            edge.level? && !@ranking.back?(edge) &&
+              @ranking.rank[edge.from] == @ranking.rank[edge.to]
+          end
+
+          # Along the row: out of the side of `from` that faces `to`. A
+          # parked `to` sits half a row lower, so the arrow runs on to
+          # above its middle and drops into it.
+          def level(edge, from, to)
+            right = to.cx >= from.cx
+            ends = right ? [from.right, to.left] : [from.left, to.right]
+            return parked_level(edge, from, to, ends.first) if parked?(from, to)
+
+            Route.new(points: ends.map { |x_pos| [x_pos, from.cy] },
+                      **level_label(edge, from, ends))
+          end
+
+          def parked?(from, to)
+            (from.cy - to.cy).abs > 1
+          end
+
+          def parked_level(edge, from, to, start_x)
+            Route.new(points: [[start_x, from.cy], [to.cx, from.cy],
+                               [to.cx, to.top]],
+                      **level_label(edge, from, [start_x, to.cx]))
+          end
+
+          # The label sits at the start of the run, unless a sibling exit
+          # leaves the same side of the decision and prints its own there:
+          # then it sits at the far end.
+          def level_label(edge, from, ends)
+            return { label_x: ends.min + 5, label_y: from.cy - 4 } unless
+              shared_side?(edge, from, ends.last)
+
+            { label_x: ends.max - 4, label_y: from.cy - 4, anchor: "end" }
+          end
+
+          def shared_side?(edge, from, end_x)
+            return false unless edge.from.kind == :decision
+
+            @ranking.forward(edge.from).any? do |other|
+              sibling_beside?(other, edge, from, end_x)
+            end
+          end
+
+          def sibling_beside?(other, edge, from, end_x)
+            return false if other.equal?(edge) || other.level?
+
+            offset = @boxes.fetch(other.to).cx - from.cx
+            offset.abs >= from.width / 2.0 &&
+              (offset <=> 0) == (end_x <=> from.cx)
+          end
+
+          def detour_side(edge, from, to)
+            return :left if @ranking.back?(edge)
+            return unless skips?(edge)
+            return same_column_side(edge, from, to) if same_column?(from, to)
+
+            blocked_side(edge, from, to)
+          end
+
+          # A drop down one column goes round the right only when a node
+          # stands in it; a clear column is drawn straight.
+          def same_column_side(edge, from, to)
+            :right unless blockers(edge, from, to).empty?
+          end
+
+          def skips?(edge)
+            @ranking.rank[edge.to] - @ranking.rank[edge.from] > 1
+          end
+
+          # Round the left when everything in the way lies to the right.
+          def blocked_side(edge, from, to)
+            boxes = blockers(edge, from, to)
+            return if boxes.empty?
+
+            boxes.all? { |box| box.cx > from.cx } ? :left : :right
+          end
+
+          # Boxes on the rows between that stand where the edge drops.
+          def blockers(edge, from, to)
+            rows = (@ranking.rank[edge.from] + 1)...@ranking.rank[edge.to]
+            drops = [from.cx, to.cx]
+            @boxes.filter_map do |node, box|
+              box if blocks?(node, box, rows, drops)
+            end
+          end
+
+          def blocks?(node, box, rows, drops)
+            node.kind != :bar && rows.cover?(@ranking.rank[node]) &&
+              drops.any? { |x_pos| x_pos.between?(box.left, box.right) }
+          end
+
+          def forward(edge, from, to)
+            start_x = anchor_x(edge.from, from, to, edge)
+            end_x = anchor_x(edge.to, to, from, edge)
+            shape = shape(edge, from, to)
+            return decision_exit(from, to, end_x, edge) if shape == :side_exit
+
+            below_frame(edge, hanging(shape, edge, [from, to],
+                                      [start_x, end_x]))
+          end
+
+          # A route that leaves the bottom of `from`.
+          def hanging(shape, edge, boxes, anchors)
+            case shape
+            when :side_entry then side_entry(*boxes, anchors.first)
+            when :straight then straight(*boxes, anchors.first)
+            else elbow(edge, boxes, *anchors)
+            end
+          end
+
+          # An edge that leaves a partition from the node's bottom crosses
+          # the frame's bottom edge; its label hangs below that edge.
+          def below_frame(edge, route)
+            leaving = edge.from.partition
+            return route unless leaving && leaving != edge.to.partition
+
+            Route.new(points: route.points, label_x: route.label_x,
+                      label_y: route.label_y + Placement::PARTITION_BELOW,
+                      anchor: route.anchor)
+          end
+
+          def shape(edge, from, to)
+            return :straight if same_column?(from, to)
+            return :side_exit if edge.from.kind == :decision
+
+            side_entry?(edge, from, to) ? :side_entry : :elbow
+          end
+
+          def side_entry?(edge, from, to)
+            edge.to.kind == :merge && !Exits.top_entry?(edge, from, to)
+          end
+
+          def straight(from, to, x_pos)
+            Route.new(points: [[x_pos, from.bottom], [x_pos, to.top]],
+                      label_x: x_pos + 5, label_y: from.bottom + @label_drop)
+          end
+
+          def elbow(edge, boxes, start_x, end_x)
+            from, to = boxes
+            return straight(from, to, start_x) if start_x == end_x
+
+            mid = run_height(edge)
+            Route.new(points: [[start_x, from.bottom], [start_x, mid],
+                               [end_x, mid], [end_x, to.top]],
+                      label_x: start_x + 5, label_y: from.bottom + @label_drop)
+          end
+
+          # Halfway down the space below the edge's row.
+          def run_height(edge)
+            row = @ranking.rank[edge.from]
+            @bottoms[row] + (@gaps.fetch(row + 1, 0.0) / 2.0)
+          end
+
+          # A branch that lands under the decision's own tip needs no side
+          # run: it drops straight, as the first branch of a switch does.
+          def decision_exit(from, to, end_x, edge)
+            return straight(from, to, end_x) if (end_x - from.cx).abs < 1
+            return jog_exit(from, to, end_x) if (end_x - from.cx).abs <
+              from.width / 2.0
+
+            side_exit(from, to, end_x, edge)
+          end
+
+          # Down from the decision's foot, across, and down into the step.
+          def jog_exit(from, to, end_x)
+            level = from.bottom + JOG
+            Route.new(points: [[from.cx, from.bottom], [from.cx, level],
+                               [end_x, level], [end_x, to.top]],
+                      label_x: end_x + 5, label_y: level + @label_drop)
+          end
+
+          def side_exit(from, to, end_x, edge)
+            sign = end_x > from.cx ? 1 : -1
+            edge_x = sign.positive? ? from.right : from.left
+            Route.new(points: [[edge_x, from.cy], [end_x, from.cy],
+                               [end_x, to.top]],
+                      **exit_label(edge, [edge_x, end_x], from, sign))
+          end
+
+          # Two branches carry their label along the run, by the decision's
+          # tip. Where there are more, the label rides the branch's own
+          # drop, so branches that share one run do not print their labels
+          # on top of each other.
+          def exit_label(edge, ends, from, sign)
+            if @ranking.forward(edge.from).size > 2
+              return { label_x: ends.last + 5, label_y: from.cy + @label_drop }
+            end
+
+            { label_x: ends.first, label_y: from.cy - RUN_LIFT,
+              anchor: sign.positive? ? "start" : "end" }
+          end
+
+          def side_entry(from, to, start_x)
+            edge_x = start_x > to.cx ? to.right : to.left
+            Route.new(points: [[start_x, from.bottom], [start_x, to.cy],
+                               [edge_x, to.cy]],
+                      label_x: start_x + 5, label_y: from.bottom + @label_drop)
+          end
+
+          # Out of one side of `from`, along a lane beside every node in
+          # the rows between, and into the same side of `to`.
+          def detour(edge, from, to, side)
+            lane = lane_x(boxes_between(edge), side)
+            left = side == :left
+            ends = left ? [from.left, to.left] : [from.right, to.right]
+            Route.new(points: loop_points(from, to, ends, lane),
+                      label_x: ends.first + (left ? -4 : 4),
+                      label_y: from.cy - 4, anchor: left ? "end" : "start")
+          end
+
+          def loop_points(from, to, ends, lane)
+            [[ends.first, from.cy], [lane, from.cy], [lane, to.cy],
+             [ends.last, to.cy]]
+          end
+
+          def boxes_between(edge)
+            first, last = [@ranking.rank[edge.from],
+                           @ranking.rank[edge.to]].minmax
+            @boxes.filter_map do |node, box|
+              box if (first..last).cover?(@ranking.rank[node])
+            end
+          end
+
+          def lane_x(boxes, side)
+            offset = DETOUR + (DETOUR_STEP * (@detours[side] += 1))
+            if side == :left
+              boxes.map(&:left).min - offset
+            else
+              boxes.map(&:right).max + offset
+            end
+          end
+
+          def same_column?(from, to)
+            (from.cx - to.cx).abs < 1
+          end
+
+          # A bar is crossed wherever its neighbour stands. A decision
+          # reaches for the middle of the branches the bar fans out to, and
+          # a bar that closes onto the merge diamond leaves from that middle.
+          def anchor_x(node, box, other, edge)
+            return box.cx unless node.kind == :bar
+            return box.anchor if middle?(node, box, other, edge)
+
+            other.cx.clamp(box.left, box.right)
+          end
+
+          def middle?(node, box, other, edge)
+            return true if edge.to.kind == :merge && node.equal?(edge.from)
+
+            edge.from.kind == :decision &&
+              !box.fan&.any? { |f| f.equal?(other) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/row_gaps.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # The space above each row, as PlantUML leaves it: 20 between
+        # steps, 10 from a decision down to a branch beside it, 6 from a
+        # branch into the diamond that closes them (23.13 from a join bar,
+        # which PlantUML sets off by a step's half-height more), and room
+        # for the label
+        # of an arrow between two rows. A row is as far from the one above
+        # as the largest of its arrows asks. A branch that leaves the foot of
+        # its decision rather than its side asks for the label's room.
+        class RowGaps
+          STEP = 20.0
+          BRANCH = 10.0
+          CLOSE = 6.0
+          BAR_CLOSE = 23.1328
+          LABEL_MARGIN = 28.33
+          LABEL_BELOW_DECISION = 11.45
+          private_constant :STEP, :BRANCH, :BAR_CLOSE, :LABEL_MARGIN,
+                           :LABEL_BELOW_DECISION
+
+          # @param frame [Float] the space a partition's frame asks where an
+          #   arrow crosses it
+          def initialize(diagram, ranking, exits, metrics, frame)
+            @ranking = ranking
+            @exits = exits
+            @metrics = metrics
+            @frame = frame
+            @asks = Array.new(ranking.rank.values.max.to_i + 1) { [] }
+            diagram.edges.each { |edge| add(edge) }
+          end
+
+          # @return [Array<Float>] the space above each row; the first is 0
+          def to_a
+            @asks.each_with_index.map do |own, row|
+              row.zero? ? 0.0 : (own.max || STEP)
+            end
+          end
+
+          private
+
+          def add(edge)
+            return if @ranking.back?(edge)
+
+            row = @ranking.rank[edge.to]
+            return unless row - @ranking.rank[edge.from] == 1
+
+            @asks[row] << [crossing(edge), arrow(edge)].max
+          end
+
+          def crossing(edge)
+            edge.from.partition == edge.to.partition ? 0.0 : @frame
+          end
+
+          # Where the arrow goes decides how far it has to run.
+          def arrow(edge)
+            height = label_height(edge)
+            return side_run(edge, height) if beside?(edge)
+            return drop(edge, height) if edge.from.kind == :decision
+
+            [STEP, labelled(height)].max
+          end
+
+          # A branch that drops from the decision's foot runs straight to its
+          # step, or jogs sideways first when its step stands off to one side.
+          def drop(edge, height)
+            below = height + LABEL_BELOW_DECISION
+            return below + LABEL_BELOW_DECISION if @exits.jog?(edge)
+
+            [STEP, below].max
+          end
+
+          def side_run(edge, height)
+            return close(edge, height) if edge.to.kind == :merge
+
+            edge.from.kind == :decision && !edge.from.bare ? BRANCH : STEP
+          end
+
+          def close(edge, height)
+            [edge.from.kind == :bar ? BAR_CLOSE : CLOSE, labelled(height)].max
+          end
+
+          def beside?(edge)
+            @exits.beside?(edge)
+          end
+
+          def labelled(height)
+            height.zero? ? 0.0 : height + LABEL_MARGIN
+          end
+
+          # The text between two rows: the arrow's own label, or a bare
+          # decision's question.
+          def label_height(edge)
+            lines = edge.label.to_s.split("\n")
+            lines = edge.to.lines if edge.to.bare && lines.empty?
+            lines.empty? ? 0.0 : @metrics.text_height(lines, role: :arrow)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/row_spread.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Stands columns left to right, each clear of every earlier one only
+        # on the rows the two share, so a box may reach under or over a
+        # neighbour's that lies on another row.
+        class RowSpread
+          # @param rows [Hash{Array => Hash{Numeric => Array(Float, Float)}}]
+          #   how far each column reaches on each row
+          # @param widths [Hash{Array => Array(Float, Float)}] the same for
+          #   the whole column
+          def initialize(rows, widths, margin)
+            @rows = rows
+            @widths = widths
+            @margin = margin
+          end
+
+          # @param solid [Array<Array>] the column keys, in order
+          # @yieldparam prior [Array] an earlier column
+          # @yieldparam key [Array] the column being placed
+          # @yieldreturn [Float] the gap to leave between the two
+          # @return [Hash{Array => Float}] each column's centre
+          def call(solid, &gap)
+            solid.each_with_index.with_object({}) do |(key, index), placed|
+              placed[key] = centre(solid.first(index), key, placed, &gap)
+            end
+          end
+
+          private
+
+          def centre(earlier, key, placed)
+            clear = earlier.each_with_index.map do |prior, at|
+              placed[prior] +
+                clearance(prior, key, yield(prior, key), at == earlier.size - 1)
+            end
+            [@margin + @widths[key].first, *clear].max
+          end
+
+          # How far right of `prior` the column's centre stands: clear of
+          # the rows they share, and no further left than the column
+          # before it.
+          def clearance(prior, key, gap, adjacent)
+            shared = @rows[prior].keys & @rows[key].keys
+            return adjacent ? 0.0 : -Float::INFINITY if shared.empty?
+
+            shared.map { |row| reach(prior, key, row) }.max + gap
+          end
+
+          def reach(prior, key, row)
+            @rows[prior][row].last + @rows[key][row].first
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # A laid-out activity diagram: its size and its marks back to front.
+        class Scene
+          attr_reader :width, :height, :marks
+
+          def initialize(width:, height:, marks:)
+            @width = width
+            @height = height
+            @marks = marks
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/text.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Turns PlantUML label markup into lines. Creole styling (`**bold**`,
+        # `__underline__`, `<b>`, `<color:..>`) stays in the line for
+        # {Creole} to draw and for {Creole.plain} to measure; an embedded
+        # image or sprite is refused, never dropped.
+        module Text
+          module_function
+
+          PLAIN = %r{</?plain>}i
+          PICTURE = /<(?:img|\$|&)/i
+          private_constant :PLAIN, :PICTURE
+
+          # @param raw [String]
+          # @param line [Integer] source line, for the refusal
+          # @return [String] lines joined by newlines
+          def clean(raw, line:)
+            if PICTURE.match?(raw)
+              raise UnsupportedConstructError.new(construct: "image",
+                                                  line: line, text: raw)
+            end
+
+            raw.gsub("\\n", "\n").gsub(PLAIN, "")
+              .split("\n").map(&:strip).join("\n").strip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "style"
+require_relative "activity/parser"
+require_relative "activity/layout"
+require_relative "activity/renderer"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML activity diagram, in the new and the legacy syntax.
+      # Dispatched to from {PlantUML.parse}.
+      module Activity
+        extend self
+
+        # Lines only an activity diagram has. A sequence declaration or a
+        # class declaration anywhere in the source wins over these.
+        MARKER = /\A(?:start|stop|kill)\z|\A(?:\#\w+)?:|\A\(\*|\Aif\s*[("]|
+                  \Awhile\s*\(|\Arepeat\b|\Aswitch\s*\(|\Afork\z|
+                  \Apartition\s/xi
+        OTHER = /\A(?:abstract[ \t]+class|class|interface|participant|actor|
+                 boundary|control|entity|database|collections|queue|
+                 autonumber|newpage|alt|loop|opt|par|critical|break|
+                 ref)\b/xi
+        private_constant :MARKER, :OTHER
+
+        # @return [Boolean] whether the source reads as an activity diagram
+        def activity?(source)
+          lines = source.dup.force_encoding(Encoding::UTF_8).scrub.lines
+          lines = lines.map(&:strip)
+          lines.none? { |line| OTHER.match?(line) } &&
+            lines.any? { |line| MARKER.match?(line) }
+        end
+
+        # @return [Notation::Parsed]
+        def parse(source)
+          sheet = Style::Reader.read(source)
+          diagram = Parser.new.parse(source)
+          diagram.style = sheet
+          Notation::Parsed.new(
+            type: :activity_diagram,
+            diagram: diagram,
+            transform: Layout,
+            renderer: Style::Bound.wrap(Renderer, sheet),
+          )
+        end
+      end
+    end
+  end
+end