toys-core 0.15.3 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1888d8d6f5f4fef954b2ae2cfb6d2c7347bacc9765b771b2cd565302c8aff33
-  data.tar.gz: 76e389e4af61edbb83832d626dbce946177eb262db260577c78d4f40b454d885
+  metadata.gz: 95f2b314888825bc99a288a9f6676060d10b2e00bd10f9fe665ce4c6c9f03c37
+  data.tar.gz: 71c89aaa21d5203eb5b8c7ae34c3fba9f408c818f3e07ca8cdc025568204fa43
 SHA512:
-  metadata.gz: 70cb4a35ff04d345c22e19aa701148ee55cf3336ecfab68bbb524c44aaa8d1306fb8106136efa337c281110203c1559c16598c8762ff4ecfb13d36fecc15f7e0
-  data.tar.gz: f6e5a7f8c84a7158da379707c48d2f560806285a684fb2f46a80649c4dbb0e1ed7c7ee240eb1b1825723ded8519dbcada6cd6896f48a33e9047855362c9010f5
+  metadata.gz: 9ee63b482c81481f02aa498aef32aa563a9d6cf6335f94b1c5820a935cb058c182dcb74572ce54f0c298e2473ca405719d50aaf11b519a592fc75ad263f53fca
+  data.tar.gz: 40ac439b3942f95d414d5253190491916d4c5dabbebd5bf32a262884d1dd3b6174f0f248ea3d7ef3dc86f38020752858ebd916c2cfe62d887f7fd84f53b5603b

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
 
 * (No significant changes)

data/lib/toys/core.rb

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

data/lib/toys/dsl/tool.rb

@@ -1467,7 +1467,7 @@ module Toys
       #     tool "foo" do
       #       to_run :foo
       #       def foo
-      #         puts "The fool tool ran!"
+      #         puts "The foo tool ran!"
       #       end
       #     end
       #
@@ -1820,7 +1820,7 @@ module Toys
         requirement = ::Gem::Requirement.new(*requirements)
         unless requirement.satisfied_by?(version)
           raise Toys::ToolDefinitionError,
-                "Toys version requirements #{requirement} not satisfied by {version}"
+                "Toys version requirements #{requirement} not satisfied by #{version}"
         end
         self
       end

data/lib/toys/input_file.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 ##
-# 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/lib/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]
     #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 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: []
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
@@ -79,10 +79,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.3/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.4/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.3
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.4
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -98,7 +98,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: Framework for creating command line executables