etassia 0.1.0

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

@@ -0,0 +1,844 @@
+# frozen_string_literal: true
+
+require_relative "../../../error"
+require_relative "../../../error/diagram_type_error"
+require_relative "../../../error/parse_error"
+require_relative "../caption"
+require_relative "chrome"
+require_relative "../unsupported_construct_error"
+require_relative "appearance"
+require_relative "arrow_syntax"
+require_relative "box"
+require_relative "diagram"
+require_relative "embedded"
+require_relative "edge"
+require_relative "fill"
+require_relative "message"
+require_relative "note"
+require_relative "note_fill"
+require_relative "outline"
+require_relative "parallel_message"
+require_relative "create"
+require_relative "paint"
+require_relative "participant"
+require_relative "ref"
+require_relative "refusals"
+require_relative "style"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Sequence
+        # Reads the PlantUML sequence subset: participant declarations,
+        # messages, notes, `return`, dividers and alt/loop/group blocks. A
+        # line outside it raises {UnsupportedConstructError}; never return a
+        # diagram with a line skipped.
+        class Parser
+          NAME = /[A-Za-z_][A-Za-z0-9_]*/
+          QUOTED = /"[^"\n]+"/
+          KINDS = %w[participant actor boundary control entity database
+                     collections queue].freeze
+
+          COLOUR = /\#(\h{6}|\h{3}|red|green|blue|yellow|orange|purple|gray|
+                       grey|cyan|magenta|lime|navy|teal|olive|maroon|silver|
+                       aqua|fuchsia|pink|brown|black|white)(?!\w)/xi
+
+          DECLARATION = /\A(#{KINDS.join('|')})[ \t]+(#{QUOTED}|#{NAME})
+                         (?:[ \t]+as[ \t]+(#{NAME}))?
+                         (?:[ \t]+<<[ \t]*([^<>\n]+?)[ \t]*>>)?
+                         (?:[ \t]+order[ \t]+(-?\d+))?
+                         (?:[ \t]+(\#\w+))?\z/xio
+          SKINPARAM_WIDTH = /\Askinparam[ \t]+MinClassWidth[ \t]+(\d+)\z/i
+          MAXMESSAGE = /maxmessagesize[ \t]+(\d+)\z/i
+          SKINPARAM_MAXMESSAGE = /\Askinparam[ \t]+#{MAXMESSAGE}/i
+          SKINPARAM_LINE = /\A#{MAXMESSAGE}/i
+          SKINPARAM_PAINT = /\Askinparam[ \t]+(\w+)[ \t]+(\S+)\z/i
+          SKINPARAM_PAINT_LINE = /\A(\w+)[ \t]+(\S+)\z/
+          SKINPARAM_OPEN = /\Askinparam[ \t]*\{\z/i
+          HIDE_FOOTBOX = /\Ahide[ \t]+footbox\z/i
+          AUTOACTIVATE = /\Aautoactivate[ \t]+(on|off)\z/i
+          TITLE = /\A(?:title|header|footer|caption|legend)[ \t]+
+                   (?!\S*(?:--|\.\.|->|<-))\S/xi
+          CHROME_OPEN = /\A(?:(title|header|footer|caption)|
+                          legend(?:[ \t]+(top|bottom))?
+                          (?:[ \t]+(left|center|right))?)\z/xi
+          CHROME_CLOSE = /\Aend[ \t]*(title|header|footer|caption|legend)\z/i
+          STYLE_OPEN = /\A<style>\z/i
+          STYLE_CLOSE = /\A<\/style>\z/i
+          MESSAGE = /\A(#{QUOTED}|#{NAME}|[\[?](?=[-<\\\/oxOX]))[ \t]*
+                     (#{ArrowSyntax::SOURCE})
+                     [ \t]*(#{QUOTED}|#{NAME}|(?<![ \t])[\]?])[ \t]*
+                     (--\+\+|\+\+--|\+\+|--|!!)?[ \t]*(#{COLOUR})?
+                     [ \t]*(?::[ \t]*(.*))?\z/xo
+          ACTIVATION = /\A(activate|deactivate)[ \t]+(#{QUOTED}|#{NAME})
+                        (?:[ \t]+(#{COLOUR}))?\z/xio
+          CREATE = /\Acreate[ \t]+(.+)\z/i
+          DESTROY = /\Adestroy[ \t]+(#{QUOTED}|#{NAME})\z/io
+          MARKS = { "++" => [:on], "--" => [:off], "!!" => [:destroy],
+                    "--++" => %i[off on], "++--" => %i[on off] }.freeze
+          TARGET = /(?:#{QUOTED}|#{NAME})/
+          NOTE = /\A(note|hnote|rnote)[ \t]+(left|right|over|across|top|bottom)
+                  (?:[ \t]+of)?
+                  (?:[ \t]+(#{TARGET}(?:[ \t]*,[ \t]*#{TARGET})*))?
+                  (?:[ \t]+(\#\w+))?[ \t]*(?::[ \t]*(.*))?\z/xio
+          REF = /\Aref[ \t]+over[ \t]+(#{TARGET}(?:[ \t]*,[ \t]*#{TARGET})*)
+                 [ \t]*:[ \t]*(\S.*)\z/xio
+          END_NOTE = /\Aend[ \t]*[hr]?note\z/i
+          BLOCK = /\A(alt|opt|loop|par|critical|break|group)
+                   (?:[ \t]+(?:\#\w+[ \t]*)?(.*))?\z/xi
+          BRANCH = /\Aelse(?:[ \t]+(.*))?\z/i
+          RETURN = /\Areturn(?:[ \t]+(.*))?\z/i
+          DIVIDER = /\A==[ \t]*(.*?)[ \t]*==\z/
+          SPACING = /\A\|\|(?:(\d+)\|\||\|\|?)\z/
+          DELAY = /\A\.\.\.(?:[ \t]*(\S.*?)[ \t]*\.\.\.)?\z/
+          BOX = /\Abox(?:[ \t]+(#{QUOTED}))?(?:[ \t]+(\#\w+))?\z/io
+          END_BOX = /\A(?:endbox|end[ \t]+box)\z/i
+          PRAGMA = /\A!pragma[ \t]+(teoz|svginteractive)[ \t]+true\z/i
+          STARTUML = /\A@startuml(?![A-Za-z0-9_])/
+          LINE_END = /\r\n|\r|\n/
+          PARALLEL = /\A&[ \t]*(.*)\z/
+          NEWPAGE = /\Anewpage\z/i
+          AUTONUMBER = /\Aautonumber(?:[ \t]+(\d+)(?:[ \t]+(\d+))?)?
+                        (?:[ \t]+"([^"]*)")?\z/xi
+          AUTONUMBER_PAUSE = /\Aautonumber[ \t]+(stop|resume)\z/i
+
+          PARALLEL_KINDS = [MESSAGE, NOTE, BLOCK].freeze
+          TIMELINE = [[MESSAGE, :message], [NOTE, :note], [BLOCK, :block],
+                      [REF, :ref], [BRANCH, :branch], [ACTIVATION, :activation],
+                      [RETURN, :reply], [DIVIDER, :divider], [DELAY, :delay],
+                      [SPACING, :spacing],
+                      [DESTROY, :destroy], [CREATE, :create],
+                      [NEWPAGE, :newpage],
+                      [AUTONUMBER, :autonumber],
+                      [AUTONUMBER_PAUSE, :counting]].freeze
+          SETTINGS = [[SKINPARAM_WIDTH, :min_width],
+                      [SKINPARAM_MAXMESSAGE, :max_message],
+                      [SKINPARAM_PAINT, :skinparam_paint],
+                      [SKINPARAM_OPEN, :open_skinparam],
+                      [HIDE_FOOTBOX, :hide_footbox],
+                      [AUTOACTIVATE, :autoactivate],
+                      [CHROME_OPEN, :open_chrome],
+                      [TITLE, :title],
+                      [STYLE_OPEN, :open_style]].freeze
+
+          private_constant :TIMELINE, :SETTINGS, :NAME, :QUOTED, :KINDS,
+                           :DECLARATION, :MESSAGE, :BOX, :END_BOX, :STARTUML,
+                           :LINE_END, :PRAGMA, :ACTIVATION, :MARKS, :TARGET,
+                           :NOTE, :END_NOTE, :REF, :BLOCK, :BRANCH, :RETURN,
+                           :DIVIDER, :DELAY, :SPACING, :DESTROY, :CREATE,
+                           :COLOUR,
+                           :SKINPARAM_WIDTH, :STYLE_OPEN, :STYLE_CLOSE,
+                           :PARALLEL, :SKINPARAM_PAINT, :SKINPARAM_PAINT_LINE,
+                           :PARALLEL_KINDS, :HIDE_FOOTBOX, :NEWPAGE,
+                           :AUTOACTIVATE, :AUTONUMBER,
+                           :AUTONUMBER_PAUSE, :TITLE,
+                           :CHROME_OPEN, :CHROME_CLOSE
+
+          # @param source [String] PlantUML source
+          # @return [Diagram] the frozen diagram
+          # @raise [UnsupportedConstructError] on the first line outside the
+          #   subset
+          # @raise [Etassia::Parser::ParseError] when the source is not valid
+          #   UTF-8 or @enduml is missing
+          def parse(source)
+            start_empty
+            phase = :before
+            lines_of(source).each_with_index do |line, index|
+              phase = step(phase, line.strip, index + 1)
+            end
+            finish(phase)
+          end
+
+          private
+
+          def start_empty
+            @participants = {}
+            @orders = {}
+            @outline = Outline.new
+            @boxes = []
+            @open_boxes = []
+            @pending_note = nil
+            @pending_style = nil
+            @skin_open = nil
+            start_settings
+          end
+
+          def start_settings
+            @appearance = Appearance.new
+            @teoz = false
+            @parallel = false
+            @footbox = true
+            @autoactivate = false
+            @title = nil
+            @chrome = Chrome::NONE
+            @pending_chrome = nil
+            @warnings = []
+          end
+
+          def lines_of(source)
+            text = source.dup.force_encoding(Encoding::UTF_8)
+            unless text.valid_encoding?
+              raise Etassia::Parser::ParseError,
+                    "Parse error: source is not valid UTF-8"
+            end
+
+            text.delete_prefix("").split(LINE_END)
+          end
+
+          def step(phase, text, number)
+            @line = number
+            return phase if skippable?(text)
+
+            case phase
+            when :before then before(text, number)
+            when :statements then statement(text, number)
+            else raise refusal(text, number, "content after @enduml")
+            end
+          end
+
+          def skippable?(text)
+            return false if @pending_note || @pending_chrome
+
+            text.empty? || text.start_with?("'")
+          end
+
+          def before(text, _number)
+            # A name after @startuml only names PlantUML's output file.
+            return :statements if STARTUML.match?(text)
+
+            raise Etassia::Engine::DiagramTypeError,
+                  "Unable to detect diagram type from source. " \
+                  "Source must start with one of: @startuml"
+          end
+
+          def statement(text, number)
+            return collect_pending(text, number) if collecting?
+            return collect_skinparam(text, number) if @skin_open
+            return end_of_diagram(text, number) if text == "@enduml"
+            return pragma(PRAGMA.match(text)) if PRAGMA.match?(text)
+
+            read(text, number)
+            :statements
+          end
+
+          def collecting?
+            @pending_note || @pending_chrome || @pending_style
+          end
+
+          def collect_pending(text, number)
+            return collect_note(text) if @pending_note
+            return collect_chrome(text, number) if @pending_chrome
+
+            collect_style(text)
+          end
+
+          def pragma(match)
+            @teoz ||= match[1].casecmp?("teoz")
+            :statements
+          end
+
+          def read(text, number)
+            if (match = DECLARATION.match(text)) && declaration?(match)
+              declare(match)
+            elsif (match = BOX.match(text))
+              open_box(match)
+            else
+              read_setting(text, number)
+            end
+          end
+
+          def read_setting(text, number)
+            SETTINGS.each do |pattern, reader|
+              match = pattern.match(text)
+              return send(reader, match, number, text) if match
+            end
+            read_structure(text, number)
+          end
+
+          def min_width(match, *)
+            set(min_width: match[1].to_i)
+          end
+
+          def max_message(match, *)
+            set(max_message: match[1].to_i)
+          end
+
+          def skinparam_paint(match, number, text)
+            painted(match[1], match[2], text, number)
+          end
+
+          def painted(key, value, text, number)
+            read = Paint.read(key, value) or raise refusal(text, number)
+
+            @appearance = @appearance.merge(read)
+          end
+
+          def open_skinparam(_match, number, _text)
+            @skin_open = number
+          end
+
+          def hide_footbox(*)
+            @footbox = false
+          end
+
+          def autoactivate(match, *)
+            @autoactivate = match[1].casecmp?("on")
+          end
+
+          # Only plain text, as {Caption} reads it; markup stays refused.
+          def title(_match, number, text)
+            caption = Caption.read(text) or raise refusal(text, number)
+
+            keep(caption.kind, caption.text)
+          end
+
+          def keep(kind, text, place = nil)
+            if kind == :title
+              @title = text
+            else
+              @chrome = @chrome.with(kind, text, place || @chrome.legend_place)
+            end
+          end
+
+          def open_chrome(match, number, text)
+            kind = (match[1] || "legend").downcase.to_sym
+            place = [match[2] || "bottom", match[3] || "center"].join(" ")
+            @pending_chrome = { kind: kind, place: place.downcase,
+                                line: number, text: text, lines: [] }
+          end
+
+          def collect_chrome(text, number)
+            raise unclosed_chrome if text == "@enduml"
+
+            if closes_chrome?(text)
+              close_chrome
+            else
+              chrome_line(text, number)
+            end
+            :statements
+          end
+
+          def closes_chrome?(text)
+            close = CHROME_CLOSE.match(text)
+            close && close[1].casecmp?(@pending_chrome[:kind].to_s)
+          end
+
+          def chrome_line(text, number)
+            kind = @pending_chrome[:kind].to_s
+            raise refusal(text, number, kind) unless Caption.plain?(text)
+
+            @pending_chrome[:lines] << text
+          end
+
+          def close_chrome
+            pending = @pending_chrome
+            @pending_chrome = nil
+            raise refusal(pending[:text], pending[:line]) if
+              pending[:lines].empty?
+
+            place = pending[:place] if pending[:kind] == :legend
+            keep(pending[:kind], pending[:lines].join("\n"), place)
+          end
+
+          def open_style(_match, number, text)
+            @pending_style = { line: number, text: text, lines: [] }
+          end
+
+          # A stereotype is drawn above the label, where the other kinds
+          # already draw their name. Only a participant takes a fill, in the
+          # forms {Fill} reads.
+          def declaration?(match)
+            participant = match[1].casecmp?("participant")
+            (match[4].nil? || participant) &&
+              (match[6].nil? || (participant && Fill.read(match[6])))
+          end
+
+          def collect_style(text)
+            if STYLE_CLOSE.match?(text)
+              close_style
+            else
+              @pending_style[:lines] << text
+            end
+            :statements
+          end
+
+          # Inside `skinparam {`, a line is `Maxmessagesize N`; anything
+          # else leaves the block unread.
+          def collect_skinparam(text, number)
+            if text == "}"
+              @skin_open = nil
+            elsif (match = SKINPARAM_LINE.match(text))
+              set(max_message: match[1].to_i)
+            else
+              block_paint(text, number)
+            end
+            :statements
+          end
+
+          def block_paint(text, number)
+            match = SKINPARAM_PAINT_LINE.match(text) or
+              raise refusal(text, number)
+
+            painted(match[1], match[2], text, number)
+          end
+
+          def close_style
+            style = @pending_style
+            @pending_style = nil
+            read = Style.read(style[:lines].join("\n"))
+            raise refusal(style[:text], style[:line]) unless read
+
+            @appearance = @appearance.merge(read)
+          end
+
+          def set(**settings)
+            @appearance = @appearance.merge(Appearance.new(**settings))
+          end
+
+          def read_structure(text, number)
+            if END_BOX.match?(text) && @open_boxes.any?
+              close_box
+            elsif @open_boxes.any? || !timeline(text)
+              raise refusal(text, number)
+            end
+          end
+
+          # Reads one line that belongs in the item sequence; false when it
+          # is not one, or when it is out of place.
+          def timeline(text)
+            parallel = PARALLEL.match(text)
+            return parallel_line(parallel[1]) if parallel
+
+            read_timeline(text)
+          end
+
+          # Only teoz draws `&` on the row above; without it PlantUML
+          # stacks the line as an ordinary one, so it stays refused.
+          def parallel_line(text)
+            return false unless @teoz && @outline.anchored?
+            return false unless PARALLEL_KINDS.any? { |kind| kind.match?(text) }
+
+            @parallel = true
+            read_timeline(text)
+          ensure
+            @parallel = false
+          end
+
+          def read_timeline(text)
+            TIMELINE.each do |pattern, reader|
+              match = pattern.match(text)
+              return send(reader, match) if match
+            end
+            text.casecmp?("end") && @outline.close_block
+          end
+
+          def block(match)
+            @outline.open_block(match[1].downcase, match[2].to_s.strip,
+                                parallel: @parallel)
+          end
+
+          # A label with a line break is the multi-line form; not drawn.
+          def ref(match)
+            return false if match[2].include?("\\n")
+
+            @outline.ref(Ref.new(targets: targets_of(match[1]),
+                                 label: match[2].strip))
+          end
+
+          def branch(match)
+            @outline.branch(match[1])
+          end
+
+          def reply(match)
+            @outline.reply(match[1])
+          end
+
+          def activation(match)
+            phase = match[1].casecmp?("activate") ? :on : :off
+            return false if match[3] && phase == :off
+
+            @outline.activation(phase, mention(match[2]), colour(match[4]))
+          end
+
+          def destroy(match)
+            @outline.destroy(mention(match[1]))
+          end
+
+          # `create X` or `create participant X`: the head appears where the
+          # next message to it is.
+          def create(match)
+            declared = DECLARATION.match(match[1])
+            if declared && declaration?(declared)
+              declare(declared)
+              return @outline.create(declared[3] || unquote(declared[2]))
+            end
+            return false unless /\A(?:#{QUOTED}|#{NAME})\z/o.match?(match[1])
+
+            @outline.create(mention(match[1]))
+          end
+
+          def autonumber(match)
+            numbering = Numbering.read(start: (match[1] || 1).to_i,
+                                       step: (match[2] || 1).to_i,
+                                       format: match[3])
+            numbering && @outline.autonumber(numbering)
+          end
+
+          def counting(match)
+            @outline.counting(match[1].casecmp?("resume"))
+          end
+
+          def newpage(_match)
+            @outline.newpage
+          end
+
+          def divider(match)
+            @outline.divider(match[1])
+          end
+
+          def spacing(match)
+            @outline.spacing(match[1]&.to_f)
+          end
+
+          def delay(match)
+            @outline.delay(match[1].to_s)
+          end
+
+          def note(match)
+            pending = pending_note_from(match) or return false
+            return positioned_note(pending, match[5]) if misplaced?(pending)
+            return false if hanging?(pending) && !hangs_from_something?
+
+            @pending_note = pending
+            match[5] ? collect_note(match[5].strip, inline: true) : true
+          end
+
+          # PlantUML has no top or bottom note. After a message the note is
+          # drawn as a `left` one; after a ref it is dropped and a warning
+          # is drawn at the top instead. Only the one-line form is read.
+          def misplaced?(pending)
+            %i[top bottom].include?(pending[:side])
+          end
+
+          def positioned_note(pending, text)
+            return false unless text && pending[:targets].empty?
+            return false if @parallel
+
+            if @outline.after_message?
+              @pending_note = pending.merge(side: :left)
+              collect_note(text.strip, inline: true)
+            elsif @outline.after_ref?
+              @warnings << "This position is ignored: #{pending[:side].upcase}"
+            end
+          end
+
+          def hangs_from_something?
+            @outline.after_message? || @outline.after_block?
+          end
+
+          # nil when the colour is not one PlantUML is known to draw.
+          def pending_note_from(match)
+            fill = NoteFill.read(match[4])
+            return if match[4] && !fill
+
+            { shape: match[1].downcase.to_sym, side: match[2].downcase.to_sym,
+              targets: targets_of(match[3]), lines: [], parallel: @parallel,
+              fill: fill, depth: 0, line: @line }
+          end
+
+          def targets_of(list)
+            list.to_s.split(",").map { |target| mention(target.strip) }
+          end
+
+          def hanging?(pending)
+            pending[:targets].empty? && %i[left right].include?(pending[:side])
+          end
+
+          def collect_note(text, inline: false)
+            if inline || closes_note?(text)
+              finish_note(inline ? text : @pending_note[:lines].join("\n"))
+            else
+              track_embedded(text)
+              @pending_note[:lines] << text
+            end
+            :statements
+          end
+
+          # An `end note` inside `{{ }}` belongs to the embedded diagram.
+          def closes_note?(text)
+            END_NOTE.match?(text) && @pending_note[:depth].zero?
+          end
+
+          def track_embedded(text)
+            pending = @pending_note
+            pending[:depth] += 1 if Embedded.opens?(text)
+            return unless Embedded.closes?(text) && pending[:depth].positive?
+
+            pending[:depth] -= 1
+          end
+
+          # A body with a `{{` line is one embedded diagram and nothing
+          # else; its own lines are read by a parser of their own.
+          def check_embedded(text, line)
+            return unless text.lines.any? { |row| Embedded.opens?(row) }
+
+            embedded = Embedded.read(text)
+            unless embedded
+              raise UnsupportedConstructError.new(
+                construct: "embedded diagram beside other note text",
+                line: line, text: "{{"
+              )
+            end
+            parse_embedded(embedded, line)
+          end
+
+          def parse_embedded(embedded, line)
+            Parser.new.parse(embedded.document)
+          rescue UnsupportedConstructError => e
+            raise UnsupportedConstructError.new(
+              construct: "#{e.construct} in an embedded diagram",
+              line: line, text: "{{"
+            )
+          end
+
+          def finish_note(text)
+            pending = @pending_note
+            @pending_note = nil
+            check_embedded(text, pending[:line])
+            @outline.note(Note.new(shape: pending[:shape],
+                                   side: pending[:side],
+                                   targets: pending[:targets], text: text,
+                                   parallel: pending[:parallel],
+                                   fill: pending[:fill]))
+          end
+
+          # PlantUML does not draw a box inside a box: the inner one is drawn
+          # beside the outer one's own members, and an outer box with none is
+          # not drawn at all.
+          def open_box(match)
+            @open_boxes.last&.store(:nested, true)
+            @open_boxes << { title: unquote(match[1].to_s), members: [],
+                             fill: Fill.read(match[2]) }
+          end
+
+          def close_box
+            box = @open_boxes.pop
+            return if box[:nested] && box[:members].empty?
+
+            @boxes << Box.new(title: box[:title], members: box[:members],
+                              fill: box[:fill])
+          end
+
+          def end_of_diagram(text, number)
+            raise refusal(text, number, "empty diagram") if @participants.empty?
+            raise unclosed_box if @open_boxes.any?
+            raise unclosed_block if @outline.open_block?
+
+            :after
+          end
+
+          def declare(match)
+            display = unquote(match[2])
+            id = match[3] || display
+            @participants[id] ||= participant(match, id, display)
+            @orders[id] ||= match[5].to_i
+            @open_boxes.last[:members] << id if @open_boxes.any?
+          end
+
+          def participant(match, id, display)
+            Participant.new(
+              id: id, label: display, kind: match[1].downcase.to_sym,
+              stereotype: match[4], fill: Fill.read(match[6])
+            )
+          end
+
+          def message(match)
+            message = build_message(match) or return false
+            return false if unplaceable?(message, match[4])
+
+            marks = marks_of(match, message)
+            return false if match[5] && marks.none? { |phase,| phase == :on }
+
+            @outline.message(message, marks)
+          end
+
+          def build_message(match)
+            style, reversed = ArrowSyntax.read(match[2])
+            ends = [endpoint(match[1], :left), endpoint(match[3], :right)]
+            return unless style && edges_readable?(ends, reversed)
+
+            from, to = reversed ? ends.reverse : ends
+            kind = @parallel ? ParallelMessage : Message
+            kind.new(from: from, to: to, label: display_label(match[7]),
+                     style: style)
+          end
+
+          # PlantUML treats doubled quotes around a message label as display
+          # delimiters. Backslashes inside that form use pair escaping; a
+          # single backslash and escaped quote remain content. Explicit line
+          # breaks must be decoded before deciding whether quotes enclose one
+          # display line.
+          def display_label(label)
+            family = "monospace" if label&.start_with?('""')
+            Message::Label.new(content: message_label(label),
+                               font_family: family)
+          end
+
+          def message_label(label)
+            doubled_quotes = label&.start_with?('""') && label.end_with?('""')
+            return label unless doubled_quotes
+            return label if label.include?("\\n")
+
+            label[2...-2].strip.gsub("\\\\", "\\")
+          end
+
+          def endpoint(token, side)
+            Edge.read(token, side) || mention(token)
+          end
+
+          # At most one end is missing, and a diagram-wide edge only for the
+          # forms measured against PlantUML: written `[->` or `->]`.
+          def edges_readable?(ends, reversed)
+            edges = ends.grep(Edge)
+            edges.size < 2 && edges.none? { |edge| reversed && edge.global? }
+          end
+
+          # A `?` end has no ring in the slice, and a missing end cannot be
+          # activated or destroyed.
+          def unplaceable?(message, suffix)
+            edge = message.edge or return false
+
+            @autoactivate || !suffix.nil? ||
+              (edge.local? && message.edge_end.circle)
+          end
+
+          # `--` deactivates the sender, `++` activates the receiver and `!!`
+          # destroys it; a colour is the fill of the bar `++` opens.
+          def marks(suffix, message, colour)
+            MARKS.fetch(suffix, []).map do |phase|
+              [phase, phase == :off ? message.from : message.to,
+               phase == :on ? colour : nil]
+            end
+          end
+
+          def marks_of(match, message)
+            if @autoactivate && match[4].nil? && match[5].nil?
+              return automatic_marks(message)
+            end
+
+            marks(match[4], message, colour(match[6]))
+          end
+
+          # After `autoactivate on` a call activates its receiver and a
+          # dashed answer deactivates its sender, when it is active. A lost
+          # message (written `x`) does neither. A message to the edge is
+          # refused: the slice cannot activate the participant it names.
+          def automatic_marks(message)
+            return [] if message.style.head.glyph == :cross
+            return [[:on, message.to, nil]] unless message.dashed
+
+            active = @outline.active?(message.from)
+            active ? [[:off, message.from, nil]] : []
+          end
+
+          def colour(token)
+            return unless token
+
+            token.match?(/\A\h+\z/) ? "##{token}" : token.downcase
+          end
+
+          def mention(name)
+            id = unquote(name)
+            @participants[id] ||= Participant.new(id: id)
+            id
+          end
+
+          def unquote(name)
+            name.delete_prefix('"').delete_suffix('"')
+          end
+
+          def finish(phase)
+            if phase == :before
+              raise Etassia::Engine::DiagramTypeError,
+                    "Unable to detect diagram type from source. " \
+                    "Source must start with one of: @startuml"
+            end
+            return diagram if phase == :after
+
+            raise Etassia::Parser::ParseError,
+                  "Parse error: missing @enduml before the end of the source"
+          end
+
+          def diagram
+            ordered_participants
+            check_boxes
+            check_numbering
+            Diagram.new(participants: @participants.values.freeze,
+                        items: @outline.items.freeze, boxes: @boxes.freeze,
+                        appearance: @appearance, footbox: @footbox,
+                        warnings: @warnings.freeze, title: @title,
+                        chrome: @chrome, teoz: @teoz)
+          end
+
+          # `order N` seats a participant left to right by N; one with none
+          # counts as 0, and equal numbers keep the order they were met in.
+          def ordered_participants
+            ranked = @participants.each_with_index.sort_by do |(id, _), index|
+              [@orders.fetch(id, 0), index]
+            end
+            @participants = ranked.to_h(&:first)
+          end
+
+          # The number of a wrapped label would sit on one of its lines,
+          # which has not been measured.
+          def check_numbering
+            return unless @appearance.max_message
+            return unless @outline.items.grep(Message).any?(&:number)
+
+            raise Etassia::Parser::ParseError,
+                  "Parse error: autonumber with Maxmessagesize is not supported"
+          end
+
+          def unclosed_block
+            Etassia::Parser::ParseError.new(
+              "Parse error: a block is never closed with end",
+            )
+          end
+
+          def unclosed_chrome
+            kind = @pending_chrome[:kind]
+            Etassia::Parser::ParseError.new(
+              "Parse error: #{kind} is never closed with end #{kind}",
+            )
+          end
+
+          def unclosed_box
+            Etassia::Parser::ParseError.new(
+              "Parse error: box #{@open_boxes.last[:title].inspect} is never " \
+              "closed with endbox",
+            )
+          end
+
+          def check_boxes
+            ids = @participants.keys
+            @boxes.each do |box|
+              places = box.members.map { |id| ids.index(id) }.sort
+              next if places.each_cons(2).all? { |a, b| b == a + 1 }
+
+              raise Etassia::Parser::ParseError,
+                    "Parse error: participants of box #{box.title.inspect} " \
+                    "are not neighbours, which is not supported"
+            end
+          end
+
+          def refusal(text, number, construct = nil)
+            UnsupportedConstructError.new(
+              construct: construct || Refusals.name_for(text),
+              line: number, text: text
+            )
+          end
+        end
+      end
+    end
+  end
+end