etassia 0.1.0

data/lib/etassia/notation/plantuml/style/colour_names.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # The CSS colour names PlantUML accepts, with the hex value its
+        # 1.2026.6 SVG output writes for each (measured against the JAR).
+        module ColourNames
+          TABLE = {
+            "aliceblue" => "#F0F8FF", "antiquewhite" => "#FAEBD7",
+            "aqua" => "#00FFFF", "aquamarine" => "#7FFFD4",
+            "azure" => "#F0FFFF", "beige" => "#F5F5DC",
+            "bisque" => "#FFE4C4", "black" => "#000000",
+            "blanchedalmond" => "#FFEBCD", "blue" => "#0000FF",
+            "blueviolet" => "#8A2BE2", "brown" => "#A52A2A",
+            "burlywood" => "#DEB887", "cadetblue" => "#5F9EA0",
+            "chartreuse" => "#7FFF00", "chocolate" => "#D2691E",
+            "coral" => "#FF7F50", "cornflowerblue" => "#6495ED",
+            "cornsilk" => "#FFF8DC", "crimson" => "#DC143C",
+            "cyan" => "#00FFFF", "darkblue" => "#00008B",
+            "darkcyan" => "#008B8B", "darkgoldenrod" => "#B8860B",
+            "darkgray" => "#A9A9A9", "darkgreen" => "#006400",
+            "darkgrey" => "#A9A9A9", "darkkhaki" => "#BDB76B",
+            "darkmagenta" => "#8B008B", "darkolivegreen" => "#556B2F",
+            "darkorange" => "#FF8C00", "darkorchid" => "#9932CC",
+            "darkred" => "#8B0000", "darksalmon" => "#E9967A",
+            "darkseagreen" => "#8FBC8F", "darkslateblue" => "#483D8B",
+            "darkslategray" => "#2F4F4F", "darkslategrey" => "#2F4F4F",
+            "darkturquoise" => "#00CED1", "darkviolet" => "#9400D3",
+            "deeppink" => "#FF1493", "deepskyblue" => "#00BFFF",
+            "dimgray" => "#696969", "dimgrey" => "#696969",
+            "dodgerblue" => "#1E90FF", "firebrick" => "#B22222",
+            "floralwhite" => "#FFFAF0", "forestgreen" => "#228B22",
+            "fuchsia" => "#FF00FF", "gainsboro" => "#DCDCDC",
+            "ghostwhite" => "#F8F8FF", "gold" => "#FFD700",
+            "goldenrod" => "#DAA520", "gray" => "#808080",
+            "green" => "#008000", "greenyellow" => "#ADFF2F",
+            "grey" => "#808080", "honeydew" => "#F0FFF0",
+            "hotpink" => "#FF69B4", "indianred" => "#CD5C5C",
+            "indigo" => "#4B0082", "ivory" => "#FFFFF0",
+            "khaki" => "#F0E68C", "lavender" => "#E6E6FA",
+            "lavenderblush" => "#FFF0F5", "lawngreen" => "#7CFC00",
+            "lemonchiffon" => "#FFFACD", "lightblue" => "#ADD8E6",
+            "lightcoral" => "#F08080", "lightcyan" => "#E0FFFF",
+            "lightgoldenrodyellow" => "#FAFAD2", "lightgray" => "#D3D3D3",
+            "lightgreen" => "#90EE90", "lightgrey" => "#D3D3D3",
+            "lightpink" => "#FFB6C1", "lightsalmon" => "#FFA07A",
+            "lightseagreen" => "#20B2AA", "lightskyblue" => "#87CEFA",
+            "lightslategray" => "#778899", "lightslategrey" => "#778899",
+            "lightsteelblue" => "#B0C4DE", "lightyellow" => "#FFFFE0",
+            "lime" => "#00FF00", "limegreen" => "#32CD32",
+            "linen" => "#FAF0E6", "magenta" => "#FF00FF",
+            "maroon" => "#800000", "mediumaquamarine" => "#66CDAA",
+            "mediumblue" => "#0000CD", "mediumorchid" => "#BA55D3",
+            "mediumpurple" => "#9370D8", "mediumseagreen" => "#3CB371",
+            "mediumslateblue" => "#7B68EE", "mediumspringgreen" => "#00FA9A",
+            "mediumturquoise" => "#48D1CC", "mediumvioletred" => "#C71585",
+            "midnightblue" => "#191970", "mintcream" => "#F5FFFA",
+            "mistyrose" => "#FFE4E1", "moccasin" => "#FFE4B5",
+            "navajowhite" => "#FFDEAD", "navy" => "#000080",
+            "oldlace" => "#FDF5E6", "olive" => "#808000",
+            "olivedrab" => "#6B8E23", "orange" => "#FFA500",
+            "orangered" => "#FF4500", "orchid" => "#DA70D6",
+            "palegoldenrod" => "#EEE8AA", "palegreen" => "#98FB98",
+            "paleturquoise" => "#AFEEEE", "palevioletred" => "#D87093",
+            "papayawhip" => "#FFEFD5", "peachpuff" => "#FFDAB9",
+            "peru" => "#CD853F", "pink" => "#FFC0CB", "plum" => "#DDA0DD",
+            "powderblue" => "#B0E0E6", "purple" => "#800080",
+            "red" => "#FF0000", "rosybrown" => "#BC8F8F",
+            "royalblue" => "#4169E1", "saddlebrown" => "#8B4513",
+            "salmon" => "#FA8072", "sandybrown" => "#F4A460",
+            "seagreen" => "#2E8B57", "seashell" => "#FFF5EE",
+            "sienna" => "#A0522D", "silver" => "#C0C0C0",
+            "skyblue" => "#87CEEB", "slateblue" => "#6A5ACD",
+            "slategray" => "#708090", "slategrey" => "#708090",
+            "snow" => "#FFFAFA", "springgreen" => "#00FF7F",
+            "steelblue" => "#4682B4", "tan" => "#D2B48C",
+            "teal" => "#008080", "thistle" => "#D8BFD8",
+            "tomato" => "#FF6347", "turquoise" => "#40E0D0",
+            "violet" => "#EE82EE", "wheat" => "#F5DEB3",
+            "white" => "#FFFFFF", "whitesmoke" => "#F5F5F5",
+            "yellow" => "#FFFF00", "yellowgreen" => "#9ACD32"
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style/defaults.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # The look PlantUML 1.2026.6 gives an unstyled diagram, measured from
+        # its SVG: the layer every skinparam, `<style>` and element colour
+        # is laid over.
+        module Defaults
+          BOX = { background: "#F1F1F1", border: "#181818",
+                  font_colour: "#000000", line_thickness: 0.5,
+                  round_corner: 12.5 }.freeze
+
+          RULES = {
+            any: { font_name: "sans-serif", font_size: 14,
+                   font_colour: "#000000", background: "#F1F1F1",
+                   border: "#181818", line_thickness: 0.5 },
+            document: { background: "#FFFFFF" },
+            state: BOX,
+            class: BOX.merge(round_corner: 2.5),
+            activity: BOX.merge(font_size: 12),
+            note: { background: "#FEFFDD", border: "#181818",
+                    line_thickness: 0.5 },
+            arrow: { border: "#181818", font_colour: "#000000",
+                     line_thickness: 1 },
+            start: { background: "#222222", border: "#222222" },
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style/inline.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "colour"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # Reads the colour a declaration carries on its own line:
+        # `#pink`, `#pink;line:blue;line.dashed;text:green`, `##blue`,
+        # `##[dashed]blue`, `#pink|white` (a gradient reads as its first
+        # colour).
+        module Inline
+          extend self
+
+          LINE_STYLES = { "dashed" => "7,7", "dotted" => "1,3",
+                          "bold" => nil, "plain" => nil }.freeze
+          LINE_ONLY = /\A##(?:\[(\w+)\])?(\S+)\z/
+          private_constant :LINE_STYLES, :LINE_ONLY
+
+          # @param text [String] the colour as written, `#` included
+          # @return [Hash] any of :background, :border, :line_style,
+          #   :font_colour; empty when the text names no colour
+          def parse(text)
+            if (match = LINE_ONLY.match(text))
+              return line_only(match)
+            end
+
+            first, *parts = text.split(";")
+            properties = { background: Colour.resolve(first) }.compact
+            parts.each { |part| property(part, properties) }
+            properties
+          end
+
+          private
+
+          def line_only(match)
+            { border: Colour.resolve(match[2]),
+              line_style: LINE_STYLES[match[1]] }.compact
+          end
+
+          def property(part, properties)
+            key, value = part.split(":", 2)
+            case key.downcase
+            when "line" then properties[:border] = Colour.resolve(value)
+            when "text" then properties[:font_colour] = Colour.resolve(value)
+            when "line.dashed", "line.dotted"
+              properties[:line_style] = LINE_STYLES[key.split(".").last]
+            end
+            properties.compact!
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "colour"
+require_relative "inline"
+require_relative "sheet"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # Reads the `skinparam` lines and `<style>` blocks of a source into a
+        # {Sheet}. A name or property it does not know is left out, never an
+        # error: the family reader still decides what it refuses.
+        class Reader
+          PROPERTIES = {
+            "backgroundcolor" => :background, "bordercolor" => :border,
+            "linecolor" => :border, "fontcolor" => :font_colour,
+            "fontname" => :font_name, "fontsize" => :font_size,
+            "linestyle" => :line_style, "roundcorner" => :round_corner,
+            "linethickness" => :line_thickness,
+            "borderthickness" => :line_thickness,
+            "thickness" => :line_thickness, "color" => :border
+          }.freeze
+          DEFAULTS = {
+            "defaultfontname" => :font_name, "defaultfontsize" => :font_size,
+            "defaultfontcolor" => :font_colour
+          }.freeze
+          SUFFIXES = PROPERTIES.keys.sort_by { |name| -name.size }.freeze
+          # A selector that names the whole diagram styles its own element.
+          WRAPPERS = { "document" => :document, "root" => :document,
+                       "element" => :any, "classdiagram" => :class,
+                       "statediagram" => :state,
+                       "activitydiagram" => :activity }.freeze
+          SKINPARAM = /\Askinparam[ \t]+(\S+?)(?:[ \t]*(\{)|[ \t]+(.+))?\z/i
+          SINGLE = /\A(\w+)(?:<<(\w+)>>)?\z/
+          STYLE_OPEN = %r{\A<style>\z}i
+          STYLE_CLOSE = %r{\A</style>\z}i
+          OPENING = /\A([\w.]+(?:[ \t]*,[ \t]*[\w.]+)*)[ \t]*\{\z/
+          PROPERTY = /\A(\w+)(?:<<(\w+)>>)?[ \t:]+(.+?)[ \t;]*\z/
+          INLINE = /\A([\w.]+)[ \t]*\{[ \t]*(\w+)[ \t:]+(.+?)[ \t;]*\}\z/
+          LINE_STYLES = { "dotted" => "1,3", "dashed" => "7,7",
+                          "bold" => nil }.freeze
+          DECLARATION = /\A(?:abstract[ \t]+class|static[ \t]+class|abstract|
+                          class|interface|enum|annotation|state)[ \t]+
+                         (?:"[^"]+"[ \t]+as[ \t]+)?([A-Za-z_][\w.]*)
+                         (?:<[^<>]+>)?(?:[ \t]*<<([^<>]+)>>)*
+                         (?:[ \t]*(\#\S+))?/xi
+          private_constant :DECLARATION, :PROPERTIES, :DEFAULTS, :SUFFIXES,
+                           :WRAPPERS,
+                           :SKINPARAM, :SINGLE, :STYLE_OPEN, :STYLE_CLOSE,
+                           :OPENING, :PROPERTY, :INLINE, :LINE_STYLES
+
+          # @param source [String] PlantUML source
+          # @return [Sheet]
+          def self.read(source)
+            new.read(source)
+          end
+
+          # @param texts [Array<String>] stripped source lines, in order
+          # @return [Array<Boolean>] for each line, whether it belongs to a
+          #   `skinparam` or `<style>` rule, which this reader owns
+          def self.styling?(texts)
+            closing = nil
+            texts.map do |text|
+              if closing
+                closing = nil if closing.match?(text)
+                next true
+              end
+
+              closing = closer(text)
+              !closing.nil? || SKINPARAM.match?(text)
+            end
+          end
+
+          # @return [Regexp, nil] what ends the block this line opens
+          def self.closer(text)
+            return STYLE_CLOSE if STYLE_OPEN.match?(text)
+
+            /\A\}\z/ if SKINPARAM.match(text)&.[](2)
+          end
+          private_class_method :closer
+
+          def initialize
+            @skin = {}
+            @style = {}
+            @block = nil
+            @path = nil
+            @elements = {}
+          end
+
+          # @return [Sheet]
+          def read(source)
+            lines(source).each { |text| feed(text) }
+            Sheet.new(skin: @skin, style: @style, elements: @elements)
+          end
+
+          private
+
+          def lines(source)
+            text = source.dup.force_encoding(Encoding::UTF_8).scrub
+            text.lines.map(&:strip).reject do |l|
+              l.empty? || l.start_with?("'")
+            end
+          end
+
+          def feed(text)
+            return style_line(text) if @path
+            return skin_block_line(text) if @block
+            return @path = [] if STYLE_OPEN.match?(text)
+
+            statement(text)
+          end
+
+          def statement(text)
+            if (match = SKINPARAM.match(text))
+              skinparam(match)
+            elsif (match = DECLARATION.match(text))
+              declaration(match)
+            end
+          end
+
+          def declaration(match)
+            written = Inline.parse(match[3].to_s)
+            written[:stereotype] = match[2].downcase if match[2]
+            @elements[match[1]] = written unless written.empty?
+          end
+
+          def skinparam(match)
+            return @block = block_target(match[1]) if match[2]
+            return unless match[3]
+
+            name, stereotype = SINGLE.match(match[1])&.captures
+            return unless name
+
+            store(@skin, *split(name.downcase), stereotype, match[3])
+          end
+
+          def block_target(written)
+            name, stereotype = SINGLE.match(written)&.captures
+            [name&.downcase, stereotype]
+          end
+
+          def skin_block_line(text)
+            return @block = nil if text == "}"
+
+            match = PROPERTY.match(text)
+            return unless match
+
+            block_property(*@block, match)
+          end
+
+          def block_property(element, stereotype, match)
+            property = match[1].downcase
+            if property.start_with?("arrow")
+              element = "arrow"
+              property = property.delete_prefix("arrow")
+            end
+            store(@skin, element&.to_sym, property, match[2] || stereotype,
+                  match[3])
+          end
+
+          def split(name)
+            return [:any, DEFAULTS[name]] if DEFAULTS.key?(name)
+
+            suffix = SUFFIXES.find { |word| name.end_with?(word) }
+            return [nil, nil] unless suffix
+
+            element = name.delete_suffix(suffix)
+            [element.empty? ? :any : element.to_sym, suffix]
+          end
+
+          def style_line(text)
+            return @path = nil if STYLE_CLOSE.match?(text)
+
+            if (match = INLINE.match(text))
+              inline_property(match)
+            elsif (match = OPENING.match(text))
+              @path.push(match[1].downcase)
+            elsif text == "}"
+              @path.pop
+            elsif (match = PROPERTY.match(text))
+              style_property(match[1].downcase, match[3])
+            end
+          end
+
+          def inline_property(match)
+            @path.push(match[1].downcase)
+            style_property(match[2].downcase, match[3])
+            @path.pop
+          end
+
+          def style_property(property, value)
+            selector = @path.last
+            # PlantUML's <style> has no BorderColor; only skinparam does.
+            return if selector.nil? || property == "bordercolor"
+
+            element, stereotype = target_of(selector)
+            store(@style, element&.to_sym, property, stereotype, value)
+          end
+
+          def target_of(selector)
+            return [WRAPPERS.fetch(selector, selector), nil] unless
+              selector.start_with?(".")
+
+            [nil, selector.delete_prefix(".")]
+          end
+
+          def store(rules, element, property, stereotype, value)
+            name = PROPERTIES.fetch(property, property)
+            return unless name.is_a?(Symbol) && (element || stereotype)
+
+            parsed = parse(name, value)
+            return if parsed.nil?
+
+            key = Style.selector(canvas(element, name), stereotype)
+            (rules[key] ||= {})[name] = parsed
+          end
+
+          # A bare `BackgroundColor` is the canvas, not every element.
+          def canvas(element, name)
+            element == :any && name == :background ? :document : element
+          end
+
+          def parse(name, value)
+            case name
+            when :background, :border, :font_colour then Colour.resolve(value)
+            when :font_size, :round_corner, :line_thickness then number(value)
+            when :font_name then value.delete('"')
+            when :line_style then LINE_STYLES[value.downcase]
+            end
+          end
+
+          def number(value)
+            Float(value)
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style/sheet.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "defaults"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # What a diagram's source says about its look, in the order PlantUML
+        # applies it: the defaults, then `skinparam`, then `<style>`, then
+        # the colours written on one element. A later layer wins; inside a
+        # layer the element's own rule wins over the global one, and a
+        # stereotype rule over both.
+        class Sheet
+          LAYERS = %i[skin style].freeze
+          private_constant :LAYERS
+
+          # @param skin [Hash{String => Hash}] skinparam rules by selector
+          # @param style [Hash{String => Hash}] `<style>` rules by selector
+          # @param elements [Hash{String => Hash}] properties by element id
+          def initialize(skin: {}, style: {}, elements: {})
+            @layers = { skin: skin, style: style }
+            @elements = elements
+            freeze
+          end
+
+          # @param id [String] an element id, as the family reader names it
+          # @param properties [Hash] the properties written on that element
+          # @return [Sheet] this sheet with the element's properties added
+          def with_element(id, properties)
+            merged = @elements.merge(id => properties) do |_, old, new|
+              old.merge(new)
+            end
+            self.class.new(skin: @layers[:skin], style: @layers[:style],
+                           elements: merged)
+          end
+
+          # @param element [Symbol] :state, :class, :activity, :note, :arrow
+          # @param property [Symbol] :background, :border, :font_colour,
+          #   :font_name, :font_size, :line_style, :round_corner,
+          #   :line_thickness
+          # @param id [String, nil] the element's id, for its own colours
+          # @param stereotype [String, nil] the element's stereotype
+          # @return [Object, nil] the winning value, nil when none is set
+          def resolve(element, property, id: nil, stereotype: nil)
+            explicit(element, property, id: id, stereotype: stereotype) ||
+              from_defaults(element, property).compact.last
+          end
+
+          # Like {#resolve}, but nil when the source itself sets nothing, for
+          # a renderer whose own default look is not PlantUML's.
+          def explicit(element, property, id: nil, stereotype: nil)
+            candidates(element, property, id, stereotype).compact.last
+          end
+
+          # The value a `<style>` rule sets for the element itself, ignoring
+          # skinparam and the defaults, for what PlantUML cascades from the
+          # `<style>` root only.
+          def from_style(element, property)
+            from_rules(@layers[:style], element, property, nil).compact.last
+          end
+
+          # @param id [String] an element id
+          # @return [Hash] the properties written on that element
+          def element(id)
+            @elements.fetch(id, {})
+          end
+
+          # @return [Boolean] whether any layer above the defaults is set
+          def styled?
+            @layers.values.any? { |rules| !rules.empty? } ||
+              !@elements.empty?
+          end
+
+          private
+
+          def candidates(element, property, id, stereotype)
+            LAYERS.flat_map do |layer|
+              from_rules(@layers[layer], element, property, stereotype)
+            end + [@elements.dig(id, property)]
+          end
+
+          def from_defaults(element, property)
+            rules = Defaults::RULES
+            [rules.dig(:any, property), rules.dig(element, property)]
+          end
+
+          def from_rules(rules, element, property, stereotype)
+            selectors(element, stereotype).map do |selector|
+              rules.dig(selector, property)
+            end
+          end
+
+          def selectors(element, stereotype)
+            [Style.selector(:any), Style.selector(element),
+             (Style.selector(element, stereotype) if stereotype),
+             (Style.selector(nil, stereotype) if stereotype)].compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "style/colour"
+require_relative "style/inline"
+require_relative "style/sheet"
+require_relative "style/reader"
+require_relative "style/bound"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # One reading of how a PlantUML diagram is styled, shared by every
+      # family: {Reader} turns the source's `skinparam` lines and `<style>`
+      # blocks into a {Sheet}, and a renderer asks the sheet for the value
+      # of a property instead of keeping its own palette.
+      module Style
+        extend self
+
+        # @param element [Symbol, nil] the element kind, nil for a bare
+        #   stereotype
+        # @param stereotype [String, nil] the stereotype, without `<<>>`
+        # @return [String] the key a rule is stored under
+        def selector(element, stereotype = nil)
+          return element.to_s unless stereotype
+
+          name = stereotype.downcase
+          element ? "#{element}<<#{name}>>" : ".#{name}"
+        end
+      end
+    end
+  end
+end