etassia 0.1.0

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Reads a relation glyph such as `<|--`, `o-down-`, `*.r.>` or `..>`.
+      #
+      # A glyph is an optional marker, a body of dashes or dots (a dot makes
+      # the line dashed) that may carry a direction word between two runs,
+      # and an optional marker. The direction word is kept as `:up`, `:down`,
+      # `:left` or `:right` for the layout; a one-character body such as
+      # `->` or `.>` lays out like `:right`. The body's length, its dashes
+      # and dots, sets how many ranks the relation spans.
+      module Arrow
+        extend self
+
+        LEFT_MARKER = '(?:<\||<|o|\*|\+)'
+        RIGHT_MARKER = '(?:\|>|>|o|\*|\+)'
+        # A bare `o` or `*` after the body only ends it before a space or a
+        # quote; otherwise it starts the class name (`A --oB`).
+        RIGHT_IN_LINE = '(?:\|>|>|(?:o|\*|\+)(?=[ \t"]))'
+        # A bracketed style (`-[#red,dashed,thickness=2]->`) stands in for
+        # the dashes; its words after the colour set the line's dashing.
+        BRACKET = '-\[[^\]]*\]-*'
+        BODY = "(?:[-.]+(?:(?:up|down|left|right|u|d|l|r)[-.]+)?" \
+               "|#{BRACKET})".freeze
+
+        # Matches one glyph; embed it, then call {parse} on the match.
+        PATTERN = "(#{LEFT_MARKER}?#{BODY}#{RIGHT_IN_LINE}?)".freeze
+
+        GLYPH = /\A(#{LEFT_MARKER})?(#{BODY})(#{RIGHT_MARKER})?\z/o
+        PLAIN = /\A(?:-->|<--|->|<-)\z/
+        KINDS = { "|" => :extension, "o" => :aggregation,
+                  "*" => :composition, "+" => :nesting }.freeze
+        PLAIN_HEADS = %w[< >].freeze
+        DIRECTIONS = { "u" => :up, "d" => :down, "l" => :left,
+                       "r" => :right }.freeze
+        DASHING = /\b(?:dashed|dotted)\b/i
+        private_constant :BRACKET, :DASHING, :LEFT_MARKER, :RIGHT_MARKER,
+                         :RIGHT_IN_LINE, :BODY, :GLYPH, :PLAIN, :KINDS,
+                         :PLAIN_HEADS, :DIRECTIONS
+
+        # @return [Hash, nil] `:markers` (side to kind, left first), `:dashed`,
+        #   `:kind` and `:head` (:left, :right, or :both with a nil kind when
+        #   both ends carry a marker), `:direction` (nil without a word),
+        #   `:length` (the body's dashes and dots) and `:plain` (a bare
+        #   association
+        #   arrow, which a sequence diagram also has); nil for `<->`, which
+        #   a sequence diagram also has and which is not drawn here
+        def parse(glyph)
+          match = GLYPH.match(glyph)
+          left, body, right = match.captures
+          return if plain_heads?(left, right)
+
+          details(glyph, left, body, right)
+        end
+
+        private
+
+        def plain_heads?(left, right)
+          [left, right].all? { |end_| PLAIN_HEADS.include?(end_) }
+        end
+
+        def details(glyph, left, body, right)
+          style = body[/\[([^\]]*)\]/, 1]
+          body = body.sub(/\[[^\]]*\]/, "") if style
+          dashed = body.include?(".") || DASHING.match?(style.to_s)
+          markers = markers_of(left, right, dashed)
+          { markers: markers, dashed: dashed, head: head_of(markers),
+            kind: single_kind(markers, dashed), plain: PLAIN.match?(glyph),
+            direction: direction_of(body), length: body.count("-.") }
+            .merge(stroke_of(style.to_s))
+        end
+
+        def markers_of(left, right, dashed)
+          { left: left, right: right }.compact
+            .transform_values { |marker| kind_of(marker, dashed) }
+        end
+
+        # The bracket's colour, thickness and dotted flag; absent keys mean
+        # the theme's own line. Of comma-separated colours the last wins, as
+        # in the JAR; of a `#red;#green` pair the first.
+        def stroke_of(style)
+          words = style.split(/[,;]/).map(&:strip)
+          { color: color_of(style),
+            width: thickness_of(words),
+            dotted: words.any? { |word| word.casecmp?("dotted") } }
+        end
+
+        def color_of(style)
+          style.split(",").filter_map do |group|
+            group.split(";").first.to_s.strip[/\A#(\w+)\z/, 1]
+          end.last
+        end
+
+        def thickness_of(words)
+          width = words.filter_map { |word| word[/\Athickness=(\d+)/, 1] }
+            .first.to_i
+          width if width.positive?
+        end
+
+        def direction_of(body)
+          word = body[/[a-z]+/]
+          return DIRECTIONS[word[0]] if word
+
+          :right if body.size == 1
+        end
+
+        def single_kind(markers, dashed)
+          return line_kind(dashed) if markers.empty?
+
+          markers.values.first if markers.size == 1
+        end
+
+        def kind_of(marker, dashed)
+          shape = marker.delete("<>")
+          return line_kind(dashed) if shape.empty?
+          return dashed ? :implementation : :extension if shape == "|"
+
+          KINDS.fetch(shape)
+        end
+
+        def line_kind(dashed)
+          dashed ? :dependency : :association
+        end
+
+        def head_of(markers)
+          return :both if markers.size == 2
+
+          markers.keys.first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # One of the five statements PlantUML draws around a diagram: its
+      # `kind` is :title, :header, :footer, :caption or :legend and `text`
+      # the one plain line written after the word.
+      class Caption
+        KINDS = %i[title header footer caption legend].freeze
+
+        # A text this notation can draw as written: no creole or HTML markup,
+        # no escape sequence, and none of the alignment words PlantUML reads
+        # after `legend`, which open a block.
+        PLAIN = /\A[[:alnum:]][[:alnum:] .,:;!?()'-]*\z/
+        ARROW_START = /\A\S*(?:--|\.\.|->|<-)/
+        ALIGNMENT = /\A(?:left|right|center|top|bottom)\z/i
+        LINE = /\A(#{KINDS.join('|')})[ \t]+(.+)\z/io
+        private_constant :PLAIN, :ARROW_START, :ALIGNMENT, :LINE
+
+        # @param text [String] one stripped source line
+        # @return [Caption, nil] nil when the line is not a caption this
+        #   notation draws: another statement, a block form, or markup
+        def self.read(text)
+          match = LINE.match(text)
+          return unless match
+
+          body = match[2].strip
+          return unless PLAIN.match?(body) && !ARROW_START.match?(body)
+          return if match[1].casecmp?("legend") && ALIGNMENT.match?(body)
+
+          new(match[1].downcase.to_sym, body)
+        end
+
+        # @return [Boolean] whether one line of a block is plain text
+        def self.plain?(text)
+          PLAIN.match?(text) && !ARROW_START.match?(text)
+        end
+
+        attr_reader :kind, :text
+
+        def initialize(kind, text)
+          @kind = kind
+          @text = text
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "caption_rows"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Places a diagram's captions around an already laid out Scene: header
+      # and title above it, legend, caption and footer below it, each on its
+      # own row. The content keeps its coordinates and moves as a whole by
+      # the Scene's `content_x` and `content_y`.
+      class CaptionLayout
+        PADDING = 5.0
+        SMALL = %i[header footer].freeze
+        SMALL_SIZE = 10.0
+        LEGEND_FILL = "#DDDDDD"
+        SMALL_COLOUR = "#888888"
+        private_constant :PADDING, :SMALL, :SMALL_SIZE, :LEGEND_FILL,
+                         :SMALL_COLOUR
+
+        # @param diagram [Diagram]
+        # @param normal_size [Float] the font size of a title, caption or
+        #   legend that the style does not set
+        # @param measure [#call] width of a text given the text and its size
+        def initialize(diagram, normal_size:, measure:)
+          @diagram = diagram
+          @normal_size = normal_size
+          @measure = measure
+        end
+
+        # @param scene [Scene] the content, freshly built: it is resized and
+        #   given the panels in place
+        # @return [Scene] the same Scene, as large as content and captions
+        def dress(scene)
+          panels = sized_panels
+          return scene if panels.empty? && @diagram.style.background.nil?
+
+          width = canvas_width(scene, panels)
+          settle(scene, width, CaptionRows.new(panels, width, scene.height))
+          scene.background = @diagram.style.background
+          scene
+        end
+
+        private
+
+        # The old width is read before it is replaced.
+        def settle(scene, width, rows)
+          scene.content_x = (width - scene.width) / 2
+          scene.content_y = rows.content_y
+          scene.width = width
+          scene.height = rows.bottom_edge
+          scene.panels = rows.panels
+        end
+
+        def canvas_width(scene, panels)
+          widest = panels.map(&:width).max.to_f
+          [scene.width, widest + (CaptionRows::GAP * 2)].max
+        end
+
+        def sized_panels
+          @diagram.captions.map { |caption| panel(caption) }
+        end
+
+        def panel(caption)
+          kind = caption.kind
+          rule = @diagram.style.rule(kind)
+          size = size_of(kind, rule)
+          Scene::Panel.new(
+            id: "caption-#{kind}", kind: kind.to_s, font_size: size,
+            content: caption.text, **extent_of(caption.text, size),
+            **look_of(kind, rule)
+          )
+        end
+
+        def extent_of(text, size)
+          { width: @measure.call(text, size) + (PADDING * 2),
+            height: (size * 1.2) + (PADDING * 2) }
+        end
+
+        def look_of(kind, rule)
+          { bordered: kind == :legend, bold: kind == :title,
+            fill: rule[:background] || (LEGEND_FILL if kind == :legend),
+            colour: rule[:colour] || (SMALL_COLOUR if SMALL.include?(kind)) }
+        end
+
+        def size_of(kind, rule)
+          (rule[:size] || default_size(kind)).to_f
+        end
+
+        def default_size(kind)
+          SMALL.include?(kind) ? SMALL_SIZE : @normal_size
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Stacks sized caption panels into the rows above and below the
+      # diagram content: header and title above it, legend, caption and
+      # footer below it, each kind on its own row.
+      class CaptionRows
+        GAP = 10.0
+        TOP = %i[header title].freeze
+        BOTTOM = %i[legend caption footer].freeze
+        private_constant :TOP, :BOTTOM
+
+        # @param panels [Array<Scene::Panel>] sized, not yet positioned
+        # @param width [Float] the width of the whole picture
+        # @param content_height [Float] the height of the diagram content
+        def initialize(panels, width, content_height)
+          @panels = panels
+          @width = width
+          @top = stack(TOP, GAP)
+          @content_y = @top.empty? ? 0.0 : @top.last.y + @top.last.height
+          @below = @content_y + content_height
+          @bottom = stack(BOTTOM, @below)
+        end
+
+        # @return [Float] where the diagram content starts
+        attr_reader :content_y
+
+        # @return [Array<Scene::Panel>] every panel, positioned
+        def panels
+          @top + @bottom
+        end
+
+        # @return [Float] the height of the whole picture
+        def bottom_edge
+          @bottom.empty? ? @below : @bottom.last.y + @bottom.last.height + GAP
+        end
+
+        private
+
+        # Stacks the kinds in `order` that are present, top to bottom from
+        # `start`, and returns them positioned.
+        def stack(order, start)
+          cursor = start
+          order.filter_map do |kind|
+            panel = @panels.find { |item| item.kind == kind.to_s }
+            next unless panel
+
+            positioned = at(panel, cursor)
+            cursor += panel.height + GAP
+            positioned
+          end
+        end
+
+        def at(panel, top)
+          left = (@width - panel.width) / 2
+          left = @width - GAP - panel.width if panel.kind == "header"
+          panel.tap do |item|
+            item.x = left
+            item.y = top
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # What PlantUML draws in a class box's header beyond its name: the
+      # circled letter (C for a class, A for an abstract class, I for an
+      # interface, E for an enum, @ for an annotation) and, in a class
+      # with no members, the two rules of its empty compartments. Placed
+      # after layout, from the final box geometry, so it never changes a
+      # size.
+      module ClassHeader
+        extend self
+
+        Glyph = Struct.new(:fill, :outline)
+
+        RADIUS = 11.0
+        # Offsets from the class name's baseline and from the start of the
+        # circle-and-name block, measured against PlantUML 1.2026.6.
+        CENTRE_ABOVE_BASELINE = 5.291
+        NAME_GAP = 3.0
+        # An empty class is 48 high: its field and method compartments end
+        # 32 and 40 below the top.
+        EMPTY_HEIGHT = 48.0
+        EMPTY_RULES = [32.0, 40.0].freeze
+        BLOCK_SHIFT = 0.5
+        # Outlines are relative to the circle's centre.
+        GLYPHS = {
+          class: Glyph.new(
+            "#ADD1B2",
+            %w[M2.4731,6.1431 Q1.8921,6.4419 1.2529,6.5913 Q0.6138,6.7407
+               -0.0918,6.7407 Q-2.5986,6.7407 -3.9185,5.0889
+               Q-5.2383,3.437 -5.2383,0.3159 Q-5.2383,-2.8135
+               -3.9185,-4.4653 Q-2.5986,-6.1172 -0.0918,-6.1172
+               Q0.6138,-6.1172 1.2612,-5.9678 Q1.9087,-5.8184
+               2.4731,-5.5195 L2.4731,-2.7969 Q1.8423,-3.3779
+               1.2488,-3.6477 Q0.6553,-3.9175 0.0244,-3.9175
+               Q-1.3203,-3.9175 -2.0051,-2.8508 Q-2.6899,-1.7842
+               -2.6899,0.3159 Q-2.6899,2.4077 -2.0051,3.4744
+               Q-1.3203,4.541 0.0244,4.541 Q0.6553,4.541 1.2488,4.2712
+               Q1.8423,4.0015 2.4731,3.4204 Z].join(" "),
+          ),
+          abstract: Glyph.new(
+            "#A9DCDF",
+            %w[M-0.1367,-4.6519 L-1.2905,0.4199 L1.0254,0.4199 Z
+               M-1.6309,-6.8931 L1.3657,-6.8931 L4.7109,5.5 L2.2622,5.5
+               L1.4985,2.437 L-1.7803,2.437 L-2.5273,5.5
+               L-4.9761,5.5 Z].join(" "),
+          ),
+          interface: Glyph.new(
+            "#B4A7E5",
+            %w[M-3.5723,-3.7349 L-3.5723,-5.8931 L3.8071,-5.8931
+               L3.8071,-3.7349 L1.3418,-3.7349 L1.3418,4.3418
+               L3.8071,4.3418 L3.8071,6.5 L-3.5723,6.5 L-3.5723,4.3418
+               L-1.1069,4.3418 L-1.1069,-3.7349 Z].join(" "),
+          ),
+          enum: Glyph.new(
+            "#EB937F",
+            %w[M3.6143,6.5 L-4.1055,6.5 L-4.1055,-5.8931 L3.6143,-5.8931
+               L3.6143,-3.7349 L-1.6567,-3.7349 L-1.6567,-1.062
+               L3.1162,-1.062 L3.1162,1.0962 L-1.6567,1.0962
+               L-1.6567,4.3418 L3.6143,4.3418 Z].join(" "),
+          ),
+          annotation: Glyph.new(
+            "#E3664A",
+            %w[M2.5767,0.2261 Q2.5767,-0.7119 2.1533,-1.2432
+               Q1.73,-1.7744 0.9912,-1.7744 Q0.2524,-1.7744
+               -0.1667,-1.2432 Q-0.5859,-0.7119 -0.5859,0.2261
+               Q-0.5859,1.1724 -0.1667,1.7036 Q0.2524,2.2349
+               0.9912,2.2349 Q1.73,2.2349 2.1533,1.7036 Q2.5767,1.1724
+               2.5767,0.2261 Z M4.1206,3.6294 L2.4937,3.6294
+               L2.4937,2.9487 Q2.1782,3.3887 1.7507,3.592 Q1.3232,3.7954
+               0.7256,3.7954 Q-0.6357,3.7954 -1.47,2.8159 Q-2.3042,1.8364
+               -2.3042,0.2261 Q-2.3042,-1.376 -1.4741,-2.3513
+               Q-0.644,-3.3267 0.7256,-3.3267 Q1.3149,-3.3267
+               1.7632,-3.1233 Q2.2114,-2.9199 2.4937,-2.5298
+               L2.4937,-2.8701 Q2.4937,-3.999 1.8752,-4.6133
+               Q1.2568,-5.2275 0.1113,-5.2275 Q-1.6152,-5.2275
+               -2.7068,-3.7085 Q-3.7983,-2.1895 -3.7983,0.2427
+               Q-3.7983,2.791 -2.5366,4.2976 Q-1.2749,5.8042
+               0.8252,5.8042 Q1.4893,5.8042 2.1118,5.6091 Q2.7344,5.4141
+               3.3071,5.0239 L4.0708,6.4849 Q3.3984,6.9414 2.6057,7.1697
+               Q1.813,7.3979 0.9082,7.3979 Q-1.9971,7.3979 -3.7236,5.4639
+               Q-5.4502,3.5298 -5.4502,0.2427 Q-5.4502,-2.9697
+               -3.8979,-4.8997 Q-2.3457,-6.8296 0.2109,-6.8296
+               Q2.0205,-6.8296 3.0706,-5.738 Q4.1206,-4.6465
+               4.1206,-2.7622 Z].join(" "),
+          ),
+        }.freeze
+        private_constant :GLYPHS, :CENTRE_ABOVE_BASELINE, :NAME_GAP,
+                         :BLOCK_SHIFT,
+                         :EMPTY_HEIGHT, :EMPTY_RULES
+
+        # @param diagram [Diagram]
+        # @param scene [Scene] class boxes already placed
+        # @param measure [#call] width of a text given the text
+        # @return [Scene] the same scene, its class boxes dressed
+        def apply(diagram, scene, measure)
+          kinds = spot_kinds(diagram)
+          scene.boxes.select { |box| box.kind == "class" }.each do |box|
+            place(box, kinds[box.id], measure)
+            rule_empty_compartments(box)
+          end
+          scene
+        end
+
+        # @return [Glyph, nil] the colour and outline of a kind's circle
+        def glyph(kind)
+          GLYPHS[kind]
+        end
+
+        # @return [Boolean] whether `hide circle` is in force
+        def circles_hidden?(diagram)
+          diagram.directives.any? do |line|
+            line.match?(/\Ahide[ \t]+circle\z/i)
+          end
+        end
+
+        private
+
+        # Class name to kind, empty when `hide circle` is in force.
+        def spot_kinds(diagram)
+          return {} if circles_hidden?(diagram)
+
+          diagram.classes.to_h { |klass| [klass.name, klass.kind] }
+        end
+
+        def rule_empty_compartments(box)
+          return unless empty?(box)
+
+          EMPTY_RULES.each { |offset| box.separators << rule_at(box, offset) }
+        end
+
+        def rule_at(box, offset)
+          y = box.y + offset
+          Scene::Segment.new(x1: box.x, y1: y, x2: box.x + box.width, y2: y)
+        end
+
+        def empty?(box)
+          box.separators.empty? &&
+            (box.height - EMPTY_HEIGHT).abs < 0.01 &&
+            box.texts.all? { |text| text.role == "class_name" }
+        end
+
+        # The circle and the name sit side by side, centred on the box.
+        def place(box, kind, measure)
+          name = sole_name(box)
+          return unless name && GLYPHS.key?(kind) && box.spot.nil?
+
+          left = name.x - (block_width(name, measure) / 2) + BLOCK_SHIFT
+          box.spot = spot_at(kind, left, name.y)
+          start_after_spot(name, left)
+        end
+
+        def start_after_spot(name, left)
+          name.x = left + (2 * RADIUS) + NAME_GAP
+          name.anchor = "start"
+        end
+
+        def sole_name(box)
+          names = box.texts.select { |text| text.role == "class_name" }
+          names.first if names.one?
+        end
+
+        def spot_at(kind, left, baseline)
+          Scene::Spot.new(kind: kind.to_s, cx: left + RADIUS,
+                          cy: baseline - CENTRE_ABOVE_BASELINE)
+        end
+
+        def block_width(name, measure)
+          (2 * RADIUS) + NAME_GAP + measure.call(name.content)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The text PlantUML draws for a class named in quotes. The part after
+      # the last dot is the class; the parts before it are its namespaces.
+      #
+      # `\n`, `\r` and `\l` end a line, `\t` is a gap and `\\` is one
+      # backslash. Any other backslash stays as written. `\uXXXX` is also
+      # read by PlantUML and is not read here, so {escapes?} lets a caller
+      # refuse it.
+      module ClassName
+        extend self
+
+        LINE_BREAKS = %w[n r l].freeze
+        GAP = "\u00A0" * 4
+        EMPTY_LINE = "\u00A0"
+        private_constant :LINE_BREAKS, :GAP, :EMPTY_LINE
+
+        # @return [Boolean] true when `name` holds a `\u` escape
+        def escapes?(name)
+          name.include?("\\u")
+        end
+
+        # @return [Array<String>] the namespaces, outermost first
+        def namespaces(name)
+          name.split(".", -1)[0...-1]
+        end
+
+        # @return [Array<String>] the drawn lines of the class itself; a
+        #   blank line is a non-breaking space so it keeps its height
+        def lines(name)
+          text = name.split(".", -1).last.gsub(/\\(.)/m) { unescape($1) }
+          text.split("\n", -1).map do |line|
+            line.strip.then { |kept| kept.empty? ? EMPTY_LINE : kept }
+          end
+        end
+
+        private
+
+        def unescape(char)
+          return "\n" if LINE_BREAKS.include?(char)
+          return GAP if char == "t"
+
+          char == "\\" ? "\\" : "\\#{char}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "node_graph"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML component and basic deployment diagram: components,
+      # interfaces and deployment nodes. Dispatched to from {PlantUML.parse}.
+      module Component
+        extend self
+
+        # Lines only a component or deployment diagram has. `package`,
+        # `database` and `interface` are not here: classes and sequences use
+        # them too.
+        MARKER = /\A(?:\[[^\]]+\]|component\s|portin\s|portout\s|\(\)\s|
+                   (?:node|cloud|file|folder|frame|storage|artifact|card|
+                   rectangle|archimate)\s)/xi
+        private_constant :MARKER
+
+        # @return [Boolean] whether the source reads as a component diagram
+        def component?(source)
+          lines = NodeGraph.lines_of(source)
+          lines.none? { |line| NodeGraph::FOREIGN.match?(line) } &&
+            lines.any? { |line| MARKER.match?(line) }
+        end
+
+        # @return [Notation::Parsed]
+        def parse(source)
+          NodeGraph.parsed(source, type: :component_diagram,
+                                   direction: :top_to_bottom,
+                                   default_kind: :interface)
+        end
+      end
+    end
+  end
+end