toys-core 0.12.2 → 0.13.0

data/lib/toys/dsl/flag.rb

@@ -22,22 +22,6 @@ module Toys
     #     end
     #
     class Flag
-      ## @private
-      def initialize(flags, acceptor, default, handler, flag_completion, value_completion,
-                     report_collisions, group, desc, long_desc, display_name)
-        @flags = flags
-        @default = default
-        @handler = handler
-        @report_collisions = report_collisions
-        @group = group
-        @desc = desc
-        @long_desc = long_desc || []
-        @display_name = display_name
-        accept(acceptor)
-        complete_flags(flag_completion, **{})
-        complete_values(value_completion, **{})
-      end
-
       ##
       # Add flags in OptionParser format. This may be called multiple times,
       # and the results are cumulative.
@@ -284,7 +268,29 @@ module Toys
         self
       end
 
-      ## @private
+      ##
+      # Called only from DSL::Tool
+      #
+      # @private
+      #
+      def initialize(flags, acceptor, default, handler, flag_completion, value_completion,
+                     report_collisions, group, desc, long_desc, display_name)
+        @flags = flags
+        @default = default
+        @handler = handler
+        @report_collisions = report_collisions
+        @group = group
+        @desc = desc
+        @long_desc = long_desc || []
+        @display_name = display_name
+        accept(acceptor)
+        complete_flags(flag_completion, **{})
+        complete_values(value_completion, **{})
+      end
+
+      ##
+      # @private
+      #
       def _add_to(tool, key)
         tool.add_flag(key, @flags,
                       accept: @acceptor, default: @default, handler: @handler,

data/lib/toys/dsl/flag_group.rb

@@ -22,13 +22,6 @@ module Toys
     #     end
     #
     class FlagGroup
-      ## @private
-      def initialize(tool_dsl, tool, flag_group)
-        @tool_dsl = tool_dsl
-        @tool = tool
-        @flag_group = flag_group
-      end
-
       ##
       # Add a flag to the current group. Each flag must specify a key which
       # the script may use to obtain the flag value from the context.
@@ -268,6 +261,17 @@ module Toys
         @flag_group.append_long_desc(long_desc)
         self
       end
+
+      ##
+      # Called only from DSL::Tool.
+      #
+      # @private
+      #
+      def initialize(tool_dsl, tool, flag_group)
+        @tool_dsl = tool_dsl
+        @tool = tool
+        @flag_group = flag_group
+      end
     end
   end
 end

data/lib/toys/dsl/positional_arg.rb

@@ -22,16 +22,6 @@ module Toys
     #     end
     #
     class PositionalArg
-      ## @private
-      def initialize(acceptor, default, completion, display_name, desc, long_desc)
-        @default = default
-        @display_name = display_name
-        @desc = desc
-        @long_desc = long_desc || []
-        accept(acceptor, **{})
-        complete(completion, **{})
-      end
-
       ##
       # Set the acceptor for this argument's values.
       # You can pass either the string name of an acceptor defined in this tool
@@ -151,21 +141,41 @@ module Toys
         self
       end
 
-      ## @private
+      ##
+      # Called only from DSL::Tool
+      #
+      # @private
+      #
+      def initialize(acceptor, default, completion, display_name, desc, long_desc)
+        @default = default
+        @display_name = display_name
+        @desc = desc
+        @long_desc = long_desc || []
+        accept(acceptor, **{})
+        complete(completion, **{})
+      end
+
+      ##
+      # @private
+      #
       def _add_required_to(tool, key)
         tool.add_required_arg(key,
                               accept: @acceptor, complete: @completion,
                               display_name: @display_name, desc: @desc, long_desc: @long_desc)
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def _add_optional_to(tool, key)
         tool.add_optional_arg(key,
                               accept: @acceptor, default: @default, complete: @completion,
                               display_name: @display_name, desc: @desc, long_desc: @long_desc)
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def _set_remaining_on(tool, key)
         tool.set_remaining_args(key,
                                 accept: @acceptor, default: @default, complete: @completion,

data/lib/toys/dsl/tool.rb

@@ -34,12 +34,6 @@ module Toys
     #     toys greet rubyists
     #
     module Tool
-      ## @private
-      def method_added(_meth)
-        super
-        DSL::Internal.current_tool(self, true)&.check_definition_state(is_method: true)
-      end
-
       ##
       # Create a named acceptor that can be referenced by name from any flag or
       # positional argument in this tool or its subtools.
@@ -1717,6 +1711,16 @@ module Toys
         end
         self
       end
+
+      ##
+      # Notify the tool definition when a method is defined in this tool class.
+      #
+      # @private
+      #
+      def method_added(_meth)
+        super
+        DSL::Internal.current_tool(self, true)&.check_definition_state(is_method: true)
+      end
     end
   end
 end

data/lib/toys/errors.rb

@@ -40,10 +40,13 @@ module Toys
   end
 
   ##
-  # A wrapper exception used to provide user-oriented context for an exception
+  # A wrapper exception used to provide user-oriented context for an error
+  # thrown during tool execution.
   #
   class ContextualError < ::StandardError
-    ## @private
+    ##
+    # @private
+    #
     def initialize(cause, banner,
                    config_path: nil, config_line: nil,
                    tool_name: nil, tool_args: nil)
@@ -57,16 +60,66 @@ module Toys
       set_backtrace(cause.backtrace)
     end
 
+    ##
+    # The underlying exception
+    # @return [::StandardError]
+    #
     attr_reader :cause
+
+    ##
+    # An overall banner message
+    # @return [String]
+    #
     attr_reader :banner
 
-    attr_accessor :config_path
-    attr_accessor :config_line
-    attr_accessor :tool_name
-    attr_accessor :tool_args
+    ##
+    # The path to the toys config file in which the error was detected
+    # @return [String]
+    #
+    attr_reader :config_path
+
+    ##
+    # The line number in the toys config file in which the error was detected
+    # @return [Integer]
+    #
+    attr_reader :config_line
+
+    ##
+    # The full name of the tool that was running when the error occurred
+    # @return [Array<String>]
+    #
+    attr_reader :tool_name
+
+    ##
+    # The arguments passed to the tool that was running when the error occurred
+    # @return [Array<String>]
+    #
+    attr_reader :tool_args
+
+    ##
+    # @private
+    #
+    attr_writer :config_path
+
+    ##
+    # @private
+    #
+    attr_writer :config_line
+
+    ##
+    # @private
+    #
+    attr_writer :tool_name
+
+    ##
+    # @private
+    #
+    attr_writer :tool_args
 
     class << self
-      ## @private
+      ##
+      # @private
+      #
       def capture_path(banner, path, **opts)
         yield
       rescue ContextualError => e
@@ -86,7 +139,9 @@ module Toys
         raise e
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def capture(banner, **opts)
         yield
       rescue ContextualError => e