etassia 0.1.0

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

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require_relative "creole"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Notes of a class diagram, placed once the classes are: a note beside
+      # a class sits on the side it names with a pointer tail running to the
+      # class, a note on a member sits at the member's row, and a free note
+      # (`note as N`) stands to the right of everything. Notes on one side of
+      # one class stack downwards.
+      #
+      # Each note is a {Scene::Box} of kind "note" whose first separator is
+      # its pointer, tip first, ending on the edge of the note that faces the
+      # class.
+      class NoteLayout
+        GAP = 30.0
+        STACK_GAP = 10.0
+        FREE_GAP = 20.0
+        TEXT_SCALE = 1.15
+        LINE_HEIGHT = 15.310546875
+        PADDING = 10.0
+        SIDE = 21.0
+        TEXT_INDENT = 6.0
+        FIRST_BASELINE = 17.568
+        ROW_CENTRE = 5.2911
+        private_constant :GAP, :STACK_GAP, :FREE_GAP, :TEXT_SCALE,
+                         :LINE_HEIGHT, :PADDING, :SIDE, :TEXT_INDENT,
+                         :FIRST_BASELINE, :ROW_CENTRE
+
+        # A rectangle, as the boxes and notes of a scene are.
+        Rect = Struct.new(:x, :y, :width, :height) do
+          def self.of(box)
+            new(box.x, box.y, box.width, box.height)
+          end
+
+          def right
+            x + width
+          end
+
+          def bottom
+            y + height
+          end
+
+          def mid_x
+            x + (width / 2)
+          end
+
+          def mid_y
+            y + (height / 2)
+          end
+
+          def overlaps?(other)
+            x < other.x + other.width && other.x < right &&
+              y < other.y + other.height && other.y < bottom
+          end
+
+          def moved(across, down)
+            Rect.new(x + across, y + down, width, height)
+          end
+        end
+        private_constant :Rect
+
+        # Where a note's top left corner goes, from the class it sits beside,
+        # the note's size and the height its centre aims at.
+        ORIGINS = {
+          left: ->(c, w, h, mid) { [c.x - GAP - w, mid - (h / 2)] },
+          right: ->(c, _w, h, mid) { [c.right + GAP, mid - (h / 2)] },
+          top: ->(c, w, h, _mid) { [c.mid_x - (w / 2), c.y - GAP - h] },
+          bottom: ->(c, w, _h, _mid) { [c.mid_x - (w / 2), c.bottom + GAP] },
+        }.freeze
+        # How far, in whole gaps, a blocked note moves out on each side.
+        OUTWARD = { left: [-1, 0], right: [1, 0], top: [0, -1],
+                    bottom: [0, 1] }.freeze
+        private_constant :ORIGINS, :OUTWARD
+
+        # @param diagram [Diagram]
+        # @param measure [#call] width of a note line at the note font
+        # @param member_measure [#call] width of a member row at the class
+        #   font; a note on a member points at the near end of that text
+        def initialize(diagram, measure, member_measure = measure)
+          @diagram = diagram
+          @measure = measure
+          @member_measure = member_measure
+        end
+
+        # @param boxes [Array<Scene::Box>] the placed class boxes
+        # @return [Array<Scene::Box>] the note boxes, in source order
+        def place(boxes)
+          start(boxes)
+          @diagram.notes.each_with_index.map do |note, index|
+            place_note(note, index).tap { |placed| @others << placed }
+          end
+        end
+
+        private
+
+        def start(boxes)
+          @by_name = boxes.to_h { |box| [box.id, box] }
+          @taken = Hash.new(0.0)
+          @free_left = free_edge(boxes)
+          @free_top = boxes.map(&:y).min.to_f
+          @others = boxes.dup
+        end
+
+        def free_edge(boxes)
+          boxes.map { |box| box.x + box.width }.max.to_f + FREE_GAP
+        end
+
+        def place_note(note, index)
+          target = note.target && @by_name[note.target]
+          target ? attached_note(note, index, target) : free_note(note, index)
+        end
+
+        def attached_note(note, index, target)
+          member = member_row(note, target)
+          frame = Rect.of(target)
+          rect = clear_of_others(note.side, target.id,
+                                 anchored(note, frame, member))
+          build(note, index, rect, pointer_for(note.side, rect, frame, member))
+        end
+
+        def free_note(note, index)
+          rect = Rect.new(@free_left, @free_top, *size(note))
+          @free_top += rect.height + STACK_GAP
+          build(note, index, rect, nil)
+        end
+
+        def size(note)
+          lines = [note.lines.size, 1].max
+          [note.lines.map { |line| line_width(line) }.max.to_f + SIDE,
+           PADDING + (lines * LINE_HEIGHT)]
+        end
+
+        def line_width(line)
+          plain = Creole.parse(line).map(&:text).join
+          @measure.call(plain) * TEXT_SCALE
+        end
+
+        # The baseline-centre of the member's row in the class box, or nil.
+        def member_row(note, target)
+          index = member_index(note)
+          return unless index
+
+          row = member_text(target, index)
+          row && [row.x, row.y - ROW_CENTRE, row.content]
+        end
+
+        def member_text(target, index)
+          target.texts.select { |text| text.role.start_with?("member") }[index]
+        end
+
+        def member_index(note)
+          return unless note.member
+
+          klass = @diagram.classes.find { |item| item.name == note.target }
+          wanted = note.member.delete('"')
+          klass&.body&.index { |item| signature(item) == wanted }
+        end
+
+        # `counter` and `start(int timeoutms)`: how a note names a member.
+        def signature(item)
+          return item.name unless item.parameters
+
+          "#{item.name}(#{item.parameters})"
+        end
+
+        def anchored(note, target, member)
+          width, height = size(note)
+          mid = member ? member[1] : target.y + (target.height / 2)
+          x, y = ORIGINS.fetch(note.side).call(target, width, height, mid)
+          Rect.new(x, y, width, height)
+        end
+
+        # Stacks below an earlier note on the same side of the class, then
+        # moves outward until nothing else stands in the way.
+        def clear_of_others(side, target_id, rect)
+          key = [target_id, side]
+          rect.y = [rect.y, @taken[key]].max if %i[left right].include?(side)
+          rect = step_out(side, rect)
+          @taken[key] = rect.bottom + STACK_GAP
+          rect
+        end
+
+        def step_out(side, rect)
+          across, down = OUTWARD.fetch(side)
+          rect = rect.moved(across * GAP, down * GAP) while blocked?(rect)
+          rect
+        end
+
+        def blocked?(rect)
+          @others.any? { |box| rect.overlaps?(box) }
+        end
+
+        # `[tip, anchor]`: the tip on the class's edge (at the member's row
+        # for a member note), the anchor on the note's facing edge.
+        def pointer_for(side, rect, target, member)
+          tip, anchor = if %i[left right].include?(side)
+                          horizontal_pointer(side, rect, target, member)
+                        else
+                          vertical_pointer(side, rect, target)
+                        end
+          Scene::Segment.new(x1: tip[0], y1: tip[1], x2: anchor[0],
+                             y2: anchor[1])
+        end
+
+        def horizontal_pointer(side, rect, target, member)
+          mid = rect.mid_y.clamp(rect.y + 6.0, rect.bottom - 6.0)
+          row = member ? member[1] : rect.mid_y
+          if side == :right
+            [[right_tip(target, member), row], [rect.x, mid]]
+          else
+            [[left_tip(target, member), row], [rect.right, mid]]
+          end
+        end
+
+        # A member note points at the text itself: the end of the text for a
+        # note on the right, its start for a note on the left.
+        def right_tip(target, member)
+          return target.x + target.width unless member
+
+          member[0] + @member_measure.call(member[2])
+        end
+
+        def left_tip(target, member)
+          member ? member[0] : target.x
+        end
+
+        def vertical_pointer(side, rect, target)
+          if side == :top
+            return [[rect.mid_x, target.y],
+                    [rect.mid_x, rect.bottom]]
+          end
+
+          [[rect.mid_x, target.y + target.height], [rect.mid_x, rect.y]]
+        end
+
+        def build(note, index, rect, pointer)
+          Scene::Box.new(id: "note-#{index}", x: rect.x, y: rect.y,
+                         width: rect.width, height: rect.height, kind: "note",
+                         fill: note.color, texts: texts(note, rect),
+                         separators: [*pointer])
+        end
+
+        def texts(note, rect)
+          note.lines.each_with_index.map do |line, index|
+            Scene::Text.new(content: line, x: rect.x + TEXT_INDENT,
+                            y: rect.y + FIRST_BASELINE + (index * LINE_HEIGHT),
+                            role: "member_note", anchor: "start")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The path of a note's outline: a rectangle whose top right corner is
+      # folded and whose pointer, the box's first separator, grows a tail
+      # from the edge it ends on.
+      module NoteOutline
+        FOLD = 10.0
+        TAIL_HALF = 4.0
+        private_constant :FOLD, :TAIL_HALF
+
+        module_function
+
+        # @param box [Scene::Box] a note box
+        # @return [String] an SVG path
+        def call(box)
+          points = edges(box, box.separators.first).flatten(1)
+          commands = points.each_with_index.map do |(x, y), index|
+            "#{index.zero? ? 'M' : 'L'} #{format('%g', x)} #{format('%g', y)}"
+          end
+          [*commands, "Z"].join(" ")
+        end
+
+        def edges(box, pointer)
+          left = box.x
+          top = box.y
+          right = left + box.width
+          bottom = top + box.height
+          [[[left, top]],
+           tail(pointer, :top, top, [left, right]),
+           [[right - FOLD, top], [right, top + FOLD]],
+           tail(pointer, :right, right, [top + FOLD, bottom]),
+           [[right, bottom]],
+           tail(pointer, :bottom, bottom, [right, left]),
+           [[left, bottom]],
+           tail(pointer, :left, left, [bottom, top])]
+        end
+
+        # The three points of a tail on one edge, in drawing order.
+        def tail(pointer, side, edge, (from, to))
+          return [] unless pointer && on_edge?(pointer, side, edge)
+
+          half = to > from ? TAIL_HALF : -TAIL_HALF
+          tail_points(pointer, side, edge, half)
+        end
+
+        def tail_points(pointer, side, edge, half)
+          along = flat?(side) ? pointer.x2 : pointer.y2
+          first, last = [along - half, along + half].map do |value|
+            flat?(side) ? [value, edge] : [edge, value]
+          end
+          [first, [pointer.x1, pointer.y1], last]
+        end
+
+        def on_edge?(pointer, side, edge)
+          value = flat?(side) ? pointer.y2 : pointer.x2
+          (value - edge).abs < 0.001
+        end
+
+        def flat?(side)
+          %i[top bottom].include?(side)
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/objects/map_rows.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../plantuml_data/boxes/table"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Objects
+        # Reads the lines inside a PlantUML `map` element: `key => value`
+        # rows, bare keys, and `key *-> target` rows that link out.
+        module MapRows
+          extend self
+
+          NAME = /[A-Za-z_][A-Za-z0-9_.]*/
+          VALUE = /\A(.+?)[ \t]*=>[ \t]*(.*)\z/
+          LINK = /\A(.+?)[ \t]+(\*?-+>)[ \t]*(#{NAME}(?:::#{NAME})?)\z/o
+          private_constant :VALUE, :LINK
+
+          # @param lines [Array<String>] the stripped lines of the body
+          # @return [Array(Array<Boxes::Row>, Array<Array(String, String,
+          #   String)>)] the rows and the key, arrow and target of each link
+          def call(lines)
+            links = []
+            rows = lines.map { |line| row(line, links) }
+            [rows, links]
+          end
+
+          private
+
+          def row(line, links)
+            if (found = LINK.match(line))
+              key, glyph, target = found.captures
+              links << [key, glyph, target]
+              PlantUMLData::Boxes::Row.new(key: key, port: key)
+            else
+              pair = VALUE.match(line)
+              PlantUMLData::Boxes::Row.new(key: pair ? pair[1] : line,
+                                           port: pair ? pair[1] : line,
+                                           value: pair ? pair[2] : "")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/objects/reader.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../arrow"
+require_relative "map_rows"
+require_relative "../../plantuml_data/boxes/table"
+require_relative "../../plantuml_data/boxes/json_reader"
+require_relative "../../plantuml_data/boxes/highlights"
+require_relative "../../plantuml_data/boxes/tree_builder"
+require_relative "../../plantuml_data/boxes/text"
+require_relative "../../../error/parse_error"
+require_relative "../unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Objects
+        # Reads PlantUML's object diagram: `object`, `map` and `json`
+        # elements, empty `class` boxes, and the relations between them. A
+        # line outside that subset raises {UnsupportedConstructError}.
+        class Reader
+          NAME = MapRows::NAME
+          LABELLED = /(?:"([^"]+)"[ \t]+as[ \t]+(#{NAME})|(#{NAME}))/o
+          ELEMENT = /\A(object|class|abstract class|interface)[ \t]+
+                     #{LABELLED}(?:[ \t]*(\{))?\z/xo
+          MAP = /\Amap[ \t]+#{LABELLED}[ \t]*\{\z/o
+          JSON_OPEN = /\Ajson[ \t]+#{LABELLED}[ \t]*\{(.*)\z/o
+          END_TEXT = '(?:"([^"]+)"[ \t]+)?'
+          END_REF = "(#{NAME}(?:::#{NAME})?)".freeze
+          RELATION = /\A#{END_REF}[ \t]+#{END_TEXT}#{Arrow::PATTERN}[ \t]*
+                      #{END_TEXT}#{END_REF}(?:[ \t]*:[ \t]*(.+))?\z/xo
+          START = /\A@startuml(?:[ \t]+\S.*)?\z/
+          TITLE = /\Atitle[ \t]+(.+)\z/i
+          DIRECTION = /\A(left to right|top to bottom) direction\z/i
+          SKIPPED = /\A(?:skinparam|hide|show|scale)\b/i
+          Boxes = PlantUMLData::Boxes
+          private_constant :Boxes, :NAME, :LABELLED, :ELEMENT,
+                           :MAP, :JSON_OPEN,
+                           :END_TEXT, :END_REF,
+                           :RELATION, :START, :TITLE, :DIRECTION, :SKIPPED
+
+          # @return [Array<Array(String, Integer)>] the stripped, non-empty,
+          #   non-comment lines of the first diagram with their numbers
+          def self.lines_of(source)
+            numbered(source)
+              .drop_while { |line, _| !line.start_with?("@start") }
+              .take_while { |line, _| !line.start_with?("@end") }
+              .reject { |line, _| line.empty? || line.start_with?("'") }
+          end
+
+          def self.numbered(source)
+            text = source.dup.force_encoding(Encoding::UTF_8).scrub
+            text.lines.map.with_index { |line, i| [line.strip, i + 1] }
+          end
+          private_class_method :numbered
+
+          # @param source [String] PlantUML source
+          # @return [Boxes::Diagram]
+          def parse(source)
+            @tables = {}
+            @links = []
+            @title = nil
+            @direction = :down
+            lines = self.class.lines_of(source)
+            @queue = lines.drop(1)
+            read(@queue.shift) until @queue.empty?
+            implicit_tables
+            Boxes::Diagram.new(tables: @tables.values, links: @links,
+                               title: @title, direction: @direction)
+          end
+
+          private
+
+          # An end of a relation nobody declared is an object of that name.
+          def implicit_tables
+            @links.flat_map { |l| [l.from, l.to] }.each do |id|
+              @tables[id] ||= Boxes::Table.new(id: id, title: id, rows: [],
+                                               kind: :object,
+                                               group: packages(id))
+            end
+          end
+
+          def read(entry)
+            @text, @number = entry
+            return if skipped?
+
+            [method(:element), method(:map), method(:json), method(:relation)]
+              .any?(&:call) || refuse
+          end
+
+          def skipped?
+            @text.match?(SKIPPED) || @text.match?(START) || title? || direction?
+          end
+
+          def title?
+            match = TITLE.match(@text)
+            match && (@title = Boxes::Text.plain(match[1]))
+          end
+
+          def direction?
+            match = DIRECTION.match(@text)
+            match && (@direction = horizontal?(match[1]) ? :right : :down)
+          end
+
+          def horizontal?(phrase)
+            phrase.downcase.start_with?("left")
+          end
+
+          def refuse
+            raise UnsupportedConstructError.new(
+              construct: @text[/\A\S+/].to_s.downcase, line: @number,
+              text: @text
+            )
+          end
+
+          def declare(label, as_name, name, kind, rows = [])
+            id = as_name || name
+            @tables[id] = Boxes::Table.new(id: id, title: label || name,
+                                           rows: rows, kind: kind,
+                                           group: as_name ? [] : packages(id))
+          end
+
+          # @return [Array<String>] the packages a dotted name stands in
+          def packages(name)
+            name.split(".")[0...-1]
+          end
+
+          def element
+            match = ELEMENT.match(@text) or return false
+            kind, label, as_name, name, open = match.captures
+            rows = open ? body_lines.map { |l| Boxes::Row.new(value: l) } : []
+            declare(label, as_name, name, kind == "object" ? :object : :class,
+                    rows)
+          end
+
+          def body_lines
+            lines = []
+            while (entry = @queue.shift)
+              return lines if entry.first == "}"
+
+              lines << entry.first
+            end
+            raise Etassia::Parser::ParseError,
+                  "Parse error: unclosed { at line #{@number}"
+          end
+
+          def map
+            match = MAP.match(@text) or return false
+            label, as_name, name = match.captures
+            rows, links = MapRows.call(body_lines)
+            declare(label, as_name, name, :map, rows)
+            map_links(as_name || name, links)
+          end
+
+          # A map row's `*->` is a plain line out of the row: the JAR draws no
+          # composition diamond for it.
+          def map_links(id, links)
+            links.each do |key, glyph, target|
+              @links << link(id, target, Arrow.parse(glyph.delete("*")), [],
+                             key)
+            end
+          end
+
+          def json
+            match = JSON_OPEN.match(@text) or return false
+            label, as_name, name, rest = match.captures
+            value = Boxes::JsonReader.new.call("{#{json_body(rest)}")
+            root = Boxes::TreeBuilder.new(Boxes::Highlights.new, inline: true)
+              .call(value)
+            adopt(root, label, as_name || name)
+          end
+
+          def json_body(first)
+            text = first.dup
+            while unbalanced?(text) && (entry = @queue.shift)
+              text << "\n" << entry.first
+            end
+            text
+          end
+
+          def unbalanced?(text)
+            text.count("{") + 1 > text.count("}")
+          end
+
+          def adopt(root, label, id)
+            @tables[id] = Boxes::Table.new(id: id, title: label || id,
+                                           rows: root.rows, kind: :inline)
+          end
+
+          def relation
+            match = RELATION.match(@text) or return false
+            from, left_text, glyph, right_text, to, label = match.captures
+            parsed = Arrow.parse(glyph) or return false
+            @links << link(from, to, parsed, [left_text, right_text, label])
+          end
+
+          def link(from, to, glyph, texts, from_port = nil)
+            source, port = from.split("::")
+            target, target_port = to.split("::")
+            tail, head, label = texts
+            Boxes::Link.new(from: source, to: target, glyph: glyph,
+                            from_row: from_port || port, to_row: target_port,
+                            label: label, tail_text: tail, head_text: head)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../plantuml_data/boxes/graph_layout"
+require_relative "../plantuml_data/boxes/renderer"
+require_relative "objects/reader"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML object diagram: `object`, `map` and `json` elements and
+      # the relations between them, drawn as boxes. Dispatched to from
+      # {PlantUML.parse}.
+      module Objects
+        extend self
+
+        # An element only an object diagram has; the families tried before
+        # this one have already refused the source.
+        ELEMENT = /\A(?:object[ \t]+["A-Za-z_]|
+                   map[ \t]+(?:"[^"]+"[ \t]+as[ \t]+\w+|\w[\w.]*)[ \t]*\{)/x
+        private_constant :ELEMENT
+
+        # @return [Boolean] whether the source reads as an object diagram
+        def objects?(source)
+          Reader.lines_of(source).any? { |line, _| ELEMENT.match?(line) }
+        end
+
+        # @return [Notation::Parsed]
+        def parse(source)
+          Notation::Parsed.new(
+            type: :object_diagram,
+            diagram: Reader.new.parse(source),
+            transform: PlantUMLData::Boxes::GraphLayout,
+            renderer: PlantUMLData::Boxes::Renderer,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # A `package` block around declared classes. `id` is what the source
+      # calls it, `title` the text drawn (the quoted name in
+      # `package "Title" as id`), `shape` is :folder or :frame (`<<Frame>>`)
+      # and `icon` is true for the `+` written before the keyword. `parent`
+      # is the id of the package it is written inside, or nil, and `color`
+      # the `#RRGGBB` fill written after its name, or nil.
+      class Package
+        attr_reader :id, :title, :shape, :icon, :parent, :color
+
+        # @param context [Hash] optional `:parent` and `:color`
+        def initialize(id:, title:, shape:, icon:, **context)
+          @id = id
+          @title = title
+          @shape = shape
+          @icon = icon
+          @parent = context[:parent]
+          @color = context[:color]
+          freeze
+        end
+
+        # @return [Array<String>] the ids of the packages around `id`,
+        #   outermost first and `id` last; empty for nil
+        def self.chain(id, packages)
+          chain = []
+          while id
+            chain.unshift(id)
+            id = packages.find { |package| package.id == id }&.parent
+          end
+          chain
+        end
+
+        # @return [Package] this package inside the package `parent`
+        def inside(parent)
+          self.class.new(id: id, title: title, shape: shape, icon: icon,
+                         parent: parent, color: color)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The fill written after a package name (`package p #yellow {`),
+      # read as the hex colour PlantUML draws.
+      module PackageColor
+        extend self
+
+        NAMED = {
+          "blue" => "#0000FF", "gray" => "#808080", "green" => "#008000",
+          "lightgray" => "#D3D3D3", "orange" => "#FFA500",
+          "pink" => "#FFC0CB", "purple" => "#800080", "red" => "#FF0000",
+          "white" => "#FFFFFF", "yellow" => "#FFFF00"
+        }.freeze
+
+        HEX = /\A\h{3}(?:\h{3})?\z/
+
+        # @param text [String] the colour with its `#`
+        # @return [String, nil] `#RRGGBB`, or nil for a name not listed
+        def hex(text)
+          digits = text.delete_prefix("#")
+          return NAMED[digits.downcase] unless HEX.match?(digits)
+
+          digits = digits.gsub(/\h/) { |digit| digit * 2 } if digits.size == 3
+          "##{digits.upcase}"
+        end
+      end
+    end
+  end
+end