etassia 0.1.0

data/lib/etassia/notation/plantuml/drawing/renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../../../renderer/base"
+require_relative "../../../svg"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Drawing
+        # Draws a {Scene}: each mark becomes the element it names.
+        class Renderer < Etassia::Renderer::Base
+          # @param scene [Scene]
+          # @return [Svg::Document]
+          def render(scene)
+            Svg::Document.new(
+              width: scene.width, height: scene.height,
+              view_box: scene.view_box
+            ).tap do |document|
+              scene.marks.each { |mark| document << element(mark) }
+            end
+          end
+
+          private
+
+          def element(mark)
+            mark.element.new.tap do |node|
+              mark.attributes.each do |name, value|
+                node.public_send(:"#{name}=", value) unless value.nil?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/drawing/scene.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Drawing
+        # One thing to draw: an SVG element class and its attributes.
+        Mark = Struct.new(:element, :attributes)
+
+        # A laid-out diagram: canvas size and marks, back to front.
+        class Scene
+          attr_reader :width, :height, :marks
+
+          def initialize(width:, height:, marks:)
+            @width = width
+            @height = height
+            @marks = marks.freeze
+            freeze
+          end
+
+          def view_box
+            "0 0 #{width} #{height}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "drawing/box"
+require_relative "drawing/face"
+require_relative "drawing/scene"
+require_relative "drawing/pen"
+require_relative "drawing/renderer"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # What the plain-picture families (network, timing, EBNF) share: a
+      # scene of marks, a pen that lays marks down and a renderer that turns
+      # them into SVG.
+      module Drawing
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ebnf/blocks.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Ebnf
+        # Sized pieces of a railroad diagram. Each knows its width, its
+        # height and `baseline`, the y of its rail from its top, and draws
+        # itself, rails included, at a position.
+        module Blocks
+          RADIUS = 12.0
+          GAP = 10.0
+          SIDE = 2 * RADIUS
+          WORD_HEIGHT = 26.4883
+          FONT_SIZE = 14
+          # The JAR puts a word's baseline 5.2910 below its rail; the pen
+          # centres text on `middle`, which sits 0.35 em above the baseline.
+          TEXT_DROP = 5.2910 - (0.35 * FONT_SIZE)
+          ARROW = 6.0
+          ARROW_HALF = 3.0
+
+          # The arrowheads that show a rail's direction. The JAR places one
+          # 40% along its rail less two pixels (measured at six spans).
+          module Arrow
+            module_function
+
+            def forward(pen, from, to, rail)
+              start = from + (0.4 * (to - from)) - 2
+              pen.polygon(head(start, rail, ARROW), stroke: "none")
+            end
+
+            # On the 26-pixel rail out of a rule, which the JAR does not
+            # place by the same measure.
+            def closing(pen, from, rail)
+              pen.polygon(head(from + 11, rail, ARROW), stroke: "none")
+            end
+
+            def backward(pen, from, to, rail)
+              start = to - (0.4 * (to - from)) - 2
+              pen.polygon(head(start, rail, -ARROW), stroke: "none")
+            end
+
+            def head(start, rail, length)
+              [[start, rail - ARROW_HALF], [start + length, rail],
+               [start, rail + ARROW_HALF]]
+            end
+          end
+
+          # The rail's bends, as the PlantUML JAR draws them: cubic curves
+          # whose handles run three quarters of the radius.
+          module Curves
+            module_function
+
+            # A turn from a horizontal rail into a vertical one.
+            def upright(from_x, from_y, run, rise, radius)
+              handle = 0.75 * radius
+              [:bezier, from_x + ((run <=> 0) * handle), from_y,
+               from_x + run, from_y + rise - ((rise <=> 0) * handle),
+               from_x + run, from_y + rise]
+            end
+
+            # A turn from a vertical rail into a horizontal one.
+            def level(from_x, from_y, run, rise, radius)
+              handle = 0.75 * radius
+              [:bezier, from_x, from_y + ((rise <=> 0) * handle),
+               from_x + run - ((run <=> 0) * handle), from_y + rise,
+               from_x + run, from_y + rise]
+            end
+
+            # From the rail at an edge down to a branch's level, `run`
+            # being the radius toward the branch (negative on the right).
+            # A bypass turns once, in an S; any other branch turns, runs
+            # straight and turns again.
+            def drop(edge, rail, level, run, smooth: false)
+              top = smooth ? (rail + level) / 2 : rail + RADIUS
+              bottom = smooth ? top : level - RADIUS
+              [[:move, edge, rail],
+               upright(edge, rail, run, top - rail, RADIUS),
+               *(smooth ? [] : [[:line, edge + run, bottom]]),
+               level(edge + run, bottom, run, level - bottom, RADIUS)]
+            end
+          end
+
+          # A block's shared shape.
+          class Block
+            attr_reader :width, :height, :baseline
+
+            def initialize(width, height, baseline)
+              @width = width
+              @height = height
+              @baseline = baseline
+            end
+          end
+
+          # A terminal, nonterminal or special sequence in a box.
+          class Word < Block
+            def initialize(pen, text, style, padding: 10.0)
+              super(pen.text_width(text, size: FONT_SIZE) + padding,
+                    WORD_HEIGHT, WORD_HEIGHT / 2)
+              @text = text
+              @style = style
+            end
+
+            def draw(pen, left, top)
+              pen.rect(left, top, width, height, **@style)
+              pen.text(@text, left + (width / 2),
+                       top + baseline + TEXT_DROP,
+                       anchor: "middle", size: FONT_SIZE)
+            end
+          end
+
+          # Nothing: just the rail, for the empty branch of an optional.
+          class Gap < Block
+            def initialize
+              super(0.0, GAP, GAP)
+            end
+
+            def draw(_pen, _left, _top); end
+          end
+
+          # Blocks one after another along the rail.
+          class Row < Block
+            JOIN = 20.0
+
+            def initialize(items)
+              ascent = items.map(&:baseline).max
+              descent = items.map { |item| item.height - item.baseline }.max
+              super(items.sum(&:width) + (JOIN * (items.size - 1)),
+                    ascent + descent, ascent)
+              @items = items
+            end
+
+            def draw(pen, left, top)
+              rail = top + baseline
+              lefts = lefts_from(left)
+              @items.each_with_index do |item, index|
+                item.draw(pen, lefts[index], rail - item.baseline)
+              end
+              join(pen, lefts, rail)
+            end
+
+            private
+
+            def lefts_from(left)
+              @items.each_with_object([left]) do |item, lefts|
+                lefts << (lefts.last + item.width + JOIN)
+              end
+            end
+
+            def join(pen, lefts, rail)
+              @items.each_cons(2).with_index do |(item, _), index|
+                pen.line(lefts[index] + item.width, rail, lefts[index + 1],
+                         rail)
+              end
+            end
+          end
+
+          # Alternatives stacked, the first on the rail, each starting at
+          # the stack's left. An empty first branch is a bypass: one rail
+          # across the top, with an arrowhead.
+          class Stack < Block
+            def initialize(branches)
+              @branches = branches
+              @smooth = branches.first.is_a?(Gap)
+              @tops = tops_of(branches)
+              super(branches.map(&:width).max + (2 * SIDE),
+                    @tops.last + branches.last.height,
+                    branches.first.baseline)
+            end
+
+            def draw(pen, left, top)
+              rail = top + baseline
+              bypass(pen, left, rail) if @smooth
+              @branches.each_with_index.drop(@smooth ? 1 : 0).each do |one, i|
+                level = top + @tops[i] + one.baseline
+                draw_branch(pen, one, left, [rail, level])
+              end
+            end
+
+            private
+
+            def tops_of(branches)
+              branches.each_with_object([0.0]) do |branch, tops|
+                tops << (tops.last + branch.height + GAP)
+              end.first(branches.size)
+            end
+
+            def bypass(pen, left, rail)
+              pen.line(left, rail, left + width, rail)
+              Arrow.forward(pen, left, left + width, rail)
+            end
+
+            def draw_branch(pen, branch, left, (rail, level))
+              inner = left + SIDE
+              branch.draw(pen, inner, level - branch.baseline)
+              turned = level != rail
+              feeds(pen, [[left, inner], [left + width, inner + branch.width]],
+                    level, turned)
+              turns(pen, left, rail, level) if turned
+            end
+
+            def feeds(pen, spans, level, turned)
+              spans.each { |edge, from| feed(pen, edge, from, level, turned) }
+            end
+
+            # The rail from a branch's end out to the stack's edge, stopping
+            # short of it where a turn takes over.
+            def feed(pen, edge, from, level, turned)
+              inset = turned ? SIDE : 0.0
+              pen.line(from, level, edge + (from > edge ? inset : -inset),
+                       level)
+            end
+
+            def turns(pen, left, rail, level)
+              pen.path(Curves.drop(left, rail, level, RADIUS, smooth: @smooth))
+              pen.path(Curves.drop(left + width, rail, level, -RADIUS,
+                                   smooth: @smooth))
+            end
+          end
+
+          # A block that may be taken again, by a line looping back over it.
+          class Loop < Block
+            INSET = 15.0
+            TURN = 8.0
+            ABOVE = 12.0
+            BACK = 5.0
+
+            def initialize(item)
+              super(item.width + (2 * INSET), item.height + ABOVE,
+                    item.baseline + ABOVE)
+              @item = item
+            end
+
+            def draw(pen, left, top)
+              rail = top + baseline
+              @item.draw(pen, left + INSET, top + ABOVE)
+              rails(pen, left, rail)
+              back(pen, [left + INSET, left + INSET + @item.width],
+                   [top + BACK, rail])
+            end
+
+            private
+
+            def rails(pen, left, rail)
+              pen.line(left, rail, left + INSET, rail)
+              pen.line(left + INSET + @item.width, rail, left + width, rail)
+            end
+
+            # The loop-back line, the JAR's: a straight run above the item
+            # with a bend at each end that drops to the rail.
+            def back(pen, (from, to), (level, rail))
+              pen.line(from, level, to, level)
+              Arrow.backward(pen, from, to, level)
+              [[from - INSET + TURN, TURN], [to + INSET - TURN, -TURN]]
+                .each { |edge, run| side(pen, edge, run, [level, rail]) }
+            end
+
+            def side(pen, edge, run, (level, rail))
+              pen.path([[:move, edge, rail - TURN],
+                        Curves.level(edge, rail - TURN, run, TURN, TURN)])
+              pen.path([[:move, edge, rail - TURN],
+                        [:line, edge, level + TURN],
+                        Curves.level(edge, level + TURN, run, -TURN, TURN)])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ebnf/layout.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "../drawing"
+require_relative "blocks"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Ebnf
+        # Draws each rule as a railroad diagram under its name, one below
+        # the other: a start dot, the rule's rail and an end dot.
+        class Layout
+          include Drawing::Pen
+
+          MARGIN = 10.0
+          TITLE_BASE = 23.5352
+          TITLE_SIZE = 14
+          # From a rule's name down to its rail, and on to the next name.
+          RULE_TOP = 12.9531
+          RULE_BOTTOM = 28.5352
+          LEAD = 26.0
+          # Past the end rail: the end dot's diameter and the margin, plus
+          # the start dot's radius the left side starts after.
+          RIGHT = 18.0
+          FOOT = 25.0
+          RAIL = "1.5"
+          PLAIN = { stroke_width: "0.5" }.freeze
+          ROUND = { fill: "#F1F1F1", rx: 5.0, stroke_width: "1.5" }.freeze
+          DASHED = { stroke_width: "1", stroke_dasharray: "5,5" }.freeze
+          SPECIAL_PADDING = 18.8594
+          private_constant :MARGIN, :TITLE_BASE, :TITLE_SIZE, :RULE_TOP,
+                           :RULE_BOTTOM, :RAIL, :LEAD, :RIGHT, :FOOT, :PLAIN,
+                           :ROUND, :DASHED, :SPECIAL_PADDING
+
+          # @param rules [Array<Rule>]
+          # @return [Drawing::Scene]
+          def call(rules, **)
+            blocks = rules.map { |rule| build(rule.expression) }
+            bottom = stack(rules, blocks)
+            width = blocks.map(&:width).max + (2 * LEAD) + MARGIN + RIGHT
+            scene(width, bottom + FOOT)
+          end
+
+          # PlantUML draws the rails at one and a half pixels.
+          def line(*coordinates, **style)
+            super(*coordinates, stroke_width: RAIL, **style)
+          end
+
+          def path(commands, **style)
+            super(commands, stroke_width: RAIL, **style)
+          end
+
+          private
+
+          # @return [Float] where the last rule's rail ends
+          def stack(rules, blocks)
+            names = rules.zip(blocks).reduce(TITLE_BASE) do |name, (rule, one)|
+              draw_rule(rule, one, name)
+              name + RULE_TOP + one.height + RULE_BOTTOM
+            end
+            names - RULE_BOTTOM
+          end
+
+          def draw_rule(rule, block, name)
+            text(rule.name, MARGIN, name - (0.35 * TITLE_SIZE),
+                 size: TITLE_SIZE, bold: true)
+            draw_rail(block, name + RULE_TOP)
+          end
+
+          def draw_rail(block, top)
+            rail = top + block.baseline
+            left = MARGIN + 4
+            circle(left, rail, 4, stroke_width: "2")
+            line(left + 4, rail, left + LEAD, rail)
+            block.draw(self, left + LEAD, top)
+            draw_end(left + LEAD + block.width, rail)
+          end
+
+          def draw_end(from, rail)
+            line(from, rail, from + LEAD, rail)
+            Blocks::Arrow.closing(self, from, rail)
+            circle(from + LEAD + 4, rail, 4, fill: INK)
+          end
+
+          def build(node)
+            case node
+            when Literal then Blocks::Word.new(self, node.text, PLAIN)
+            when Reference then Blocks::Word.new(self, node.name, ROUND)
+            when Special then Blocks::Word.new(self, node.text, DASHED,
+                                               padding: SPECIAL_PADDING)
+            else compound(node)
+            end
+          end
+
+          def compound(node)
+            case node
+            when Sequence then Blocks::Row.new(node.items.map { |n| build(n) })
+            when Choice then Blocks::Stack.new(node.branches.map do |n|
+              build(n)
+            end)
+            when Optional then Blocks::Stack.new([Blocks::Gap.new,
+                                                  build(node.item)])
+            else repeated(node)
+            end
+          end
+
+          def repeated(node)
+            loop_block = Blocks::Loop.new(build(node.item))
+            return loop_block if node.least.positive?
+
+            Blocks::Stack.new([Blocks::Gap.new, loop_block])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/ebnf/model.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Ebnf
+        # What a rule's right-hand side is made of.
+        Literal = Struct.new(:text, keyword_init: true)
+        Reference = Struct.new(:name, keyword_init: true)
+        Special = Struct.new(:text, keyword_init: true)
+        Sequence = Struct.new(:items, keyword_init: true)
+        Choice = Struct.new(:branches, keyword_init: true)
+        Optional = Struct.new(:item, keyword_init: true)
+        # `{ x }` is a Repetition with `least` 0 and `{ x }-` one with 1.
+        Repetition = Struct.new(:item, :least, keyword_init: true)
+
+        # One `name = expression ;`.
+        Rule = Struct.new(:name, :expression, keyword_init: true)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "../state/reader"
+require_relative "../../../error/parse_error"
+require_relative "model"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Ebnf
+        # Reads `name = expression ;` rules in the ISO EBNF notation:
+        # `,` sequence, `|` choice, `[ ]` optional, `{ }` repetition (`{ }-`
+        # one or more), `( )` grouping, quoted terminals, `? ?` special
+        # sequences and `(* *)` comments. Anything else raises
+        # {Etassia::Parser::ParseError}.
+        class Reader
+          TOKEN = /\s*(?:(?<string>"[^"]*"|'[^']*')|(?<special>\?[^?]*\?)|
+                   (?<name>[A-Za-z_]\w*(?:[ \t]+[A-Za-z_]\w*)*)|
+                   (?<mark>[=,|;\[\]{}()-]))/xm
+          COMMENT = /\(\*.*?\*\)/m
+          private_constant :TOKEN, :COMMENT
+
+          # @param source [String] PlantUML source
+          # @return [Array<Rule>]
+          def parse(source)
+            body = State::Reader.lines_of(source).map(&:first).join("\n")
+            @tokens = tokenize(body.gsub(COMMENT, " "))
+            rules = []
+            rules << rule until @tokens.empty?
+            raise fail_with("no rule found") if rules.empty?
+
+            rules
+          end
+
+          private
+
+          def tokenize(text)
+            tokens = []
+            scanner = StringScanner.new(text)
+            until scanner.skip(/\s*\z/)
+              unless scanner.scan(TOKEN)
+                raise fail_with("cannot read #{scanner.rest[0,
+                                                            20].inspect}")
+              end
+
+              tokens << token_of(scanner)
+            end
+            tokens
+          end
+
+          def token_of(scanner)
+            %i[string special name mark].each do |kind|
+              value = scanner[kind]
+              return [kind, value.strip] if value
+            end
+          end
+
+          def rule
+            name = take(:name)
+            take(:mark, "=")
+            expression = choice
+            take(:mark, ";")
+            Rule.new(name: name, expression: expression)
+          end
+
+          def choice
+            branches = [sequence]
+            branches << sequence while consume?("|")
+            branches.one? ? branches.first : Choice.new(branches: branches)
+          end
+
+          def sequence
+            items = [term]
+            items << term while consume?(",")
+            items.one? ? items.first : Sequence.new(items: items)
+          end
+
+          def term
+            kind, value = @tokens.shift
+            case kind
+            when :string then Literal.new(text: value[1..-2])
+            when :special then Special.new(text: value[1..-2].strip)
+            when :name then Reference.new(name: value)
+            when :mark then bracketed(value)
+            else raise fail_with("unexpected end of rule")
+            end
+          end
+
+          def bracketed(mark)
+            case mark
+            when "[" then Optional.new(item: closed(choice, "]"))
+            when "{" then repetition
+            when "(" then closed(choice, ")")
+            else raise fail_with("unexpected #{mark.inspect}")
+            end
+          end
+
+          def repetition
+            item = closed(choice, "}")
+            Repetition.new(item: item, least: consume?("-") ? 1 : 0)
+          end
+
+          def closed(node, mark)
+            take(:mark, mark)
+            node
+          end
+
+          def consume?(mark)
+            return false unless @tokens.first == [:mark, mark]
+
+            @tokens.shift
+            true
+          end
+
+          def take(kind, value = nil)
+            token = @tokens.shift
+            return token[1] if token && token[0] == kind &&
+              (value.nil? || token[1] == value)
+
+            raise fail_with("expected #{value || kind}")
+          end
+
+          def fail_with(message)
+            Etassia::Parser::ParseError.new("EBNF: #{message}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "ebnf/reader"
+require_relative "ebnf/layout"
+require_relative "drawing"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML EBNF diagram (`@startebnf`): each rule drawn as a
+      # railroad diagram.
+      module Ebnf
+        extend self
+
+        STARTER = /\A(?:\xEF\xBB\xBF)?(?:[ \t]*(?:'[^\n]*)?\r?\n)*
+                   [ \t]*@startebnf(?![A-Za-z0-9_])/xn
+        private_constant :STARTER
+
+        # @return [Boolean] whether the source opens an EBNF diagram
+        def ebnf?(source)
+          source.b.match?(STARTER)
+        end
+
+        # @return [Notation::Parsed]
+        def parse(source)
+          Notation::Parsed.new(
+            type: :ebnf_diagram, diagram: Reader.new.parse(source),
+            transform: Layout, renderer: Drawing::Renderer
+          )
+        end
+      end
+    end
+  end
+end