etassia 0.1.0

data/lib/etassia/notation/plantuml/state/plane.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Rectangles and segments on the page, a rectangle as
+        # `[left, top, right, bottom]`.
+        module Plane
+          STEPS = 60
+
+          extend self
+
+          def rect(box)
+            [box.x, box.y, box.x + box.w, box.y + box.h]
+          end
+
+          def around(centre, half)
+            [centre.first - half.first, centre.last - half.last,
+             centre.first + half.first, centre.last + half.last]
+          end
+
+          def grow(rect, margin)
+            rect.zip([-margin, -margin, margin, margin]).map(&:sum)
+          end
+
+          def corners(rect)
+            [[rect[0], rect[1]], [rect[2], rect[1]],
+             [rect[2], rect[3]], [rect[0], rect[3]]]
+          end
+
+          def centre(rect)
+            [(rect[0] + rect[2]) / 2.0, (rect[1] + rect[3]) / 2.0]
+          end
+
+          def meet?(one, other)
+            one[0] < other[2] && other[0] < one[2] &&
+              one[1] < other[3] && other[1] < one[3]
+          end
+
+          def inside?(rect, spot)
+            spot.first.between?(rect[0], rect[2]) &&
+              spot.last.between?(rect[1], rect[3])
+          end
+
+          # @return [Boolean] whether the segment passes through the rect
+          def crosses?(rect, from, to)
+            (0..STEPS).any? do |step|
+              inside?(rect, along(from, to, step.fdiv(STEPS)))
+            end
+          end
+
+          def along(from, to, fraction)
+            from.zip(to).map do |start, finish|
+              start + ((finish - start) * fraction)
+            end
+          end
+
+          # @return [Array] the point a fraction of the way along the
+          #   polyline's length, with the stretch it lies on
+          def at_length(points, fraction)
+            stretch, left = stretch_at(points, fraction)
+            back = (1 + (left / length(stretch))).clamp(..1.0)
+            [along(*stretch, back), *stretch]
+          end
+
+          # @return [Array(Array, Float)] the stretch a length along the
+          #   polyline lies on, and how far along that stretch it is
+          def stretch_at(points, fraction)
+            stretches = points.each_cons(2).reject { |from, to| from == to }
+            left = length(points) * fraction
+            stretch = stretches.find { |one| (left -= length(one)) <= 0 }
+            [stretch || stretches.last, left]
+          end
+
+          def length(points)
+            points.each_cons(2).sum do |from, to|
+              Math.hypot(to.first - from.first, to.last - from.last)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/state/ranking.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # The ranks PlantUML's layout (graphviz) gives the states of a
+        # diagram, read across every container at once. A state sits one rank
+        # below the states that lead to it, and a composite spans the ranks
+        # from its own top to its bottom, so two composites whose spans
+        # overlap stand side by side, as graphviz draws them, instead of one
+        # above the other.
+        #
+        # A transition into a composite arrives at its top and one out of it
+        # leaves from its bottom. A transition that would close a cycle is
+        # left out of the ranking, as graphviz reverses it; the search that
+        # finds it starts from the composites no start marker enters, so the
+        # cycle is cut at the transition into such a composite.
+        class Ranking
+          # @param nodes [Hash{String=>Hash}] the graph's states by id
+          # @param children [Array<Hash>] the top-level states
+          # @param edges [Array<Hash>] the transitions, ELK-shaped
+          def initialize(children, edges)
+            @arcs = Hash.new { |hash, key| hash[key] = [] }
+            @order = []
+            @ends = {}
+            @starts = []
+            structure(children)
+            edges.each { |edge| transition(edge) }
+            @entered = entered_by_start(edges)
+          end
+
+          # @return [Range, nil] the ranks a composite spans
+          def span(id)
+            ends = @ends[id]
+            return unless ends
+
+            (rank[ends.first]..rank[ends.last])
+          end
+
+          # @return [Boolean] whether a state ranks below a composite's bottom
+          def below?(id, composite)
+            rank[known(id)] > rank[@ends.fetch(composite).last]
+          end
+
+          # @return [Boolean] whether two composites share a rank
+          def overlap?(one, other)
+            first = span(one)
+            second = span(other)
+            return false unless first && second
+
+            first.cover?(second.begin) || second.cover?(first.begin)
+          end
+
+          private
+
+          def structure(children, owner = nil)
+            children.reject { |node| note?(node) }.each do |node|
+              enter(node, owner)
+            end
+          end
+
+          def entered_by_start(edges)
+            from_start = edges.select do |edge|
+              @starts.include?(edge[:sources].first)
+            end
+            from_start.map { |edge| edge[:targets].first }
+          end
+
+          def note?(node)
+            node.dig(:metadata, :state_type) == "note"
+          end
+
+          def enter(node, owner)
+            top, bottom = keys_of(node)
+            @order << top
+            @starts << node[:id] if node.dig(:metadata, :state_type) == "start"
+            link(owner, top, bottom)
+            structure(node[:children] || [], [top, bottom]) if top != bottom
+          end
+
+          def link(owner, top, bottom)
+            return unless owner
+
+            @arcs[owner.first] << top
+            @arcs[bottom] << owner.last
+          end
+
+          def keys_of(node)
+            return [node[:id]] * 2 unless node[:children]&.any?
+
+            @ends[node[:id]] = [[node[:id], :top], [node[:id], :bottom]]
+          end
+
+          def transition(edge)
+            from = bottom_of(edge[:sources].first)
+            to = top_of(edge[:targets].first)
+            @arcs[from] << to if from && to && from != to
+          end
+
+          def bottom_of(id)
+            @ends.key?(id) ? @ends[id].last : known(id)
+          end
+
+          def top_of(id)
+            @ends.key?(id) ? @ends[id].first : known(id)
+          end
+
+          def known(id)
+            id if @order.include?(id)
+          end
+
+          # Longest path from the sources, over the arcs that do not close a
+          # cycle. Composites are searched first.
+          def rank
+            @rank ||= begin
+              acyclic = Hash.new { |hash, key| hash[key] = [] }
+              cut_cycles(acyclic)
+              depths(acyclic)
+            end
+          end
+
+          def cut_cycles(acyclic)
+            state = {}
+            composites, leaves = @order.partition { |key| key.is_a?(Array) }
+            free, entered = composites.partition do |key|
+              @entered.none?(key.first)
+            end
+            roots = free + entered + leaves
+            roots.each { |key| visit(key, state, acyclic) }
+          end
+
+          def visit(key, state, acyclic)
+            return if state[key]
+
+            state[key] = :open
+            @arcs[key].each do |target|
+              next if state[target] == :open
+
+              acyclic[key] << target
+              visit(target, state, acyclic)
+            end
+            state[key] = :done
+          end
+
+          def depths(acyclic)
+            depth = Hash.new(0)
+            keys = acyclic.keys | acyclic.values.flatten(1) | @order
+            topological(keys, acyclic).each do |key|
+              deepen(depth, key, acyclic[key])
+            end
+            depth
+          end
+
+          def deepen(depth, key, targets)
+            targets.each do |target|
+              depth[target] = [depth[target], depth[key] + 1].max
+            end
+          end
+
+          def topological(keys, acyclic)
+            seen = {}
+            sorted = []
+            keys.each { |key| sort_from(key, acyclic, seen, sorted) }
+            sorted.reverse
+          end
+
+          def sort_from(key, acyclic, seen, sorted)
+            return if seen[key]
+
+            seen[key] = true
+            acyclic[key].each do |target|
+              sort_from(target, acyclic, seen, sorted)
+            end
+            sorted << key
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require_relative "../../../diagram/state_diagram"
+require_relative "../../../error/parse_error"
+require_relative "../unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Reads PlantUML state-diagram source into the StateDiagram model.
+        #
+        # A state belongs to the scope that first mentions it. `[*]` is the
+        # start of the scope when it begins a transition and the end of the
+        # scope when it ends one; `[H]` and `[H*]` are the scope's shallow and
+        # deep history, or those of the state they follow. History is a state
+        # labelled `H` or `H*`, which the layout draws as a circle. `scale`
+        # only resizes PlantUML's output; {.scale_of} reads it for the
+        # renderer. A line outside this subset raises
+        # {UnsupportedConstructError}.
+        class Reader
+          NAME = /[A-Za-z_][A-Za-z0-9_.]*/
+          MARK = /\[(?:\*|H\*?)\]/
+          ARROW = /-+(?:[a-z]+-+)?>/
+          FLAT = /\A-(?:right-)?>\z/
+          END_STATE = /\A(?:--|\|\|)\z/
+          STATE_OPEN = /\Astate[ \t]+(?:"([^"]+)"[ \t]+as[ \t]+(#{NAME})|
+                         (#{NAME}))(?:[ \t]*<<([^<>]+)>>)?
+                         (?:[ \t]*(\#\S+))?
+                         (?:[ \t]*(\{))?(?:[ \t]*:[ \t]*(.+))?\z/xo
+          TRANSITION = /\A(#{NAME}#{MARK}?|#{MARK})[ \t]*(#{ARROW})[ \t]*
+                        (#{NAME}#{MARK}?|#{MARK})
+                        (?:[ \t]*:[ \t]*(.+))?\z/xo
+          REVERSED = /\A(#{NAME}#{MARK}?|#{MARK})[ \t]*<-+[ \t]*
+                      (#{NAME}#{MARK}?|#{MARK})
+                      (?:[ \t]*:[ \t]*(.+))?\z/xo
+          NOTE = /\Anote[ \t]+(left|right|top|bottom)[ \t]+of[ \t]+(#{NAME})
+                  (?:[ \t]*:[ \t]*(.+))?\z/xio
+          END_NOTE = /\Aend[ \t]*note\z/i
+          DESCRIPTION = /\A(#{NAME})[ \t]*:[ \t]*(.+)\z/o
+          STYLE_BLOCK = %r{\A<style>\z}i
+          END_STYLE = %r{\A</style>\z}i
+          SKIN_BLOCK = /\Askinparam[ \t]+\S+[ \t]*\{\z/i
+          SKIPPED = /\A(?:scale\b|title\b|hide\b|skinparam\b|left to right
+                     direction\z|top to bottom direction\z)/xi
+          SCALE = /\Ascale[ \t]+(\d+(?:\.\d+)?)(?:[ \t]+(width|height))?\z/i
+          HISTORY = { "[H]" => ["history", "H"],
+                      "[H*]" => ["deep_history", "H*"] }.freeze
+          private_constant :NAME, :MARK, :ARROW, :END_STATE, :STATE_OPEN,
+                           :FLAT, :TRANSITION, :REVERSED, :SCALE, :NOTE,
+                           :END_NOTE,
+                           :STYLE_BLOCK, :END_STYLE, :SKIN_BLOCK,
+                           :DESCRIPTION, :SKIPPED, :HISTORY
+
+          # @return [Array<Array(String, Integer)>] the stripped, non-empty,
+          #   non-comment lines of the first diagram, with their numbers
+          def self.lines_of(source)
+            text = source.dup.force_encoding(Encoding::UTF_8).scrub
+            diagram_lines(text).reject do |line, _|
+              line.empty? || line.start_with?("'")
+            end
+          end
+
+          # @return [Array(Float, Symbol), nil] the number of a `scale` line
+          #   and what it sizes: :width, :height or :factor
+          def self.scale_of(source)
+            match = lines_of(source).filter_map do |line,|
+              SCALE.match(line)
+            end.first
+            return unless match
+
+            [match[1].to_f, (match[2] || "factor").downcase.to_sym]
+          end
+
+          def self.diagram_lines(text)
+            numbered = text.lines.map.with_index { |l, i| [l.strip, i + 1] }
+            body = numbered.drop_while { |line, _| !line.start_with?("@start") }
+            body.drop(1).take_while { |line, _| !line.start_with?("@end") }
+          end
+          private_class_method :diagram_lines
+
+          # @return [Array<Array(String, String)>] the source and target ids
+          #   of each transition written with a single-dash arrow (`->`,
+          #   `-right->`), which PlantUML draws on one rank, left to right
+          attr_reader :flat
+
+          # @param source [String] PlantUML source
+          # @return [Etassia::Diagram::StateDiagram]
+          # @raise [UnsupportedConstructError] on a line outside the subset
+          # @raise [Etassia::Parser::ParseError] when a `{` is never closed
+          def parse(source)
+            @flat = []
+            @model = Etassia::Diagram::StateDiagram.new(direction: "TB")
+            @states = {}
+            @scopes = [nil]
+            @note = nil
+            @owners = {}
+            @closing = nil
+            self.class.lines_of(source).each { |line| read(*line) }
+            raise unclosed unless @scopes.size == 1 && @note.nil?
+
+            @model
+          end
+
+          private
+
+          def read(text, number)
+            return note_line(text) if @note
+            return if skipped?(text)
+            return close_scope if text == "}"
+            return if statement(text)
+
+            raise UnsupportedConstructError.new(
+              construct: "state statement", line: number, text: text,
+            )
+          end
+
+          def skipped?(text)
+            return skip_block(text) || true if @closing
+            return open_skipped(text) || true if skipped_block?(text)
+
+            SKIPPED.match?(text) || END_STATE.match?(text)
+          end
+
+          def skipped_block?(text)
+            STYLE_BLOCK.match?(text) || SKIN_BLOCK.match?(text)
+          end
+
+          # The `skinparam x {` and `<style>` bodies are read by
+          # {Style::Reader}; this reader only steps over them.
+          def open_skipped(text)
+            @closing = STYLE_BLOCK.match?(text) ? END_STYLE : /\A\}\z/
+          end
+
+          def skip_block(text)
+            @closing = nil if @closing.match?(text)
+          end
+
+          def statement(text)
+            declaration(text) || transition(text) || note(text) ||
+              description(text)
+          end
+
+          # A note is one line (`note left of A : text`) or a block closed by
+          # `end note`; `\n` in the text breaks a line, as PlantUML draws it.
+          def note(text)
+            match = NOTE.match(text)
+            return unless match
+
+            target = ensure_state(match[2])
+            if match[3]
+              add_note(target, match[1], match[3])
+            else
+              @note = [target, match[1].downcase, []]
+            end
+            true
+          end
+
+          def note_line(text)
+            return end_note if END_NOTE.match?(text)
+
+            @note.last << text
+          end
+
+          def end_note
+            target, side, lines = @note
+            @note = nil
+            add_note(target, side, lines.join("<br>"))
+          end
+
+          def add_note(target, side, text)
+            @model.notes << Etassia::Diagram::StateNote.new(
+              id: "#{target.id}----note#{@model.notes.size}",
+              text: text.gsub("\\n", "<br>").strip,
+              target_id: target.id, position: side.downcase
+            )
+          end
+
+          def unclosed
+            Etassia::Parser::ParseError.new(
+              "Parse error: a state body is never closed with }",
+            )
+          end
+
+          def close_scope
+            @scopes.pop if @scopes.size > 1
+          end
+
+          def declaration(text)
+            match = STATE_OPEN.match(text)
+            return unless match
+
+            state = ensure_state(match[2] || match[3])
+            adopt(state)
+            state.label = match[1] if match[1]
+            describe(state, match[7]) if match[7]
+            @scopes.push(state) if match[6]
+            true
+          end
+
+          # `state X` names where X lives: a state first met as a transition
+          # target inside another body is moved to the scope that declares it.
+          def adopt(state)
+            parent = @scopes.last
+            return if parent.equal?(owner_of(state))
+
+            (owner_of(state)&.children || @model.states).delete(state)
+            (parent ? parent.children : @model.states) << state
+            @owners[state.id] = parent
+          end
+
+          def owner_of(state)
+            @owners[state.id]
+          end
+
+          def transition(text)
+            from, to, label, flat = parts_of(text)
+            return unless from
+
+            source = endpoint(from, :source)
+            target = endpoint(to, :target)
+            add_transition(source, target, label)
+            @flat << [source.id, target.id] if flat
+            true
+          end
+
+          # @return [Array(String, String, String, Boolean)] source, target,
+          #   label as written and whether the arrow is a single-dash one;
+          #   nil when the line is no transition
+          def parts_of(text)
+            if (match = TRANSITION.match(text))
+              [match[1], match[3], match[4], FLAT.match?(match[2])]
+            elsif (match = REVERSED.match(text))
+              [match[2], match[1], match[3], false]
+            end
+          end
+
+          def description(text)
+            match = DESCRIPTION.match(text)
+            return unless match
+
+            describe(ensure_state(match[1]), match[2])
+            true
+          end
+
+          def describe(state, text)
+            state.description = text
+            state.descriptions = [*titled(state), text]
+          end
+
+          # A described state keeps its name as the first line, as PlantUML
+          # draws it.
+          def titled(state)
+            state.descriptions.empty? ? [state.label] : state.descriptions
+          end
+
+          def add_transition(from, to, label)
+            @model.transitions << Etassia::Diagram::StateTransition.new(
+              from_id: from.id, to_id: to.id, trigger: label,
+            )
+          end
+
+          def endpoint(written, role)
+            marker = written[MARK]
+            return ensure_state(written) unless marker
+
+            owner = written.delete_suffix(marker)
+            marker_state(marker, role,
+                         (ensure_state(owner) unless owner.empty?))
+          end
+
+          def marker_state(marker, role, owner)
+            return history_state(marker, owner) if HISTORY.key?(marker)
+
+            kind = role == :source ? "start" : "end"
+            special("#{scope_id}_#{kind}", "[*]", kind, @scopes.last)
+          end
+
+          def history_state(marker, owner)
+            kind, label = HISTORY.fetch(marker)
+            parent = owner || @scopes.last
+            id = "#{parent&.id || 'root'}_#{kind}"
+            special(id, label, "normal", parent)
+          end
+
+          def scope_id
+            @scopes.last&.id || "root"
+          end
+
+          def special(id, label, type, parent)
+            @states[id] ||= build_state(id, label, type, parent)
+          end
+
+          def ensure_state(id)
+            @states[id] ||= build_state(id, id, "normal", @scopes.last)
+          end
+
+          def build_state(id, label, type, parent)
+            node = Etassia::Diagram::StateNode.new(
+              id: id, label: label, state_type: type,
+            )
+            (parent ? parent.children : @model.states) << node
+            @owners[id] = parent
+            node
+          end
+        end
+      end
+    end
+  end
+end