cli-dispatcher 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 850d024672db8785ec7d329961a30baf9e8d4f1724189f6cf6250472cc17e5e8
-  data.tar.gz: 11e2ab38ddd9cc99d7ec2b66bf4b97d229a470ded4295ef2e7ecddca99bca74e
+  metadata.gz: e946454a75a033c55b82ca4814654e27e75f8635ea02b42ad5fbd95a6cc7b4c8
+  data.tar.gz: f964e67077a8e2077a44db8b033d5a82be7fcbe10e9f2cad11504b6116e8397e
 SHA512:
-  metadata.gz: 3f5a3f85f1f64785b526df560efe2ef2ee94b031d0ef9bd47d43fd6500eaf4faba0b70a6230d1ccbc49db4d9a8d0681a1ba17edd847c105ab0b8d106568ccb2f
-  data.tar.gz: e6c3a31bd0825b3ae234dd68b6432e5a5b7f0fe4daf76a9494545018d264615630f89368b1c352d950be23a66be76e36fa5a3059bb38ad411d37f91912480f5a
+  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
 
   #
@@ -289,7 +342,7 @@ module Structured
     def default_element(*args, **params)
       if (key_params = params.delete(:key))
         @default_key = element_data(
-          key_params.delete(:type) || Object, key_params
+          key_params.delete(:type) || Object, **key_params
         )
       else
         @default_key = element_data(Symbol, preproc: proc { |s| s.to_sym })
@@ -451,6 +504,21 @@ module Structured
       end
     end
 
+    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
@@ -534,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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cli-dispatcher
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Charles Duan
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-15 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: []