configuratrix 0.0.1.alpha

data/lib/configuratrix/schema-util.rb

@@ -0,0 +1,314 @@
+require 'delegate'
+
+module Configuratrix
+module Internal
+
+
+# Module to prepend to the singleton class of an uninitialized config object to
+# make it fail in a more descriptive way.  Useful for the default of a
+# non-required subconfig (via Config#new_unloaded).
+module UnloadedConfig
+  def [](field_name)
+    if self.class.fields_schema.find { _1.attribute_name == field_name }
+      raise Err::NoSuchValue, <<~END
+        #{self.class} is unloaded; cannot access #{field_name}
+      END
+    end
+    super
+  end
+end
+
+
+# Module to prepend to the singleton class of an uninitialized config object to
+# make it provide only default values for fields.  Useful for the default of a
+# non-required subconfig (via Config#new_defaulty).
+module DefaultyConfig
+  def [](field_name)
+    schema_init unless instance_variable_defined? :@field_map
+    unless @field_map.include? field_name
+      field_schema = (
+        self.class.fields_schema.find { _1.attribute_name == field_name })
+      unless field_schema.nil?
+        @field_map[field_name] = field_schema.new
+      end
+    end
+    super
+  end
+end
+
+  
+module SourceUtil
+  # Load each given source within a config schema, handling interdependencies.
+  def self.parse_all(sources, within:)
+    config_schema = within
+    todo = sources.dup
+    complete_sources = []
+
+    loop do
+      ready_sources, unready_sources = (
+        todo.partition { _1.ready? complete_sources } )
+      ready_sources.each do |source|
+        source.cross_configure complete_sources
+        source.parse config_schema
+        complete_sources << source
+      end
+
+      if unready_sources == todo
+        # Progress has stopped.  If we have any complete sources, that'll do.
+        break unless complete_sources.empty?
+        raise Err::PathologicalSchema, <<~END
+          sources did not become ready: #{unready_sources.map &:name}
+        END
+      end
+      todo = unready_sources
+    end
+    complete_sources .map { [ _1.name, _1 ] } .to_h
+  end
+end
+
+
+# A range that keeps track of how many values a field may take.  Ensures
+# preconditions, normalizes range for easy comparison, and provides arity util
+# methods.
+class Arity < DelegateClass(Range)
+  private_class_method :new
+
+  # Validate, normalize, and internalize the given range as an arity.
+  def self.from_range(range)
+    lower = range.begin
+    unless Integer === lower and lower > 0
+      raise Err::BadArgument, <<~END
+        minimum arity must be a natural number, not #{lower}
+      END
+    end
+    upper = range.end || Float::INFINITY
+    unless (Integer === upper and upper >= lower) or upper == Float::INFINITY
+      raise Err::BadArgument, <<~END
+        invalid arity range #{lower} to #{upper}
+      END
+    end
+    upper -= 1 if range.exclude_end?
+    new Range.new(lower, upper, false)
+  end
+
+  # Quickly make an arity with exactly one value.
+  def self.from_int(int)
+    from_range(int..int)
+  end
+
+  # Allow arity to be compared to both ranges and to integers.
+  def ==(other)
+    case other
+    in nil
+      false
+    in Integer
+      self.begin == other and self.end == other
+    in Range
+      other_end = other.end || Float::INFINITY
+      other_end -= 1 if other.exclude_end?
+      self.begin == other.begin and self.end == other_end
+    in Arity
+      __getobj__ == other.__getobj__
+    else
+      raise Err::BadArgument, <<~END
+        comparison of Arity with #{other.inspect} failed
+      END
+    end
+  end
+  def !=(other); !(self == other); end
+
+  def satisfied_by?(count)
+    return true if unspecified?
+    include? count
+  end
+  def saturated_by?(count)
+    return false if unspecified?
+    count >= self.end
+  end
+  def unspecified?; self == Unspec; end
+  def demands_plurality?; self != Unspec and self != 1; end
+  def endless?; self.end.nil? or self.end == Float::INFINITY; end
+
+  def to_s
+    return '<unspecified>' if unspecified?
+    return self.begin.to_s if self.begin == self.end
+    super
+  end
+
+  Unspec = new(nil..nil)
+end
+
+
+# Class methods that facilitate defining nested trees of classes as with a
+# configuration schema.  Mix-in this module only with `extend`.
+module NestingSchema
+  def self.extended(mod)
+    # To extend a class with NestingSchema is to say that the class's basename
+    # should also be a namespace for subclasses.  Explicitly marking such
+    # classes with a constant allows possible further customization by
+    # subclassing without fragmenting the collection of classes under the
+    # nest's basename.
+    # See also #nest and its callers.
+    mod.const_set :NEST, mod
+    # It is useful for some nesting classes like Field to change the
+    # information given by #inspect, but there are times where #name will
+    # return nil but the address-based inspect gives useful information.
+    class << mod
+      alias :ruby_address :inspect
+    end
+  end
+
+  # Create a subclass of the current class, specified by block.  If a name is
+  # given, the class will be set as a constant under base_namespace.  The
+  # nesting path under base_namespace will be of the form Field::VitalVal for a
+  # class stemming from Field.nested_class!(:vital_val).
+  # Only the leaf of the parent class name is considered, so
+  # SomeModule::Field.nested_class! would place named subclasses in
+  # base_namespace::Field as well, not base_namespace::SomeModule::Field.
+  #
+  # Note: Being assigned to a constant for the first time is how Ruby
+  #       classes get their internal names.
+  # Note: Ruby puts classes defined by class blocks into Object if that block is
+  #       not already contained within a class or module block.
+  # Note: Here 'class block' and 'module block' refer only to blocks opened
+  #       with `class <Classname>` or `module <Modulename>` since `Class.new`
+  #       does not affect the constant nesting.  See also Module::nesting.
+  def nested_class!(name=nil, under: Object, &block)
+    base_namespace = under
+    subclass = Class.new(self, &block)
+    unless name.nil?
+      subclass.alias!(name, under: base_namespace)
+    end
+    subclass
+  end
+
+  # Place create a recognizeable constant within base_namespace that refers to
+  # this class.  Constants are of the form <base>::NestingBasename::Name.  If
+  # no constant has previously been set to this class, then the full resulting
+  # name will also become the class's name.
+  # See Also: #nested_class!
+  def alias!(name=basename, under:Object)
+    base_namespace = under
+    # Put Fields in ::Field, etc.
+    nest_name = nest.const_name
+    unless base_namespace.constants(false).include? nest_name
+      base_namespace.const_set nest_name, Module.new
+    end
+    namespace = base_namespace.const_get nest_name
+
+    namespace.const_set NestingSchemaUtil.consty_name(name), self
+  end
+
+  # Access the portion of my schema that was specified as an extension of me by
+  # `other_class`.
+  def toggles(other_class)
+    our_kind_of_toggles = nest.const_get(:TOGGLE_TYPE, NO_INHERIT)
+    if !other_class.const_defined?(our_kind_of_toggles, NO_INHERIT)
+      raise Err::NoSuchValue, <<~END
+        #{other_class} is missing a
+        #{other_class}::#{our_kind_of_toggles} definition
+      END
+    end
+    their_toggles_for_us = other_class.const_get(our_kind_of_toggles)
+    toggle_registers[other_class] ||= their_toggles_for_us.new
+  end
+  def toggle_registers; @toggle_registers ||= {}; end
+
+  # Get this class's nest.  The nest is the class under whose basename all
+  # subclasses are to be organized, e.g. ::Field::SomeField where Field was
+  # `extend`ed by NestingSchema.
+  def nest; self::NEST; end
+
+  # Get only the leaf name of the class, e.g. A from the class Foo::Bar::A.
+  def basename; name.split('::').last; end
+
+  def const_name; basename.to_sym; end
+
+  def attribute_name; NestingSchemaUtil.attry_name(basename); end
+
+  # These kinds of classes are often defined with do-blocks and so may not know
+  # their names at the point an error is raised.  But, since the base classes
+  # this module extends are defined in class blocks, we know someone up the
+  # chain has a useful basename.
+  def name; super || "<anonymous #{nest.basename}>"; end
+
+  # #succ allows schema classes to be used in ranges
+  def succ; superclass; end
+
+  # spaceship allows schema classes to be used in ranges
+  def <=>(other)
+    return -1 if self <  other
+    return 0  if self == other
+    return 1  if self >  other
+    raise "can't compare #{self} to unrelated #{other}"
+  end
+
+  # Companion methods to include into the extended class to allow objects to
+  # more easily interact with their schemas.
+  module InstanceMethods
+    def schema; self.class; end
+
+    def name; schema.attribute_name; end
+
+    def type; schema.name; end
+  end
+end
+
+  
+module NestingSchemaUtil
+  # Search for name among the members of lister, then call the appropriate
+  # lambda based on the situation.
+  # lister must take a boolean specifying whether to include inherited values
+  # in the list or not.  This distinction allows for the separation of local
+  # and remote values.
+  def self.absent_local_or_remote(name, lister, absent:, local:, remote:)
+    if !lister.(true).include? name
+      absent.()
+    elsif lister.(false).include? name
+      local.()
+    else
+      remote.()
+    end
+  end
+
+  # #send :message to each class in class_range and `+` the resulting values
+  # all together.  If base_case is not nil, the result of calling it without
+  # arguments is added at the end.
+  # Classes aren't normally usable in ranges, but NestingSchema classes form
+  # ranges by superclassing toward an ancestor.
+  def self.roll_up(message, class_range, base_case: nil)
+    value = class_range .map { _1.send message } .reduce :+
+
+    unless base_case.nil?
+      value += base_case.call
+    end
+
+    value
+  end
+
+  # Turn an :attribute_like symbol into a :ConstLike symbol.
+  def self.consty_name(name)
+    name .to_s .downcase .split('_') .map(&:capitalize) .join .to_sym
+  end
+
+  # Turn a :ConstLike symbol into an :attribute_like symbol.
+  def self.attry_name(name)
+    name .to_s .gsub(/([a-z])([A-Z])/, '\1_\2') .downcase .to_sym
+  end
+end
+
+class HookedArray < DelegateClass(Array)
+  def initialize(&block)
+    super []
+    @hook = block
+  end
+
+  def <<(new_entry)
+    @hook.call new_entry
+    super new_entry
+    self
+  end
+end
+
+end
+end