elkrb 1.0.0 → 2.0.0

data/lib/elkrb/options/resolver.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "../errors"
+require_relative "decimal"
+require_relative "element_options"
+require_relative "option_map"
+require_relative "spellings"
+require_relative "unhonoured_report"
+
+module Elkrb
+  module Options
+    # Reads layout options in one order: element layoutOptions, element
+    # properties, call-level options, registry default. The caller names the
+    # elements to consult; nothing is inherited from a parent. Every spelling
+    # the registry knows reaches the same value, and an explicit false or 0 is
+    # a value, not a miss.
+    #
+    # @example
+    #   resolver = Elkrb::Options::Resolver.new(spacing_node_node: 40)
+    #   resolver.get("elk.spacing.nodeNode", node, graph) # => 40.0
+    class Resolver
+      NUMERIC_TYPES = %i[float integer].freeze
+      private_constant :NUMERIC_TYPES
+
+      # @param call_options [Hash] the options passed to the layout call, under
+      #   any key spelling; Symbol keys are read like String keys
+      def initialize(call_options = {})
+        @spellings = Spellings.new
+        @call = OptionMap.new(call_options, @spellings)
+      end
+
+      # @param key [String, Symbol] any registry id or alias, or a custom key
+      # @param elements [Array<#layout_options, #properties, nil>] consulted
+      #   in the order given
+      # @param default [Object] returned when nothing names the key;
+      #   :registry means the registry default, nil means nil
+      # @return [Object] the value, coerced to the registry type for a known
+      #   id and left as written for an unknown one
+      # @raise [Elkrb::ValidationError] when the value cannot be coerced to
+      #   the registered type, or is a non-finite number
+      def get(key, *elements, default: :registry)
+        id = @spellings.id(key)
+
+        elements.each do |element|
+          value = element_value(element, id)
+          return coerce(id, value) unless value.nil?
+        end
+
+        value = @call.value(id)
+        return coerce(id, value) unless value.nil?
+
+        default == :registry ? Registry.default(id) : default
+      end
+
+      # True when the call asked for strict option handling.
+      #
+      # @raise [Elkrb::ValidationError] when strict: is neither true nor
+      #   false, so a typo cannot silently turn strictness off
+      def strict?
+        case (strict = @call.value(@spellings.id("strict")))
+        when true then true
+        when false, nil then false
+        else
+          raise ValidationError,
+                "option strict must be true or false, got #{strict.inspect}"
+        end
+      end
+
+      # Reports every key in the graph's layoutOptions, at any level, that the
+      # registry does not know or does not fully honour, and every registered
+      # key in an element's properties or the call that it does not. A key
+      # only some algorithms read is reported only where the algorithm laying
+      # out its element does not read it. Unknown property names and call keys
+      # are not reported. Warns once per key; with strict: true it raises
+      # before anything is logged.
+      #
+      # @param graph [Elkrb::Graph::Graph]
+      # @param algorithm_name [#call] name as written => registered name or nil
+      # @raise [Elkrb::Error] in strict mode, naming each such key
+      def report_unhonoured(graph,
+                            algorithm_name: UnhonouredReport::AS_WRITTEN)
+        strict = strict?
+        report = UnhonouredReport.new(
+          graph, @spellings, @call,
+          root_algorithm: algorithm_name.call(get("elk.algorithm", graph)),
+          algorithm_name: algorithm_name
+        )
+        return if report.empty?
+
+        raise Error, report.strict_message if strict
+
+        report.log
+      end
+
+      private
+
+      def element_value(element, id)
+        ElementOptions.new(element, @spellings).value(id)
+      end
+
+      def coerce(id, value)
+        coerced = coerce_value(id, numeric_input(id, value))
+        unless finite?(coerced)
+          raise ValidationError,
+                "option #{id} must be a finite number, got #{value.inspect}"
+        end
+
+        coerced
+      end
+
+      # A string for a numeric option must be plain decimal, so "abc" and
+      # "0x10" raise instead of becoming 0.0. It is parsed here, once.
+      def numeric_input(id, value)
+        return value unless value.is_a?(String)
+        return value unless NUMERIC_TYPES.include?(Registry.all.dig(id, :type))
+
+        Decimal.parse(value) ||
+          raise(ValidationError,
+                "invalid value #{value.inspect} for option #{id}")
+      end
+
+      # The one delegate call the rescue covers. Registry.coerce raises
+      # NoMethodError/TypeError for a value of the wrong shape (an Array for
+      # a Float), ArgumentError for malformed padding, and RangeError
+      # (FloatDomainError, Complex) for a number that cannot be an Integer or
+      # Float; all are bad input here, and the caller needs the option's name.
+      def coerce_value(id, value)
+        Registry.coerce(id, value)
+      rescue ArgumentError, TypeError, NoMethodError, RangeError, EncodingError
+        raise ValidationError,
+              "invalid value #{value.inspect} for option #{id}"
+      end
+
+      # Infinity or NaN anywhere in a coerced number, padding or vector.
+      def finite?(coerced)
+        components(coerced).none? { |n| n.is_a?(Float) && !n.finite? }
+      end
+
+      def components(coerced)
+        case coerced
+        when Float then [coerced]
+        when Options::ElkPadding then coerced.to_h.values
+        when Options::KVector then coerced.to_a
+        when Options::KVectorChain then coerced.vectors.flat_map(&:to_a)
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/options/spellings.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Elkrb
+  module Options
+    # @api private
+    #
+    # Resolves an option key, as a Symbol or String, to its canonical id and
+    # ranks how canonical that spelling is. Registry.canonical scans every
+    # registered id for a suffix match, so each distinct name is resolved once.
+    class Spellings
+      ELK_LONG_PREFIX = "org.eclipse.elk."
+      ELK_SHORT_PREFIX = "elk."
+      private_constant :ELK_LONG_PREFIX, :ELK_SHORT_PREFIX
+
+      def initialize
+        @resolved = {}
+      end
+
+      # @param key [String, Symbol]
+      # @return [Array(String, Integer)] the canonical id (an unknown key
+      #   stays under its own name) and the spelling's rank, lowest best:
+      #   the id, then its org.eclipse.elk. form, then each alias in
+      #   registry order, then the shorter dot-suffixes of the id, the
+      #   longer first. No two spellings of one id share a rank.
+      def resolve(key)
+        name = key.to_s
+        @resolved[name] ||= begin
+          id = Registry.canonical(name) || name
+          [id, rank(name, id)]
+        end
+      end
+
+      def id(key)
+        resolve(key).first
+      end
+
+      private
+
+      def rank(name, id)
+        return 0 if name == id
+        return 1 if name == long_form(id)
+
+        2 + other_rank(name, id)
+      end
+
+      # An alias by its place in the registry, else a dot-suffix of the id
+      # after all the aliases, the longer suffix first.
+      def other_rank(name, id)
+        aliases = Array(Registry.all[id]&.fetch(:aliases, nil))
+        aliases.index(name) || (aliases.size + id.length - name.length)
+      end
+
+      def long_form(id)
+        return id unless id.start_with?(ELK_SHORT_PREFIX)
+
+        ELK_LONG_PREFIX + id.delete_prefix(ELK_SHORT_PREFIX)
+      end
+    end
+  end
+end

