etassia 0.1.0

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

@@ -0,0 +1,442 @@
+# frozen_string_literal: true
+
+require_relative "class_name"
+require_relative "diagram"
+require_relative "klass"
+require_relative "member"
+require_relative "note"
+require_relative "package"
+require_relative "portion_visibility"
+require_relative "style_reader"
+require_relative "relation"
+require_relative "unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Collects what the parser reads, one line at a time, into a Diagram.
+      #
+      # A class mentioned in a relation before (or without) being declared
+      # exists as an implicit :class. A later declaration may give it its
+      # kind; redeclaring an explicitly declared class as another kind is
+      # refused, because this notation cannot say what it means.
+      #
+      # Source with only `-->` and `<--` relations is a sequence diagram to
+      # PlantUML and is refused; see `class_only?` and `GLOBAL_COMMAND`.
+      class DiagramBuilder
+        # The words PlantUML 1.2026.6 reads as a global command, not a
+        # participant, at the start of a sequence-diagram line.
+        GLOBAL_COMMAND =
+          /\A(?:caption|footer|header|legend|mainframe|title)[ \t]/i
+        SMETANA = /\A!pragma[ \t]+layout[ \t]+smetana\z/i
+        private_constant :SMETANA
+
+        def initialize
+          @kinds, @bodies, @explicit, @extras, @captions =
+            Array.new(5) { {} }
+          @relations, @junctions, @directives, @notes, @hidden_tags,
+            @packages = Array.new(6) { [] }
+        end
+
+        # A kind written twice keeps the later text, as PlantUML does.
+        def caption(caption)
+          @captions[caption.kind] = caption
+        end
+
+        # @raise [UnsupportedConstructError] on a second block, whose
+        #   precedence over the first is not read
+        def open_style(number, text)
+          refuse(text, number, "second style block") if @style_reader
+
+          @style_line = number
+          @style_reader = StyleReader.new
+        end
+
+        # @return [Symbol] :closed when the line ended the block, else :open
+        def style_line(text, number)
+          @style_reader.feed(text, number)
+        end
+
+        # @return [Integer, nil] the line of the style block opened last
+        def open_style_line
+          @style_line
+        end
+
+        def directive(text)
+          @directives << text
+        end
+
+        # `hide $tag` affects every class carrying the tag, whether the class
+        # is declared before or after the line.
+        def hide_tag(tag, number, text)
+          @hidden_tags << [tag, number, text]
+        end
+
+        # Opens a package; the classes declared until {#close_package} are
+        # in it, and a package opened before then is inside it.
+        def open_package(package, number, text)
+          if @packages.any? { |known| known.id == package.id }
+            refuse(text, number, "package declared twice")
+          end
+
+          parent = implicit_parents(package.id, number, text)
+          @packages << package.inside(parent)
+          scopes.push([package, number, text])
+        end
+
+        def package_open?
+          !scopes.empty?
+        end
+
+        # @raise [UnsupportedConstructError] when the package holds no class,
+        #   directly or in a package inside it
+        def close_package
+          package, number, text = scopes.pop
+          members = @extras.values.count do |entry|
+            chain_of(entry[:package]).include?(package.id)
+          end
+          refuse(text, number, "empty package") if members.zero?
+        end
+
+        # @return [Integer, nil] the line of the innermost package still open
+        def open_package_line
+          scopes.last && scopes.last[1]
+        end
+
+        def junction(junction, number, text)
+          mention(junction.owner)
+          @junctions << [junction, number, text]
+        end
+
+        # @return [Array(String, Integer)] the class whose body was opened
+        #   last and the line it was opened on
+        def open_class
+          @open
+        end
+
+        # Opens a note; its text arrives through {#add_note_line}.
+        # @raise [Etassia::Parser::ParseError] when the class is unknown, as
+        #   PlantUML refuses a note on a class not yet mentioned
+        def open_note(head, number, lines = [])
+          if head[:target] && !@kinds.key?(head[:target])
+            raise Etassia::Parser::ParseError,
+                  "Parse error: line #{number} puts a note on " \
+                  "#{head[:target]}, which is not declared before it"
+          end
+
+          @note = [head, number, lines]
+        end
+
+        # @return [String, nil] the class defined last, which a note written
+        #   without `of` sits beside
+        def last_defined
+          @kinds.keys.last
+        end
+
+        def add_note_line(text)
+          @note.last << text
+        end
+
+        def close_note
+          head, _number, lines = @note
+          @notes << Note.new(head, lines: lines.freeze)
+          @note = nil
+        end
+
+        # @return [Integer, nil] the line the unclosed note was opened on
+        def open_note_line
+          @note && @note[1]
+        end
+
+        # @return [Boolean] true until a class is declared or mentioned
+        def empty?
+          @kinds.empty?
+        end
+
+        # Declares a class and, when `entry[:body]` is true, opens its body.
+        # `entry` holds :name, :kind, :body, :generics and :stereotypes.
+        def declare(entry, number, text)
+          name, kind = entry.values_at(:name, :kind)
+          home = home_of(name, number, text)
+          refuse_package_clash(name, home, number, text)
+          mention(name)
+          refuse_redeclaration(name, kind, number, text)
+          record_class(name, kind, entry.merge(package: home))
+          @open = [name, number] if entry[:body]
+        end
+
+        def record_class(name, kind, entry)
+          @kinds[name] = kind
+          @explicit[name] = true
+          @class_evidence = true
+          @extras[name] = entry.slice(:generics, :stereotypes, :tags, :package)
+        end
+
+        def add_member(member)
+          @bodies.fetch(@open.first) << member
+        end
+
+        # A member written outside a body, as `Name : member`.
+        def add_member_to(name, member)
+          mention(name)
+          @class_evidence = true
+          @bodies.fetch(name) << member
+        end
+
+        def relate(relation, number, text)
+          refuse_new_class_in_package(relation, number, text)
+          refuse_new_qualified_class(relation, number, text)
+          [relation.left, relation.right].each { |name| mention_end(name) }
+          @sequence_arrow ||= [number, text] if sequence_arrow?(relation, text)
+          @class_evidence ||= class_only?(relation)
+          @relations << relation
+        end
+
+        # @return [Diagram] frozen, with every class once in order of first
+        #   mention
+        # @raise [UnsupportedConstructError] when PlantUML would read the
+        #   source as a sequence diagram
+        def diagram
+          refuse_sequence_diagram
+          @junctions.each { |entry| refuse_unrelated_junction(*entry) }
+
+          visible(build_classes)
+        end
+
+        private
+
+        def build_classes
+          visibility = PortionVisibility.new(@directives)
+          @kinds.map do |name, kind|
+            body = @bodies.fetch(name).dup.freeze
+            visibility.apply(Klass.new(name: name, kind: kind, body: body,
+                                       **@extras.fetch(name, {})))
+          end
+        end
+
+        def visible(classes)
+          hidden = hidden_names(classes)
+          refuse_attachments_to(hidden)
+          return smetana_visible(classes, hidden) if smetana?
+
+          kept = classes.reject { |klass| hidden.include?(klass.name) }
+          gone = hidden + unoccupied_ids(kept)
+          assemble(kept, @relations.reject { |rel| touches?(rel, gone) })
+        end
+
+        def hidden_names(classes)
+          classes.select { |klass| hidden?(klass) }.map(&:name)
+        end
+
+        def smetana_visible(classes, hidden)
+          gone = unoccupied_ids(classes)
+          relations = @relations.reject { |relation| touches?(relation, gone) }
+            .map do |relation|
+              touches?(relation, hidden) ? relation.as_layout_only : relation
+            end
+          assemble(classes, relations)
+        end
+
+        def assemble(classes, relations)
+          Diagram.new(
+            classes: classes.freeze, relations: relations.freeze,
+            junctions: @junctions.map(&:first).freeze,
+            directives: @directives.dup.freeze, notes: @notes.dup.freeze,
+            packages: occupied_packages(classes).freeze,
+            captions: @captions.values.freeze, style: style_sheet
+          )
+        end
+
+        def style_sheet
+          @style_reader ? @style_reader.sheet : StyleSheet.new
+        end
+
+        # A package whose every class is hidden draws no frame.
+        def occupied_packages(classes)
+          named = occupied_ids(classes)
+          @packages.select { |package| named.include?(package.id) }
+        end
+
+        def unoccupied_ids(classes)
+          @packages.map(&:id) - occupied_ids(classes)
+        end
+
+        def occupied_ids(classes)
+          classes.flat_map { |klass| chain_of(klass.package) }
+        end
+
+        def chain_of(id)
+          Package.chain(id, @packages)
+        end
+
+        # `package a.b.c` also opens `a` and `a.b`, each inside the one
+        # before. Returns the id the package itself sits inside.
+        def implicit_parents(id, number, text)
+          *outer, _leaf = id.split(".")
+          outer.each_index.reduce(scope_id) do |parent, index|
+            id = outer.first(index + 1).join(".")
+            open_implicit(id, parent, number, text)
+            id
+          end
+        end
+
+        def open_implicit(id, parent, number, text)
+          known = @packages.find { |other| other.id == id }
+          if known.nil?
+            @packages << Package.new(id: id, title: id.split(".").last,
+                                     shape: :folder, icon: false,
+                                     parent: parent)
+          elsif known.parent != parent
+            refuse(text, number, "package name shared by two packages")
+          end
+        end
+
+        # The package a class lives in. A name written with dots lives in
+        # the namespaces before its last dot, which PlantUML opens itself.
+        def home_of(name, number, text)
+          return scope_id unless name.include?(".")
+
+          refuse_misplaced_qualified(name, number, text)
+          implicit_parents(name, number, text)
+        end
+
+        def refuse_misplaced_qualified(name, number, text)
+          unless scopes.empty? && name.split(".", -1).none?(&:empty?)
+            refuse(text, number, "qualified class name here")
+          end
+          return unless ClassName.namespaces(name).any? { _1.include?("\\") }
+
+          refuse(text, number, "escape in a namespace name")
+        end
+
+        def package?(name)
+          @packages.any? { |package| package.id == name }
+        end
+
+        def scopes
+          @scopes ||= []
+        end
+
+        def scope_id
+          scopes.last&.first&.id
+        end
+
+        def hidden?(klass)
+          @hidden_tags.any? { |tag, *| klass.tags.include?(tag) }
+        end
+
+        def smetana?
+          @directives.any? { |line| line.match?(SMETANA) }
+        end
+
+        def touches?(relation, names)
+          names.include?(relation.left) || names.include?(relation.right)
+        end
+
+        # PlantUML's result for a note or association class on a hidden
+        # class is not measured, so it is not drawn.
+        def refuse_attachments_to(hidden)
+          attached = @junctions.map { |junction, *| junction.owner }
+          owners = attached + @notes.map(&:target)
+          return unless owners.intersect?(hidden)
+
+          _tag, number, text = @hidden_tags.first
+          raise UnsupportedConstructError.new(
+            construct: "hide of a class with a note or association class",
+            line: number, text: text
+          )
+        end
+
+        def refuse_sequence_diagram
+          return unless @sequence_arrow && !@class_evidence
+
+          number, text = @sequence_arrow
+          raise UnsupportedConstructError.new(
+            construct: "sequence diagram", line: number, text: text,
+          )
+        end
+
+        # PlantUML joins the two classes itself when no relation was
+        # written; this notation has no relation to hang the class on.
+        def refuse_unrelated_junction(junction, number, text)
+          pair = [junction.from, junction.to].sort
+          return if @relations.any? { |r| [r.left, r.right].sort == pair }
+
+          raise UnsupportedConstructError.new(
+            construct: "association class without its relation",
+            line: number, text: text
+          )
+        end
+
+        def refuse(text, number, construct)
+          raise UnsupportedConstructError.new(
+            construct: construct, line: number, text: text,
+          )
+        end
+
+        # A class lives in one place; a name met outside its package would
+        # be a second class to PlantUML.
+        def refuse_package_clash(name, home, number, text)
+          refuse(text, number, "class named like a package") if package?(name)
+          return unless @kinds.key?(name)
+          return if @extras.dig(name, :package) == home
+
+          refuse(text, number, "class declared in more than one place")
+        end
+
+        def refuse_new_class_in_package(relation, number, text)
+          return if scopes.empty?
+          return if [relation.left, relation.right].all? { |name| @kinds[name] }
+
+          refuse(text, number, "class first mentioned in a package")
+        end
+
+        # A qualified name met before it is declared would put the class
+        # outside the namespaces PlantUML gives it.
+        def refuse_new_qualified_class(relation, number, text)
+          [relation.left, relation.right].each do |name|
+            next if !name.include?(".") || @kinds.key?(name) || package?(name)
+
+            refuse(text, number, "qualified class name first mentioned " \
+                                 "in a relation")
+          end
+        end
+
+        def refuse_redeclaration(name, kind, number, text)
+          return unless @explicit[name] && @kinds[name] != kind
+
+          raise UnsupportedConstructError.new(
+            construct: "redeclaration as another kind", line: number,
+            text: text
+          )
+        end
+
+        def sequence_arrow?(relation, text)
+          !class_only?(relation) && !GLOBAL_COMMAND.match?(text)
+        end
+
+        # True when only a class diagram has this relation: a multiplicity, or
+        # an arrow other than a plain `-->` or `<--`.
+        def class_only?(relation)
+          return true if relation.left_multiplicity
+          return true if relation.right_multiplicity
+
+          !relation.plain?
+        end
+
+        # A name that is a package's id, with no class of that name, is the
+        # package: the relation runs to its frame.
+        def mention_end(name)
+          return if !@kinds.key?(name) && package?(name)
+
+          mention(name)
+        end
+
+        def mention(name)
+          @kinds[name] ||= :class
+          @bodies[name] ||= []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The name PlantUML lets an opener carry: `@startuml foo` and
+      # `@startuml(id=foo)`. PlantUML uses it only to name the output file; it
+      # never changes the drawing, so the parsers accept it and drop it, and
+      # the notation hands it to the caller through {Notation::Parsed#name}.
+      #
+      # The name is the source text as written, stripped. It is untrusted:
+      # it may hold spaces, dots, slashes (`../evil`) or quotes. Etassia never
+      # uses it as a path; a caller that does must sanitise it first.
+      module DiagramName
+        extend self
+
+        # `@start<tag>`, then an optional `(id=NAME)` and optional text.
+        OPENER = /\A@start[a-z]+(?:\((?:id=)?([^)]*)\))?(?:[ \t]+(.*))?\z/
+        PAD = '[ \t\v\f\x00]'
+        # The first line that is not blank and not a `'` comment, after an
+        # optional byte order mark; matched on raw bytes so no input raises.
+        FIRST_LINE = /\A(?:\xEF\xBB\xBF)?
+                      (?:#{PAD}*(?:'[^\r\n]*)?(?:\r\n|\r|\n))*
+                      #{PAD}*(@start[^\r\n]*)/xn
+        private_constant :OPENER, :PAD, :FIRST_LINE
+
+        # @param source [String] PlantUML source, any bytes
+        # @return [String, nil] the name the opener carries, or nil when it
+        #   carries none, is not valid UTF-8, or the source has no opener
+        def read(source)
+          line = opener_line(source)
+          match = line && OPENER.match(line)
+          clean(match && (match[2] || match[1]))
+        end
+
+        private
+
+        # nil when there is no opener or its bytes are not valid UTF-8.
+        def opener_line(source)
+          line = FIRST_LINE.match(source.b)&.[](1)&.force_encoding("UTF-8")
+          line.strip if line&.valid_encoding?
+        end
+
+        def clean(name)
+          name = name&.strip
+          name unless name.nil? || name.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Lines that restyle or steer a diagram without adding to its model:
+      # which layout engine PlantUML uses, what it hides, its skin
+      # parameters, its layout direction. The parser records them in the
+      # Diagram's `directives`; {PortionVisibility} applies the hide and
+      # show lines that remove members or stereotype labels.
+      module Directives
+        extend self
+
+        TARGET = '(?:[A-Za-z_][A-Za-z0-9_]*[ \t]+|<<[^<>\s]+>>[ \t]+)'
+        PATTERNS = [
+          /\A!pragma[ \t]+(?:layout[ \t]+(?:smetana|dot)|
+            svginteractive[ \t]+(?:true|false))\z/ix,
+          /\A(?:hide|show)[ \t]+(?:empty[ \t]+)?#{TARGET}?
+            (?:members|attributes|methods|fields|circle|stereotype)\z/ix,
+          /\Askinparam[ \t]+[A-Za-z0-9_.]+(?:<<[^<>\s]+>>)?[ \t]+
+            [^{}\s][^{}]*\z/ix,
+          /\A(?:left to right|top to bottom) direction\z/i,
+        ].freeze
+        private_constant :TARGET, :PATTERNS
+
+        # @param text [String] one stripped source line
+        def match?(text)
+          PATTERNS.any? { |pattern| pattern.match?(text) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Drawing
+        # A rectangle's left, top, width and height.
+        Box = Struct.new(:left, :top, :width, :height) do
+          def right
+            left + width
+          end
+
+          def bottom
+            top + height
+          end
+
+          def centre
+            left + (width / 2)
+          end
+
+          def middle
+            top + (height / 2)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Drawing
+        # How wide PlantUML's face sets text. The closest advances etassia
+        # carries are DejaVu Sans, within about 5% of the JAR's.
+        module Face
+          # The share of a font size between the middle of a line and its
+          # baseline: etassia anchors text by its middle, the JAR by its
+          # baseline.
+          MIDDLE = 0.3418
+
+          module_function
+
+          # @return [Float]
+          def width(text, size:, bold: false)
+            TextMeasurement.measure_in(bold ? :dejavu_bold : :dejavu,
+                                       text.to_s, font_size: size)[:width]
+          end
+
+          # @return [Float] the width of the widest line of `text`, split at
+          #   a newline or a literal backslash-n
+          def widest_line(text, size:, bold: false)
+            text.to_s.split(/\\n|\n/, -1).map do |line|
+              width(line, size: size, bold: bold)
+            end.max.to_f
+          end
+
+          # @return [Float] the middle of a line whose baseline is given
+          def middle(baseline, size)
+            baseline - (MIDDLE * size)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../../../svg"
+require_relative "../../../text_measurement"
+require_relative "face"
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Drawing
+        # Lays marks into `marks`, the array a layout owns, in PlantUML's
+        # look: dark one-and-a-half pixel strokes on white.
+        module Pen
+          INK = "#181818"
+          COMMAND_KEYS = { move: %i[x y], line: %i[x y],
+                           curve: %i[cx cy x y],
+                           bezier: %i[c1x c1y c2x c2y x y], close: [] }.freeze
+          FONT_SIZE = 12
+
+          def marks
+            @marks ||= []
+          end
+
+          def rect(left, top, width, height, **style)
+            put(Svg::Rect, { x: left, y: top, width: width, height: height,
+                             fill: "none", stroke: INK, stroke_width: "1" },
+                style)
+          end
+
+          def line(startx, starty, endx, endy, **style)
+            put(Svg::Line, { x1: startx, y1: starty, x2: endx, y2: endy,
+                             stroke: INK, stroke_width: "1" }, style)
+          end
+
+          # @param commands [Array<Hash, Array>] path commands, each a hash
+          #   for {Svg::Path.build_path_data} or a tuple such as
+          #   `[:line, x, y]`, `[:curve, cx, cy, x, y]` or
+          #   `[:bezier, c1x, c1y, c2x, c2y, x, y]`
+          def path(commands, **style)
+            hashes = commands.map { |one| command_hash(one) }
+            data = Svg::Path.build_path_data(hashes)
+            put(Svg::Path, { d: data, fill: "none", stroke: INK,
+                             stroke_width: "1" }, style)
+          end
+
+          def polygon(points, **style)
+            put(Svg::Polygon, { points: Svg::Polygon.build_points(points),
+                                fill: INK, stroke: INK, stroke_width: "1" },
+                style)
+          end
+
+          def ellipse(center_x, center_y, radius_x, radius_y, **style)
+            put(Svg::Ellipse, { cx: center_x, cy: center_y, rx: radius_x,
+                                ry: radius_y, fill: "none", stroke: INK,
+                                stroke_width: "1" }, style)
+          end
+
+          def circle(center_x, center_y, radius, **style)
+            put(Svg::Circle, { cx: center_x, cy: center_y, r: radius,
+                               fill: "none", stroke: INK, stroke_width: "1" },
+                style)
+          end
+
+          # @param options [Hash] `size`, `anchor` (an SVG text-anchor),
+          #   `bold`, `family` and `fill`
+          def text(content, left, middle, **options)
+            put(Svg::Text, { x: left, y: middle, content: content.to_s,
+                             text_anchor: "start", font_family: "sans-serif",
+                             font_size: FONT_SIZE.to_s, fill: INK,
+                             dominant_baseline: "middle" },
+                typeface(options))
+          end
+
+          def text_width(content, size: FONT_SIZE)
+            Face.width(content, size: size)
+          end
+
+          def scene(width, height)
+            Scene.new(width: width.ceil, height: height.ceil, marks: marks)
+          end
+
+          private
+
+          def command_hash(command)
+            return command unless command.is_a?(Array)
+
+            type, *numbers = command
+            COMMAND_KEYS.fetch(type).zip(numbers).to_h.merge(type: type)
+          end
+
+          def typeface(options)
+            { font_size: options[:size]&.to_s, fill: options[:fill],
+              text_anchor: options[:anchor], font_family: options[:family],
+              font_weight: ("bold" if options[:bold]) }.compact
+          end
+
+          def put(element, defaults, style)
+            marks << Mark.new(element, defaults.merge(style))
+          end
+        end
+      end
+    end
+  end
+end