configuratrix 0.0.1.alpha

data/lib/configuratrix/sources/command_line.rb

@@ -0,0 +1,585 @@
+require_relative '../schema'
+require_relative 'util'
+
+module Configuratrix
+module Sources
+
+class CommandLine < Source
+  init  { @line_tokens = ARGV }
+  parse { |config_schema|
+    @value_map = Parser.parse(config_schema, @line_tokens.map(&:dup))
+  }
+
+  # Per-field configurations pertinent to command line parsing.
+  TOGGLES = [
+    # nil or a one-character symbol in [a-zA-Z].  A symbol maps, e.g., :x to
+    # "-x" on the command line.
+    :short_flag,
+    # For fields where :positional is true, the fields are given all command
+    # line values not associated with flags.  The values are given to
+    # positional fields in declaration order successively as each field is
+    # satisfied.
+    :positional,
+    # At most one positional field per config may be marked as the command
+    # selector.  When the command selector receives its value, command line
+    # parsing changes context from the current config to the named command's
+    # subconfig.
+    :command_selector,
+    # This field isn't the one that selected the command, it is one of the
+    # subconfigs associated with an available command.
+    :command_subconfig,
+  ]
+  class FieldToggles < Internal::ToggleStruct[*TOGGLES]
+    SHORT_FLAG = -> { /^[a-zA-Z]$/ =~ _1 and _1.is_a? Symbol }
+    def short_flag=(...); reject_unless super, matches: SHORT_FLAG; end
+
+    def positional=(...); reject_unless super, matches: A::BOOL; end
+    def command_selector=(...); reject_unless super, matches: A::BOOL; end
+    def command_subconfig=(...); reject_unless super, matches: A::BOOL; end
+  end
+
+  class Parser
+    def self.parse(config_schema,tokens)
+      new(config_schema).parse(tokens)
+    end
+
+    def initialize(config_schema)
+      @config_view = ConfigView.new(config_schema)
+      # source of tokens to parse
+      @stream = nil
+    end
+
+    def parse(tokens)
+      @stream = Internal::Stream.new(tokens.each)
+      # Whether tokens that look like flags should be treated like flags.  This
+      # becomes false upon encountering the "--" token.
+      @flags_are_visible = true
+
+      parse_command_line
+
+      @config_view.finalize
+      @config_view.root[:value_map]
+    end
+
+    private
+
+    def parse_command_line
+      loop do
+        case peek
+        in []
+          return
+        in    [LONG_FLAG] if @flags_are_visible
+          parse_long_flag
+        in   [SHORT_FLAG] if @flags_are_visible
+          parse_short_flag
+        in [END_OF_FLAGS] if @flags_are_visible
+          take!
+          @flags_are_visible = false
+        in [String]
+          parse_positional
+        end
+      end
+    end
+
+    def parse_long_flag
+      raw_token = take!(:LONG_FLAG)
+      # remove the now functionless leading "--"
+      token = raw_token.sub(LONG_FLAG, '')
+
+      # handle "--key=value"
+      if token.include? SINGLE_TOKEN_KEY_VALUE_BOUNDARY
+        key, value_str = split_single_token_kv(token)
+
+        return unmarshal_and_store_for_field(
+          raw_token,
+          value_str,
+          (field_for key),
+        )
+      end
+
+      # If `token` wasn't a single-token key-value pair, then it's the key.
+
+      # Accommodate the convention of using the prefix "no-" to signal the
+      # negation of a long flag.
+      # Danger!  If field keys aren't prevented from starting with "no-"
+      # themselves, then deleting NEGATORY_PREFIX creates ambiguity between
+      # "--no-chance" standing for negated "chance" or just "no-chance".
+      # Validation via #approve_field safely covers this sharp edge.
+      negated = (token.delete_prefix! NEGATORY_PREFIX) != nil
+      # Having to press shift for underscore is a big drag on operating a cli
+      # quickly, but dashes are illegal in field names.
+      token.gsub! '-', '_'
+      # Dashes in the key string couldn't have served any other purpose to this
+      # parser anyway, so it's safe to obliterate them unconditionally like
+      # this.
+
+      key = token.to_sym
+      field = field_for key
+
+      # Key's all set; on to value
+
+      if negated
+        # A negated flag must take on its type's negative value.  Nothing else
+        # to do for this token.
+        if !field.value_type.respond_to? :negatory
+          raise Err::FieldNotApplicable, <<~END
+            '#{raw_token}' : #{field} can not be negated
+          END
+        end
+
+        value = field.value_type.negatory(field.list_of_default)
+        return store_for_field(raw_token, value, field)
+      end
+
+      # If the field's type has an implicit positive value, then we must apply
+      # that value now and be done with the token.  If the type also allows
+      # explicit values, they must be provided via the --key=value format which
+      # has already been handled.  These restrictions prevent ambiguity in the
+      # command line grammar.
+      # For example, in "--bool 0":
+      #  - Is :bool being implicitly affirmed true followed by positional
+      #    argument "0"?
+      #  - Is :bool being explicitly declared false by the following "0" token?
+      # Better to resolve this now by always preferring the implicit option and
+      # leaving explicit values to --key=value.
+      if field.value_type.respond_to? :affirmative
+        value = field.value_type.affirmative(field.list_of_default)
+        return store_for_field(raw_token, value, field)
+      end
+
+      # By this point the value must be the next command line token.
+
+      unless field.value_type.respond_to? :unmarshal
+        # Die before unmarshal_and_store_for_field: here we have the additional
+        # context that :affirm was also tried.
+        raise Err::FieldNotApplicable, <<~END
+          '#{raw_token}' : #{field} can be neither set explicitly nor affirmed
+          implicitly
+        END
+      end
+
+      raw_token << " " << (value_str = take!(:VALUE))
+      unmarshal_and_store_for_field( raw_token, value_str, field )
+    end
+
+    def parse_short_flag
+      raw_token = take!(:SHORT_FLAG)
+      token = raw_token.sub(SHORT_FLAG, '')
+
+      # handle -k=value
+      if token.include? SINGLE_TOKEN_KEY_VALUE_BOUNDARY
+        key, value_str = split_single_token_kv(token)
+        # single-token short flags may not specify multiple flags at once.
+        if key.length > 1
+          raise Err::BadSyntax, <<~END
+            '#{raw_token}' : cannot combine multiple short flags and '='
+            assignment
+          END
+        end
+        field = field_for_short_flag key
+        return unmarshal_and_store_for_field( raw_token, value_str, field )
+      end
+
+      # If it wasn't a single-token key-value pair, then this token must just
+      # be the key(s).
+      case token.chars.map(&:to_sym)
+      in []
+        # no keys should never happen
+        raise Err::BadSyntax, <<~END
+          '#{raw_token}' : no short flags given
+        END
+      in [sole_key]
+        # One key by itself (e.g. `[:c]` from "-c") can represent fields with
+        # two potential value representations:
+        #  - Implicit, where the flag receives a certain value that is
+        #    particular to the field's Type.
+        #    e.g. `[:c]` from "-c" affirming the boolean `:c` field to `true`.
+        #  - Explicit, where the value is taken from the following line token.
+        # For fields that support implicit affirmation we will never take the
+        # following line token to be the field's explicit value.
+        #
+        # This prohibition eliminates ambiguity in the command line grammar.
+        # Fields can still be implicitly affirmable and work with explicit
+        # values via the -k=v syntax.
+        field = field_for_short_flag sole_key
+        if field.value_type.respond_to? :affirmative
+          value = field.value_type.affirmative(field.list_of_default)
+          store_for_field(raw_token, value, field)
+        else
+          # Only for non-affirmable types will we take the next token as value.
+          raw_token << " " << (value_str = take!(:VALUE))
+          unmarshal_and_store_for_field( raw_token, value_str, field )
+        end
+      in [*keys]
+        # with multiple keys, they all must be settable implicitly
+        fields = keys.map { field_for_short_flag _1 }
+        misplaced = fields.reject { _1.value_type.respond_to? :affirmative }
+        unless misplaced.empty?
+          bad_flags = misplaced.map {
+            "-#{_1.toggles(CommandLine).short_flag}"
+          } .join(" and ")
+          raise Err::FieldNotApplicable, <<~END
+            '#{raw_token}' : #{bad_flags} can't be specified without a value
+          END
+        end
+        # Set all fields named by `keys` to their implicit affirmative values.
+        fields.map do |field|
+          value = field.value_type.affirmative(field.list_of_default)
+          store_for_field(raw_token, value, field)
+        end
+      end
+    end
+
+    def parse_positional
+      raw_token = take!
+      positional_stack = @config_view[:positionals].stack
+      if positional_stack.empty?
+        raise Err::DanglingValue, <<~END
+          '#{raw_token}' : no further values expected
+        END
+      end
+      field = positional_stack.pop
+      unless @config_view[:multi_minder].saturated_after_next? field
+        positional_stack.push field
+      end
+
+      unmarshal_and_store_for_field( raw_token, raw_token, field )
+
+      if toggles_of(field).command_selector
+        selected_subconfig = @config_view[:value_map][field.attribute_name]
+        unselected_subconfigs = (
+          @config_view[:subconfig_fields].map(&:attribute_name)
+                                         .select { selected_subconfig != _1 })
+
+        # Removing the submaps for unselected subconfigs signals to
+        # Types::Subconfig not to load them.
+        @config_view[:value_map].reject! { |k,v|
+          unselected_subconfigs.include? k
+        }
+
+        @config_view.enter selected_subconfig
+      end
+    end
+
+    #
+    # Parsing Helpers
+    #
+
+    def peek; @stream.peek; end
+    def take; @stream.take; end
+
+    # Take a required value.  If args are not empty, they are taken to be
+    # symbols naming consts in Recognizers, one of which must match the value.
+    def take!(*names)
+      case take
+      in []
+        suffix = names.join(' or ')
+        suffix = ", needed " + suffix unless suffix.empty?
+        raise Err::BadSyntax, <<~END
+          unexpected end of input#{suffix}
+        END
+      in [value]
+        if (names.empty? or
+            names.map { Recognizers.const_get _1 } .any? { _1 === value })
+          value
+        else
+          raise Err::BadSyntax, <<~END
+            unexpected #{value.inspect}, must be #{names.join(' or ')}
+          END
+        end
+      end
+    end
+
+    # properly split a token of the form "key=value"
+    def split_single_token_kv(token)
+        # If the delimiter appears more than once, the subsequent occurrences
+        # are just part of the value.  So, split the token into at most 2
+        # pieces: the key; and the value, equalses and all.
+        key_str, value_str = token.split SINGLE_TOKEN_KEY_VALUE_BOUNDARY, 2
+        [key_str.to_sym, value_str]
+    end
+
+    # Fetch the schema for the named field, or raise since we've encountered a
+    # key not in the schema.
+    def field_for(key)
+      true_schema = @config_view[:schema]
+      field_name_in_context(key) do |field_name|
+        config_schema = @config_view[:schema]
+        if !config_schema.field_defined? field_name
+          raise Err::NoSuchField, <<~END
+            #{true_schema} has no field :#{key}
+          END
+        end
+        return config_schema.field_get field_name
+      end
+    end
+
+    # Call the supplied block with the field name from raw_key, after
+    # temporarily advancing the ConfigView context down any path encoded in
+    # raw_key, e.g. :'a.b.field' or :field
+    def field_name_in_context(raw_key, &block)
+      keys = raw_key .to_s .split('.') .map(&:to_sym)
+      path = keys[0..-2]
+      field = keys.last
+
+      @config_view.subcontext(path) do
+        block.call field.to_sym
+      end
+    end
+
+    def field_for_short_flag(short_key)
+      key = @config_view[:shorts_to_longs][short_key]
+      if key.nil?
+        raise Err::AmbiguousName, <<~END
+          short flag -#{short_key} doesn't stand for anything
+        END
+      end
+      field_for key
+    end
+
+    def unmarshal_and_store_for_field(raw_token, value_str, field)
+      unless field.value_type.respond_to? :unmarshal
+        raise Err::FieldNotApplicable, <<~END
+          '#{raw_token}' : #{field} cannot be given an explicit value
+        END
+      end
+      # Parse and set the value, giving a nicer error message on parse
+      # failure than the type can give by itself.
+      begin
+        store_for_field(raw_token, field.value_type.unmarshal(value_str), field)
+      rescue Err::MarshalUnacceptable
+        raise $!.exception("'#{raw_token}' : " +
+          "#{field} cannot accept '#{value_str}' as a value: #{$!}")
+      end
+    end
+
+    def store_for_field(raw_token, value, field)
+      @config_view[:multi_minder].append(value, field, human_context: raw_token)
+    end
+
+    def toggles_of(field); field.toggles(CommandLine); end
+
+    # Mediates the interaction between the parser and the config, allowing for
+    # subconfigs to be handled transparently to the parsing logic.
+    class ConfigView
+      attr_accessor :root
+
+      def initialize(config_schema)
+        @root = ConfigContext.new
+        @root[:schema] = config_schema
+        @root[:value_map] = {}
+        @root[:multi_minder] = Internal::MultiValueMinder.new(@root[:value_map])
+        build_tree @root
+
+        @context = @root
+      end
+
+      def enter(name)
+        @context = @context.children.fetch name
+      end
+
+      def leave; @context = @context.parent; end
+
+      def subcontext(path, &block)
+        path.each { enter _1 }
+        block.call
+        path.each { leave }
+      end
+
+      def finalize
+        all_contexts.each do |context|
+          CommandLine.validate_config_postconditions context
+        end
+      end
+
+      def build_tree(context)
+        context.survey
+        CommandLine.validate_config_preconditions context
+        # Recur on all fields with internal config schemata.
+        context[:schema].fields_schema.select {
+          _1.const_defined?(:Config, NO_INHERIT)
+        }.each do |field_schema|
+          subname = field_schema.attribute_name
+
+          child = ConfigContext.new
+          child.parent = context
+          child[:schema] = field_schema::Config
+          context[:value_map][subname] = {}
+          child[:value_map] = context[:value_map][subname]
+          child[:multi_minder] = Internal::MultiValueMinder.new(
+            child[:value_map])
+          context.children[subname] = child
+
+          build_tree child
+        end
+      end
+
+      def all_contexts
+        Enumerator.new do |output|
+          queue = [@root]
+          while !queue.empty? do
+            context = queue.pop
+            output.yield context
+            queue.prepend(*context.children.values)
+          end
+        end
+      end
+
+      def [](...); @context.[](...); end
+      def []=(...); @context.[]=(...); end
+
+      context_sensitive_values = [
+        :schema,  # the schema of the config we're currently parsing into
+        :value_map,  # the map into which newly parsed values should be put
+        :multi_minder,  # manager of multi-value args, see MultiValueMinder
+        :positionals,  # see Positionals
+        :shorts_to_longs,  # map from 1-char short flags to full flag names
+        :command_field,  # the field that selects the command
+        :subconfig_fields, # subconfigs for commands
+      ]
+      class ContextSensitives < Struct.new(*context_sensitive_values)
+        def initialize
+          self.positionals = Positionals.new
+        end
+      end
+
+      class ConfigContext < Struct.new(:parent, :payload, :children)
+        def initialize
+          self.payload = ContextSensitives.new
+          self.children = {}
+        end
+
+        def survey
+          survey = Internal::ToggleSurvey.new(self[:schema], FieldToggles)
+          fetch = -> { self[:schema].field_get _1 }
+          # declare survey plan
+          shorts_to_longs = survey.canvas_for(:short_flag).values_to_owners
+          command_field = (
+            survey.canvas_for(:command_selector).name.map(&fetch).last)
+          positionals_schema = survey.canvas_for(:positional).names.map(&fetch)
+          subconfig_fields = (
+            survey.canvas_for(:command_subconfig) .names .map(&fetch))
+
+          # execute and unpack results
+          survey.fetch_results
+          self[:shorts_to_longs] = ~shorts_to_longs
+          self[:command_field] = ~command_field
+          self[:positionals].schema = ~positionals_schema
+          self[:subconfig_fields] = ~subconfig_fields
+        end
+
+        # Brackets give quick access to payload values without having them
+        # intermixed with metadata like #parent.
+        def [](...); self.payload.[](...); end
+        def []=(...); self.payload.[]=(...); end
+      end
+
+      # Schema of all the positional arguments in a context along with the
+      # stack of the next positionals to receive parsed values.
+      class Positionals < Struct.new(:schema, :stack)
+        def initialize
+          self.schema = []
+          self.stack = []
+        end
+        def schema=(schema_list)
+          super
+          self.stack = schema_list.reverse
+        end
+      end
+    end
+
+
+    # 'normally' a flag key and value are separated by being in separate tokens
+    # (--key value), but also offering a non-tokenizing delimiter (--key=value)
+    # allows for greater flexibility (e.g.  --testarg=--filter=foo).
+    SINGLE_TOKEN_KEY_VALUE_BOUNDARY = '='
+    # Specifying a field like `--no-field` asks the field's value type to
+    # produce its generic negative value.
+    NEGATORY_PREFIX = 'no-'
+
+    module Recognizers
+      # The types of command line tokens.
+      LONG_FLAG    = /^--(?=.)/
+      SHORT_FLAG   = /^-(?=[^-])/
+      END_OF_FLAGS = /^--$/
+      # Categorical
+      NON_VALUE    = Regexp.union(LONG_FLAG, SHORT_FLAG, END_OF_FLAGS)
+      VALUE        = -> { !(NON_VALUE === _1) }
+    end
+    include Recognizers
+  end
+
+  # Verify that the given field schema is not fundamentamentally incompatible
+  # with CommandLine parsing.
+  def self.approve_field(field_schema)
+    super
+    # If a field's name starts with :no_, then the convenience equivalence of
+    # dash and underscore makes this field ambiguous with the negation of a
+    # valid potential field name, e.g. :no_chance vs. negated :chance.
+    # Prohibiting fields that start with :no_ seems a small price to pay for a
+    # quick and non-bug-prone guarantee of unambiguity.
+    if field_schema.attribute_name.start_with? 'no_'
+      raise Err::PathologicalSchema, <<~END
+        field #{field_schema.name} conflicts with the `no-` negatory flag
+        prefix on the command line.
+      END
+    end
+  end
+
+  def self.validate_config_preconditions(context)
+    positionals_schema = context[:positionals].schema
+    # Positionals are inherently values without explicit keys; it doesn't
+    # make sense for positionals to only produce implicit values for explicit
+    # keys.
+    bads = positionals_schema.reject { _1.value_type.respond_to? :unmarshal }
+    unless bads.empty?
+      raise Err::FieldNotApplicable, <<~END
+        positional fields must take explicit values, unlike #{bads.join(', ')}
+      END
+    end
+    # It would be very confusing to get yelled at for a missing value in one
+    # positional, only to add a value and have it get consumed by a lurking
+    # optional before the required positional.
+    positionals_schema.each_cons(2) do |prior,later|
+      if !prior.required? and later.required?
+        raise Err::PathologicalSchema, <<~END
+          required positional #{later} cannot follow optional #{prior}
+        END
+      end
+    end
+    # If a positional field would never stop consuming values, then it must
+    # be the last positional.
+    first_endless = positionals_schema.find { _1.arity.endless? }
+    unless first_endless.nil? or first_endless == positionals_schema.last
+      inaccessibles = (positionals_schema.slice_after { first_endless == _1 }
+                                         .to_a.last.join(', '))
+      raise Err::PathologicalSchema, <<~END
+        #{first_endless} accepts any number of values, so #{inaccessibles}
+        will never receive values
+      END
+    end
+    # A command permanently changes out of the current config context, so any
+    # following positionals in this config are inaccessible.
+    command_field = context[:command_field]
+    unless command_field.nil? or command_field == positionals_schema.last
+      inaccessibles = (positionals_schema.slice_after(command_field)
+                                          .to_a.last.join(', '))
+      raise Err::PathologicalSchema, <<~END
+        positionals beyond the command selector will never receive values:
+        #{inaccessibles}
+      END
+    end
+  end
+
+  def self.validate_config_postconditions(context)
+    unless (bads = context[:multi_minder].incompletes).empty?
+      raise Err::IncompleteValue, <<~END
+         some fields were specified without enough values:
+         #{bads.join(', ')}
+      END
+    end
+  end
+end
+
+end
+end

