cli-dispatcher 1.1.12 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c29617c61e15163c0659136e753b0b0951b51c68a0a4dc4980d414b5ba249e
-  data.tar.gz: 727155a4945b77fccef856fa796403d61441f9f0361e66cdf961b109088dc523
+  metadata.gz: 850d024672db8785ec7d329961a30baf9e8d4f1724189f6cf6250472cc17e5e8
+  data.tar.gz: 11e2ab38ddd9cc99d7ec2b66bf4b97d229a470ded4295ef2e7ecddca99bca74e
 SHA512:
-  metadata.gz: b06116458ead3b2f14799c97d9095621074679bfab4483b9de3465cb69dfa8aae50671949534e4e03638a1d1666f46762f92bb4fade081e983aaa71ce108679e
-  data.tar.gz: 5625718e2281259a478dea7efa64cdd75d11b4c28e792644ffe01dac8beea2f869fdc170ad9d698ae6a85f37401b520cb22d7efe3f420f1104263b06dca7fce8
+  metadata.gz: 3f5a3f85f1f64785b526df560efe2ef2ee94b031d0ef9bd47d43fd6500eaf4faba0b70a6230d1ccbc49db4d9a8d0681a1ba17edd847c105ab0b8d106568ccb2f
+  data.tar.gz: e6c3a31bd0825b3ae234dd68b6432e5a5b7f0fe4daf76a9494545018d264615630f89368b1c352d950be23a66be76e36fa5a3059bb38ad411d37f91912480f5a

data/lib/structured.rb

@@ -172,7 +172,8 @@ module Structured
   # raises an error, but classes may override this method to use the undefined
   # elements.
   #
-  # @param element The unknown element name, converted to a symbol.
+  # @param element The unknown element name. For a YAML file, this is typically
+  # a string.
   #
   # @param val The value associated with the unknown element.
   #
@@ -212,6 +213,7 @@ module Structured
     def reset_elements
       @elements = {}
       @default_element = nil
+      @default_key = nil
       @class_description = nil
     end
 
@@ -266,14 +268,32 @@ module Structured
 
     #
     # Accepts a default element for this class. The arguments are the same as
-    # those for element_data.
+    # those for element_data except as noted below.
     #
-    # **Caution**: The type argument should almost always be a single class, and
-    # not a hash. This is because the default arguments are automatically
+    # If this method is called, then for any keys found in an input hash that
+    # have no corresponding #element declaration in the Structured class, the
+    # method receive_any will be invoked. The value from the input hash
+    # will be processed based on any type declaration, `preproc`, and `check`
+    # given to default_element.
+    #
+    # The default element keys can be processed based on the argument `key`,
+    # which should be a hash corresponding to the element_data arguments plus
+    # the key :type with the default key's expected type. If `key` is not given,
+    # then the key must be and is automatically converted to a Symbol.
+    #
+    # **Caution**: The `type` argument should almost always be a single class,
+    # and not a hash. This is because the default arguments are automatically
     # treated like a hash, with the otherwise-undefined element names being the
     # keys of the hash.
     #
     def default_element(*args, **params)
+      if (key_params = params.delete(:key))
+        @default_key = element_data(
+          key_params.delete(:type) || Object, key_params
+        )
+      else
+        @default_key = element_data(Symbol, preproc: proc { |s| s.to_sym })
+      end
       @default_element = element_data(*args, **params)
     end
 
@@ -384,47 +404,28 @@ module Structured
       input_err("Initializer is not a Hash") unless hash.is_a?(Hash)
       hash = try_read_file(hash)
 
-      @elements.each do |elt, data|
-        Structured.trace(elt.to_s) do
-          val = hash[elt] || hash[elt.to_s]
-          next if process_nil_val(obj, elt, val, data)
-
-          if data[:preproc]
-            val = try_run(data[:preproc], obj, val, "preproc")
-            next if process_nil_val(obj, elt, val, data)
-          end
-
-          cval = convert_item(val, data[:type], obj)
-
-          # Check for validity after preproc and conversion are run
-          if data[:check] && !try_run(data[:check], obj, cval, "check")
-            input_err "Value #{cval} failed check for #{elt}"
-          end
-
-          # Use the converted value
-          apply_val(obj, elt, cval)
+      @elements.each do |key, data|
+        Structured.trace(key.to_s) do
+          val = hash[key] || hash[key.to_s]
+          cval = process_value(obj, val, data)
+          apply_val(obj, key, cval) if cval
         end
       end
 
       # Process unknown elements
-      unknown_elts = (hash.keys.map(&:to_sym) - @elements.keys)
-      return if unknown_elts.empty?
+      unknown_keys = hash.keys.reject { |k| @elements.include?(k.to_sym) }
+      return if unknown_keys.empty?
       unless @default_element
-        input_err("Unexpected element(s): #{unknown_elts.join(', ')}")
+        input_err("Unexpected element(s): #{unknown_keys.join(', ')}")
       end
