etassia 0.1.0

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../style"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # A parsed activity diagram: nodes and edges in source order, the
+        # swimlanes in order of first use, an optional title and the notices
+        # PlantUML prints above the drawing.
+        class Diagram
+          attr_reader :nodes, :edges, :lanes, :title, :warnings
+          # @return [Style::Sheet] what the source says about fonts and
+          #   looks; the layout sizes boxes from it
+          attr_accessor :style
+          # @return [Boolean] whether it was written in the legacy `(*)`
+          #   syntax, which PlantUML ranks differently from the new one
+          attr_accessor :legacy
+
+          # @param lanes [Array<Array(String, String)>] name and colour
+          def initialize(nodes:, edges:, lanes: [], title: nil, warnings: [])
+            @nodes = nodes
+            @edges = edges
+            @lanes = lanes
+            @title = title
+            @warnings = warnings
+            @style = Style::Sheet.new
+            @legacy = false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # A flow arrow between two nodes.
+        class Edge
+          attr_reader :from, :to, :label, :colour, :style
+          # @return [Symbol, nil] :left or :right when the arrow lies along
+          #   its row (legacy syntax)
+          attr_accessor :direction
+
+          # @param from [Node]
+          # @param to [Node]
+          # @param label [String, nil]
+          # @param colour [String, nil] an SVG colour
+          # @param style [Symbol, nil] :dashed, :dotted or :bold
+          def initialize(from:, to:, label: nil, colour: nil, style: nil)
+            @from = from
+            @to = to
+            @label = label
+            @colour = colour
+            @style = style
+          end
+
+          # @return [Boolean] whether the arrow lies along its row
+          def level?
+            !@direction.nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "arrow_head"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Draws an edge: its path, its arrow head and its label.
+        class EdgeMarks
+          INK = "#181818"
+          DASHES = { dashed: "7,5", dotted: "2,4" }.freeze
+          QUESTION_GAP = 13.0
+          private_constant :INK, :DASHES, :QUESTION_GAP
+
+          # @param curved [Boolean] draw each straight edge as a cubic, as
+          #   PlantUML does in the legacy syntax
+          def initialize(router, canvas, curved: false)
+            @router = router
+            @canvas = canvas
+            @curved = curved
+          end
+
+          # @param edge [Edge]
+          def draw(edge)
+            return if edge.from.equal?(edge.to)
+
+            route = @router.call(edge)
+            paint(edge, route.points)
+            label(edge, route)
+            question(edge.to, route.points.last(2)) if edge.to.bare
+          end
+
+          private
+
+          def paint(edge, points)
+            colour = edge.colour || INK
+            @canvas.path(points, stroke: colour, width: width(edge),
+                                 dash: DASHES[edge.style], curve: @curved)
+            @canvas.polygon(ArrowHead.points(points.last(2)), fill: colour,
+                                                              stroke: colour)
+          end
+
+          # A bare decision's question stands left of the arrow into it,
+          # level with the middle of the arrow.
+          def question(node, segment)
+            tail, tip = segment
+            @canvas.lines(node.lines, [tip.first - QUESTION_GAP,
+                                       ((tail.last + tip.last) / 2) + 10.0],
+                          anchor: "end", role: :arrow)
+          end
+
+          def width(edge)
+            edge.style == :bold ? 2.5 : 1.0
+          end
+
+          def label(edge, route)
+            return unless edge.label
+
+            @canvas.lines(edge.label.split("\n"),
+                          [route.label_x, route.label_y],
+                          anchor: route.anchor, role: :arrow)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # How an arrow leaves its node, once the columns are centred: from
+        # the foot of a decision, straight or with a jog to a step standing
+        # under the decision's width, or from its side.
+        class Exits
+          # A step that stands over the diamond closing the branches drops
+          # into its top instead of its side; a bar runs round to the side.
+          #
+          # @return [Boolean]
+          def self.top_entry?(edge, from, to)
+            edge.to.kind == :merge && edge.from.kind != :bar &&
+              from.spans?(to.cx)
+          end
+
+          # @param columns [Columns]
+          # @param boxes [Hash{Node => Box}]
+          def initialize(columns, boxes)
+            @columns = columns
+            @boxes = boxes
+          end
+
+          # @return [Boolean] whether the arrow runs beside its row: out of
+          #   a decision's side, or into the side of the diamond that closes
+          #   branches
+          def beside?(edge)
+            !same_column?(edge) && !under?(edge) && sideways?(edge)
+          end
+
+          # @return [Boolean] whether the arrow leaves a decision's foot and
+          #   has to jog sideways to reach its step
+          def jog?(edge)
+            under?(edge) && !same_column?(edge)
+          end
+
+          def same_column?(edge)
+            @columns.key[edge.from] == @columns.key[edge.to]
+          end
+
+          private
+
+          def sideways?(edge)
+            return edge.from.kind == :decision unless edge.to.kind == :merge
+
+            !Exits.top_entry?(edge, @boxes[edge.from], @boxes[edge.to])
+          end
+
+          def under?(edge)
+            edge.from.kind == :decision &&
+              (@boxes[edge.to].cx - @boxes[edge.from].cx).abs <
+                @boxes[edge.from].width / 2.0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "box"
+require_relative "placement"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Draws what frames the flow: the title, swimlane bands and
+        # partition frames.
+        class FrameMarks
+          PARTITION_PAD = 10.0
+          LANE_FLOOR = 20.0
+          LANE_RULE = "#000000"
+          WARNING_PAPER = "#FFFFCC"
+          WARNING_INK = "#FFDD88"
+          private_constant :PARTITION_PAD, :LANE_FLOOR,
+                           :LANE_RULE, :WARNING_PAPER, :WARNING_INK
+
+          def initialize(diagram, placement, canvas, metrics)
+            @diagram = diagram
+            @placement = placement
+            @canvas = canvas
+            @metrics = metrics
+          end
+
+          def title
+            return unless @diagram.title
+
+            origin = [Layout::MARGIN, Layout::MARGIN + 14]
+            @canvas.lines(@diagram.title.split("\n"), origin, weight: "bold",
+                                                              size: 14)
+          end
+
+          # PlantUML's notices, in a yellow box under the title: one
+          # monospace line each.
+          def warnings
+            rows = @diagram.warnings
+            return if rows.empty?
+
+            left = Layout::MARGIN
+            top = left + (@diagram.title ? Placement::TITLE_HEIGHT : 0)
+            @canvas.rect(notice_box(rows, left, top), fill: WARNING_PAPER,
+                                                      stroke: WARNING_INK,
+                                                      radius: 2.5,
+                                                      role: :warning)
+            @canvas.mono_lines(rows, [left + 7, top + 10.6406],
+                               pitch: Placement::WARNING_PITCH)
+          end
+
+          def lanes
+            floor = @placement.bottoms.last + LANE_FLOOR
+            ceiling = @placement.top - Placement::HEADER_HEIGHT
+            @placement.bands.each { |band| lane(band, ceiling, floor) }
+          end
+
+          def partitions
+            @diagram.nodes.filter_map(&:partition).uniq.each do |name|
+              members = @diagram.nodes.select { |n| n.partition == name }
+              partition(name, members.map { |n| @placement.boxes[n] })
+            end
+          end
+
+          private
+
+          def notice_box(rows, left, top)
+            Box.spanning(left, top, left + @canvas.mono_width(rows) + 10,
+                         top + (Placement::WARNING_PITCH * rows.size) - 5)
+          end
+
+          def lane(band, ceiling, floor)
+            left = band[:left]
+            right = band[:right]
+            @canvas.rect(Box.spanning(left, ceiling, right, floor),
+                         fill: band[:colour] || "none")
+            [left, right].each do |x_pos|
+              @canvas.path([[x_pos, ceiling], [x_pos, floor]],
+                           stroke: LANE_RULE, width: 1.5)
+            end
+            @canvas.lines([band[:name]], [(left + right) / 2, ceiling + 20],
+                          anchor: "middle", size: Placement::LANE_TITLE)
+          end
+
+          def partition(name, boxes)
+            frame = frame_around(boxes, name)
+            @canvas.rect(frame, fill: "none", role: :partition)
+            @canvas.lines([name],
+                          [frame.left + 8,
+                           frame.top + @metrics.size(:partition) + 3],
+                          role: :partition)
+          end
+
+          # The frame is as tall above the nodes as the title is, and wide
+          # enough that the title ends before the arrow that enters it.
+          def frame_around(boxes, name)
+            top = boxes.min_by(&:top)
+            left = [boxes.map(&:left).min - PARTITION_PAD,
+                    top.cx - title_width(name)].min
+            Box.spanning(left, top.top - @placement.head,
+                         reach(boxes, :right, :max),
+                         reach(boxes, :bottom, :max))
+          end
+
+          def reach(boxes, edge, extreme)
+            boxes.map(&edge).public_send(extreme) + PARTITION_PAD
+          end
+
+          def title_width(name)
+            (1.12 * @metrics.text_width([name], role: :partition)) + 12
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # The two steps of a two-step side lane that PlantUML hangs from the
+        # lane's ends rather than from the rows of the lane beside it: the
+        # first sits just under its decision, the last just over the diamond
+        # that closes the branches. Neither asks the rows for any height, so
+        # a bar in the neighbouring lane is not set off from its steps by a
+        # box that belongs to another lane.
+        class LaneSteps
+          # @return [Hash{Node => Node}] each step hung from the decision,
+          #   with the step that follows it
+          attr_reader :heads
+          # @return [Hash{Node => Node}] each step hung from the diamond
+          #   closing its branches, with that diamond
+          attr_reader :tails
+
+          # @param diagram [Diagram]
+          # @param ranking [Ranking]
+          # @param exits [Exits]
+          def initialize(diagram, ranking, exits)
+            @ranking = ranking
+            @exits = exits
+            @heads = {}.compare_by_identity
+            @tails = {}.compare_by_identity
+            @edges = diagram.legacy ? [] : diagram.edges
+            @edges.select { |edge| closing?(edge) }.each { |edge| hang(edge) }
+          end
+
+          # @return [Boolean] whether the step hangs from either end
+          def hung?(node)
+            @heads.key?(node) || @tails.key?(node)
+          end
+
+          # @param node [Node]
+          # @param height [Float] the height of the node's box
+          # @param tops [Array<Float>] the top of each row
+          # @return [Float, nil] where the step's centre stands, or nil when
+          #   the rows place it
+          def centre(node, height, tops)
+            return tops[@ranking.rank[node]] + (height / 2.0) if
+              @heads.key?(node)
+
+            diamond = @tails[node]
+            return unless diamond
+
+            tops[@ranking.rank[diamond]] - RowGaps::CLOSE - (height / 2.0)
+          end
+
+          private
+
+          def hang(tail_edge)
+            head = @edges.find { |entry| lane?(entry, tail_edge.from) }
+            return unless head
+
+            @tails[tail_edge.from] = tail_edge.to
+            @heads[head.to] = tail_edge.from
+          end
+
+          # A step that reaches the closing diamond beside its row, from
+          # more than one row up.
+          def closing?(edge)
+            edge.to.kind == :merge && !@ranking.back?(edge) &&
+              @ranking.rank[edge.to] - @ranking.rank[edge.from] > 1 &&
+              @exits.beside?(edge)
+          end
+
+          # The edge that brings a decision's side branch to the first step
+          # of a lane ending at `tail`; the lane is those two steps.
+          def lane?(entry, tail)
+            step = entry.to
+            entry.from.kind == :decision && @exits.beside?(entry) &&
+              @ranking.forward(step).map(&:to) == [tail]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Keeps each swimlane band as wide as its title, which the JAR draws
+        # at one size in every lane. A band that falls short takes the rest
+        # evenly from the first and last columns of its lane.
+        class LaneTitles
+          # @param metrics [Metrics] measures the title
+          # @param size [Numeric] the title's font size
+          # @param pad [Float] the room kept about the title in its band
+          def initialize(metrics, size, pad)
+            @metrics = metrics
+            @size = size
+            @pad = pad
+          end
+
+          # @param bands [Array<Hash>] the bands, each with its `:name`,
+          #   its `:left` and `:right`, and the `:columns` of its lane
+          # @param reach [Reach] widened where a band falls short
+          # @return [Integer] how many bands were short
+          def widen(bands, reach)
+            bands.count { |band| widen_band(band, reach) }
+          end
+
+          private
+
+          def widen_band(band, reach)
+            half = shortfall(band) / 2
+            return unless half.positive?
+
+            reach.widen_column(band[:columns].first, 0, half)
+            reach.widen_column(band[:columns].last, 1, half)
+          end
+
+          def shortfall(band)
+            @metrics.text_width([band[:name]], size: @size) + @pad -
+              (band[:right] - band[:left])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "columns"
+require_relative "marks"
+require_relative "metrics"
+require_relative "placement"
+require_relative "ranking"
+require_relative "router"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Places an activity {Diagram} top to bottom: rows from {Ranking},
+        # columns from {Columns}, routes from {Router}. The result is
+        # deterministic and uses fixed spacing.
+        class Layout
+          MARGIN = 14.0
+
+          # @param diagram [Diagram]
+          # @return [Scene]
+          def call(diagram, **)
+            ranking = Ranking.new(diagram)
+            columns = Columns.new(diagram, ranking)
+            marks = build(diagram, ranking, columns, MARGIN)
+            if marks.min_x < MARGIN
+              marks = build(diagram, ranking, columns,
+                            (2 * MARGIN) - marks.min_x)
+            end
+            marks.scene
+          end
+
+          private
+
+          def build(diagram, ranking, columns, margin)
+            metrics = Metrics.new(diagram.style)
+            placement = Placement.new(diagram, ranking, columns, margin,
+                                      metrics)
+            router = Router.new(boxes: placement.boxes, ranking: ranking,
+                                bottoms: placement.bottoms,
+                                gaps: placement.gaps,
+                                label_drop: metrics.size(:arrow) + 1)
+            Marks.new(diagram, placement, router, metrics).tap(&:build)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative "builder"
+require_relative "text"
+require_relative "arrow_style"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Reads the legacy syntax: `(*) --> "Action"` arrows between named
+        # activities, with `if` ... `else` ... `endif`. A direction hint such
+        # as `-left->` is a layout hint and is not kept. The node the flow is
+        # at is `@current`; an arrow with no source starts there.
+        #
+        # PlantUML's own reader is followed where it differs from the new
+        # syntax: the flow after `endif` is the last node the branch drew
+        # (no join, no merge node), `(*)` is a node the flow can leave, and
+        # a quoted activity written twice is one node. An arrow `->`, or one
+        # with `-right->` or `-left->`, lies along its row.
+        class LegacyParser
+          ARROW = /-+(?:\[[^\]]*\]|left|right|up|down)?-*>/
+          STATEMENT = /\A(?<source>\(\*(?:top)?\)|"[^"]*"|={2,}[^=]+={2,}|\w+)?
+                       \s*(?<arrow>#{ARROW})\s*(?:\[(?<label>[^\]]*)\])?
+                       \s*(?<dest>.+?)\s*\z/xm
+          IF = /\Aif\s+(?:"(?<cond>.*)"|\((?<paren>.*)\))\s+then\z/i
+          TITLE = /\Atitle\s+(.+)\z/i
+          BAR = /\A={2,}\s*(.+?)\s*={2,}\z/
+          ACTIVITY = /\A"(.*)"(?:\s+as\s+(\w+))?\z/m
+          private_constant :TITLE, :ARROW, :STATEMENT, :IF, :BAR, :ACTIVITY
+
+          # @param entries [Array<Array(String, Integer)>] lines and numbers
+          # @return [Diagram]
+          def parse(entries)
+            reset
+            join_quoted(entries).each { |line, number| statement(line, number) }
+            refuse("unclosed if", "") unless @frames.empty?
+            @builder.diagram.tap { |diagram| diagram.legacy = true }
+          end
+
+          private
+
+          def reset
+            @builder = Builder.new
+            @current = nil
+            @stop = nil
+            @frames = []
+            @names = {}
+            @labels = {}
+            @bars = {}
+          end
+
+          # A quoted activity may run over several lines.
+          def join_quoted(entries)
+            entries.each_with_object([]) do |(line, number), joined|
+              open_entry = joined.last
+              if open_entry && open_entry[0].count('"').odd?
+                open_entry[0] = "#{open_entry[0]}\n#{line}"
+              else
+                joined << [line, number]
+              end
+            end
+          end
+
+          def statement(line, number)
+            @number = number
+            @line = line
+            case line
+            when TITLE then @builder.title = clean(Regexp.last_match(1))
+            when IF then open_if(Regexp.last_match)
+            when /\Aelse\z/i then open_else
+            when /\Aendif\z/i then close_if
+            when STATEMENT then flow(Regexp.last_match)
+            else refuse("statement", line)
+            end
+          end
+
+          def open_if(match)
+            text = clean(match[:cond] || match[:paren])
+            decision = legacy(@builder.node(:decision, text: text, bare: true))
+            @builder.connect(@current, decision) if @current
+            @frames << decision
+            @current = decision
+          end
+
+          def open_else
+            @current = top
+          end
+
+          # The flow carries on from the last node the closing branch drew.
+          def close_if
+            top
+            @frames.pop
+          end
+
+          def legacy(node)
+            node.tap { |item| item.legacy = true }
+          end
+
+          def flow(match)
+            from = source_of(match)
+            style = ArrowStyle.parse(match[:arrow][/\[([^\]]*)\]/, 1],
+                                     line: @number)
+            dest = destination(match[:dest])
+            edge = @builder.connect(from, dest,
+                                    label: arrow_label(match[:label]), **style)
+            edge.direction = direction(match[:arrow])
+            @current = dest
+          end
+
+          def direction(arrow)
+            return :right if arrow == "->"
+
+            arrow[/left|right/]&.to_sym
+          end
+
+          # The node an arrow leaves: the one written, else wherever the
+          # flow is.
+          def source_of(match)
+            written = match[:source]
+            return resolve(written) if written
+
+            @current or refuse("arrow without a source", @line)
+          end
+
+          def arrow_label(label)
+            label && clean(label)
+          end
+
+          def resolve(source)
+            case source
+            when /\A\(\*(?:top)?\)\z/ then @builder.node(:start)
+            when /\A"/ then activity(source)
+            when BAR then bar(Regexp.last_match(1))
+            else @names.fetch(source) do
+                   refuse("undefined activity #{source}", @line)
+                 end
+            end
+          end
+
+          def destination(text)
+            return (@stop ||= @builder.node(:stop)) if
+              text.match?(/\A\(\*(?:top)?\)\z/)
+            return bar(Regexp.last_match(1)) if text.match(BAR)
+            return activity(text) if text.start_with?('"')
+
+            @names.fetch(text) { refuse("undefined activity #{text}", @line) }
+          end
+
+          def activity(text)
+            match = ACTIVITY.match(text) or refuse("activity", text)
+            return @labels[match[1]] ||= action(match[1]) unless match[2]
+
+            @names[match[2]] = action(match[1])
+          end
+
+          def action(text)
+            @builder.node(:action, text: clean(text))
+          end
+
+          def bar(name)
+            @bars[name] ||= legacy(@builder.node(:bar, text: name))
+          end
+
+          def top
+            @frames.last or refuse("else/endif without if", @line)
+          end
+
+          def clean(text)
+            Text.clean(text, line: @number)
+          end
+
+          def refuse(construct, text)
+            raise UnsupportedConstructError.new(construct: construct,
+                                                line: @number, text: text)
+          end
+        end
+      end
+    end
+  end
+end