configuratrix 0.0.1.alpha

data/lib/configuratrix/language.rb

@@ -0,0 +1,639 @@
+require_relative 'language-util'
+
+module Configuratrix
+module Internal
+
+# These methods are the statements used to define a configuration.
+#
+# The methods become class methods of the Config class itself.  Defining a
+# configuration for a script is defining a subclass of Config, so these methods
+# can be called directly (i.e. with implicit receiver) within the class block.
+# If you're using a shortcut method where you never see the schema class, the
+# methods are available in whatever block defines the configuration.
+module ConfigSchemaLanguage
+  private
+
+  # Add a config field named `name` and defined by `block`.  Config objects
+  # will have a method of the same name to get the field's value for the
+  # configuration.
+  #
+  # If name is not given, and in its place one keyword argument is given, then
+  # the key will be the field's name, and the value will be the field's
+  # default value.  A block can be given to define the field further just as
+  # with the no-default form.
+  #   for example:
+  # field :no_default
+  # field defaults_to: 42
+  #
+  # If the field already exists, block is class_exec'd against that (after the
+  # default is set if specified).  See FieldSchemaLanguage for the statements
+  # available in field blocks.  The resulting field class will be named
+  # <self.name>::Field::Name.
+  def field(name=nil, **kwargs, &block)
+    name, has_default, default_value = (
+      Internal::ConfigSchemaLanguageUtil.unpack_field_args(name, kwargs))
+
+    target = Internal::NestingSchemaUtil.absent_local_or_remote(
+      name,
+      method(:fields),
+      absent: -> { field_add Field.nested_class!(name, under: self) },
+      local:  -> { field_get name },
+      remote: -> { field_lift name },
+    )
+
+    if has_default
+      target.class_exec { default default_value }
+    end
+
+    target.class_exec(&block) if block
+    target
+  end
+
+  # Define a positional command line argument.  See also #field.
+  def arg(name=nil, **kwargs, &user_block)
+    schema = field(name, **kwargs) do
+      loads_from :command_line
+      positional
+      count 1
+    end
+    schema.class_exec(&user_block) if user_block
+    schema
+  end
+
+  # Declare a command the script can follow.  A command has two essential parts:
+  #   - a name that becomes an acceptable value for the implicit :command
+  #     positional argument
+  #   - a subconfig specific to the command (defined by &block; see also
+  #     ConfigSchemaLanguage)
+  # On a command line, after the :command is specified, all further values are
+  # interpreted within the named command's subconfig.
+  # If a command is declared with a default (see #field), the default must be
+  # :default.  Such a declaration marks the default command if none is
+  # specified by the script inputs.
+  def command(name=nil, **kwargs, &block)
+    name, has_default, default_value = (
+      Internal::ConfigSchemaLanguageUtil.unpack_field_args(
+        name, kwargs, declaring: :command))
+    if has_default
+      command_is_default = true
+      if default_value != :default
+        raise Err::BadArgument, <<~END
+          a command can take no default value, only `:default` to mark which of
+          the commands is the default
+        END
+      end
+    end
+
+    # Initialize/extend the positional field that selects the command to
+    # include this new command.
+    arg :command do
+      type_must_be :enum
+      type { enum_symbols << name }
+      count 1
+      default name if command_is_default
+
+      toggles(Sources::CommandLine).command_selector = true
+    end
+
+    subconfig_field = subconfig name
+    subconfig_field .toggles(Sources::CommandLine) .command_subconfig = true
+    subconfig_field::Config.class_exec(&block) if block
+  end
+
+  # Define a field that does not contain a value, but a subconfiguration with a
+  # distinct field namespace.
+  # &block defines that subconfig using the same language as the root config.
+  # (ConfigSchemaLanguage).  However, behavioral differences vs root Config
+  # can be found in Subconfig.
+  # Only source definitions in the root config are used: do not modify sources
+  # in subconfigs.  (Field#loads_from is unrelated and still works.)
+  def subconfig(name=nil, **kwargs, &block)
+    name, default_was_given, name_of_default = (
+      Internal::ConfigSchemaLanguageUtil.unpack_field_args(
+        name, kwargs, declaring: :subconfig))
+
+    # Get the appropriate snippet of FieldSchemaLanguage to set up the
+    # subconfig field's default value.  This will be exec'd against the field's
+    # schema.
+    set_default = if not default_was_given
+                    # never overwrite an explicit configuration implicitly
+                    -> {
+                      if not default_explicit?
+                        default self::Config.new_defaulty
+                      end
+                    }
+                  else
+                    case name_of_default
+                    when :required
+                      -> { required }
+                    when :unloaded
+                      -> { default self::Config.new_unloaded }
+                    when :defaulty
+                      -> { default self::Config.new_defaulty }
+                    else
+                      raise Err::BadArgument, <<~END
+                        Subconfig default must be :required, :unloaded or
+                        :defaulty.  If no default value is specified, and the
+                        subconfig default has not been previously configured,
+                        then it will be set like :defaulty.
+                      END
+                    end
+                  end
+
+    superconfig = self
+
+    # At last, we can define the subconfig field itself.
+
+    field name do
+      type_must_be :subconfig
+      # Set up the schema class for the subconfig as FieldName::Config, if
+      # that hasn't been done already for this field name.
+      if not const_defined?(:Config, NO_INHERIT)
+        schema = Class.new(superconfig)
+        schema.const_set(:SUBCONFIG_NAME, name)
+        # It's not useful to have subconfigs behave exactly like the root
+        # config, so inject the appropriate behavioral differences.  If we are
+        # making a sub-subconfig, then we don't need to add a duplicate copy of
+        # Subconfig to the ancestry.
+        #
+        # Testing `is_a? Subconfig` should not be done anywhere else: all the
+        # behavioral differences must be contained within the Subconfig module
+        # itself for clarity.
+        if !schema.is_a? Subconfig
+          schema.singleton_class.prepend Subconfig
+          schema.prepend Subconfig::InstanceMethods
+        end
+
+        const_set :Config, schema
+      end
+
+      self::Config.class_exec(&block) if block
+
+      self.instance_exec(&set_default)
+    end
+  end
+
+  # Modify the named source to affect how values will be loaded into this
+  # config.  If it's desired to define a source from scratch, use #new_source.
+  #
+  # See SourceSchemaLanguage for the statements available in source blocks.
+  def source(name, &block)
+    # While #sources does look in Mutable::DefaultSources, it does not look at
+    # builtins that are not default.  In order to have non-default sources to
+    # use as templates without always also using them, we have to do some extra
+    # searching here ourselves.
+    handle_absent = -> {
+      const_name = NestingSchemaUtil.consty_name(name)
+      mod = Mutable::BuiltinSources
+      if mod.constants.include? const_name
+        # we can't even use normal lift since we're reaching outside of the
+        # schema's ancestry.
+        lifted = mod.const_get(const_name).clone
+        lifted.alias! name, under: self
+        source_add lifted
+      else
+        raise Err::NoSuchSource, <<~END
+          #{name} is not a source in #{self.name}, use new_source to define one
+          from scratch
+        END
+      end
+    }
+
+    target = NestingSchemaUtil.absent_local_or_remote(
+      name,
+      method(:sources),
+      absent: handle_absent,
+      local:  -> { source_get name },
+      remote: -> { source_lift name },
+    )
+
+    target.class_exec(&block) if block
+  end
+
+  # Define a new source from scratch.
+  # See SourceSchemaLanguage for the callbacks a Source needs, and see
+  # Source::BaseBehaviors to see which ones your use will have to override.
+  #
+  # The new Source will be named <self.name>::Source::Name.
+  def new_source(name, &block)
+    # non-default builtin sources have to be handled specially.  See also
+    # #source.
+    const_name = NestingSchemaUtil.consty_name(name)
+    builtins = Mutable::BuiltinSources
+    if builtins.constants.include? const_name
+      raise Err::NameCollision, <<~END
+        can't shadow built-in source #{const_name}, use `source :#{name}` to use
+        or reconfigure it
+      END
+    end
+
+    # we can use the same lambda for local and remote
+    prevent_overwrite = -> {
+      raise Err::NameCollision, <<~END
+        #{name} already names the source #{source_get name}
+      END
+    }
+
+    target = NestingSchemaUtil.absent_local_or_remote(
+      name,
+      method(:sources),
+      absent: -> { source_add Source.nested_class!(name, under: self) },
+      local:  prevent_overwrite,
+      remote: prevent_overwrite,
+    )
+
+    target.class_exec(&block) if block
+  end
+
+  # Also load values from a config file.  The config file path is taken either
+  # from the default given here, or from a value explicitly given on the
+  # command line via `--config-file`.  Format is either the Source schema
+  # object that can load the file, or the name of the file type (:yaml for
+  # YamlFile).  If format is nil, the file extension is assumed to be the file
+  # type name.
+  def file(default_path, format=nil)
+    config_schema = self
+    field_name = :config_file
+    source_schema =
+      Internal::ConfigSchemaLanguageUtil.resolve_file_source_schema(
+        default_path, format)
+
+    source :command_line do
+      path = [ *config_schema.subconfig_path, field_name ]
+      # XXX what would it mean if #file were called more than once?
+      toggles(source_schema).file_path_field = path.join('.')
+    end
+    field field_name do
+      type_must_be :string
+      default default_path
+    end
+  end
+
+  # Modify the named value type to affect how values will be loaded into this
+  # config.  If it's desired to define a type from scratch, use #new_type.
+  #
+  # See TypeSchemaLanguage for the statements available in type blocks.
+  def type(name, &block)
+    target = NestingSchemaUtil.absent_local_or_remote(
+      name,
+      method(:types),
+      absent: -> {
+        raise Err::NoSuchType, <<~END
+          #{name} is not a type in #{self.name}, use new_type to define one from
+          scratch
+        END
+      },
+      local:  -> { type_get name },
+      remote: -> { type_lift name },
+    )
+
+    target.class_exec(&block) if block
+  end
+
+  # Define a new value type from scratch.
+  # See TypeSchemaLanguage for the callbacks a Type can define and their
+  # meaning.
+  #
+  # The new Type will be named <self.name>::Type::Name.
+  def new_type(name, &block)
+    # we can use the same lambda for local and remote
+    prevent_overwrite = -> {
+      raise Err::NameCollision, <<~END
+        #{name} already names the type #{type_get name}
+      END
+    }
+
+    target = NestingSchemaUtil.absent_local_or_remote(
+      name,
+      method(:types),
+      absent: -> { type_add Type.nested_class!(name, under: self) },
+      local:  prevent_overwrite,
+      remote: prevent_overwrite,
+    )
+
+    target.class_exec(&block) if block
+  end
+
+end
+
+
+# These methods are the statements used to define an individual field.
+#
+# The methods are added to Field as class methods.
+# See Also: ConfigSchemaLanguage
+module FieldSchemaLanguage
+  private
+
+  # Declare that the field must explicitly be given a value for the
+  # configuration to be valid.
+  def required; raw_set_default([]); end
+
+  # Set the value this field holds when no value is given explicitly.
+  def default(value)
+    # Infer the type if there is none
+    unless typed?
+      inferred = infer_value_type value
+      if inferred.nil?
+        raise Err::TypeUndefined, <<~END
+          The type of #{value.inspect} could not be inferred; to use this value
+          as a default, specify `type :<typename>` before `default <value>` in
+          the field block.
+        END
+      end
+      set_value_type inferred
+    end
+
+    # Infer the arity if there is none and the value is explicitly pluraloid.
+    plurality = value_type.plurality
+    if !arity_explicit? and plurality != nil and plurality.can_be?.(value)
+      set_arity plurality.atoms_of(value).count
+    end
+
+    raw_set_default [value]
+  end
+
+  # Specify the attribute_names of the only kinds of source you want the field
+  # to potentially draw from.  `loads_from :any` restores the default condition
+  # of allowing any source.
+  def loads_from(first, *rest)
+    case [first, *rest]
+    in [:any]
+      set_acceptable_sources nil
+    in [*source_names]
+      set_acceptable_sources source_names
+    end
+  end
+
+  # Specify the value type of this field.
+  # `name` selects a type from the config schema by its attribute_name.  If a
+  # block is also passed, a copy of the named type is lifted and modified by
+  # block.
+  # If name is nil, then the field's type is modified.  If the type is not
+  # internal to this field, a copy is lifted before modification.  If the field
+  # is untyped, a blank internal type is defined before modification.  This
+  # immediate type will be named <field>::Type::InternalType.
+  def type(name=nil, &block)
+    if name.nil? and block.nil?
+      raise Err::BadArgument, <<~END
+        use `type {}` if you really want to set a totally blank type
+      END
+    end
+    type = if name.nil? and not typed?
+             Type.nested_class!(:internal_type, under: self, &block)
+           elsif name.nil?
+             value_type
+           else
+             self::CONTAINING_CONFIG.type_get name
+           end
+
+    if block != nil
+      # If the Type is external to this Field, then it is not safe to mutate it
+      # and we must lift a copy for modification.
+      unless type.ruby_address.start_with? "#{ruby_address}::Type::"
+        sire = type
+        type = sire.clone
+        type.alias! sire.attribute_name, under: self
+      end
+      type.class_exec(&block)
+    end
+
+    set_value_type type
+  end
+
+  def type_must_be(name)
+    if typed?
+      return value_type if value_type.attribute_name == name
+      raise Err::UnsafeReopen, <<~END
+        will not treat #{value_type.attribute_name} #{self} as #{name};
+        is there a name collision?
+      END
+    else
+      type name
+    end
+  end
+
+  # Specify the single character symbol that this field may be referred to as
+  # in a command line, like `-f` for :f.  The character must be in [a-zA-Z].
+  def short_flag(name=nil)
+    toggles(Sources::CommandLine).short_flag = (
+      name || self.attribute_name
+    ).to_sym
+  end
+
+  # Sets the field to be treated as a positional argument in command lines.
+  def positional
+    toggles(Sources::CommandLine).positional = true
+  end
+  # Removes the positional argument distinction in command lines.
+  def not_positional
+    toggles(Sources::CommandLine).positional = false
+  end
+
+  # Indicate how many values of its type the field must get in order to be
+  # valid.  The default nil means any number, with the most recent overwriting
+  # any previous values.  An integer specifies an exact requirement, and a
+  # range specifies a range of acceptable numbers (including endless ranges for
+  # arbitrary varargs).
+  def count(spec); set_arity(spec); end
+end
+
+
+# These methods are the statements used to define an individual source.
+# See Also: ConfigSchemaLanguage
+#
+# The blocks passed to these statements will override particular instance
+# methods used at key points in the process of using a Source, allowing for
+# arbitrary sources in a common interface.  See the builtins defined in
+# sources/ for examples.
+#
+# Notably, the various blocks of a Source may count on being able to read each
+# other's instance variables since they'll be invoked against a common source
+# object.
+# See Also: Source::BaseBehaviors
+module SourceSchemaLanguage
+  private
+
+  def initialize(&block)
+    SourceSchemaLanguage.enact self, :initialize, &block
+  end
+  alias_method :init, :initialize
+
+  # This block must return a boolean indicating whether the source is in a
+  # state where it can function correctly.  A config file source has to have
+  # its path set, for example.  ready? may be called multiple times in the
+  # course of loading a set of sources.
+  #
+  # Block may take one parameter: the list of already-completed source objects
+  # which may be used for interdependencies like a config file source looking
+  # for an optional path override from :command_line.
+  def ready?(&block)
+    SourceSchemaLanguage.enact self, :ready?, &block
+  end
+
+  # This block is the opportunity to resolve dependencies on other sources,
+  # e.g. getting a config file path out of command line arguments.  Called
+  # after ready? but before parse.  The block may take one argument, the list
+  # of source objects that have already been parsed.
+  def cross_configure(&block)
+    SourceSchemaLanguage.enact self, :cross_configure, &block
+  end
+
+  # This block must load all the data relevant to the source and prepare any
+  # data structures for answering fields' queries about the keys and values
+  # available.  Block may take one argument, the config schema.
+  def parse(&block)
+    SourceSchemaLanguage.enact self, :parse, &block
+  end
+
+  # This block must return a boolean indicating whether a given key has a value
+  # loaded by the source.  Block may take one argument, the key.
+  # The key is a subconfig path: e.g. [ :foo, :bar, :some_field ]
+  def key?(&block)
+    SourceSchemaLanguage.enact self, :key?, &block
+  end
+
+  # This block must return the appropriate value loaded by this source for the
+  # given key.  If the source did not load a value for the key, it must raise
+  # KeyError.  Block may take one argument, the key.
+  # The key is a subconfig path: e.g. [ :foo, :bar, :some_field ]
+  def get(&block)
+    SourceSchemaLanguage.enact self, :get, &block
+  end
+
+  # Copy the block to the appropriate method without raising warning for
+  # redefining a method since that's what we actually want.
+  def self.enact(target, name, &block)
+    target.remove_method(name) if target.instance_methods(false).include? name
+    target.define_method(name) do |*args|
+      self.instance_exec(*args, &block)
+    end
+  end
+end
+
+
+# These methods are the statements used to define an individual value type.
+# See Also: ConfigSchemaLanguage
+#
+# The blocks passed to these statements will form the bodies of class methods
+# on the schema to be called as needed in the processing of its containing
+# fields.
+#
+# Unlike a source, there is no sharing of variables between the various blocks.
+# Each function must be able to act based only on its arguments.  Instance
+# variables will be those of the Type schema and will be therby shared by all
+# fields of the same type.
+module TypeSchemaLanguage
+  private
+
+  # If specified, this block must produce a well-defined value that corresponds
+  # with the marshalled representation passed as the argument.  If it cannot,
+  # it must raise Err::MarshalUnacceptable.
+  # In a command line, #parse enables specification of a field of this type in
+  # the form of `--field value` or `--field=value`, possibly among others.
+  def parse(&block)
+    TypeSchemaLanguage.enact self, :unmarshal, &block
+  end
+
+  # If specified, this block must produce the implicit value for a field of
+  # this type.  The block may take one argument: a unitary list containing the
+  # field's default value, or the empty list if there is none.
+  # In a command line, #affirm enables specification of a field of this type in
+  # the form of `--field`, possibly among others.
+  # Note that specifying an #affirm block on a type with a #parse block may
+  # restrict the ways in which an explicit value may be specified.  In a
+  # command line, `--field value` becomes ambiguous and so only `--field=value`
+  # remains if both #parse and #affirm are specified.
+  def affirm(&block)
+    TypeSchemaLanguage.enact self, :affirmative, args: :lax, &block
+  end
+
+  # If specified, this block must produce the implicit value for the negation
+  # of a field of this type.  The block may take one argument: a unitary list
+  # containing the field's default value, or the empty list if there is none.
+  # In a command line, #negate enables specification of a field of this type in
+  # the form of `--no-field`.
+  def negate(&block)
+    TypeSchemaLanguage.enact self, :negatory, args: :lax, &block
+  end
+
+  # If specified, this block must produce a boolean indicating whether the
+  # argument is an appropriate (unmarshalled) value for the type.
+  def recognize?(&block)
+    TypeSchemaLanguage.enact self, :recognize_atom?, &block
+  end
+
+  # Analogous to `recognize?` but stronger.  For a type to claim a value is to
+  # say that value implies the type.  Consider that many types may want to
+  # recognize nil as an acceptable value, but only String claims it.
+  #
+  # Any types in a config that specify this method will get an opportunity to
+  # claim untyped fields when the default value is set.  See also #priority.
+  def claim?(&block)
+    TypeSchemaLanguage.enact self, :assert_claim, &block
+  end
+  # Shortcut for types that don't need to distinguish between recognition and
+  # claiming.
+  def claim_all_recognized; claim? { self === _1 }; end
+
+  # Influence the order in which Types are given the chance to claim a default
+  # field value as implying the Type.  Builtins have priority 0.  Any negative
+  # number, :early, or :high will cause a type to get a chance before the
+  # builtins.  Any positive number, :late, or :low will guarantee that the
+  # builtins have a go first.  :reset will return the type to priority 0.
+  def priority(value)
+    @priority = case value
+                in :reset
+                  0
+                in :early | :high
+                  -1000
+                in :late  | :low
+                  1000
+                in Numeric
+                  value
+                end
+  end
+
+  # Specify how a type may accept multiple values.  If spec is a symbol, its
+  # upcase must name a constant in Type::Plurality.  Otherwise, spec is treated
+  # as a Plurality object itself.  By default, types take multiple values
+  # :as_array.
+  def multivalue(spec)
+    block = if spec.is_a? Symbol
+              name = spec.upcase
+              unless Type::Plurality.constants(false).include? name
+                raise Err::ValuelessKey, <<~END
+                  `#{name}` does not name a plurality
+                END
+              end
+              plurality = Type::Plurality.const_get name
+              -> { plurality }
+            else
+              -> { spec }
+            end
+    TypeSchemaLanguage.enact self, :plurality, &block
+  end
+
+  # Copy the block to the appropriate method without raising warning for
+  # redefining a method since that's what we actually want.
+  # If `args` is :strict, then the block must take exactly the appropriate
+  # arguments for the function.  If it is :lax, then the block can take fewer
+  # arguments if it has no need for the input.
+  def self.enact(target, name, args: :strict, &block)
+    if target.singleton_methods(false).include? name
+      target.singleton_class.remove_method(name)
+    end
+
+    case args
+    in :strict
+      target.define_singleton_method(name, &block)
+    in :lax
+      target.define_singleton_method(name) do |*args|
+        block.(*args)
+      end
+    end
+  end
+end
+
+
+end
+end