toys 0.15.3 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57b1253240949a832b30bab7889080d57c7a756f30d2db5aa3f639c86190ea45
-  data.tar.gz: bf4a045fcef88634614042023c58dbb2ccc48e4992fb23935ae0c13dcd1ff695
+  metadata.gz: dde2dacbdd40f393c28b751ae14b40d1b8348e790f36a82e4dec6c5d36b9efec
+  data.tar.gz: 18ab3366caa4264a3b5ca322f87f095258c5298a423af1d90c6f86c76a979d93
 SHA512:
-  metadata.gz: c1acf98ea97a5b08f03b703ac7caeb0a9a329f507717a516833bd60a53f8f3ae506aa3d91d23d0da4a213ceccffd67c6acf427e4cbeff37a9ce85a45bcd20587
-  data.tar.gz: 837994ddbe9dd840bb59499e6676b0446058a5c9598536328455d4724948ebfe5736b6842295c9519f26fba6a276f41a50391c8e4c50219ef4f957ebdff93687
+  metadata.gz: 9524f54ede25c686d56d13e838cca9582bb31d2e2c9533fdf17c70d9ec80459abd897641442cfd5fed03d51078ff2ec17d70b02d7ddccabe27b03ae6ba40ff1c
+  data.tar.gz: 5c83c1f88969a64ea75f5dd6bff60bb681004221091eb6fc0b6a57e49593d8fabb1fa24f310e09e5779301ac9939387ba5fe51b20cd02d59dd383b953b7417ea

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+### v0.15.4 / 2024-01-04
+
+* FIXED: Fix error message when failing assertion of the toys version
+* DOCS: Various documentation improvements
+
 ### v0.15.3 / 2023-10-31
 
 * FIXED: Minitest template defers calling autorun until after tests are loaded, which should eliminate stringio warnings when running Rails tests without bundler integration

data/core-docs/toys/core.rb

@@ -9,6 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.15.3"
+    VERSION = "0.15.4"
   end
 end

data/core-docs/toys/dsl/tool.rb

@@ -1310,7 +1310,7 @@ module Toys
       #     tool "foo" do
       #       to_run :foo
       #       def foo
-      #         puts "The fool tool ran!"
+      #         puts "The foo tool ran!"
       #       end
       #     end
       #

data/core-docs/toys/input_file.rb

@@ -1,8 +1,11 @@
 ##
 # **_Defined in the toys-core gem_**
 #
-# This module is a namespace for constant scopes. Whenever a configuration file
-# is parsed, a module is created under this parent for that file's constants.
+# This module is the root namespace for tool definitions loaded from files.
+# Whenever a toys configuration file is parsed, a module is created under this
+# parent for that file's contents. Tool classes defined in that file, along
+# with mixins and templates, and any other classes, modules, and constants
+# defined, are located within that file's module.
 #
 module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
   ##

data/core-docs/toys/source_info.rb

@@ -5,17 +5,49 @@ module Toys
   # Information about the source of a tool, such as the file, git repository,
   # or block that defined it.
   #
+  # This object represents a source of tool information and definitions. Such a
+  # source could include:
+  #
+  # * A toys directory
+  # * A single toys file
+  # * A file or directory loaded from git
+  # * A config block passed directly to the CLI
+  # * A tool block within a toys file
+  #
+  # The SourceInfo provides information such as the tool's context directory,
+  # and locates data and lib directories appropriate to the tool. It also
+  # locates the tool's source code so it can be reported when an error occurs.
+  #
+  # Each tool has a unique SourceInfo with all the information specific to that
+  # tool. Additionally, SourceInfo objects are arranged in a containment
+  # hierarchy. For example, a SourceInfo object representing a toys files could
+  # have a parent representing a toys directory, and an object representing a
+  # tool block could have a parent representing an enclosing block or a file.
+  #
+  # Child SourceInfo objects generally inherit some attributes of their parent.
+  # For example, the `.toys` directory in a project directory defines the
+  # context directory as that project directory. Then all tools defined under
+  # that directory will share that context directory, so all SourceInfo objects
+  # descending from that root will inherit that value (unless it's changed
+  # explicitly).
+  #
+  # SourceInfo objects can be obtained in the DSL from
+  # {Toys::DSL::Tool#source_info} or at runtime by getting the
+  # {Toys::Context::Key::TOOL_SOURCE} key. However, they are created internally
+  # by the Loader and should not be created manually.
+  #
   class SourceInfo
     ##
     # The parent of this SourceInfo.
     #
     # @return [Toys::SourceInfo] The parent.
