configuratrix 0.0.1.alpha

data/lib/configuratrix/sources/yaml_file.rb

@@ -0,0 +1,506 @@
+require_relative '../schema'
+require 'psych'
+
+module Configuratrix
+module Sources
+
+class YamlFile < Source
+  ready? { |sources|
+    (@stream or
+     sources.any? { _1.schema.toggles(YamlFile).file_path_field }
+    )
+  }
+
+  cross_configure { |sources|
+    return if @stream
+    # Find the source that might have our path to the yaml file, as well as the
+    # config path to the specific field that holds the file path.
+    path_source = sources.find { _1.schema.toggles(YamlFile).file_path_field }
+    file_path_field_path = (
+      path_source.schema.toggles(YamlFile).file_path_field
+                 .split('.').map(&:to_sym)
+    )
+    # If the source doesn't have a file path for us, we'll have to wait until
+    # we receive the config schema in the parse step to extract the default
+    # path.
+    @file_path = if path_source.key? file_path_field_path
+                   path_source.get file_path_field_path
+                 else
+                   -> { _1[*file_path_field_path].default_value }
+                 end
+  }
+
+  parse { |config_schema|
+    # If we didn't get the file path from an explicit value, extract the
+    # default from config_schema.
+    @file_path = @file_path.call(config_schema) if @file_path .respond_to? :call
+    @location = Location.new @file_path
+    @stream = File.open @file_path if @stream.nil?
+
+    @value_map = {}
+    # Let Psych handle the actual yaml parsing, we'll just follow along with
+    # the parser events.
+    begin
+      Psych::Parser.new(
+        EventHandler.new(
+          config_schema, @value_map, @location
+        )
+      ) .parse @stream
+    rescue Psych::SyntaxError
+      raise Err::BadSyntax, $!.to_s
+    rescue NoMatchingPatternError
+      raise Err::BadSyntax, <<~RANT_OVER
+        #{@location}: :#{$!} cannot appear in this part of a YamlFile
+      RANT_OVER
+    end
+    # Clean up.
+    @stream.close
+    @value_map
+  }
+
+  TOGGLES = [
+    # The config path to the field containing the yaml file path for YamlFile.
+    :file_path_field,
+  ]
+  class SourceToggles < Internal::ToggleStruct[*TOGGLES]
+    def file_path_field=(...); reject_unless super, matches: A::STRING; end
+  end
+
+  # Shell class for routing parser events to the appropriate State handlers.
+  class EventHandler < Psych::Handler
+    def initialize(config_schema, output, location)
+      @location = location
+      # Event recording and replay supports YAML aliases.
+      @macros = MacroMeister.new self, location
+      # The parse stack dictates which State the current event should be routed
+      # to.
+      @the_stack = [ State::Root.new(
+          config_schema,
+          output,
+          location,
+          @macros,
+      ) ]
+    end
+
+  private
+
+    # Psych provides many events, but we only need to hear about these.
+    RELEVANT_EVENTS = [ :scalar, :start_mapping, :end_mapping, :start_sequence,
+                        :end_sequence, :alias, :start_document, :end_document ]
+    Event = Struct.new(:name, :data) do
+      # Ruby has no native deep copy mechanism, but failure to copy deeply
+      # results in seemingly dup'd Events actually sharing a data struct.
+      def dup; o = super; o.data = o.data.dup; o; end
+    end
+
+    # Each kind of event has its own set of data.
+    VectorData = Struct.new(:anchor, :tag, :implicit, :style)
+    ScalarData = Struct.new(:value, :anchor, :tag, :plain, :quoted, :style)
+    AliasData = Struct.new(:reference)
+    DocumentData = Struct.new(:version, :tag_directives, :implicit)
+    def self.no_data; []; end
+    def self.ignore_data(...); []; end
+
+    MAKE_EVENT_DATA = {
+      start_mapping: (VectorData.method :new),
+      end_mapping: (method :no_data),
+      start_sequence: (VectorData.method :new),
+      end_sequence: (method :no_data),
+      scalar: (ScalarData.method :new),
+      alias: (AliasData.method :new),
+      start_document: (DocumentData.method :new),
+      end_document: (method :ignore_data),
+    }
+
+    # Initial entry point for events handed down from Psych.  Events replayed
+    # as part of macros don't pass through here, they go directly to #offer.
+    def receive(event)
+      # Don't allow tags anywhere to reduce potential confusion since they have
+      # no effect.
+      if event.data.respond_to? :tag and event.data.tag
+        raise Err::BadSyntax, <<~RANT_OVER
+          explicit tags are not allowed: type info comes from config schema
+        RANT_OVER
+      end
+      # has no effect if no macros are being recorded right now
+      @macros.record event
+      # Offer the event back to this handler, resolving any aliases and
+      # offering their complete macros as applicable.
+      @macros.offer event
+    end
+
+  public
+
+    # Delegate control of the parser for this event to the State at the top of
+    # the stack.
+    def offer(event)
+      loop do
+        memos = []
+        # Take the state at the top of the stack, give it the event, and let it
+        # decide what states should replace it on the stack.
+        @the_stack.push(
+          *@the_stack.pop.receive_event(event, memos))
+
+        # If the current state rejected the event, we'll give it to the new top
+        # of the stack.
+        break unless memos .include? :reject_event!
+        raise "stuck!" if @the_stack == @stack_checkpoint
+        @stack_checkpoint = @the_stack.dup
+      end
+    end
+
+    def inspect; "#<#{self.class.name}:#{object_id}>"; end
+
+    # Hook up all the Psych::Handler methods so Parser can send us events.
+    RELEVANT_EVENTS.each do |name|
+      define_method name do |*data|
+        event = Event.new(
+          name,
+          MAKE_EVENT_DATA[name].call(*data),
+        )
+        receive event
+      end
+    end
+    # Pass Psych's location updates directly to our location handler.
+    def event_location(...); @location.update(...); end
+
+  end
+
+  # Keep track of where the parser is in the file, including whether the
+  # current event is being replayed from a previous point in the file via a
+  # macro.
+  Location = Struct.new(
+    :path,
+    :start_line, :start_column, :end_line, :end_column,
+    :alias_of
+  ) do
+    def update(*args)
+      (self.start_line, self.start_column, self.end_line, self.end_column
+      ) = args
+    end
+    # All we ever need to actually do with the location is show it to the user.
+    def to_s(omit_path: nil)
+      path = self.path || "<YAML>" unless omit_path
+      str = [ path, start_line+1, start_column+1 ] .join ':'
+      str << " (copied from #{alias_of.to_s omit_path: true})" if alias_of
+      str
+    end
+  end
+
+  # Parser events are handled by a state machine, each different behavior being
+  # handled by a distinct State subclass.
+  class State
+    # States generally need to know where parsing is, what bit of schema
+    # they're parsing for, whom to tell about new macros needing recording, and
+    # where to hand retrieved values off to.
+    def initialize(location: nil, schema: nil, macros: nil, minder: nil)
+      @location = location if location
+      @schema = schema if schema
+      @macros = macros if macros
+      @value_minder = minder if minder
+    end
+
+    # Where it all begins. . . at last!
+    class Root < State
+      def initialize(config_schema, output_map, location, macros)
+        @steps = [ :preamble, :build, :output ]
+        @config_schema = config_schema
+        @output_map = output_map
+        @location = location
+        @macros = macros
+      end
+      def receive_event(event, memos)
+        case event.name
+        # The root object of a yamlfile must be a map, which is to say a config!
+        in :start_mapping
+          assert_step :build; next_step!
+          # We are just making sure that the root of the yaml file is a config,
+          # now we can hand off to the general config handler.
+          memos << :reject_event!
+          @value_minder = Internal::MultiValueMinder.new
+          [ self,
+            substate(GetConfig, schema: @config_schema, minder: @value_minder)
+          ]
+        in :start_document unless this_step == :preamble
+          bad_syntax! "YamlFile may not contain multiple documents!"
+        in :start_document
+          next_step!
+          unless event.data.tag_directives.empty?
+            # *we* are the schema; allowing tag directives would be confusing
+            # since they'd have no effect.
+            bad_syntax! "tag directives not permitted!"
+          end
+          [ self ]
+        in :end_document
+          assert_step :output; next_step!
+          # If the document is over, then GetConfig must be done populating the
+          # value minder for us.
+          @output_map.update @value_minder.value_map
+        end
+      end
+    end
+
+    # Turn a yaml map into a config!
+    class GetConfig < State
+      def initialize(...); super; @steps = [ :open, :collect_pairs ]; end
+      def receive_event(event, memos)
+        case event.name
+        in :start_mapping if this_step == :open
+          next_step!
+          @anchor = @macros.open_macro? event
+          [ self ]
+        in :scalar | :start_mapping | :start_sequence
+          assert_step :collect_pairs
+          # Other than handling the opening and closing of the map, the rest is
+          # up to the field getter.
+          memos << :reject_event!
+          [ self,
+            substate(GetKey),
+          ]
+        in :end_mapping
+          assert_step :collect_pairs; next_step!
+          # Now that the config is done, double-check that no values were
+          # partially specified.
+          unless (bads = @value_minder.incompletes).empty?
+            raise Err::IncompleteValue, <<~RANT_OVER
+              some fields were specified without enough values:
+              #{bads.join(', ')}
+            RANT_OVER
+          end
+          @macros.close_macro @anchor if @anchor
+          []
+        end
+      end
+    end
+
+    # Locate the schema for the field whose value is coming up next.
+    class GetKey < State
+      def initialize(...); super; @steps = [ :get ]; end
+      def receive_event(event, memos)
+        case event.name
+        in :scalar
+          assert_step :get; next_step!
+          @macros.macro? event
+          # Yaml gives us a string, we get the field schema it names.
+          key = event.data.value.to_sym
+          field_schema = @schema.field_get key
+          # Yaml allows repeat keys, but we don't want the ambiguity.  If a
+          # field needs multiple values, they will be provided via a yaml
+          # sequence.
+          if @value_minder.value_map.key? key
+            raise Err::DanglingValue, <<~RANT_OVER
+              #{@location}: #{field_schema} already specified!
+            RANT_OVER
+          end
+          # Now we have a proper field schema to give to the value getter.
+          [ substate(GetFieldValue,
+                     schema: field_schema),
+          ]
+        in :start_mapping | :start_sequence
+          bad_syntax! "YamlFile map keys must be strings!"
+        end
+      end
+    end
+
+    # Load the value for a field's @schema.
+    class GetFieldValue < State
+      def initialize(...); super; @steps = [ :get ]; end
+      def receive_event(event, memos)
+        assert_step :get; next_step!
+        case event.name
+        in :scalar
+          @macros.macro? event
+          field_value event.data.value
+          []
+        in :start_sequence
+          memos << :reject_event!
+          [ substate(GetSequenceField) ]
+        in :start_mapping
+          # A map as a value must be a subconfig, so we just need to make way
+          # for GetConfig.
+          unless @schema.const_defined?(:Config, NO_INHERIT)
+            bad_syntax! "#{@schema.attribute_name} is not a subconfig!"
+          end
+          memos << :reject_event!
+          @value_minder.append({}, @schema, human_context: @location.to_s)
+          [ substate(GetConfig,
+                     schema: @schema::Config,
+                     minder: Internal::MultiValueMinder.new(
+                       @value_minder.value_map[@schema.attribute_name])),
+          ]
+        end
+      end
+    end
+
+    # Populate a plural field with values from a yaml sequence.
+    class GetSequenceField < State
+      def initialize(...); super; @steps = [ :open, :collect ]; end
+      def receive_event(event, memos)
+        case event.name
+        in :start_sequence unless this_step == :open
+          bad_syntax! "no nested lists!"
+        in :start_sequence
+          assert_step :open; next_step!
+          # Can this field even accept a sequence?
+          unless @schema.arity.demands_plurality?
+            raise Err::FieldNotApplicable, <<~RANT_OVER
+              #{@location}: #{@schema} does not take multiple values!
+            RANT_OVER
+          end
+          @anchor = @macros.open_macro? event
+          [ self ]
+        in :end_sequence
+          # Got all the values, was it enough?
+          assert_step :collect; next_step!
+          unless @value_minder.satisfied?(@schema)
+            raise Err::IncompleteValue, <<~RANT_OVER
+              #{@schema} requires #{@schema.arity.begin} values
+            RANT_OVER
+          end
+          []
+        in :scalar
+          @macros.macro? event
+          # repeatedly calling field_value allows the multi-value minder to
+          # handle combining the values.
+          field_value event.data.value
+          [ self ]
+        end
+      end
+    end
+
+    # General State functions available to all states.
+
+    # Unmarshal an individual field value and give it to the minder to store it
+    # appropriately.  Also, gracefully handle unmarshal failures.
+    def field_value(value_string)
+      unless @schema.value_type.respond_to? :unmarshal
+        bad_syntax! <<~RANT_OVER
+          #{@schema} cannot be take its value from a string!
+        RANT_OVER
+      end
+      @value_minder.append(
+        @schema.value_type.unmarshal(value_string),
+        @schema,
+        human_context: @location.to_s,
+      )
+    rescue Err::MarshalUnacceptable
+      raise subexception $!, <<~RANT_OVER
+        #{@location}:
+        #{@schema} cannot accept '#{value_string}' as a value: #{$!}
+      RANT_OVER
+    end
+    # Create a new state of the given class, passing down our instance
+    # variables for any values not explicitly given to the initializer.
+    def substate(state_class, *args, **kwargs)
+      location, schema, macros, minder = [
+        @location, @schema, @macros, @value_minder
+      ]
+      sub = state_class.new(*args, **kwargs)
+      sub.instance_exec do
+        @location ||= location; @schema ||= schema; @macros ||= macros
+        @value_minder ||= minder
+      end
+      sub
+    end
+    # Guard against bugs by asserting the order in which events should arrive
+    # at a state.
+    def this_step; @steps.first; end
+    def next_step!; @steps.shift; end
+    def assert_step(step); fail if this_step != step; end
+
+    def subexception(superexception, message)
+      message = message.lines(chomp: true).join(' ').strip
+      superexception.exception message
+    end
+
+    def bad_syntax!(chide="bad syntax")
+      raise Err::BadSyntax, <<~END
+        #{chide} @ #{@location}
+      END
+    end
+  end
+
+  # Recording, storing, and replaying macros.
+  class MacroMeister
+    def initialize(event_handler, location)
+      @event_handler = event_handler
+      @handler_location = location
+      @pending_macros = []
+      @macros = {}
+    end
+
+    # Let States pass any ol' event down to us and not worry about whether it's
+    # actually relevant to macro recording.
+    def open_macro?(event)
+      open_macro event if event.data.anchor
+      event.data.anchor
+    end
+
+    def open_macro(event)
+      @pending_macros.push [ Step.from_raw(event, @handler_location) ]
+    end
+
+    def close_macro(name); @macros[name] = @pending_macros.pop; end
+
+    # Scalars are just one event, so don't make States call open and close
+    # right after one another for a scalar.  See #open_macro?
+    def macro?(event)
+      return unless event.data.anchor
+      open_macro event
+      close_macro event.data.anchor
+    end
+
+    # Add the current parser event to any macros currently being recorded.
+    def record(event)
+      return if @pending_macros.empty?
+      step = Step.from_raw(event, @handler_location)
+      @pending_macros.each { _1 << step }
+    end
+
+    # Satisfy a yaml alias by replaying the events associated with the named
+    # anchor.
+    def replay(anchor)
+      unless @macros.key? anchor
+        raise Err::BadReference, <<~RANT_OVER
+          cannot alias nonexistant anchor #{anchor} @ #{@handler_location}
+        RANT_OVER
+      end
+      original_alias = @handler_location.alias_of
+
+      @macros .fetch(anchor) .each do |step|
+        @handler_location.alias_of = step.location
+        offer step.event
+      end
+
+      @handler_location.alias_of = original_alias
+    end
+
+    # Wrapper around EventHandler#offer, transparently replacing yaml alias
+    # events with the appropriate macro contents.
+    def offer(event)
+      if event.name == :alias
+        replay event.data.reference
+      else
+        @event_handler.offer event
+      end
+    end
+
+    # At every step in a macro, we need to know what we're replaying, and where
+    # that event originally came from.
+    Step = Struct.new(:event, :location) do
+      # Prevent spurious macro re-recording on playback by stripping anchors
+      # before recording.
+      def self.from_raw(event, location)
+        o = new
+        o.event = event.dup
+        o.event.data.anchor = nil if o.event.data.respond_to? :anchor
+        o.location = location.dup
+        o
+      end
+    end
+  end
+
+end
+
+end
+end

