etassia 0.1.0

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "klass"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # What the `hide` and `show` lines take out of a class: its fields,
+      # its methods or its stereotype labels. A line names every class, one
+      # class, or the classes carrying a `<<stereotype>>`; for the
+      # stereotype portion a `<<stereotype>>` target hides only that label.
+      # Lines apply in source order wherever the class is declared, and a
+      # later line overrides an earlier one, as in PlantUML.
+      #
+      # `hide empty members` and `hide circle` change only how a class is
+      # drawn, so they are not read here.
+      class PortionVisibility
+        RULE = /\A(hide|show)[ \t]+
+                (?:(?!empty[ \t])([A-Za-z_][A-Za-z0-9_]*|<<[^<>\s]+>>)[ \t]+)?
+                (members|attributes|fields|methods|stereotype)\z/ix
+        PORTIONS = {
+          "members" => %i[field method], "attributes" => %i[field],
+          "fields" => %i[field], "methods" => %i[method],
+          "stereotype" => %i[stereotype]
+        }.freeze
+        private_constant :RULE, :PORTIONS
+
+        # @param directives [Array<String>] the Diagram's directive lines
+        def initialize(directives)
+          @rules = directives.filter_map { |line| rule(line) }
+        end
+
+        # @return [Klass] `klass` without its hidden members and stereotype
+        #   labels; `klass` itself when nothing is hidden
+        def apply(klass)
+          return klass if @rules.empty?
+
+          Klass.new(
+            name: klass.name, kind: klass.kind, package: klass.package,
+            body: klass.body.select { |member| member?(klass, member) }.freeze,
+            stereotypes: stereotypes(klass), generics: klass.generics,
+            tags: klass.tags
+          )
+        end
+
+        private
+
+        def rule(line)
+          match = RULE.match(line)
+          return unless match
+
+          { show: match[1].casecmp?("show"), target: match[2],
+            portions: PORTIONS.fetch(match[3].downcase) }
+        end
+
+        def member?(klass, member)
+          shown?(member.kind) { |target| covers?(klass, target) }
+        end
+
+        def stereotypes(klass)
+          klass.stereotypes.select do |label|
+            shown?(:stereotype) do |target|
+              target == "<<#{label}>>" || (!stereotype?(target) &&
+                covers?(klass, target))
+            end
+          end.freeze
+        end
+
+        # The last rule for `portion` whose target the block accepts.
+        def shown?(portion)
+          @rules.reduce(true) do |shown, rule|
+            next shown unless rule[:portions].include?(portion)
+
+            yield(rule[:target]) ? rule[:show] : shown
+          end
+        end
+
+        def covers?(klass, target)
+          return true if target.nil?
+          return klass.name == target unless stereotype?(target)
+
+          klass.stereotypes.include?(target[2..-3])
+        end
+
+        def stereotype?(target)
+          target&.start_with?("<<")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # Places the small graph family whose bracketed relation qualifiers
+      # make PlantUML honour written direction words and one-dash same-rank
+      # links. Ordinary two-dash links advance down a rank; each extra dash
+      # advances one more rank.
+      class QualifiedAssociationLayout
+        RADIAL_HORIZONTAL_GAP = 80.0
+        FAN_HORIZONTAL_GAP = 35.0
+        MIXED_HORIZONTAL_GAP = 70.0
+        COMPACT_HORIZONTAL_GAP = 130.0
+        STANDARD_VERTICAL_GAP = 100.0
+        MIXED_NEAR_VERTICAL_GAP = 60.0
+        MIXED_LONG_VERTICAL_GAP = 80.0
+        COMPACT_VERTICAL_GAP = 120.0
+        COMPONENT_GAP = 25.0
+        FAN_PARENT_ALLOWANCE = 35.0
+        private_constant :RADIAL_HORIZONTAL_GAP, :FAN_HORIZONTAL_GAP,
+                         :MIXED_HORIZONTAL_GAP, :COMPACT_HORIZONTAL_GAP,
+                         :STANDARD_VERTICAL_GAP,
+                         :MIXED_NEAR_VERTICAL_GAP,
+                         :MIXED_LONG_VERTICAL_GAP,
+                         :COMPACT_VERTICAL_GAP, :COMPONENT_GAP,
+                         :FAN_PARENT_ALLOWANCE
+
+        def self.for(diagram)
+          return unless isolated_class_graph?(diagram)
+          return unless qualified_relations?(diagram.relations)
+
+          new(diagram)
+        end
+
+        def self.isolated_class_graph?(diagram)
+          diagram.packages.empty? && diagram.notes.empty? &&
+            diagram.junctions.empty?
+        end
+
+        def self.qualified_relations?(relations)
+          relations.any? { |relation| qualifier?(relation) } &&
+            relations.none? do |relation|
+              relation.left_role || relation.right_role
+            end
+        end
+
+        def self.qualifier?(relation)
+          [relation.left_multiplicity, relation.right_multiplicity]
+            .compact.any? { |text| text.start_with?("[") }
+        end
+        private_class_method :isolated_class_graph?, :qualified_relations?,
+                             :qualifier?
+
+        def initialize(diagram)
+          @names = diagram.classes.map(&:name)
+          @classes = diagram.classes
+          @relations = diagram.relations
+          @directives = diagram.directives
+        end
+
+        # Fan-out parents span the compact row occupied by their targets.
+        # This is the node constraint dot applies before it places ranks.
+        def constrained_sizes(sizes)
+          constrained = sizes.transform_values(&:dup)
+          fan_relations.each do |parent, outgoing|
+            widen_fan_parent(constrained, parent, outgoing.map(&:right))
+          end
+          constrained
+        end
+
+        def widen_fan_parent(constrained, parent, children)
+          child_width = children.sum { |name| constrained.fetch(name).first }
+          row_width = child_width + (FAN_HORIZONTAL_GAP * (children.size - 1))
+          parent_size = constrained.fetch(parent)
+          parent_size[0] = [parent_size.first,
+                            row_width + FAN_PARENT_ALLOWANCE].max
+        end
+
+        # @param sizes [Hash{String => Array(Float, Float)}]
+        # @param origin [Array(Float, Float)]
+        # @return [Hash{String => Array(Float, Float)}] top-left corners
+        def place(sizes, origin)
+          edge = origin.first
+          components.each_with_object({}) do |component, corners|
+            logical = spread_collisions(logical_positions(component))
+            placed, width = place_component(component, logical, sizes,
+                                            [edge, origin.last])
+            corners.merge!(placed)
+            edge += width + COMPONENT_GAP
+          end
+        end
+
+        private
+
+        attr_reader :names, :classes, :relations, :directives
+
+        def fan_relations
+          relations.group_by(&:left).select do |_parent, outgoing|
+            outgoing.size > 2 && outgoing.all? do |relation|
+              relation.direction.nil? && relation.length > 1
+            end
+          end
+        end
+
+        def components
+          unseen = names.dup
+          unseen.each_with_object([]) do |name, found|
+            next unless unseen.include?(name)
+
+            component = reachable(name)
+            found << component
+            unseen -= component
+          end
+        end
+
+        def reachable(root)
+          seen = []
+          queue = [root]
+          until queue.empty?
+            name = queue.shift
+            next if seen.include?(name)
+
+            seen << name
+            queue.concat(neighbours(name))
+          end
+          seen
+        end
+
+        def neighbours(name)
+          relations.filter_map do |relation|
+            relation.right if relation.left == name
+          end + relations.filter_map do |relation|
+            relation.left if relation.right == name
+          end
+        end
+
+        def logical_positions(component)
+          positions = { component.first => [0.0, 0.0] }
+          queue = [component.first]
+          until queue.empty?
+            name = queue.shift
+            visit_connected(name, positions, queue)
+          end
+          positions
+        end
+
+        def visit_connected(name, positions, queue)
+          connected(name).each do |other, delta|
+            next if positions.key?(other)
+
+            positions[other] = add(positions.fetch(name), delta)
+            queue << other
+          end
+        end
+
+        def connected(name)
+          relations.filter_map do |relation|
+            delta = relation_delta(relation)
+            if relation.left == name
+              [relation.right, delta]
+            elsif relation.right == name
+              [relation.left, delta.map(&:-@)]
+            end
+          end
+        end
+
+        def relation_delta(relation)
+          case relation.direction
+          when :up then [0.0, -1.0]
+          when :down then [0.0, 1.0]
+          when :left then [-1.0, 0.0]
+          when :right then [1.0, 0.0]
+          else default_delta(relation)
+          end
+        end
+
+        def default_delta(relation)
+          return [1.0, 0.0] if relation.length == 1
+
+          [0.0, [relation.length - 1, 1].max.to_f]
+        end
+
+        def add(first, second)
+          first.zip(second).map(&:sum)
+        end
+
+        def spread_collisions(positions)
+          positions.group_by { |_name, point| point }.each_value do |entries|
+            spread(entries, positions) if entries.size > 1
+          end
+          positions
+        end
+
+        def spread(entries, positions)
+          middle = (entries.size - 1) / 2.0
+          entries.each_with_index do |(name, point), index|
+            positions[name] = [point.first + index - middle, point.last]
+          end
+        end
+
+        def place_component(component, logical, sizes, origin)
+          columns = axis_layout(component, logical, sizes,
+                                axis: 0,
+                                origin: origin.first)
+          rows = axis_layout(component, logical, sizes,
+                             axis: 1,
+                             origin: origin.last)
+          corners = component_corners(component, logical, sizes,
+                                      [columns, rows])
+          extent = axis_extent(columns, origin.first)
+          span_fan_parent(component, corners, extent)
+        end
+
+        def component_corners(component, logical, sizes, (columns, rows))
+          component.to_h do |name|
+            [name, [centred(name, logical, sizes, columns, 0),
+                    centred(name, logical, sizes, rows, 1)]]
+          end
+        end
+
+        def span_fan_parent(component, corners, width)
+          return [corners, width] unless fan_component?(component)
+
+          inset = FAN_PARENT_ALLOWANCE / 2
+          shifted = corners.transform_values { |left, top| [left + inset, top] }
+          [shifted, width + FAN_PARENT_ALLOWANCE]
+        end
+
+        def axis_layout(component, logical, sizes, options)
+          axis = options.fetch(:axis)
+          data = { component: component, logical: logical, sizes: sizes }
+          layout = { cursor: options.fetch(:origin) }
+          coordinates = axis_coordinates(data, axis)
+          coordinates.each do |coordinate|
+            gap = axis_gap(component, axis, coordinate, coordinates, logical)
+            place_axis(layout, data, coordinate, axis, gap)
+          end
+          layout
+        end
+
+        def axis_coordinates(data, axis)
+          data.fetch(:component).map do |name|
+            data.fetch(:logical).fetch(name)[axis]
+          end.uniq.sort
+        end
+
+        def place_axis(layout, data, coordinate, axis, gap)
+          span = axis_span(data.fetch(:component), data.fetch(:logical),
+                           data.fetch(:sizes), axis, coordinate)
+          layout[coordinate] = [layout.fetch(:cursor), span]
+          layout[:cursor] += span + gap
+        end
+
+        def axis_gap(component, axis, coordinate, coordinates, logical)
+          return 0.0 if coordinate == coordinates.last
+          return horizontal_gap(component) if axis.zero?
+
+          vertical_gap(component, coordinate, coordinates, logical)
+        end
+
+        def horizontal_gap(component)
+          return COMPACT_HORIZONTAL_GAP if compact?
+          return MIXED_HORIZONTAL_GAP if mixed_kind?
+          return FAN_HORIZONTAL_GAP if fan_component?(component)
+
+          RADIAL_HORIZONTAL_GAP
+        end
+
+        def vertical_gap(component, coordinate, coordinates, logical)
+          return COMPACT_VERTICAL_GAP if compact?
+          return STANDARD_VERTICAL_GAP unless mixed_kind?
+
+          first = coordinates.first
+          return MIXED_LONG_VERTICAL_GAP if coordinate == first &&
+            long_qualified_source?(component, logical)
+
+          MIXED_NEAR_VERTICAL_GAP
+        end
+
+        def fan_component?(component)
+          fan_relations.keys.any? { |parent| component.include?(parent) }
+        end
+
+        def compact?
+          directives.include?("hide empty members")
+        end
+
+        def mixed_kind?
+          classes.any? { |klass| klass.kind != :class }
+        end
+
+        def long_qualified_source?(component, logical)
+          top = component.min_by { |name| logical.fetch(name).last }
+          relations.any? do |relation|
+            relation.left == top && relation.length > 2 &&
+              self.class.send(:qualifier?, relation)
+          end
+        end
+
+        def axis_span(component, logical, sizes, axis, coordinate)
+          names = component.select do |name|
+            logical.fetch(name)[axis] == coordinate
+          end
+          names.delete(fan_parent(component)) if fan_parent_in_column?(
+            component, names, axis
+          )
+          names.filter_map do |name|
+            sizes.fetch(name)[axis] if logical.fetch(name)[axis] == coordinate
+          end.max
+        end
+
+        def fan_parent_in_column?(component, names, axis)
+          axis.zero? && names.size > 1 && fan_parent(component)
+        end
+
+        def fan_parent(component)
+          fan_relations.keys.find { |name| component.include?(name) }
+        end
+
+        def centred(name, logical, sizes, layout, axis)
+          left, span = layout.fetch(logical.fetch(name)[axis])
+          left + ((span - sizes.fetch(name)[axis]) / 2)
+        end
+
+        def axis_extent(layout, origin)
+          layout.fetch(:cursor) - origin
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "scene"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The small box PlantUML draws at the class end of a link written with
+      # a bracketed qualifier, `A [key: string] *-- B`: a one-line box
+      # outside the class, centred on a steep link and beside a flat one,
+      # with the link starting at its far side.
+      module QualifierBox
+        extend self
+
+        # Ratios to the font size, measured on PlantUML 1.2026.6.
+        HEIGHT = 18.4883 / 14.0
+        BASELINE = 14.5352 / 14.0
+        INSET = 2.0
+        OVERLAP = 0.5
+        private_constant :HEIGHT, :BASELINE, :INSET, :OVERLAP
+
+        Placed = Data.define(:box, :clearance, :outward) do
+          # @return [Array<Float>] the point moved clear of the box
+          def clear(endpoint)
+            endpoint.zip(outward).map { |at, step| at + (step * clearance) }
+          end
+        end
+
+        # @param content [String] the qualifier's text
+        # @param endpoint [Array<Float>] where the link meets the class
+        # @param outward [Array<Float>] unit vector from the class along the
+        #   link
+        # @param text_width [Float] the text's width at `size`
+        # @param size [Float] the font size
+        # @return [Placed] the box and how far along the link it pushes the
+        #   link's start
+        def place(content, endpoint, outward, text_width, size)
+          axis = outward[1].abs >= outward[0].abs ? 1 : 0
+          frame = [text_width + (2 * INSET), size * HEIGHT]
+          left, top, reach = layout(axis, endpoint, outward[axis], *frame)
+          Placed.new(box: build(content, [left, top, *frame], size),
+                     clearance: reach / outward[axis].abs, outward: outward)
+        end
+
+        private
+
+        def layout(axis, endpoint, sign, width, height)
+          if axis == 1
+            across(endpoint, sign, width, height)
+          else
+            beside(endpoint, sign, width, height)
+          end
+        end
+
+        def across(endpoint, sign, width, height)
+          ex, ey = endpoint
+          top = sign.positive? ? ey - OVERLAP : ey - height + OVERLAP
+          [ex - (width / 2), top, height - OVERLAP]
+        end
+
+        def beside(endpoint, sign, width, height)
+          ex, ey = endpoint
+          left = sign.positive? ? ex - OVERLAP : ex - width + OVERLAP
+          [left, ey - (height / 2), width - OVERLAP]
+        end
+
+        def build(content, (left, top, width, height), size)
+          text = Scene::Text.new(content: content, x: left + INSET,
+                                 y: top + (size * BASELINE),
+                                 role: "qualifier", anchor: "start")
+          Scene::Box.new(id: "qualifier", x: left, y: top, width: width,
+                         height: height, texts: [text], separators: [],
+                         kind: "qualifier")
+        end
+      end
+    end
+  end
+end