-      unknown_elts.each do |elt|
-        Structured.trace(elt.to_s) do
-          de = @default_element
-          val = hash[elt] || hash[elt.to_s]
-          if de[:preproc]
-            val = try_run(de[:preproc], obj, val, "default preproc")
-          end
-          item = convert_item(val, de[:type], obj)
-          if de[:check] && !try_run(de[:check], obj, item, "check")
-            input_err "Value #{item} failed default element check"
-          end
-          item.receive_key(elt) if item.is_a?(Structured)
-          obj.receive_any(elt, item)
+      unknown_keys.each do |key|
+        Structured.trace(key.to_s) do
+          val = hash[key]
+          ckey = process_value(obj, key, @default_key)
+          cval = process_value(obj, val, @default_element)
+          next unless cval
+          cval.receive_key(ckey) if cval.is_a?(Structured)
+          obj.receive_any(ckey, cval)
         end
       end
     end
@@ -450,24 +451,53 @@ module Structured
       end
     end
 
-    # Deals with a nil value (either because no value was given, or because a
-    # preproc deleted it).
+
+    #
+    # Given an element value and an #element_data hash of processing tools
+    # element, applies those processing tools. Namely, apply any preproc, check
+    # the type and perform other checks, and perform any conversions. The return
+    # value should be usable as the received value for the corresponding
+    # element.
     #
-    # * If val is non-nil, then this method returns false.
+    # If this method returns nil, then there is no element to process. This
+    # method may also raise an InputError.
+    #
+    def process_value(obj, val, data)
+      val, ret = process_nil_val(val, data)
+      return val if ret
+      if data[:preproc]
+        val = try_run(data[:preproc], obj, val, "preproc")
+        val, ret = process_nil_val(val, data)
+        return val if ret
+      end
+
+      cval = convert_item(val, data[:type], obj)
+      if data[:check] && !try_run(data[:check], obj, cval, "check")
+        input_err "Value #{cval} failed check"
+      end
+      return cval
+    end
+
+    #
+    # Performs processing of an element value to deal with the possibility that
+    # the value is nil. This method returns [ the new value, boolean of whether
+    # to stop processing ] according to the following rules:
+    #
+    # * If val is non-nil, then this method returns val itself, and processing
+    #   should not stop.
     # * If val is nil and this element is non-optional, then this method raises
     #   an error.
-    # * If val is nil and the element is optional, *and* the element has a
-    #   default value, then the object has the default value applied to the
-    #   element.
-    # * In any event, if val is nil and the element is optional, returns true
-    #   which should signal to the caller to stop further processing of the
-    #   element.
-    #
-    def process_nil_val(obj, elt, val, data)
-      return false if val
-      input_err("Missing (or preproc deleted) #{elt}") unless data[:optional]
-      apply_val(obj, elt, data[:default]) unless data[:default].nil?
-      return true
+    # * If val is nil and the element is optional, then the object's default
+    #   value is returned, and processing should stop.
+    # * If there is no default value for an optional element, then nil is
+    #   returned, and processing should also stop.
+    #
+    def process_nil_val(val, data)
+      return [ val, false ] if val
+      unless data[:optional]
+        input_err("Required element is missing (or was deleted by a preproc)")
+      end
+      return [ data[:default], true ]
     end
 
     # Applies a value to an element for an object, after all processing for the
@@ -542,12 +572,22 @@ module Structured
       end
     end
 
+    #
+    # Several types can be automatically converted:
+    #
+    # * Symbol into String
+    # * String into Regexp
+    #
     def try_autoconvert(type, item)
 
       if type == String && item.is_a?(Symbol)
         return item.to_s
       end
 
+      if type == Symbol && item.is_a?(String)
+        return item.to_sym
+      end
+
       # Special case in which strings will be converted to Regexps
       if type == Regexp && item.is_a?(String)
         begin
@@ -563,7 +603,11 @@ module Structured
     # Receive hash values that are to be converted to Structured objects
     def convert_structured(item, type, parent)
       unless item.is_a?(Hash)
-        input_err("#{item.inspect} not a #{type} or Structured hash")
+        if type.include?(Structured)
+          input_err("#{item.inspect} not a Structured hash for #{type}")
+        else
+          input_err("#{item.inspect} not a #{type}")
+        end
       end
 
       unless type.include?(Structured) || type.include?(StructuredPolymorphic)
@@ -604,7 +648,8 @@ module Structured
 
       if @default_element
         io.puts(
-          "  All other elements: #{describe_type(@default_element[:type])}"
+          "  All other elements: #{describe_type(@default_key[:type])} => " \
+          "#{describe_type(@default_element[:type])}"
         )
         if @default_element[:description]
           io.puts(TextTools.line_break(

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cli-dispatcher
 version: !ruby/object:Gem::Version
-  version: 1.1.12
+  version: 1.2.0
 platform: ruby
 authors:
 - Charles Duan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 2024-11-15 00:00:00.000000000 Z
 dependencies: []
 description: |
   Library for creating command-line programs that accept commands. Also