configuratrix 0.0.1.alpha

data/lib/configuratrix/schema.rb

@@ -0,0 +1,970 @@
+require_relative 'language'
+require_relative 'schema-util'
+
+module Configuratrix
+
+# A config is a collection of named values.
+class Config
+  # This is where you want to look (language.rb) for the statements used to
+  # define a config.
+  extend Internal::ConfigSchemaLanguage
+
+
+  #
+  # Instance Methods:
+  #   These methods are available on the actual config object resulting from
+  #   parsing script args etc.
+  #
+
+  # Plumbing such as #schema.
+  include Internal::NestingSchema::InstanceMethods
+
+  # This is where the methods for getting the fields' values live.  We don't
+  # know what they are yet!
+  #
+  # To find the methods defined by a given config
+  # schema, use explicit scoping (e.g. #schema::FieldAttributes or
+  # ConfigClass::FieldAttributes).  Otherwise, you'll always get
+  # Config::FieldAttributes itself which should generally be empty.
+  #
+  # The module isn't even included into the class until a schema puts something
+  # into it via #mutable_instance_field_module!  And even then it will most
+  # likely be an independent copy of this module that belongs to a subclass.
+  module FieldAttributes
+    # Add a method to objects of this schema to access the value of field by
+    # its attribute_name.  Call only on modules received via
+    # #mutable_instance_field_module!
+    def self.register(field)
+      attr_name = field.attribute_name
+      define_method attr_name do
+        self[attr_name].value
+      end
+    end
+  end
+
+  # Get the Field object for the given name.
+  def [](field_name)
+    unless @field_map.include? field_name
+      raise Err::ValuelessKey, <<~END
+        #{self} has no field `#{field_name}` (or, field added to schema after
+        config object initialized)
+      END
+    end
+    @field_map.fetch field_name
+  end
+
+  private
+  
+  def initialize
+    schema.validate
+    schema_init
+    config_init
+  end
+
+  module Innards
+    # Do only the initialization that does not require the actual sources to be
+    # ready.
+    def schema_init
+      schema_field_init
+      schema_source_init
+    end
+    def schema_field_init
+      @field_map = (schema
+        .fields_schema 
+        .map { [ _1.attribute_name, _1.new(self) ] }
+        .to_h)
+    end
+    def schema_source_init
+      @sources = schema.sources_schema.map(&:new)
+    end
+
+    # Parse and prepare a usable config.
+    def config_init
+      config_source_init
+      config_field_init
+    end
+    def config_source_init
+      if source_objects.empty?
+        raise Err::PathologicalSchema, <<~END
+          #{schema.name} has no sources to load from: use source :dummy if
+          desired
+        END
+      end
+      @source_map = Internal::SourceUtil.parse_all(
+        source_objects, within: schema)
+    end
+    def config_field_init
+      # It seems like you could use `from: @source_map.values` since they are
+      # the ready sources, but order is significant.
+      available_sources = source_objects .select { _1.ready?(source_objects) }
+      @field_map.values.each do |field|
+        field.send :take_value_from, available_sources
+      end
+    end
+
+    def source_map; @source_map; end
+    def source_objects; @sources; end
+    def subconfig_path; []; end
+  end
+  include Innards
+
+  public
+
+
+  #
+  # Class Methods:
+  #   These methods modify the class itself (the schema of the config) and
+  #   affect how args etc. will be parsed into a configuration.
+  #
+
+  extend Internal::NestingSchema
+
+  # Get the names of all the fields in this config schema.  Inherited fields
+  # are included if `true` is passed.
+  def self.fields(...); fields_schema(...).map(&:attribute_name); end
+
+  # Get the list of all Field classes relevant to this config, including
+  # inherited fields if `inherit`.
+  def self.fields_schema(inherit=true)
+    ultimate = inherit ? Config : self
+    Internal::NestingSchemaUtil.roll_up(
+      :local_fields,
+      self..ultimate,
+    ) .uniq &:basename
+  end
+
+  def self.field_defined?(name,inherit=true)
+    fields(inherit).include?(name)
+  end
+
+  # Add a new field into the config schema.
+  def self.field_add(field)
+    name = field.attribute_name
+
+    if field_defined? name
+      raise Err::NameCollision, <<~END
+        #{name} already names a field in #{self.name}
+      END
+    end
+
+    local_fields << field
+    field
+  end
+
+  # Clone the named field and re-add it, shadowing the ancestor's version.
+  def self.field_lift(attribute_name)
+    unless field_defined? attribute_name
+      raise Err::ValuelessKey, <<~END
+        `#{attribute_name}` names no field in #{name}
+      END
+    end
+    lifted = field_get(attribute_name).clone
+    lifted.alias! attribute_name, under: self
+
+    lifted.send :detatch_config
+    local_fields << lifted
+    lifted
+  end
+
+  # Get the schema (Field subclass) for the given field name.
+  def self.field_get(name, inherit=true)
+    unless field_defined? name
+      raise Err::ValuelessKey, <<~END
+        #{self.name} has no field `#{name}`
+      END
+    end
+    fields_schema(inherit) .find { _1.attribute_name == name }
+  end
+
+  # Get the schema for the given field path, entering subconfigs as necessary.
+  def self.[](*field_path)
+    case field_path
+    in [ field_name ]
+      field_get field_name
+    in [ subconfig_name, *sub_path ]
+      field_get(subconfig_name)::Config[*sub_path]
+    end
+  end
+
+  # Enumerate all the fields not only in this config, but in all subconfigs as
+  # well.  Each enumeration includes the field schema, the schema of the config
+  # containing the field, and the string path to that subconfig (or empty
+  # string for root config).
+  def self.fields_universe
+    this_config = self
+    Enumerator.new do |output|
+      fields_schema.each do |field_schema|
+        output.yield(field_schema, this_config)
+        
+        # Recur on any subconfig.
+        if field_schema.const_defined?(:Config, NO_INHERIT)
+          subenum = field_schema::Config.fields_universe
+
+          subenum.each do |field_schema,subconfig_schema|
+            output.yield field_schema, subconfig_schema
+          end
+        end
+      end
+    end
+  end
+
+  # Get the names of all the sources in this config schema.  Inherited and
+  # default sources are included if `true` is passed.
+  def self.sources(...); sources_schema(...).map(&:attribute_name); end
+
+  # Get the list of all Source classes relevant to this config.  If `inherit`
+  # is true, then inherited sources as well as those of
+  # Configuratrix::Mutable::DefaultSources are included.
+  def self.sources_schema(inherit=true)
+    if inherit
+      ultimate = Config
+      base_case = -> {
+        mod = Mutable::DefaultSources
+        mod .constants .map { mod.const_get _1 }
+      }
+    else
+      ultimate = self
+      base_case = nil
+    end
+    Internal::NestingSchemaUtil.roll_up(
+      :local_sources,
+      self..ultimate,
+      base_case: base_case
+    ).uniq &:basename
+  end
+
+  def self.source_defined?(name,inherit=true)
+    sources(inherit).include?(name)
+  end
+
+  # Add a new source into the config schema.
+  def self.source_add(source)
+    name = source.attribute_name
+
+    if source_defined? name
+      raise Err::NameCollision, <<~END
+        #{name} already names a source in #{self.name}
+      END
+    end
+
+    local_sources << source
+    source
+  end
+
+  # Clone the named source and re-add it, shadowing the ancestor's version.
+  def self.source_lift(name)
+    unless source_defined? name
+      raise Err::ValuelessKey, <<~END
+        `#{name}` names no source in #{self.name}
+      END
+    end
+    lifted = source_get(name).clone
+    lifted.alias! name, under: self
+
+    local_sources << lifted
+    lifted
+  end
+
+  # Get the schema (Source subclass) for the given source name.
+  def self.source_get(name)
+    unless source_defined? name
+      raise Err::ValuelessKey, <<~END
+        #{self.name} has no source `#{name}`
+      END
+    end
+    sources_schema .find { _1.attribute_name == name }
+  end
+
+  # Get the names of all the types in this config schema.  Inherited and
+  # default types are included if `true` is passed.
+  def self.types(...); types_schema(...).map(&:attribute_name); end
+
+  # Get the list of all Type classes relevant to this config.  If `inherit` is
+  # true, then inherited types as well as those of
+  # Configuratrix::Mutable::DefaultTypes are included.
+  def self.types_schema(inherit=true)
+    if inherit
+      ultimate = Config
+      base_case = -> {
+        mod = Mutable::DefaultTypes
+        mod .constants .map { mod.const_get _1 }
+      }
+    else
+      ultimate = self
+      base_case = nil
+    end
+    Internal::NestingSchemaUtil.roll_up(
+      :local_types,
+      self..ultimate,
+      base_case: base_case
+    ).uniq &:basename
+  end
+
+  def self.type_defined?(name,inherit=true); types(inherit).include?(name); end
+
+  # Add a new type into the config schema.
+  def self.type_add(type)
+    name = type.attribute_name
+
+    if type_defined? name
+      raise Err::NameCollision, <<~END
+        #{name} already names a value type in #{self.name}
+      END
+    end
+
+    local_types << type
+    type
+  end
+
+  # Clone the named type and re-add it, shadowing the ancestor's version.
+  def self.type_lift(name)
+    unless type_defined? name
+      raise Err::ValuelessKey, <<~END
+        `#{name}` names no type in #{self.name}
+      END
+    end
+    lifted = type_get(name).clone
+    lifted.alias! name, under: self
+
+    local_types << lifted
+    lifted
+  end
+
+  # Get the schema (Type subclass) for the given value type name.
+  def self.type_get(name)
+    unless type_defined? name
+      raise Err::ValuelessKey, <<~END
+        #{self.name} has no value type `#{name}`
+      END
+    end
+    types_schema .find { _1.attribute_name == name }
+  end
+
+  # Where is this config located among the config system?
+  def self.subconfig_path
+    segments = []
+    cursor = self
+    while cursor.const_defined?(:SUBCONFIG_NAME, NO_INHERIT)
+      segments.prepend cursor::SUBCONFIG_NAME
+      cursor = cursor.superclass
+    end
+    segments
+  end
+  def self.subconfig_tree
+    local_fields.select {
+      _1.const_defined?(:Config, NO_INHERIT)
+    }.map {
+      [ _1.attribute_name, _1::Config.subconfig_tree ]
+    }.to_h
+  end
+
+  # Get an unloaded config object.  Throws on field access (because unloaded)
+  # while still differentiating nonexistent fields.
+  #
+  # Because an unloaded config has no object state (as underscored by the use
+  # of #allocate over #new in this method), it is even safe to set a
+  # new_unloaded value as a subconfig default before the subconfig's schema is
+  # finalized.
+  def self.new_unloaded
+    obj = allocate
+    obj.singleton_class.prepend Internal::UnloadedConfig
+    obj
+  end
+
+  # Get an unloaded config that will JIT initialize the appropraite field
+  # objects, but will not load any data into them.  This results in a config
+  # that will give defaults or throw on reference to values of fields that have
+  # no defaults.
+  #
+  # Because the config's Field objects are initialized JIT, it is safe to set a
+  # new_defaulty value as a subconfig default before the subconfig's schema is
+  # finalized.
+  def self.new_defaulty
+    obj = allocate
+    obj.singleton_class.prepend Internal::DefaultyConfig
+    obj
+  end
+
+  # Check for any structural incompatibilities in the schema that can only be
+  # checked when we're sure the schema classes are done being edited (which is
+  # to say we can't check them until just before building an actual config
+  # object).
+  def self.validate
+    fields_universe.each do |field_schema|
+      sources_schema.each { _1.approve_field field_schema }
+    end
+  end
+
+  #
+  # Private Class Methods
+  #
+
+  def self.local_fields
+    @fields ||= Internal::HookedArray.new do |field_schema|
+      if field_schema.config_attached?
+        raise "BUG: adding field still attached to another config" 
+      end
+      field_schema.const_set :CONTAINING_CONFIG, self
+      mutable_instance_field_module!.register field_schema
+    end
+  end
+  private_class_method :local_fields
+
+  def self.local_sources
+    @sources ||= Internal::HookedArray.new do |source_schema|
+      # enforce reserved words
+      if [ :any ].include? source_schema.attribute_name
+        raise Err::WordIsReserved, <<~END
+          no source can be named :#{source_schema.attribute_name}
+        END
+      end
+    end
+  end
+  private_class_method :local_sources
+
+  def self.local_types; @types ||= []; end
+  private_class_method :local_types
+
+  # Get the module for this particular class that keeps the instance methods
+  # for accessing field values.  If this class doesn't have one, copy it from
+  # Config::FieldAttriutes so self::FieldAttributes#register exists.  to this
+  # class.
+  def self.mutable_instance_field_module!
+    unless constants(false).include? :FieldAttributes
+      const_set :FieldAttributes, Config::FieldAttributes.clone
+    end
+    mod = self::FieldAttributes
+
+    unless ancestors.include? mod
+      prepend mod
+    end
+
+    mod
+  end
+  private_class_method :mutable_instance_field_module!
+
+end
+
+
+# This module is prepended onto the singleton class of each subconfig to
+# reflect the semantic differences between the root config and subconfigs.
+module Subconfig
+  # If subconfigs inherited fields, then there would be no separation of the
+  # namespaces.  But, to avoid breaking the interface, discard an inherit
+  # parameter anyway.
+  def field_defined?(name,inherit=nil); super(name,false); end
+  def field_get(name,inherit=nil); super(name,false); end
+  def fields(inherit=nil); super(false); end
+  def fields_schema(inherit=nil); super(false); end
+
+  # Sources, on the other hand, have no business in subconfigs.  The same
+  # source objects built from the sources_schema of the root config will simply
+  # change namespaces when encountering inputs for a subconfig.  So, any
+  # modifications to sources in subconfigs are meaningless.  Note that fields
+  # in subconfigs are still free to use #loads_from.
+  def self.no_sourcing!(method,schema)
+    raise Err::PathologicalSchema, <<~END
+      #{method}: source definitions in subconfigs (#{schema}) have no effect
+    END
+  end
+  def source_add(...); Subconfig.no_sourcing!(__method__,self); end
+  def source_lift(...); Subconfig.no_sourcing!(__method__,self); end
+
+  private
+
+  def new_source(...); Subconfig.no_sourcing!(__method__,self); end
+  def source(...); Subconfig.no_sourcing!(__method__,self); end
+
+    # This module is prepended to the instance methods of Subconfigs.
+  module InstanceMethods
+    def initialize(superconfig)
+      @superconfig = superconfig
+      super()
+    end
+
+    def schema_source_init; end
+    def config_source_init; end
+
+    def source_objects; @superconfig.source_objects; end
+    def subconfig_path
+      [ *@superconfig.subconfig_path, self::SUBCONFIG_NAME ]
+    end
+  end
+end
+
+
+# A field is one named value.
+class Field
+  TOGGLE_TYPE = :FieldToggles
+
+  # This is where you want to look (language.rb) for the statements used to
+  # define a field.
+  extend Internal::FieldSchemaLanguage
+
+
+  #
+  # Instance Methods:
+  #   These methods are available on the actual field object resulting from
+  #   parsing script args etc.
+  #
+
+  include Internal::NestingSchema::InstanceMethods
+
+  def initialize(containing_config=nil)
+    @containing_config = containing_config if containing_config
+  end
+
+  def value
+    # instance_variable_defined? is used over @value.nil? to distinguish
+    # between an actual nil value for the field and Ruby just giving back nil
+    # for any undefined @variable.
+    if instance_variable_defined? :@value
+      @value
+    else
+      default
+    end
+  end
+
+  def default; schema.default_value; end
+
+  def containing_config; @containing_config; end
+
+  private
+
+  # Take up the value from the first acceptable source that contains the
+  # appropriate key.  Sources must already be parsed.
+  def take_value_from(sources)
+    case schema.value_type.take_value_for(self, from: sources)
+    in [ value ]
+      @value = value
+    in []
+      if schema.required?
+        key = [ *schema.subconfig_path, name ]
+        raise Err::RequirementUnmet, <<~END
+          #{key.join '.'} is required
+        END
+      end
+    end
+  end
+
+  public
+
+
+  #
+  # Class Methods:
+  #   These methods modify the class itself (the schema of the field) and
+  #   affect how args etc. will be parsed into this field.
+  #
+
+  extend Internal::NestingSchema
+
+  # Whether this field must have a value for a config to be valid.
+  def self.required?; list_of_default.empty?; end
+
+  # Get the value for this field when none is given explicitly.  To allow any
+  # value as default without ambiguity, an error is raised if this is called on
+  # a required field.
+  def self.default_value
+    case list_of_default
+    in []
+      raise Err::NoSuchValue, <<~END
+        required field `#{self}` has no default
+      END
+    in [value]
+      value
+    end
+  end
+
+  # Get an Array that either solely contains the field's default value, or
+  # contains nothing if the field is required.
+  def self.list_of_default; @list_of_default || []; end
+
+  # It is sometimes useful to discern between a field that's required by
+  # default and a field that was explicitly marked required.
+  def self.default_explicit?; @list_of_default != nil; end
+
+  # Arity specifies how many values a field must get in order to be complete.
+  #
+  # The default Unspec arity means that the most recent value given to a field
+  # is its value.  This mirrors common command line behavior.  An explicit
+  # arity specifies a number or a range of numbers of values acceptable to the
+  # field.  See also Arity.
+  #
+  # Arity is separate from a field being required or not.  Fields with arity
+  # other than nil or 1 require their value_type to have a non-nil #plurality.
+  def self.arity; @arity || Internal::Arity::Unspec; end
+
+  def self.arity_explicit?; @arity != nil; end
+
+  # Get the list of attribute names of sources this field is willing to load
+  # from (e.g. :command_line).  nil indicates any source is acceptable.
+  def self.acceptable_sources; @acceptable_sources.dup; end
+
+  # Get the Type subclass that corresponds to values of this Field type.
+  def self.value_type; @value_type || Mutable::DefaultType; end
+
+  # Whether the field has an explicit value_type.
+  def self.typed?; @value_type != nil; end
+
+  def self.config_attached?; const_defined?(:CONTAINING_CONFIG, NO_INHERIT); end
+
+  def self.subconfig_path
+    if config_attached?
+      self::CONTAINING_CONFIG.subconfig_path
+    else
+      []
+    end
+  end
+
+  def self.to_s; [ *subconfig_path, attribute_name ] .join('.'); end
+  def self.inspect; "#{name}(#{value_type.name})"; end
+
+  #
+  # Private Class Methods
+  #
+
+  # Directly set @list_of_default: emtpy list means required field.
+  def self.raw_set_default(list_of_value)
+    @list_of_default = list_of_value
+    assert_consistent_default!
+    @list_of_default
+  end
+  private_class_method :raw_set_default
+
+  # See #arity.
+  def self.set_arity(value)
+    @arity = case value
+             in nil
+               Internal::Arity::Unspec
+             in Range
+               Internal::Arity.from_range value
+             in Integer
+               Internal::Arity.from_int value
+             end
+    # the default value of a field must satisfy the field's arity.
+    assert_consistent_default!
+    @arity
+  end
+  private_class_method :set_arity
+
+  # Specify a list of :source_names specifying the only sources this field may
+  # be loaded from.
+  def self.set_acceptable_sources(list); @acceptable_sources = list; end
+  private_class_method :set_acceptable_sources
+
+  # The Type subclass that dictates the form of values appropriate for this
+  # field.
+  def self.set_value_type(typeclass)
+    @value_type = typeclass
+    assert_consistent_default!
+    @value_type
+  end
+  private_class_method :set_value_type
+
+  # Get the highest priority type that recognizes value, or nil.
+  def self.infer_value_type(value)
+    (self::CONTAINING_CONFIG
+      .types_schema
+      .select { _1.respond_to? :assert_claim }
+      .sort_by(&:inference_priority)
+      .find { _1.assert_claim value }
+    )
+  end
+  private_class_method :infer_value_type
+
+  # The default value must always agree with the value_type and the arity of
+  # the field.
+  def self.assert_consistent_default!
+    # required fields have no default to check
+    return if required?
+
+    case problem_with_value? default_value
+    in nil
+    in :type
+      raise Err::ValueUnrecognized, <<~END
+        default value #{default_value.inspect} is not a #{value_type}: set a
+        compatible `type` or clear the default with `required`
+      END
+    in :arity, count
+      raise Err::ArityMismatch, <<~END
+        field accepting #{arity} value(s) cannot have a default with
+        #{count} values: set a compatible `count` or clear the default with
+        `required`
+      END
+    in :must_wrap
+      raise Err::ValueUnrecognized, <<~END
+        plural field demands default value be
+        #{value_type.plurality.description}, not `#{default_value}`
+      END
+    in :must_unwrap
+      raise Err::ValueUnrecognized, <<~END
+        non-plural field demands default value be singular, not
+        #{value_type.plurality.description}
+      END
+    end
+  end
+  private_class_method :assert_consistent_default!
+
+  def self.problem_with_value?(value)
+    type = value_type
+    plurality = type.plurality
+
+    if type.discerning?
+      unless type === value
+        return :type
+      end
+    end
+
+    unless plurality.nil?
+      count = plurality.atoms_of(value).count
+      unless arity.satisfied_by? count
+        return [:arity, count]
+      end
+      if arity.demands_plurality? and !plurality.can_be?.(value)
+        return :must_wrap
+      end
+      if !arity.demands_plurality? and plurality.must_be?.(value)
+        return :must_unwrap
+      end
+    end
+
+    nil
+  end
+  private_class_method :problem_with_value?
+
+  def self.detatch_config
+    remove_const :CONTAINING_CONFIG
+  end
+  private_class_method :detatch_config
+end
+
+# A source loads data and parses out keys and values for Fields to select and
+# encapsulate.
+class Source
+  TOGGLE_TYPE = :SourceToggles
+
+  # This is where you want to look (language.rb) for the statements used to
+  # define a source.
+  extend Internal::SourceSchemaLanguage
+
+
+  #
+  # Instance Methods:
+  #   These methods are available on the actual source object resulting from
+  #   parsing script args etc.
+  #
+
+  include Internal::NestingSchema::InstanceMethods
+
+  # Throw an error indicating a request for a value cannot be fulfilled.
+  def undefined!(key=nil)
+    suffix = unless key.nil?
+               " for #{key}"
+             else
+               ""
+             end
+    raise Err::ValuelessKey, <<~END
+      #{schema.name} cannot return undefined value#{suffix}
+    END
+  end
+  
+  # These are the methods meant for overriding in subclasses.  See
+  # SourceSchemaLanguage for the details of their behavior and use.
+  module BaseBehaviors
+    def ready?(other_sources); true; end
+
+    def cross_configure(other_sources); end
+
+    def parse(field_schemas); @value_map = Hash.new; end
+
+    def key?(key)
+      get key
+      true
+    rescue KeyError
+      false
+    end
+
+    # Must raise if the key is not present: nil is a valid explicit value.
+    def get(key)
+      [ @value_map, *key ] .reduce { _1 .fetch _2 }
+    end
+  end
+  include BaseBehaviors
+
+
+  #
+  # Class Methods:
+  #
+
+  extend Internal::NestingSchema
+  
+  # Individual kinds of sources may have quirks that make them unsafe or
+  # incompatible with certain schemas.  This function must raise an error under
+  # Err::BadSchema if the given field cannot be reconciled while this source is
+  # enabled.
+  def self.approve_field(field_schema); end
+
+end
+
+# A Type marshals individual values from source inputs into Ruby values.  A
+# type may also be able to recognize values of its own kind, allowing for field
+# type inference from a provided default value.
+class Type
+  # This is where you want to look (language.rb) for the statements used to
+  # define a type.
+  extend Internal::TypeSchemaLanguage
+
+  # Since types do not have per-config state, they have no instance methods and
+  # it is not necessary to instantiate Type objects.
+  private_class_method :new
+
+  extend Internal::NestingSchema
+
+  # To allow user-defined types to preempt recognition of common values like
+  # true or false when necessary, Field classes are sorted by this value (low
+  # to high) before finding the first one that recognizes a given default
+  # value.  Builtins all have priority=0, so any negative value will preempt
+  # them.
+  def self.inference_priority; @priority || 0; end
+
+  # Helper function to raise the appropriate exception when a value can't be
+  # parsed as the Type.  The caller of the parsing function is expected to
+  # craft the exception message since it already knows both the Type and the
+  # value as well.
+  def self.nope!(str=nil); raise Err::MarshalUnacceptable.new(str); end
+
+  # A discerning type can tell if an unmarshalled value would be an appropriate
+  # value of the type.  Undiscerning types are asking for trouble.
+  def self.discerning?; respond_to?(:recognize_atom?); end
+
+  # Whether a value (singular or plural) falls into the type.
+  def self.===(value)
+    raise NotImplementedError unless respond_to? :recognize_atom?
+
+    must_be_atom = (plurality.nil? or
+                    !plurality.can_be?.(value))
+    if must_be_atom
+      recognize_atom? value
+    else
+      plurality.deconstruct.(value).all? { recognize_atom? _1 }
+    end
+  end
+
+  def self.take_value_for(field, from:)
+    sources = if field.schema.acceptable_sources.nil?
+                from
+              else
+                from.select {
+                  field.schema.acceptable_sources.include? _1.name
+                }
+              end
+
+    if sources.empty?
+      raise Err::PathologicalSchema, <<~END
+        field #{field.schema} has no viable sources, accepts:
+        [#{field.schema.acceptable_sources.map(&:name).join(', ')}]
+        available: [#{from.map(&:name).join(', ')}]
+      END
+    end
+
+    key = [ *field.schema.subconfig_path, field.schema.attribute_name ]
+    sources.each do |source|
+      next unless source.key? key
+      return [ source.get(key) ]
+    end
+
+    []
+  end
+
+  class << self
+    # The contexts in which a type can be extracted depends on which of the
+    # following methods are actually defined on a Type class.  See
+    # TypeSchemaLanguage (language.rb) for how to set those up and more details
+    # about their usage.
+
+    # def unmarshal(serialized)
+
+    # def affirmative(default_value)
+
+    # def negatory(default_value)
+
+    # def recognize_atom?(singular_candidate)
+
+    def plurality; Plurality::AS_ARRAY; end
+
+    # def assert_claim(value)
+  end
+
+  # A Plurality object dictates how a type can be applied to a field that may
+  # take multiple values.  See Field#arity for more info on multi-value fields
+  # and when a plural type may be required.  Types are plural by default by
+  # allowing multiple values to be represented as an Array.
+  Plurality = Struct.new(
+    # proc that prepares an individual value to be combineable
+    :wrap_atom,
+    # Proc that produces the combination of a plural value in progress and a
+    # newly-wrapped atom.
+    :combine,
+    # Proc that returns whether a given value can safely be treated as plural.
+    :can_be?,
+    # Proc that returns whether a given value is unambiguously plural.
+    :must_be?,
+    # Proc that returns an enumeration of all the subvalues of a plural value.
+    :deconstruct,
+    # A human friendly description of what it means for a value to be plural,
+    # like "in an array".
+    :description,
+  )
+  class Plurality
+    # If a plural value can't be deconstructed into atoms, then it must be an
+    # atom itself.
+    def atoms_of(value)
+      return deconstruct.(value) if can_be?.(value)
+      [value].each 
+    end
+
+    class << self
+      # Define Plurality::NAME and give it a useful #inspect.  (A struct full
+      # of procs just has an extremely verbose but useless #inspect.)
+      def constant(name)
+        -> (**struct_pairs) {
+          raise unless struct_pairs.keys.sort == members.sort
+          obj = new(*(members.map { struct_pairs.fetch _1 } ))
+          obj.define_singleton_method(:inspect) { "Plurality::#{name}" }
+          obj.freeze
+          const_set name, obj
+        }
+      end
+      private :constant
+    end
+
+    constant(:AS_ARRAY)[
+      wrap_atom: ->   { [_1] },
+      combine: ->     { _1 + _2 },
+      can_be?: ->     { Array === _1 },
+      must_be?: ->    { Array === _1 },
+      deconstruct: -> { _1.each },
+      description: "in an array",
+    ]
+
+    constant(:AS_SUM)[
+      wrap_atom: ->   { _1 },
+      combine: ->     { _1 + _2 },
+      can_be?: ->     { _1 .respond_to? :+ },
+      must_be?: ->    { false },
+      deconstruct: -> { [ _1 ] .each },
+      description: nil,
+    ]
+
+    constant(:AS_PRODUCT)[
+      wrap_atom: ->   { _1 },
+      combine: ->     { _1 * _2 },
+      can_be?: ->     { _1 .respond_to? :* },
+      must_be?: ->    { false },
+      deconstruct: -> { [ _1 ] .each },
+      description: nil,
+    ]
+  end
+end
+
+end