cli-dispatcher 1.1.12 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c29617c61e15163c0659136e753b0b0951b51c68a0a4dc4980d414b5ba249e
-  data.tar.gz: 727155a4945b77fccef856fa796403d61441f9f0361e66cdf961b109088dc523
+  metadata.gz: e946454a75a033c55b82ca4814654e27e75f8635ea02b42ad5fbd95a6cc7b4c8
+  data.tar.gz: f964e67077a8e2077a44db8b033d5a82be7fcbe10e9f2cad11504b6116e8397e
 SHA512:
-  metadata.gz: b06116458ead3b2f14799c97d9095621074679bfab4483b9de3465cb69dfa8aae50671949534e4e03638a1d1666f46762f92bb4fade081e983aaa71ce108679e
-  data.tar.gz: 5625718e2281259a478dea7efa64cdd75d11b4c28e792644ffe01dac8beea2f869fdc170ad9d698ae6a85f37401b520cb22d7efe3f420f1104263b06dca7fce8
+  metadata.gz: d93f6c815a777f40501094b84bc386178f8a45b20b6dccb4809667d3c7f855b2899a1aa48df04e9cc71eee43353b4105dd911ad1c422f187e276193aa75e8446
+  data.tar.gz: 6d81ee52b9cac75a9446b221b7b8c8edf767b5998146a87a14bfe0e9353e80ebfbb4b57ce639c3d2d7c1b7f5fb29c1bc809197b3d07aa71a7cfd7c355295eb99

data/lib/structured.rb

@@ -36,6 +36,8 @@ require 'yaml'
 # As a result, at the end of the initialization of a Structured object, it will
 # have instance variables set corresponding to all the defined elements.
 #
+# == Customization of Structured Classes
+#
 # The above explanation is default behavior, and several customizations are
 # available.
 #
@@ -58,6 +60,57 @@ require 'yaml'
 # Please read the documentation for Structured::ClassMethods for more on
 # defining expected elements, type checking, and so on.
 #
+# == Subfiles as Input
+#
+# The Structured class provides automatic support for separating inputs into
+# YAML subfiles. This is useful for including complex objects in a file. Two
+# types of subfile inputs are supported: those for object hashes, and those for
+# arrays.
+#
+# To include a subfile as part of an object hash, include the key `read_file` in
+# the hash, with the value being the file to be read. (Other keys besides
+# `read_file` may be included.) The subfile should itself contain YAML for a
+# hash with further keys for the object.
+#
+# To include multiple subfiles in an array, set the first element of the array
+# to the string `read_file`, and then the other elements of the array should be
+# filenames. These subfiles should contain YAML for arrays.
+#
+# Consider a Structured object for a book, containing elements for the title,
+# subtitle, and an array of authors. The input file could look like this:
+#
+#   ---
+#   title: A Book
+#   subtitle: Containing Many Pages
+#   author:
+#     - John Q. Public
+#     - Jane Doe
+#
+# Using the subfile feature, the input file could instead look like:
+#
+#   ---
+#   title: A Book
+#   read_file: subtitle_file.yaml
+#   author:
+#     - read_file
+#     - author_file.yaml
+#
+# This would instruct Structured to read hash keys out of `subtitle_file.yaml`,
+# and to read array elements out of `author_file.yaml`. These two files, in
+# turn, should look like:
+#
+#   # subtitle_file.yaml
+#   ---
+#   subtitle: Containing Many Pages
+#
+#   # author_file.yaml
+#   ---
+#   - John Q. Public
+#   - Jane Doe
+#
+# When incorporated, Structured will combine these subfiles as if they were a
+# single object specification.
+#
 module Structured
 
   #
@@ -172,7 +225,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 +266,7 @@ module Structured
     def reset_elements
       @elements = {}
       @default_element = nil
+      @default_key = nil
       @class_description = nil
     end
 
@@ -266,14 +321,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 +457,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 +504,68 @@ module Structured
       end
     end
 
-    # Deals with a nil value (either because no value was given, or because a
-    # preproc deleted it).
+    def try_read_array(filenames)
+      new_item = []
+      begin
+        filenames.each do |file|
+          begin
+            res = YAML.load_file(file)
+            raise InputError unless res.is_a?(Array)
+            new_item.concat(res)
+          rescue
+            input_err("Failed to read array from #{file}: #$!")
+          end
+        end
+      end
+      return new_item
+    end
+
+    #
+    # 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 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
+
     #
-    # * If val is non-nil, then this method returns false.
+    # 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
@@ -504,6 +602,7 @@ module Structured
       when Array
         input_err("#{item} is not Array") unless item.is_a?(Array)
         Structured.trace(Array) do
+          item = try_read_array(item[1..-1]) if item.first.to_s == 'read_file'
           return item.map.with_index { |i, idx|
             Structured.trace(idx) do
               convert_item(i, type.first, parent)
@@ -542,12 +641,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 +672,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 +717,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.1
 platform: ruby
 authors:
 - Charles Duan
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 2024-12-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Library for creating command-line programs that accept commands. Also
@@ -28,7 +28,8 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/charlesduan/cli-dispatcher
-post_install_message: 
+  documentation_uri: https://rubydoc.info/gems/cli-dispatcher/
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -43,8 +44,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: Command-line command dispatcher
 test_files: []