data/lib/configuratrix/sources/environment.rb

@@ -0,0 +1,60 @@
+require_relative '../schema'
+
+module Configuratrix
+module Sources
+
+class Environment < Source
+  ready? { schema .const_defined? :PREFIX }
+
+  init { @env = ENV.to_hash }
+  parse { |config_schema|
+    @value_map = config_schema.subconfig_tree
+    parse_config(config_schema)
+  }
+
+  def parse_config(config_schema)
+    target_map = [
+      @value_map, *config_schema.subconfig_path ] .reduce { _1 .fetch _2 }
+
+    # Parse all the leaf fields in this config.
+    config_schema .fields_schema .map {
+      [ env_key(config_schema, _1.attribute_name), _1 ]
+    } .select { |key,field|
+      @env.key? key and field.value_type.respond_to? :unmarshal
+    } .each do |key,field|
+      value_str = @env .fetch key
+      begin
+        target_map[field.attribute_name] = field.value_type.unmarshal(value_str)
+      rescue Err::MarshalUnacceptable
+        raise $!.exception "ENV[ #{key} ] : #{field} " +
+                           "cannot accept '#{value_str}' as a value"
+      end
+    end
+
+    # Recur on subconfig fields.
+    config_schema .fields_schema .select {
+      _1.const_defined?(:Config, NO_INHERIT)
+    } .each do |field|
+      parse_config field::Config
+    end
+    @value_map
+  end
+
+  def env_key(config_schema, field_name)
+    (PREFIX.to_s +
+     [ *config_schema.subconfig_path, field_name ] .join('__')
+    ) .upcase .to_sym
+  end
+
+  # Set the prefix that will be prepended to field names when looking them up
+  # from the environment.  Setting this constant enables loading from the
+  # environment, use PREFIX = '' if you want the variable names to be the same
+  # as the (UPCASED) field names.
+  def self.prefix(str)
+    remove_const :PREFIX if const_defined? :PREFIX
+    const_set :PREFIX, str
+  end
+end
+
+end
+end