-    # @return [nil] if this SourceInfo is the root.
+    # @return [nil] if this SourceInfo is a root.
     #
     attr_reader :parent
 
     ##
-    # The root ancestor of this SourceInfo.
+    # The root ancestor of this SourceInfo. This generally represents a source
+    # that was added directly to a CLI in code.
     #
     # @return [Toys::SourceInfo] The root ancestor.
     #
@@ -33,14 +65,16 @@ module Toys
     # The context directory path (normally the directory containing the
     # toplevel toys file or directory).
     #
+    # This is not affected by setting a custom context directory for a tool.
+    #
     # @return [String] The context directory path.
-    # @return [nil] if there is no context directory (perhaps because the tool
-    #     is being defined from a block)
+    # @return [nil] if there is no context directory (perhaps because the root
+    #     source was a block)
     #
     attr_reader :context_directory
 
     ##
-    # The source, which may be a path or a proc.
+    # The source, which may be a path or a proc depending on the {#source_type}.
     #
     # @return [String] Path to the source file or directory.
     # @return [Proc] The block serving as the source.
@@ -48,7 +82,15 @@ module Toys
     attr_reader :source
 
     ##
-    # Return the type of source.
+    # The type of source. This could be:
+    #
+    # * `:file`, representing a single toys file. The {#source} will be the
+    #   filesystem path to that file.
+    # * `:directory`, representing a toys directory. The {#source} will be the
+    #   filesystem path to that directory.
+    # * `:proc`, representing a proc, which could be a toplevel block added
+    #   directly to a CLI, a `tool` block within a toys file, or a block within
+    #   another block. The {#source} will be the proc itself.
     #
     # @return [:file,:directory,:proc]
     #
@@ -57,13 +99,17 @@ module Toys
     ##
     # The path of the current source file or directory.
     #
+    # This could be set even if {#source_type} is `:proc`, if that proc is
+    # defined within a toys file. The only time this is not set is if the
+    # source is added directly to a CLI in a code block.
+    #
     # @return [String] The source path
     # @return [nil] if this source has no file system path.
     #
     attr_reader :source_path
 
     ##
-    # The source proc.
+    # The source proc. This is set if {#source_type} is `:proc`.
     #
     # @return [Proc] The source proc
     # @return [nil] if this source has no proc.
@@ -71,7 +117,8 @@ module Toys
     attr_reader :source_proc
 
     ##
-    # The git remote.
+    # The git remote. This is set if the source, or one of its ancestors, comes
+    # from git.
     #
     # @return [String] The git remote
     # @return [nil] if this source is not fron git.
@@ -79,7 +126,8 @@ module Toys
     attr_reader :git_remote
 
     ##
-    # The git path.
+    # The git path. This is set if the source, or one of its ancestors, comes
+    # from git.
     #
     # @return [String] The git path. This could be the empty string.
     # @return [nil] if this source is not fron git.
@@ -87,7 +135,8 @@ module Toys
     attr_reader :git_path
 
     ##
-    # The git commit.
+    # The git commit. This is set if the source, or one of its ancestors, comes
+    # from git.
     #
     # @return [String] The git commit.
     # @return [nil] if this source is not fron git.
@@ -95,7 +144,7 @@ module Toys
     attr_reader :git_commit
 
     ##
-    # The user-visible name of this source.
+    # A user-visible name of this source.
     #
     # @return [String]
     #

data/lib/toys/version.rb

@@ -5,5 +5,5 @@ module Toys
   # Current version of the Toys command line executable.
   # @return [String]
   #
-  VERSION = "0.15.3"
+  VERSION = "0.15.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.15.3
+  version: 0.15.4
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-31 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toys-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.15.3
+        version: 0.15.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.15.3
+        version: 0.15.4
 description: Toys is a configurable command line tool. Write commands in Ruby using
   a simple DSL, and Toys will provide the command line executable and take care of
   all the details such as argument parsing, online help, and error reporting. Toys
@@ -121,10 +121,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.15.3/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.15.4/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.15.3
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.15.4
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -140,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
 summary: A configurable command line tool