etassia 0.1.0

data/lib/etassia/notation/plantuml/sequence/chrome_rows.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "chrome"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # Sizes and places the title, header, caption, footer and legend of
+        # a sequence diagram. The constants are the rows PlantUML draws for
+        # them: `lead` is the room a text takes beyond its lines, `base` the
+        # first baseline below the row's top and `step` the line height.
+        class ChromeRows
+          LINE = 16.49
+          STYLES = {
+            header: { step: 11.78, lead: 1.0, base: 9.67, anchor: "end",
+                      size: 10.0, colour: "#888888", pad: 0.0 },
+            title: { step: LINE, lead: 21.0, base: 23.54, anchor: "middle",
+                     pad: 27.0, bold: true },
+            caption: { step: LINE, lead: 3.0, base: 16.54, anchor: "middle",
+                       pad: 2.0 },
+            footer: { step: 11.78, lead: 1.0, base: 11.67, anchor: "middle",
+                      size: 10.0, colour: "#888888", pad: 0.0 },
+          }.freeze
+          LEGEND_BEFORE = { top: 12.0, bottom: 14.0 }.freeze
+          LEGEND_AFTER = { top: 13.0, bottom: 11.0 }.freeze
+          LEGEND_BOX = 10.0
+          LEGEND_SIDE = 12.0
+          LEGEND_PAD = 5.0
+          LEGEND_BASE = 18.54
+
+          # @param diagram [Diagram]
+          # @param measure [#call] width of a text given the text, a size and
+          #   whether it is drawn bold
+          def initialize(diagram, measure)
+            @diagram = diagram
+            @chrome = diagram.chrome
+            @measure = measure
+          end
+
+          # @return [Float] what a kind pushes the rest of the diagram by
+          def room(kind)
+            count = lines(kind).size
+            return 0.0 if count.zero?
+
+            STYLES.fetch(kind)[:lead] + (STYLES.fetch(kind)[:step] * count)
+          end
+
+          # @return [Float] the room above the participants
+          def top_room
+            room(:header) + room(:title) + legend_room(:top)
+          end
+
+          # @return [Float] the room below the participants
+          def bottom_room
+            legend_room(:bottom) + room(:caption) + room(:footer)
+          end
+
+          # @return [Float] the width the texts need on their own
+          def width
+            kinds = STYLES.keys.map { |kind| text_width(kind) }
+            [*kinds, legend_width + (2 * LEGEND_SIDE)].max
+          end
+
+          # @param top [Float] where the rows above the participants start
+          # @param bottom [Float] where the participants end
+          # @param canvas [Float] the width the texts are placed in
+          # @return [Array<Scene::TextBlock>] the header, caption and footer
+          #   that are written, each with its placed lines
+          def blocks(top, bottom, canvas)
+            tops = row_tops(top, bottom)
+            %i[header caption footer].filter_map do |kind|
+              next if lines(kind).empty?
+
+              Scene::TextBlock.new(id: kind.to_s,
+                                   texts: texts(kind, tops[kind], canvas))
+            end
+          end
+
+          # @param top [Float] where the rows above the participants start
+          # @return [Scene::Title, nil]
+          def title(top, canvas)
+            return if lines(:title).empty?
+
+            Scene::Title.new(
+              texts: texts(:title, top + room(:header), canvas),
+            )
+          end
+
+          # @param top [Float] where the rows above the participants start
+          # @param bottom [Float] where the participants end
+          # @return [Scene::Legend, nil]
+          def legend(top, bottom, canvas)
+            return if lines(:legend).empty?
+
+            edge = @chrome.legend_edge
+            above = top + room(:header) + room(:title)
+            start = edge == :top ? above : bottom
+            box(start + LEGEND_BEFORE.fetch(edge), canvas)
+          end
+
+          # @return [Array<String>] the lines of one kind, empty if unset
+          def lines(kind)
+            return @diagram.title.to_s.split("\n") if kind == :title
+
+            @chrome.lines(kind)
+          end
+
+          private
+
+          def row_tops(top, bottom)
+            caption = bottom + legend_room(:bottom)
+            { header: top, title: top + room(:header), caption: caption,
+              footer: caption + room(:caption) }
+          end
+
+          def texts(kind, top, canvas)
+            style = STYLES.fetch(kind)
+            lines(kind).each_with_index.map do |line, index|
+              text = style.slice(:anchor, :colour, :size)
+              y = top + style[:base] + (style[:step] * index)
+              PlantUML::Scene::Text.new(content: line, role: kind.to_s,
+                                        x: anchor_x(style, canvas), y: y,
+                                        **text)
+            end
+          end
+
+          def anchor_x(style, canvas)
+            style[:anchor] == "end" ? canvas : canvas / 2
+          end
+
+          def text_width(kind)
+            style = STYLES.fetch(kind)
+            widest = lines(kind).map do |line|
+              @measure.call(line, style[:size], bold: style.fetch(:bold, false))
+            end.max
+            widest ? widest + style[:pad] : 0.0
+          end
+
+          def legend_height
+            LEGEND_BOX + (LINE * lines(:legend).size)
+          end
+
+          def legend_room(edge)
+            return 0.0 if lines(:legend).empty? || @chrome.legend_edge != edge
+
+            LEGEND_BEFORE.fetch(edge) + legend_height + LEGEND_AFTER.fetch(edge)
+          end
+
+          def legend_width
+            widest = lines(:legend).map { |line| @measure.call(line, nil) }.max
+            widest ? widest + (2 * LEGEND_PAD) : 0.0
+          end
+
+          def box(top, canvas)
+            left = legend_left(canvas)
+            Scene::Legend.new(
+              x: left, y: top, width: legend_width, height: legend_height,
+              texts: legend_texts(left + LEGEND_PAD, top)
+            )
+          end
+
+          def legend_left(canvas)
+            case @chrome.legend_side
+            when :left then LEGEND_SIDE
+            when :right then canvas - LEGEND_SIDE - legend_width
+            else (canvas - legend_width) / 2
+            end
+          end
+
+          def legend_texts(left, top)
+            lines(:legend).each_with_index.map do |line, index|
+              PlantUML::Scene::Text.new(
+                content: line, role: "legend", x: left,
+                y: top + LEGEND_BASE + (LINE * index), anchor: "start"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/create.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # `create X`: the next message to X makes its head appear at that
+        # row instead of at the top of the diagram.
+        class Create
+          # @param items [Array] a diagram's items
+          # @return [Hash{Message => String}] each message that creates a
+          #   participant, with that participant's id
+          def self.messages(items)
+            pending = nil
+            items.each_with_object({}.compare_by_identity) do |item, found|
+              pending = item.participant if item.is_a?(Create)
+              next unless item.is_a?(Message) && pending == item.to
+
+              found[item] = pending
+              pending = nil
+            end
+          end
+
+          attr_reader :participant
+
+          def initialize(participant:)
+            @participant = participant
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/delay.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # A `...` or `... text ...` line: time passes between two messages.
+        class Delay
+          attr_reader :label
+
+          def initialize(label:)
+            @label = label
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/destroy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # `destroy X`, or the `!!` that ends a message line: a cross on the
+        # lifeline of `participant`.
+        class Destroy
+          attr_reader :participant
+
+          def initialize(participant:)
+            @participant = participant
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "appearance"
+require_relative "chrome"
+require_relative "keyword_defaults"
+require_relative "message"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # What the sequence parser returns: participants in order of first
+        # mention, the items (messages, notes, fragment edges, dividers) in
+        # source order and the boxes around neighbouring participants.
+        # Private to this notation.
+        class Diagram
+          EXTRAS = { footbox: true, warnings: [].freeze, title: nil,
+                     chrome: Chrome::NONE, teoz: false }.freeze
+          private_constant :EXTRAS
+
+          attr_reader :participants, :items, :boxes, :appearance, :warnings,
+                      :title, :chrome
+
+          # @param appearance [Appearance] what skinparam and `<style>` set
+          # @param footbox [Boolean] false after `hide footbox`
+          # @param warnings [Array<String>] drawn as banners above the heads
+          # @param title [String, nil] the lines drawn above everything
+          # @param chrome [Chrome] the header, footer, caption and legend
+          def initialize(participants:, items:, boxes: [].freeze,
+                         appearance: Appearance.new, **extras)
+            @participants = participants
+            @items = items
+            @boxes = boxes
+            @appearance = appearance
+            assign_extras(KeywordDefaults.resolve(extras, EXTRAS))
+            freeze
+          end
+
+          # @return [Integer, nil] the narrowest participant head asked for
+          def min_head_width
+            appearance.min_width
+          end
+
+          def footbox?
+            @footbox
+          end
+
+          def teoz?
+            @teoz
+          end
+
+          # @return [Diagram] this diagram with other items
+          def with_items(items)
+            Diagram.new(participants: participants, items: items,
+                        boxes: boxes, appearance: appearance,
+                        footbox: footbox?, warnings: warnings, title: title,
+                        chrome: chrome, teoz: teoz?)
+          end
+
+          def messages
+            items.grep(Message)
+          end
+
+          # The parser refuses a diagram with no participant.
+          def valid?
+            !participants.empty?
+          end
+
+          def diagram_type
+            :sequence_diagram
+          end
+
+          private
+
+          def assign_extras(extras)
+            @footbox = extras[:footbox]
+            @warnings = extras[:warnings]
+            @title = extras[:title]
+            @chrome = extras[:chrome]
+            @teoz = extras[:teoz]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/divider.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # A `== text ==` line across the whole diagram.
+        class Divider
+          attr_reader :label
+
+          def initialize(label:)
+            @label = label
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # The missing end of a message with no participant there: `[->` and
+        # `->]` run to the edge of the diagram, `?->` and `->?` run a label's
+        # length from the participant they are written beside.
+        class Edge
+          # Room between the participant and the end of such an arrow, on top
+          # of the label.
+          RUN_PADDING = 24.0
+          # A ring at the edge sits this far inside it.
+          RING_INSET = 8.0
+
+          TOKENS = { "[" => false, "]" => false, "?" => true }.freeze
+          private_constant :TOKENS
+
+          attr_reader :side
+
+          # @param token [String] `[`, `]` or `?` as written
+          # @param side [Symbol] :left or :right, by position in the line
+          # @return [Edge, nil] nil for a token that is not an edge
+          def self.read(token, side)
+            return unless TOKENS.key?(token)
+
+            new(side: side, local: TOKENS.fetch(token))
+          end
+
+          def initialize(side:, local:)
+            @side = side
+            @local = local
+            freeze
+          end
+
+          # Measured from the participant instead of from the diagram edge.
+          def local?
+            @local
+          end
+
+          def global?
+            !@local
+          end
+
+          def left?
+            side == :left
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/embedded.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # A sequence diagram written inside a note between `{{` and `}}`
+        # lines. The block is the whole note body, and its first line may be
+        # `scale N`.
+        class Embedded
+          OPEN = /\A\{\{\z/
+          CLOSE = /\A\}\}\z/
+          SCALE = /\Ascale[ \t]+(\d+(?:\.\d+)?)\z/i
+          private_constant :OPEN, :CLOSE, :SCALE
+
+          # @return [Boolean] whether a note body line opens an embedded
+          #   block
+          def self.opens?(line)
+            OPEN.match?(line.strip)
+          end
+
+          # @return [Boolean] whether a note body line closes one
+          def self.closes?(line)
+            CLOSE.match?(line.strip)
+          end
+
+          # @param text [String] the note body
+          # @return [Embedded, nil] nil when the body is not exactly one
+          #   block
+          def self.read(text)
+            lines = text.split("\n", -1).map(&:strip)
+            return unless whole?(lines)
+
+            body = lines[1..-2]
+            scale = SCALE.match(body.first.to_s)
+            body = body.drop(1) if scale
+            new(body.join("\n"), scale ? scale[1].to_f : 1.0)
+          end
+
+          # The block opens on the first line and only closes on the last.
+          def self.whole?(lines)
+            return false unless lines.size > 1
+            return false unless opens?(lines.first) && closes?(lines.last)
+
+            early_close(lines).nil?
+          end
+          private_class_method :whole?
+
+          # @return [Integer, nil] the index of a line before the last that
+          #   closes the opening line's block
+          def self.early_close(lines)
+            depth = 0
+            lines[0..-2].each_index.find do |index|
+              depth += 1 if opens?(lines[index])
+              depth -= 1 if closes?(lines[index])
+              depth.zero?
+            end
+          end
+          private_class_method :early_close
+
+          attr_reader :body, :scale
+
+          def initialize(body, scale)
+            @body = body
+            @scale = scale
+            freeze
+          end
+
+          # @return [String] the block as a diagram of its own
+          def document
+            "@startuml\n#{body}\n@enduml\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/fill.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../style/colour_names"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # The colour written after a participant: `#RGB`, `#RRGGBB`,
+        # `#RRGGBBAA`, `#transparent` or a CSS colour name.
+        # PlantUML draws a fully transparent one as no fill, and keeps any
+        # other alpha as a fill opacity.
+        class Fill
+          PATTERN = /\#(\h{8}|\h{6}|\h{3}|transparent|[a-z]+)(?!\w)/i
+          OPAQUE = 255
+          NONE = "none"
+
+          attr_reader :colour, :opacity
+
+          # @return [Fill, nil] nil when the token is not one of the forms
+          def self.read(token)
+            digits = token&.match(PATTERN)&.[](1)
+            return unless digits
+            return new(NONE) if digits.casecmp?("transparent")
+
+            from_hex(digits) || named(digits)
+          end
+
+          def self.named(name)
+            hex = PlantUML::Style::ColourNames::TABLE[name.downcase]
+            new(hex) if hex
+          end
+          private_class_method :named
+
+          def self.from_hex(digits)
+            return unless digits.match?(/\A\h{3}(?:\h{3}|\h{5})?\z/)
+
+            full = digits.length == 3 ? digits.gsub(/./) { |c| c * 2 } : digits
+            alpha = full.length == 8 ? full[6, 2].hex : OPAQUE
+            return new(NONE) if alpha.zero?
+
+            new("##{full[0, 6].upcase}", alpha == OPAQUE ? nil : alpha)
+          end
+          private_class_method :from_hex
+
+          # @param alpha [Integer, nil] 1..254, or nil for an opaque colour
+          def initialize(colour, alpha = nil)
+            @colour = colour
+            @opacity = alpha && (alpha / 255.0).round(5)
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/sequence/fragment.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # One edge of a `alt ... else ... end` style block. `phase` is :open,
+        # :else or :close; `keyword` is the opening word (alt, loop, group).
+        # An :open edge is `parallel` when its line began with `&`.
+        class Fragment
+          attr_reader :phase, :keyword, :label
+
+          def initialize(phase:, keyword:, label: nil, parallel: false)
+            @phase = phase
+            @keyword = keyword
+            @label = label
+            @parallel = parallel
+            freeze
+          end
+
+          def parallel?
+            @parallel
+          end
+        end
+      end
+    end
+  end
+end