data/lib/elkrb/options/unhonoured_report.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "element_options"
+require_relative "option_map"
+require_relative "registry"
+require_relative "spellings"
+
+module Elkrb
+  module Options
+    # @api private
+    #
+    # The option keys in a graph's elements, at any level, that the registry
+    # does not know or does not fully honour, plus the call's own registered
+    # keys that are not fully honoured. An element's sources are those of
+    # ElementOptions. A key that is partial across algorithms (see
+    # Registry's readers) is judged against the algorithm that lays out the
+    # element carrying it, and a call key against every algorithm in play.
+    # Built and read by Resolver#report_unhonoured.
+    class UnhonouredReport
+      NESTED_COLLECTIONS = %i[children edges ports labels].freeze
+      CONTROL_CHARACTERS = /[[:cntrl:]]/
+      ALGORITHM_ID = "elk.algorithm"
+      # Takes an algorithm name as written; answers the name it is
+      # registered under, or nil when it is not registered.
+      AS_WRITTEN = :to_s.to_proc
+      private_constant :NESTED_COLLECTIONS, :CONTROL_CHARACTERS, :ALGORITHM_ID
+
+      # @param graph [Elkrb::Graph::Graph]
+      # @param spellings [Spellings]
+      # @param call [OptionMap] the options passed to the layout call
+      # @param root_algorithm [String, nil] the algorithm laying out the
+      #   graph, by registered name
+      # @param algorithm_name [#call] resolves a name written in the options
+      #   to a registered name; AS_WRITTEN takes every name as registered
+      def initialize(graph, spellings = Spellings.new,
+                     call = OptionMap.new({}, spellings),
+                     root_algorithm: nil, algorithm_name: AS_WRITTEN)
+        @spellings = spellings
+        @graph = graph
+        @root_algorithm = root_algorithm
+        @algorithm_name = algorithm_name
+        @findings = findings_for(graph, call)
+      end
+
+      def empty?
+        @findings.empty?
+      end
+
+      # @return [String] one message naming every finding
+      def strict_message
+        described = @findings.map do |id, status|
+          "#{printable(id)} " \
+            "(#{status ? "#{status}, not honoured" : 'unknown'})"
+        end
+        "strict mode: unknown or unhonoured layout option(s): " \
+          "#{described.join(', ')}"
+      end
+
+      # Partly honoured and accepted keys warn; unknown keys log at DEBUG
+      # because elkjs ignores them too.
+      def log
+        @findings.each do |id, status|
+          if status.nil?
+            Elkrb.logger.debug(
+              "elkrb: unknown option #{printable(id)}: stored and echoed",
+            )
+          else
+            Elkrb.logger.warn(warning_for(id, status))
+          end
+        end
+      end
+
+      private
+
+      # { canonical id => status }; status is nil for an unknown key. An
+      # unknown key in the call is not reported: the call also carries engine
+      # flags such as strict. The call's nested properties
+      # map is never read as options, so it is not reported either.
+      def findings_for(graph, call)
+        occurrences(laid_out_elements(graph), call)
+          .each_with_object({}) do |(id, algorithms), findings|
+          status = Registry.status(id)
+          findings[id] = status if unread?(id, status, algorithms)
+        end
+      end
+
+      # [[canonical id, algorithm/carrier routes that would read it]], one per
+      # place a key is written. A call key reaches every level, so any
+      # algorithm in play may read it.
+      def occurrences(levels, call)
+        in_play = levels.filter_map { |_, algorithm, _| algorithm }.uniq
+        written = written_occurrences(levels)
+        called = call.own_ids.select { |id| Registry.status(id) }
+        call_routes = in_play.map { |algorithm| [algorithm, :call] }
+        (written + called.map { |id| [id, call_routes] }).uniq
+      end
+
+      def written_occurrences(levels)
+        levels.flat_map do |options, _, routes|
+          options.ids.map { |id| [id, routes] }
+        end
+      end
+
+      def unread?(id, status, routes)
+        status != :honoured &&
+          routes.none? do |algorithm, carrier|
+            Registry.read_by?(id, algorithm, carrier: carrier)
+          end
+      end
+
+      # [[ElementOptions, algorithm, carrier]] for every element reachable
+      # from the graph, breadth first. Leaf elements inherit the algorithm of
+      # their enclosing layout level. Iterative, so a deeply nested graph
+      # cannot overflow the stack here; an element reachable by two paths is
+      # visited once for each algorithm that would lay out the level above it.
+      def laid_out_elements(graph)
+        visits = [[graph, @root_algorithm]]
+        seen = {}
+        visits.filter_map do |element, enclosing| # visits grows as it is walked
+          next if seen.key?(key = [element.object_id, enclosing])
+
+          seen[key] = true
+          level_of(element, enclosing).tap do |level|
+            nested_elements(element).each { |c| visits << [c, level[1]] }
+          end
+        end
+      end
+
+      def level_of(element, enclosing)
+        options = ElementOptions.new(element, @spellings)
+        algorithm = layout_algorithm(element, options, enclosing)
+        [options, algorithm, routes_for(element, algorithm, enclosing)]
+      end
+
+      # The algorithm a compound node is laid out by is its own registered
+      # elk.algorithm, else the one laying out the level it sits in, the way
+      # HierarchicalProcessor picks it.
+      def layout_algorithm(element, options, enclosing)
+        return enclosing if element.equal?(@graph)
+        return enclosing unless compound?(element)
+
+        own = options.value(ALGORITHM_ID)
+        (own && @algorithm_name.call(own)) || enclosing
+      end
+
+      def compound?(element)
+        element.respond_to?(:children) && !Array(element.children).empty?
+      end
+
+      # A compound is both the graph laid out by its own algorithm and a node
+      # routed by the enclosing algorithm. Its options can therefore be read
+      # in either role.
+      def routes_for(element, algorithm, enclosing)
+        if compound?(element) && !element.equal?(@graph)
+          [[algorithm, :compound], [enclosing, :node]].uniq
+        else
+          [[algorithm, carrier(element)]]
+        end
+      end
+
+      def carrier(element)
+        return :root if element.equal?(@graph)
+        return :compound if compound?(element)
+        return :edge if element.respond_to?(:sources)
+        return :port if element.respond_to?(:side)
+        return :label if element.respond_to?(:text)
+
+        :node
+      end
+
+      def nested_elements(element)
+        NESTED_COLLECTIONS.flat_map do |collection|
+          next [] unless element.respond_to?(collection)
+
+          Array(element.public_send(collection))
+        end
+      end
+
+      # An unknown key comes from the input file; keep control characters
+      # and invalid bytes out of the log and the error message.
+      def printable(id)
+        id.to_s.scrub.gsub(CONTROL_CHARACTERS) { |char| char.dump[1..-2] }
+      end
+
+      def warning_for(id, status)
+        if status == :partial
+          "elkrb: option #{id} is partially honoured: #{Registry.note(id)}"
+        else
+          "elkrb: option #{id} is accepted but not honoured in this version"
+        end
+      end
+    end
+  end
+end