configuratrix 0.0.1.alpha

data/lib/configuratrix/sources/util.rb

@@ -0,0 +1,303 @@
+module Configuratrix
+module Internal
+
+# Wrapper for an enumeration that exchanges raising StopIteration when no
+# values remain to returning a list that is empty if the stream was exhausted,
+# or a list containing only the resulting value from the stream.
+class Stream
+  def initialize(enumeration)
+    @enumeration = enumeration
+  end
+
+  def take; get_via(:next); end
+
+  def peek; get_via(:peek); end
+
+  def raw; @enumeration; end
+
+  private
+
+  def get_via(message)
+    [@enumeration.public_send(message)]
+  rescue StopIteration
+    []
+  end
+end
+
+# Keep track of the pending partial values for a collection of fields, and
+# handle the addition of subsequent values according to the relevant field's
+# schema.
+class MultiValueMinder
+  attr_accessor :value_map
+
+  def initialize(value_map = {})
+    # A read-only view into the current values of fields.  Used when computing
+    # a new combination with a new given value.
+    @value_map = value_map
+    # The number of values a named field has been observed receiving.
+    @value_counts = Hash.new 0
+    # The observed arities of the fields that pass through.  Powers
+    # #incompletes.
+    @arities = Hash.new
+  end
+
+  def satisfied?(field)
+    field.arity.satisfied_by? @value_counts[field.attribute_name]
+  end
+
+  def saturated_after_next?(field)
+    field.arity.saturated_by? (@value_counts[field.attribute_name] + 1)
+  end
+
+  def incompletes
+    @value_counts.filter_map do |name,count|
+      name unless @arities[name].satisfied_by? count
+    end
+  end
+
+  # Add value to the total value of field, returning the new combined value.
+  # If the arity is not plural, the value will be returned without
+  # modification.
+  def append(value, field, human_context: nil)
+    name = field.attribute_name
+    arity = field.arity
+    @arities[name] = arity
+
+    unless arity.unspecified?
+      # An explicit arity must have room left for values.
+      if arity.saturated_by? @value_counts[name]
+        raise Err::DanglingValue, <<~END
+          '#{human_context}' : #{field} cannot accept more than
+          #{@value_counts[name]} value(s)
+        END
+      end
+      @value_counts[name] += 1
+      # Explicit arities other than 1 require plurality handling.
+      if arity.demands_plurality?
+        plurality = field.value_type.plurality
+        value = plurality.wrap_atom.(value)
+        if @value_map.include? name
+          value = plurality.combine.(@value_map[name], value)
+        end
+      end
+    end
+
+    @value_map[field.attribute_name] = value
+  end
+end
+
+# Functionality common to all sources for discovering individual schema class'
+# preferences about their representation within the source.  Do not include
+# this module in classes directly; use only subclasses of ToggleStruct[].
+# See also Sources::CommandLine::FieldToggles.
+module ToggleStruct
+  # Create a customized struct with the named entries and functionality
+  # relevant to all toggle register classes.
+  def self.[](*entry_names)
+    Struct.new(*entry_names) do
+      def self.inherited(subclass)
+        subclass.const_set :Struct, self
+      end
+      include ToggleStruct
+      extend  ToggleStruct::ClassMethods
+      # This is the back door to writing values without validation, since
+      # validation is done by overriding specific member= methods.
+      private :[]=
+    end
+  end
+  module ClassMethods
+    # Get a proc to extract the value of the named toggle from any schema
+    # objects passed to the proc.  The schema object must respond to
+    # :toggles(class) with a the approriate ToggleStruct for the given class.
+    def getter_of(name)
+      unless members.include? name
+        raise "BUG: #{name} is not a member of #{self}"
+      end
+      # Now we return the getter that will ask any schema object for its
+      # toggles relevant to our domain, so we can get the `name`d object out of
+      # those toggles.  a.k.a. the getter of name
+      -> schema {
+        unless schema.respond_to? :toggles
+          raise "BUG: #{schema} does not support config toggles"
+        end
+        register = schema.toggles(domain) || self.new
+        unless self === register
+          raise "BUG: #{self} asked to operate on #{register.class}"
+        end
+        register.public_send name
+      }
+    end
+
+    # self is named SomeSuchClass::SomeSuchToggles; get me SomeSuchClass!
+    def domain
+      (self
+        .name
+        .split('::')[0..-2]
+        .reduce(Object) { |mod,class_name| mod.const_get(class_name) }
+      )
+    end
+  end
+
+  # It only makes sense to use mutation wrappers under an entry= method.
+  ENTRY_MUTATOR = /^([a-zA-Z0-9_-]+)=$/
+
+  # Unless `matches === value`, raise NoCanToggle.  Otherwise, return value.
+  def reject_unless(value, matches:)
+    asker = caller.first[/`(.*)'/,1]
+    unless ENTRY_MUTATOR =~ asker
+      raise "BUG: reject_unless must be called from a struct member= method"
+    end
+    key = asker[ENTRY_MUTATOR,1].to_sym
+
+    if matches === value
+      value
+    else
+      self[key] = nil
+      raise Err::NoCanToggle, <<~END
+        #{self.class}: can't set :#{key} to #{value.inspect}
+      END
+    end
+  end
+
+  # Common toggle validators: "matches A something"
+  module A
+    BOOL = -> { false == _1 or true == _1 }
+    SYMBOL = -> { _1 .is_a? Symbol }
+    STRING = -> { _1 .is_a? String }
+  end
+end
+
+# Bring together the knowledge required to find out what, if anything, all the
+# fields in a config schema have a toggle set to.
+class ToggleSurvey
+  def initialize(config_schema, register_class)
+    @config_schema = config_schema
+    @register_class = register_class
+    @toggles_prefix =
+      @register_class .name .split("::") .last .delete_suffix "Toggles"
+    configure_for @toggles_prefix
+    @canvas_orders = []
+  end
+
+  def canvas_for(name)
+    pending_result = PendingResult.new
+    @canvas_orders << CanvasOrder.new(
+      name, @register_class.getter_of(name), pending_result)
+    pending_result
+  end
+
+  def fetch_results
+    # fold each object's toggle values into the prehash (list of k,v pairs) for
+    # the relevant order.
+    @population_schema.reduce(@canvas_orders) { |orders,schema_object|
+      orders.each { |order|
+        value = order.getter.call(schema_object)
+        order.prehash << [ schema_object.attribute_name, value ] if value
+        order
+      }
+    } .each { |filled_order|
+      # Take the newly constructed prehashes and return results to clients.
+      results = Results.new(filled_order.prehash, filled_order.topic,
+                            @population_label, @config_schema)
+      filled_order .pending_result .resolve_pending_result results
+    }
+    @canvas_orders = []
+  end
+
+  private
+
+  def configure_for(population_type)
+    case @toggles_prefix
+    in "Field"
+      @population_label = "fields"
+      @population_schema = @config_schema.fields_schema
+    end
+  end
+
+  CanvasOrder = Struct.new(:topic, :getter, :pending_result, :prehash) do
+    def initialize(topic, getter, pending_result, prehash=[]); super; end
+  end
+
+  class Results
+    def initialize(prehash, toggle_surveyed, population, config_schema)
+      @prehash = prehash
+      @toggle_surveyed = toggle_surveyed
+      @population = population
+      @config_schema = config_schema
+    end
+
+    def names; @prehash.filter_map { |k,v| k if v }; end
+    def name
+      names = self.names
+      return names if names.size <= 1
+      raise Err::NameCollision, <<~END
+        #{@toggle_surveyed} must select a single member of #{@population}
+        of #{@config_schema}, but it selects #{names}
+      END
+    end
+
+    def names_to_values; @prehash.to_h; end
+
+    def names_holding(t); @prehash.filter_map { |k,v| k if t == v }; end
+
+    # For every value a toggle takes in a population, a list of the members
+    # that hold that value.
+    def value_clusters; invert(false); end
+    # See #value_clusters, plus the assertion that every value is associated
+    # with exactly one key.
+    def values_to_owners; invert(true); end
+
+    def invert(strict)
+      (@prehash
+        # Hash#group_by groups all the [k,v] pairs with a common result.
+        .group_by { |name,value| value }
+        # We have `v => [ [k,v], [k,v], ...]`, but we need `v => [k, k, ...]`.
+        .transform_values { _1.map { |name,value| name } }
+        # Now we have a hash from values to all the names that have that value
+        # for @toggle_surveyed
+        .map { |value,common_names|
+          case common_names
+          in [ name ]
+            # If we're not being strict, we need list values in all cases.
+            name = [ name ] if not strict
+            # If only one key points to a certain value, then that value can
+            # safely be a key for just that former key.
+            [value, name]
+          in [ *names ]
+            if strict
+              raise Err::NameCollision, <<~END
+                #{@toggle_surveyed} must be unique among #{@population}
+                of #{@config_schema}, but #{names} share #{value}
+              END
+            end
+            [value, names]
+          end
+        }
+        .to_h
+      )
+    end
+  end
+end
+
+class PendingResult
+  def initialize; @queue = []; end
+
+  def method_missing(name, *args, &block)
+    child = self.class.new
+    @queue << [ name, args, block, child ]
+    child
+  end
+
+  def resolve_pending_result(resolution)
+    @resolved = resolution
+    @queue.each do |name,args,block,child|
+      child.resolve_pending_result resolution.send(name,*args,&block)
+    end
+  end
+
+  # unary tilde unwraps the resolved value
+  def ~; @resolved; end
+end
+
+end
+end