data/lib/configuratrix/sources.rb

@@ -0,0 +1,64 @@
+require_relative 'schema'
+require_relative 'sources/command_line'
+require_relative 'sources/environment'
+begin
+  require_relative 'sources/yaml_file'
+rescue LoadError; end
+
+module Configuratrix
+
+module Sources
+  # Source that's always ready but never has values.  Used for signaling that
+  # it's actually desired to have no viable sources over just misconfiguring no
+  # sources.
+  class Dummy < Source
+    ready? { true }
+    parse  {}
+    key?   { false }
+    get    {  undefined! _1 }
+  end
+
+  # Source that relies entirely on Souce::BaseBehaviors.  By default it's
+  # essentially Dummy with extra steps.
+  # Having #parse set @value_map to something hashy makes for a nice testing
+  # source.
+  class Blank < Source
+  end
+end
+
+# Modules in the Configuratrix::Mutable namespace may be modified by client
+# code wishing to personalize global defaults.
+#
+# This must never be done in library code because it disturbs preconditions.
+# Mutable changes will affect all subsequent schema definitions and
+# modifications.  Additionally when modifying DefaultSources, the subsequent
+# loading of all configs is affected.
+#
+# Customization can be cleanly accomplished by `require`ing a short file with a
+# script author's preferences alongside the `require` for Configuratrix.
+module Mutable
+
+  # Every constant defined in this module is added by default to lists of Sources.
+  module DefaultSources
+    CommandLine = Sources::CommandLine
+    YamlFile = Sources::YamlFile if Sources.const_defined? :YamlFile
+    Environment = Sources::Environment
+
+    def self.add(source_class)
+      const_set source_class.const_name, source_class
+    end
+  end
+
+  # Every constant defined in this module is available for inclusion and
+  # customization in a config.  `source :dummy` will resolve to the Dummy below.
+  module BuiltinSources
+    Dummy = Sources::Dummy
+    Blank = Sources::Blank
+
+    def self.add(source_class)
+      const_set source_class.const_name, source_class
+    end
+  end
+
+end
+end

