etassia 0.1.0

data/lib/etassia/notation/plantuml/tree/role.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Tree
+        # What a tree node carries beyond its text, spelled as the node's IR
+        # role: the side of its parent it hangs on, whether it draws no box,
+        # and the fill a style class gave it. `left_boxless_bg_lightgreen`
+        # reads back as all three.
+        class Role
+          PATTERN = /\A(left|right)(_boxless)?(?:_bg_([0-9a-z]+))?\z/
+          HEX = /\A(?:\h{6}|\h{3})\z/
+          private_constant :PATTERN, :HEX
+
+          attr_reader :side, :fill
+
+          # @param role [String, nil] an IR node role
+          # @return [Role]
+          def self.parse(role)
+            match = PATTERN.match(role.to_s)
+            return new("right", false, nil) unless match
+
+            new(match[1], !match[2].nil?, fill_of(match[3]))
+          end
+
+          # A fill is a CSS colour name or three or six hex digits; a role
+          # token cannot hold the `#`.
+          def self.fill_of(token)
+            return unless token
+
+            token.match?(HEX) ? "##{token}" : token
+          end
+          private_class_method :fill_of
+
+          # @return [String] the role token for the parts
+          def self.spell(side:, boxless: false, fill: nil)
+            token = side.dup
+            token << "_boxless" if boxless
+            token << "_bg_#{fill.delete_prefix('#').downcase}" if fill
+            token
+          end
+
+          def initialize(side, boxless, fill)
+            @side = side
+            @boxless = boxless
+            @fill = fill
+          end
+
+          def boxless
+            @boxless
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/tree/rules.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "../style/colour"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Tree
+        # What the `<style>` blocks of a mindmap or work breakdown source say
+        # about its nodes and connectors. A rule's selectors nest
+        # (`arrow { :depth(2) { LineColor blue } }`); it applies to an
+        # element that every selector of its path names: `node`, `arrow`,
+        # `boxless`, `:depth(n)`, and the diagram wrapper. A later rule wins
+        # over an earlier one of the same specificity, a longer path over a
+        # shorter one. A selector this class does not know never matches.
+        class Rules
+          WRAPPERS = %w[wbsdiagram mindmapdiagram document root
+                        element].freeze
+          KINDS = %w[node arrow boxless].freeze
+          DEPTH = /\A:depth\((\d+)\)\z/
+          OPENING = /\A(.+?)[ \t]*\{\z/
+          PROPERTY = /\A(\w+)[ \t:]+(.+?)[ \t;]*\z/
+          NAMES = { "linecolor" => :stroke, "backgroundcolor" => :fill,
+                    "fontcolor" => :font_colour,
+                    "linethickness" => :stroke_width,
+                    "linestyle" => :dasharray,
+                    "roundcorner" => :round_corner }.freeze
+          Rule = Struct.new(:path, :properties, :order)
+          private_constant :WRAPPERS, :KINDS, :DEPTH, :OPENING, :PROPERTY,
+                           :NAMES, :Rule
+
+          # @param text [String] the inside of one `<style>` block
+          # @return [Rules]
+          def self.parse(text)
+            new.add(text)
+          end
+
+          def initialize
+            @rules = []
+          end
+
+          # @param text [String] the inside of one `<style>` block
+          # @return [Rules] self
+          def add(text)
+            path = []
+            tokens(text).each { |line| path = read(line, path) }
+            self
+          end
+
+          # @return [Boolean] whether any rule is set
+          def any?
+            !@rules.empty?
+          end
+
+          # @param depth [Integer] 0 for the root
+          # @param boxless [Boolean] whether the node draws no box
+          # @return [Hash] the properties the node's rules set
+          def node(depth, boxless: false)
+            tags = ["node", "depth(#{depth})"]
+            tags << "boxless" if boxless
+            resolve(tags)
+          end
+
+          # @param depth [Integer] the depth of the parent the connector
+          #   leaves, 0 for the root
+          # @return [Hash] the properties the connector's rules set
+          def arrow(depth)
+            resolve(["arrow", "depth(#{depth})"])
+          end
+
+          private
+
+          def tokens(text)
+            text.gsub(%r{//[^\n]*}, "").gsub("{", "{\n").gsub("}", "\n}\n")
+              .lines.map(&:strip).reject(&:empty?)
+          end
+
+          def read(line, path)
+            return path.first(path.length - 1) if line == "}"
+
+            opening = OPENING.match(line)
+            return path + [opening[1].downcase.split(/[ \t]*,[ \t]*/)] if
+              opening
+
+            store(path, line)
+            path
+          end
+
+          def store(path, line)
+            match = PROPERTY.match(line)
+            name = NAMES[match && match[1].downcase]
+            return unless name
+
+            @rules << Rule.new(path.dup, { name => match[2] },
+                               @rules.length)
+          end
+
+          def resolve(tags)
+            matching = @rules.select { |rule| applies?(rule.path, tags) }
+            ordered = matching.sort_by do |rule|
+              [specificity(rule), rule.order]
+            end
+            typed(ordered.map(&:properties).reduce({}, :merge))
+          end
+
+          def applies?(path, tags)
+            path.all? do |alternatives|
+              alternatives.any? { |selector| names?(selector, tags) }
+            end
+          end
+
+          def names?(selector, tags)
+            return true if WRAPPERS.include?(selector)
+
+            depth = DEPTH.match(selector)
+            return tags.include?("depth(#{depth[1]})") if depth
+
+            KINDS.include?(selector) && tags.include?(selector)
+          end
+
+          def specificity(rule)
+            rule.path.count { |alternatives| !wrapper?(alternatives) }
+          end
+
+          def wrapper?(alternatives)
+            alternatives.all? { |selector| WRAPPERS.include?(selector) }
+          end
+
+          def typed(found)
+            found.to_h { |name, value| [name, convert(name, value)] }
+              .compact
+          end
+
+          def convert(name, value)
+            case name
+            when :stroke, :fill, :font_colour then Style::Colour.resolve(value)
+            when :stroke_width, :round_corner then number(value)
+            else dash(value)
+            end
+          end
+
+          def number(value)
+            Float(value)
+          rescue ArgumentError
+            nil
+          end
+
+          def dash(value)
+            length = number(value)
+            "#{length.to_i},#{length.to_i}" if length&.positive?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/tree/wbs_layout.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "layout"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Tree
+        # PlantUML's work breakdown structure: the root on top, its children
+        # in a row under a bus line, and every deeper level hanging in a
+        # column from the middle of its parent with short stubs to each box.
+        class WbsLayout < Layout
+          ROW_GAP = 40.0
+          COLUMN_GAP = 15.0
+          BLOCK_GAP = 20.0
+          STUB = 10.0
+          private_constant :ROW_GAP, :COLUMN_GAP, :BLOCK_GAP, :STUB
+
+          private
+
+          def font_size
+            12.0
+          end
+
+          def gap_between_trees
+            BLOCK_GAP
+          end
+
+          # The jar leaves a boxless node's text one above and below.
+          def boxless_pad_y
+            1.0
+          end
+
+          def stroke_width
+            1.5
+          end
+
+          def place_tree(root, top)
+            blocks = row_blocks(root, top)
+            hub = box(root, hub_centre(blocks) - (root.width / 2.0), top)
+            bus(hub, blocks)
+            [top + root.height, *blocks.map(&:bottom)].max
+          end
+
+          def row_blocks(root, top)
+            row_top = top + root.height + ROW_GAP
+            root.children.map { |child| row_block(child, row_top) }
+          end
+
+          def hub_centre(blocks)
+            return 0.0 if blocks.empty?
+
+            (blocks.first.center + blocks.last.center) / 2.0
+          end
+
+          # A first-level child with its descendants, left to right.
+          Block = Struct.new(:box, :bottom) do
+            def center
+              box.x + (box.item.width / 2.0)
+            end
+          end
+          private_constant :Block
+
+          def row_block(item, top)
+            boxes_from = @boxes.size
+            segments_from = @segments.size
+            placed = box(item, 0.0, top)
+            bottom = hang(placed)
+            align_row(@boxes[boxes_from..], segments_from)
+            Block.new(placed, bottom)
+          end
+
+          def align_row(members, segments_from)
+            offset = (@row_end || 0.0) - members.map(&:x).min
+            members.each { |member| member.x += offset }
+            shift_segments(segments_from, offset)
+            @row_end = members.map(&:right).max + BLOCK_GAP
+          end
+
+          def shift_segments(from, offset)
+            (from...@segments.length).each do |index|
+              @segments[index] = shift_path(@segments[index], offset)
+            end
+          end
+
+          def bus(hub, blocks)
+            return if blocks.empty?
+
+            mid = hub.item.height + hub.y + (ROW_GAP / 2.0)
+            trunk(hub, mid)
+            branches(blocks, mid)
+          end
+
+          def trunk(hub, mid)
+            centre = hub.x + (hub.item.width / 2.0)
+            segment(centre, hub.y + hub.item.height, centre, mid, 0)
+          end
+
+          def branches(blocks, mid)
+            xs = blocks.map(&:center)
+            segment(xs.min, mid, xs.max, mid, 0) if xs.min != xs.max
+            blocks.each { |b| segment(b.center, mid, b.center, b.box.y, 0) }
+          end
+
+          # Hangs the children of a placed box under it; returns the bottom
+          # of the lowest thing placed.
+          def hang(parent)
+            item = parent.item
+            bottom = parent.y + item.height
+            return bottom if item.children.empty?
+
+            centre = parent.x + (item.width / 2.0)
+            ends = hang_columns(parent, centre, bottom + COLUMN_GAP)
+            join_columns(centre, bottom, ends, parent_depth(item))
+          end
+
+          # The depth a connector under this item is styled by.
+          def parent_depth(item)
+            item.level - 1
+          end
+
+          def hang_columns(parent, centre, top)
+            right, left = parent.item.children.partition do |child|
+              child.side == "right"
+            end
+            [column(parent, right, centre, top, 1),
+             column(parent, left, centre, top, -1)]
+          end
+
+          # Joins the columns' last boxes to the parent; returns the lowest
+          # bottom.
+          def join_columns(centre, from, ends, depth)
+            last_centre = ends.filter_map(&:last).max
+            segment(centre, from, centre, last_centre, depth) if last_centre
+            ends.map(&:first).max
+          end
+
+          # Stacks children in one column; returns [bottom, last centre].
+          def column(_parent, items, centre, top, direction)
+            cursor = top
+            last = nil
+            lowest = top - COLUMN_GAP
+            items.each do |item|
+              placed = stub_box(item, centre, cursor, direction)
+              last = placed.mid_y
+              lowest = hang(placed)
+              cursor = lowest + COLUMN_GAP
+            end
+            [lowest, last]
+          end
+
+          def stub_box(item, mid, cursor, direction)
+            edge = direction.positive? ? mid + STUB : mid - STUB - item.width
+            placed = box(item, edge, cursor)
+            reach = direction.positive? ? placed.x : placed.right
+            segment(mid, placed.mid_y, reach, placed.mid_y,
+                    parent_depth(item) - 1)
+            placed
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "tree/reader"
+require_relative "tree/mindmap_layout"
+require_relative "tree/wbs_layout"
+require_relative "tree/renderer"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML mindmap (`@startmindmap`) and work breakdown structure
+      # (`@startwbs`). The front end reads either into the hierarchy graph
+      # Etassia's mindmap uses; the layouts and the renderer are PlantUML's
+      # own, because Mermaid's mindmap is a force layout of coloured shapes
+      # and PlantUML draws a tree. Dispatched to from {PlantUML.parse}.
+      module Tree
+        extend self
+
+        # kind => [IR graph id, layout]
+        KINDS = {
+          "mindmap" => ["mindmap", MindmapLayout],
+          "wbs" => ["wbs", WbsLayout],
+        }.freeze
+        private_constant :KINDS
+
+        # @param source [String] PlantUML source
+        # @param kind [String] "mindmap" or "wbs"
+        # @return [Notation::Parsed]
+        def parse(source, kind)
+          id, layout = KINDS.fetch(kind)
+          reader = Reader.new
+          diagram = reader.parse(source, id: id)
+          Notation::Parsed.new(
+            type: :mindmap, diagram: diagram,
+            transform: layout.styled(reader.rules), renderer: Renderer
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../../error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Raised for PlantUML that is valid or invalid but outside the subset
+      # this notation reads. A Etassia::Error, so the engine propagates it
+      # unwrapped.
+      class UnsupportedConstructError < Etassia::Error
+        # Longest stretch of the offending line the message quotes.
+        EXCERPT_LIMIT = 60
+        private_constant :EXCERPT_LIMIT
+
+        # @return [String] what was refused, e.g. "enum" or "note"
+        attr_reader :construct
+
+        # @return [Integer] 1-based line of the construct
+        attr_reader :line
+
+        def initialize(construct:, line:, text:)
+          @construct = construct
+          @line = line
+          super("PlantUML #{construct} is not yet supported " \
+                "(line #{line}): #{excerpt(text).inspect}")
+        end
+
+        private
+
+        def excerpt(text)
+          return text if text.length <= EXCERPT_LIMIT
+
+          "#{text[0, EXCERPT_LIMIT - 3]}..."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Names the PlantUML construct on a line the parser does not read.
+      #
+      # A name is for the person reading the error, not a promise that the
+      # construct is valid PlantUML. `name_for` is asked only after the parser
+      # has refused a line. `member_construct` is also asked first, because a
+      # separator or modifier would otherwise read as a field.
+      module UnsupportedConstructs
+        extend self
+
+        # The element types of `plantuml -language` (section `;type`, 1.2026.6),
+        # less the five the parser reads, plus the statements that are not an
+        # element: note, layout, styling and page commands.
+        KEYWORDS = %w[
+          action actor agent analog archimate artifact binary
+          boundary card circle cloud clock collections component concise
+          control database dataclass diamond entity exception file folder
+          frame hexagon json label map metaclass network node nwdiag object
+          package packetdiag participant person port portin portout process
+          protocol queue record rectangle relationship robust stack state
+          storage struct usecase yaml
+          allow_mixing allowmixing caption footer header hide hnote legend
+          namespace newpage note remove restore rnote scale set show skinparam
+          stereotype title together
+        ].freeze
+
+        # A keyword that PlantUML reads in any letter case is also a plausible
+        # class name (`State --> Idle`), so a keyword whose next token is an
+        # arrow is a relation, not that construct.
+        KEYWORD = /\A(#{KEYWORDS.join('|')})\b
+                   (?![ \t]+(?:"[^"]*"[ \t]+)?\S*(?:--|\.\.|->|<-))/iox
+
+        # Valid in any scope, so a class body names them too.
+        GLOBAL_RULES = [
+          [/\A!/, "preprocessor directive"],
+        ].freeze
+
+        # Tried in order. A String is the construct's name; nil means the
+        # first capture group is, lowercased. PlantUML reads keywords and
+        # modifiers in any letter case, so a pattern holding letters is /i.
+        STATEMENT_RULES = [
+          [KEYWORD, nil],
+          *GLOBAL_RULES,
+          [/\A[+\-#~]package\b/i, "package"],
+          [/\A(?:left to right|top to bottom) direction\z/i,
+           "layout direction"],
+          [/\A(?:abstract|class|interface|static[ \t]+class)\b(?=.*<<)/i,
+           "stereotype"],
+          [/\A(?:abstract[ \t]+class|class|interface|static[ \t]+class)
+             [ \t]+"/ix, "quoted class name"],
+          [/\A(?:abstract|class|interface|static[ \t]+class)\b/i,
+           "class declaration form"],
+          [/\.\.>|<\.\./, "dependency arrow"],
+          [/[ \t](?:-{3,}|\.{3,}|-[a-z]+-)>?[ \t]/i,
+           "arrow direction or length"],
+          [/[ \t](?:->|<-|->>|<<-)[ \t]/, "single-dash arrow"],
+        ].freeze
+
+        MEMBER_RULES = [
+          *GLOBAL_RULES,
+          [/\{classifier\}|\{(?:static|abstract|field|method)\}\z/i,
+           "member modifier"],
+          [/\A(?:--|==|\.\.|__)/, "member separator"],
+          [/<</, "stereotype"],
+        ].freeze
+
+        private_constant :KEYWORDS, :KEYWORD, :GLOBAL_RULES, :STATEMENT_RULES,
+                         :MEMBER_RULES
+
+        # @param text [String] one stripped source line
+        # @param scope [Symbol] :statement, or :member inside a class body
+        # @return [String] the construct's name
+        def name_for(text, scope)
+          if scope == :member
+            member_construct(text) || "member declaration"
+          else
+            first_match(STATEMENT_RULES, text) || "statement"
+          end
+        end
+
+        # @return [String, nil] the name of the unsupported member construct
+        #   the line holds, nil when it holds none
+        def member_construct(text)
+          first_match(MEMBER_RULES, text)
+        end
+
+        private
+
+        def first_match(rules, text)
+          rules.each do |pattern, name|
+            match = pattern.match(text)
+            return name || match[1].downcase if match
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "node_graph"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML use case diagram: actors, use cases and the links
+      # between them. Dispatched to from {PlantUML.parse}.
+      module Usecase
+        extend self
+
+        # Lines only a use case diagram has: `:Actor:`, `(Use case)` and the
+        # `usecase` keyword. `(A, B)` is a class diagram's association class.
+        PAIR = /\(\s*\w+\s*,\s*\w+\s*\)/
+        MARKER = /\A(?:usecase\s|:[^:;]+:(?:\s|\z)|
+                  \((?!#{PAIR.source[2..]})[^()*]+\)(?:\s|\z))/xi
+        private_constant :PAIR, :MARKER
+
+        # @return [Boolean] whether the source reads as a use case diagram
+        def usecase?(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: :usecase_diagram,
+                                   direction: :top_to_bottom,
+                                   default_kind: :actor)
+        end
+      end
+    end
+  end
+end