data/lib/configuratrix/types.rb

@@ -0,0 +1,121 @@
+require_relative 'schema'
+require 'set'
+
+module Configuratrix
+
+module Types
+  class String < Type
+    recognize? {  _1 .is_a? ::String or _1.nil? }
+    # Many types may want to recognize nil, but only String should claim it.
+    claim_all_recognized
+
+    parse { _1.to_s }
+  end
+
+  class Symbol < Type
+    recognize? { _1 .is_a? ::Symbol }
+    claim_all_recognized
+
+    parse { _1.to_sym }
+  end
+
+  class Int < Type
+    recognize? {  _1 .is_a? ::Integer }
+    claim_all_recognized
+
+    parse { 
+      # Ruby will detect radix quite nicely automatically, but it also includes
+      # '0' as a prefix for octal which is too much of a gotcha for just
+      # happening to pass 0100 instead of 100.
+      radix = 10
+      radix = 16 if /^-?0x/i =~ _1
+      radix = 2  if /^-?0b/i =~ _1
+      Integer(_1, radix, exception: false) or nope! "not integer!"
+    }
+  end
+
+  class Float < Type
+    recognize? { _1 .is_a? ::Float }
+    claim_all_recognized
+
+    parse { Float(_1, exception: false) or nope! "not float!" }
+  end
+
+  class Bool < Type
+    # enables `--boolfield`
+    affirm { true }
+    # enables `--no-boolfield`
+    negate { false }
+
+    recognize? { _1 == true or _1 == false }
+    claim_all_recognized
+
+    # covers `--boolfield=value`
+    parse {
+      case _1
+      when /^(true|t|yes|y|1)$/i
+        true
+      when /^(false|f|no|n|0)$/i
+        false
+      else
+        nope! "true or false!"
+      end
+    }
+  end
+
+  class Enum < Type
+    def self.enum_symbols; @values ||= Set.new; end
+
+    recognize? { enum_symbols.include? _1 }
+    parse {
+      value = _1.downcase.to_sym
+      if enum_symbols.include? value
+        value
+      else
+        nope! "not in #{enum_symbols}!"
+      end
+    }
+  end
+
+  class Subconfig < Type
+    recognize? { _1 .is_a? Configuratrix::Config }
+
+    # A subconfig is no ordinary field; we can't simply parse it all in one go.
+    # We have to construct a subconfig object to recur on all its fields.
+    def self.take_value_for(field, from:)
+      sources = from
+      key = [ *field.schema.subconfig_path, field.schema.attribute_name ]
+      if sources.none? { _1.key? key }
+        []
+      else
+        [ field.schema::Config.new(field.containing_config) ]
+      end
+    end
+  end
+end
+
+# Modules in the Configuratrix::Mutable namespace may be modified by client
+# code wishing to personalize global defaults.
+#
+# This must never be done in library code because it disturbs preconditions.
+# Mutable changes will affect all subsequent schema definitions and
+# modifications.
+#
+# Customization can be cleanly accomplished by `require`ing a short file with a
+# script author's preferences alongside the `require` for Configuratrix.
+module Mutable
+
+  # Every constant defined in this module is added by default to lists of Types.
+  module DefaultTypes
+    include Types
+
+    def self.add(source_class)
+      const_set source_class.const_name, source_class
+    end
+  end
+
+  # The type that an untyped field implicitly uses.
+  DefaultType = DefaultTypes::String
+
+end
+end

data/lib/configuratrix.rb

@@ -0,0 +1,12 @@
+require_relative 'configuratrix/initialize'
+# Look here for the statements you can make when defining a configuration for
+# your script.
+require_relative 'configuratrix/language'
+# Config and the other base classes that define a blank generic config.
+require_relative 'configuratrix/schema'
+# Built-in means of loading and organizing values to put into fields.
+require_relative 'configuratrix/sources'
+# Built-in means of translating strings into values for fields.
+require_relative 'configuratrix/types'
+# All the Error classes particular to this library.
+require_relative 'configuratrix/errors'