toys 0.14.6 → 0.15.0

data/core-docs/toys/tool_definition.rb

@@ -18,12 +18,12 @@ module Toys
       ##
       # Create a completion given configuration options.
       #
-      # @param complete_subtools [Boolean] Whether to complete subtool names
-      # @param include_hidden_subtools [Boolean] Whether to include hidden
+      # @param complete_subtools [true,false] Whether to complete subtool names
+      # @param include_hidden_subtools [true,false] Whether to include hidden
       #     subtools (i.e. those beginning with an underscore)
-      # @param complete_args [Boolean] Whether to complete positional args
-      # @param complete_flags [Boolean] Whether to complete flag names
-      # @param complete_flag_values [Boolean] Whether to complete flag values
+      # @param complete_args [true,false] Whether to complete positional args
+      # @param complete_flags [true,false] Whether to complete flag names
+      # @param complete_flag_values [true,false] Whether to complete flag values
       # @param delegation_target [Array<String>,nil] Delegation target, or
       #     `nil` if none.
       #
@@ -35,7 +35,7 @@ module Toys
 
       ##
       # Whether to complete subtool names
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_subtools?
         # Source available in the toys-core gem
@@ -43,7 +43,7 @@ module Toys
 
       ##
       # Whether to include hidden subtools
-      # @return [Boolean]
+      # @return [true,false]
       #
       def include_hidden_subtools?
         # Source available in the toys-core gem
@@ -51,7 +51,7 @@ module Toys
 
       ##
       # Whether to complete flags
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flags?
         # Source available in the toys-core gem
@@ -59,7 +59,7 @@ module Toys
 
       ##
       # Whether to complete positional args
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_args?
         # Source available in the toys-core gem
@@ -67,7 +67,7 @@ module Toys
 
       ##
       # Whether to complete flag values
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flag_values?
         # Source available in the toys-core gem
@@ -99,7 +99,7 @@ module Toys
     #
     # The following settings are supported:
     #
-    #  *  `propagate_helper_methods` (_Boolean_) - Whether subtools should
+    #  *  `propagate_helper_methods` (_boolean_) - Whether subtools should
     #     inherit methods defined by parent tools. Defaults to `false`.
     #
     class Settings < ::Toys::Settings
@@ -302,19 +302,33 @@ module Toys
     attr_reader :completion
 
     ##
-    # The interrupt handler.
+    # The run handler.
     #
-    # @return [Proc] The interrupt handler proc
-    # @return [Symbol] The name of a method to call
-    # @return [nil] if there is no interrupt handler
+    # This handler is called to run the tool. Normally it is a method name,
+    # represented by a symbol. (The default is `:run`.) It can be set to a
+    # different method name, or to a proc that will be called with `self` set
+    # to the tool context. Either way, it takes no arguments. The run handler
+    # can also be explicitly set to `nil` indicating a non-runnable tool;
+    # however, typically a tool is made non-runnable simply by leaving the run
+    # handler set to `:run` and not defining the method.
     #
-    attr_reader :interrupt_handler
+    # @return [Proc] if the run handler is defined as a Proc
+    # @return [Symbol] if the run handler is defined as a method
+    # @return [nil] if the tool is explicitly made non-runnable
+    #
+    attr_reader :run_handler
 
     ##
     # The usage error handler.
     #
-    # @return [Proc] The usage error handler proc
-    # @return [Symbol] The name of a method to call
+    # This handler is called when at least one usage error is detected during
+    # argument parsing, and is called instead of the `run` method. It can be
+    # specified as a Proc, or a Symbol indicating a method to call. It
+    # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
+    # argument.
+    #
+    # @return [Proc] if the usage error handler is defined as a Proc
+    # @return [Symbol] if the user error handler is defined as a method
     # @return [nil] if there is no usage error handler
     #
     attr_reader :usage_error_handler
@@ -346,9 +360,37 @@ module Toys
       # Source available in the toys-core gem
     end
 
+    ##
+    # Return the signal handler for the given signal.
+    #
+    # This handler is called when the given signal is received, immediately
+    # taking over the execution as if it were the new run handler. The signal
+    # handler can be specified as a Proc, or a Symbol indicating a method to
+    # call. It optionally takes the `SignalException` as the sole argument.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @return [Proc] if the signal handler is defined as a Proc
+    # @return [Symbol] if the signal handler is defined as a method
+    # @return [nil] if there is no handler for the given signal
+    #
+    def signal_handler(signal)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Return the interrupt handler. This is equivalent to `signal_handler(2)`.
+    #
+    # @return [Proc] if the interrupt signal handler is defined as a Proc
+    # @return [Symbol] if the interrupt signal handler is defined as a method
+    # @return [nil] if there is no handler for the interrupt signals
+    #
+    def interrupt_handler
+      # Source available in the toys-core gem
+    end
+
     ##
     # Returns true if this tool is a root tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def root?
       # Source available in the toys-core gem
@@ -356,23 +398,35 @@ module Toys
 
     ##
     # Returns true if this tool is marked as runnable.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def runnable?
       # Source available in the toys-core gem
     end
 
     ##
-    # Returns true if this tool handles interrupts.
-    # @return [Boolean]
+    # Returns true if this tool handles interrupts. This is equivalent to
+    # `handles_signal?(2)`.
+    #
+    # @return [true,false]
     #
     def handles_interrupts?
       # Source available in the toys-core gem
     end
 
+    ##
+    # Returns true if this tool handles the given signal.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @return [true,false]
+    #
+    def handles_signal?(signal)
+      # Source available in the toys-core gem
+    end
+
     ##
     # Returns true if this tool handles usage errors.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def handles_usage_errors?
       # Source available in the toys-core gem
@@ -380,7 +434,7 @@ module Toys
 
     ##
     # Returns true if this tool has at least one included module.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_modules?
       # Source available in the toys-core gem
@@ -388,7 +442,7 @@ module Toys
 
     ##
     # Returns true if there is a specific description set for this tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_description?
       # Source available in the toys-core gem
@@ -397,7 +451,7 @@ module Toys
     ##
     # Returns true if at least one flag or positional argument is defined
     # for this tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_arguments?
       # Source available in the toys-core gem
@@ -405,7 +459,7 @@ module Toys
 
     ##
     # Returns true if this tool has any definition information.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_definition?
       # Source available in the toys-core gem
@@ -413,7 +467,7 @@ module Toys
 
     ##
     # Returns true if this tool's definition has been finished and is locked.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def definition_finished?
       # Source available in the toys-core gem
@@ -421,7 +475,7 @@ module Toys
 
     ##
     # Returns true if this tool has disabled argument parsing.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def argument_parsing_disabled?
       # Source available in the toys-core gem
@@ -429,7 +483,7 @@ module Toys
 
     ##
     # Returns true if this tool enforces flags before args.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def flags_before_args_enforced?
       # Source available in the toys-core gem
@@ -437,7 +491,7 @@ module Toys
 
     ##
     # Returns true if this tool requires exact flag matches.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def exact_flag_match_required?
       # Source available in the toys-core gem
@@ -648,7 +702,7 @@ module Toys
     # Enforce that flags must come before args for this tool.
     # You may disable enforcement by passoing `false` for the state.
     #
-    # @param state [Boolean]
+    # @param state [true,false]
     # @return [self]
     #
     def enforce_flags_before_args(state = true)
@@ -659,7 +713,7 @@ module Toys
     # Require that flags must match exactly. (If false, flags can match an
     # unambiguous substring.)
     #
-    # @param state [Boolean]
+    # @param state [true,false]
     # @return [self]
     #
     def require_exact_flag_match(state = true)
@@ -686,10 +740,10 @@ module Toys
     #     formats. Defaults to the empty array.
     # @param name [String,Symbol,nil] The name of the group, or nil for no
     #     name.
-    # @param report_collisions [Boolean] If `true`, raise an exception if a
+    # @param report_collisions [true,false] If `true`, raise an exception if a
     #     the given name is already taken. If `false`, ignore. Default is
     #     `true`.
-    # @param prepend [Boolean] If `true`, prepend rather than append the
+    # @param prepend [true,false] If `true`, prepend rather than append the
     #     group to the list. Default is `false`.
     # @return [self]
     #
@@ -733,7 +787,7 @@ module Toys
     # @param complete_values [Object] A specifier for shell tab completion
     #     for flag values associated with this flag. Pass any spec
     #     recognized by {Toys::Completion.create}.
-    # @param report_collisions [Boolean] Raise an exception if a flag is
+    # @param report_collisions [true,false] Raise an exception if a flag is
     #     requested that is already in use or marked as disabled. Default is
     #     true.
     # @param group [Toys::FlagGroup,String,Symbol,nil] Group for
@@ -860,26 +914,56 @@ module Toys
     end
 
     ##
-    # Set the run handler block
+    # Set the run handler.
     #
-    # @param proc [Proc] The runnable block
+    # This handler is called to run the tool. Normally it is a method name,
+    # represented by a symbol. (The default is `:run`.) It can be set to a
+    # different method name, or to a proc that will be called with `self` set
+    # to the tool context. Either way, it takes no arguments. The run handler
+    # can also be explicitly set to `nil` indicating a non-runnable tool;
+    # however, typically a tool is made non-runnable simply by leaving the run
+    # handler set to `:run` and not defining the method.
     #
-    def run_handler=(proc)
+    # @param handler [Proc,Symbol,nil] the run handler
+    #
+    def run_handler=(handler)
       # Source available in the toys-core gem
     end
 
     ##
-    # Set the interrupt handler.
+    # Set the interrupt handler. This is equivalent to calling
+    # {#set_signal_handler} for the `SIGINT` signal.
     #
-    # @param handler [Proc,Symbol] The interrupt handler
+    # @param handler [Proc,Symbol] The interrupt signal handler
     #
     def interrupt_handler=(handler)
       # Source available in the toys-core gem
     end
 
+    ##
+    # Set the handler for the given signal.
+    #
+    # This handler is called when the given signal is received, immediately
+    # taking over the execution as if it were the new `run` method. The signal
+    # handler can be specified as a Proc, or a Symbol indicating a method to
+    # call. It optionally takes the `SignalException` as the sole argument.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @param handler [Proc,Symbol] The signal handler
+    #
+    def set_signal_handler(signal, handler)
+      # Source available in the toys-core gem
+    end
+
     ##
     # Set the usage error handler.
     #
+    # This handler is called when at least one usage error is detected during
+    # argument parsing, and is called instead of the `run` method. It can be
+    # specified as a Proc, or a Symbol indicating a method to call. It
+    # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
+    # argument.
+    #
     # @param handler [Proc,Symbol] The usage error handler
     #
     def usage_error_handler=(handler)

data/core-docs/toys/utils/exec.rb

@@ -12,6 +12,27 @@ module Toys
     # This class is not loaded by default. Before using it directly, you should
     # `require "toys/utils/exec"`
     #
+    # ### The exec service
+    #
+    # The main entrypoint class is this one, {Toys::Utils::Exec}. It's a
+    # "service" object that provides functionality, primarily methods that
+    # spawn processes. Create it like any object:
+    #
+    #     require "toys/utils/exec"
+    #     exec_service = Toys::Utils::Exec.new
+    #
+    # There are two "primitive" functions: {#exec} and {#exec_proc}. The {#exec}
+    # method spawns an operating system process specified by an executable and
+    # a set of arguments. The {#exec_proc} method takes a `Proc` and forks a
+    # Ruby process. Both of these can be heavily configured with stream
+    # handling, result handling, and numerous other options described below.
+    # The class also provides convenience methods for common cases such as
+    # spawning a Ruby process, spawning a shell script, or capturing output.
+    #
+    # The exec service class also stores default configuration that it applies
+    # to processes it spawns. You can set these defaults when constructing the
+    # service class, or at any time by calling {#configure_defaults}.
+    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -20,7 +41,7 @@ module Toys
     # If you start a background process, its streams will be redirected to null
     # by default, and control will be returned to you immediately.
     #
-    # When a process is running, you can control it using a
+    # While a process is running, you can control it using a
     # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
     # the process's input and output streams, send it signals, or wait for it
     # to complete.

data/core-docs/toys/utils/standard_ui.rb

@@ -0,0 +1,184 @@
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # An object that implements standard UI elements, such as error reports and
+    # logging, as provided by the `toys` command line. Specifically, it
+    # implements pretty formatting of log entries and stack traces, and renders
+    # using ANSI coloring where available via {Toys::Utils::Terminal}.
+    #
+    # This object can be used to implement `toys`-style behavior when creating
+    # a CLI object. For example:
+    #
+    #     require "toys/utils/standard_ui"
+    #     ui = Toys::Utils::StandardUI.new
+    #     cli = Toys::CLI.new(**ui.cli_args)
+    #
+    class StandardUI
+      ##
+      # Create a Standard UI.
+      #
+      # By default, all output is written to `$stderr`, and will share a single
+      # {Toys::Utils::Terminal} object, allowing multiple tools and/or threads
+      # to interleave messages without interrupting one another.
+      #
+      # @param output [IO,Toys::Utils::Terminal] Where to write output. You can
+      #     pass a terminal object, or an IO stream that will be wrapped in a
+      #     terminal output. Default is `$stderr`.
+      #
+      def initialize(output: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # The terminal underlying this UI
+      #
+      # @return [Toys::Utils::Terminal]
+      #
+      attr_reader :terminal
+
+      ##
+      # A hash that maps severities to styles recognized by
+      # {Toys::Utils::Terminal}. Used to style the header for each log entry.
+      # This hash can be modified in place to adjust the behavior of loggers
+      # created by this UI.
+      #
+      # @return [Hash{String => Array<Symbol>}]
+      #
+      attr_reader :log_header_severity_styles
+
+      ##
+      # Convenience method that returns a hash of arguments that can be passed
+      # to the {Toys::CLI} constructor. Includes the `:error_handler` and
+      # `:logger_factory` arguments.
+      #
+      # @return [Hash]
+      #
+      def cli_args
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Returns an error handler conforming to the `:error_handler` argument to
+      # the {Toys::CLI} constructor. Specifically, it returns the
+      # {#error_handler_impl} method as a proc.
+      #
+      # @return [Proc]
+      #
+      def error_handler
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Returns a logger factory conforming to the `:logger_factory` argument
+      # to the {Toys::CLI} constructor. Specifically, it returns the
+      # {#logger_factory_impl} method as a proc.
+      #
+      # @return [Proc]
+      #
+      def logger_factory
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Implementation of the error handler. As dictated by the error handler
+      # specification in {Toys::CLI}, this must take a {Toys::ContextualError}
+      # as an argument, and return an exit code.
+      #
+      # The base implementation uses {#display_error_notice} and
+      # {#display_signal_notice} to print an appropriate message to the UI's
+      # terminal, and uses {#exit_code_for} to determine the correct exit code.
+      # Any of those methods can be overridden by a subclass to alter their
+      # behavior, or this main implementation method can be overridden to
+      # change the overall behavior.
+      #
+      # @param error [Toys::ContextualError] The error received
+      # @return [Integer] The exit code
+      #
+      def error_handler_impl(error)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Implementation of the logger factory. As dictated by the logger factory
+      # specification in {Toys::CLI}, this must take a {Toys::ToolDefinition}
+      # as an argument, and return a `Logger`.
+      #
+      # The base implementation returns a logger that writes to the UI's
+      # terminal, using {#logger_formatter_impl} as the formatter. It sets the
+      # level to `Logger::WARN` by default. Either this method or the helper
+      # methods can be overridden to change this behavior.
+      #
+      # @param _tool {Toys::ToolDefinition} The tool definition of the tool to
+      #     be executed
+      # @return [Logger]
+      #
+      def logger_factory_impl(_tool)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Returns an exit code appropriate for the given exception. Currently,
+      # the logic interprets signals (returning the convention of 128 + signo),
+      # usage errors (returning the conventional value of 2), and tool not
+      # runnable errors (returning the conventional value of 126), and defaults
+      # to 1 for all other error types.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [Exception] The exception raised. This method expects the
+      #     original exception, rather than a ContextualError.
+      # @return [Integer] The appropriate exit code
+      #
+      def exit_code_for(error)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Displays a default output for a signal received.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [SignalException]
+      #
+      def display_signal_notice(error)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Displays a default output for an error. Displays the error, the
+      # backtrace, and contextual information regarding what tool was run and
+      # where in its code the error occurred.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [Toys::ContextualError]
+      #
+      def display_error_notice(error)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Implementation of the formatter used by loggers created by this UI's
+      # logger factory. This interface is defined by the standard `Logger`
+      # class.
+      #
+      # This method can be overridden to change the behavior of loggers created
+      # by this UI.
+      #
+      # @param severity [String]
+      # @param time [Time]
+      # @param _progname [String]
+      # @param msg [Object]
+      # @return [String]
+      #
+      def logger_formatter_impl(severity, time, _progname, msg)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys-core.rb

@@ -12,12 +12,53 @@
 # This module contains the command line framework underlying Toys. It can be
 # used to create command line executables using the Toys DSL and classes.
 #
+# ## Common starting points
+#
+# Some of the most commonly needed class documentation is listed below:
+#
+# * For information on the DSL used to write tools, start with
+#   {Toys::DSL::Tool}.
+# * The base class for tool runtime (i.e. that defines the basic methods
+#   available to a tool's implementation) is {Toys::Context}.
+# * For information on writing mixins, see {Toys::Mixin}.
+# * For information on writing templates, see {Toys::Template}.
+# * For information on writing acceptors, see {Toys::Acceptor}.
+# * For information on writing custom shell completions, see {Toys::Completion}.
+# * Standard mixins are defined under the {Toys::StandardMixins} module.
+# * Various utilities are defined under {Toys::Utils}. Some of these serve as
+#   the implementations of corresponding mixins.
+# * The main entrypoint for the command line framework is {Toys::CLI}.
+#
+# Other important internal classes are listed below.
+#
+# * The definition of a tool is represented by {Toys::ToolDefinition} along
+#   the helpers {Toys::Flag}, {Toys::PositionalArg}, and {Toys::FlagGroup}.
+# * Argument parsing is implemented by {Toys::ArgParser}.
+# * The process of finding and loading a tool definition given a tool name, is
+#   implemented by {Toys::Loader}.
+# * Text wrapping is handled by {Toys::WrappableString}.
+# * The settings system is implemented by {Toys::Settings}.
+#
 module Toys
   ##
   # **_Defined in the toys-core gem_**
   #
   # Namespace for DSL classes. These classes provide the directives that can be
-  # used in configuration files. Most are defined in {Toys::DSL::Tool}.
+  # used in configuration files.
+  #
+  # DSL directives that can appear at the top level of Toys files and tool
+  # blocks are defined by the {Toys::DSL::Tool} module.
+  #
+  # Directives that can appear within a block passed to {Toys::DSL::Tool#flag}
+  # are defined by the {Toys::DSL::Flag} class.
+  #
+  # Directives that can appear within a {Toys::DSL::Tool#flag_group} block or
+  # any of its related directives, are defined by the {Toys::DSL::FlagGroup}
+  # class.
+  #
+  # Directives that can appear within a {Toys::DSL::Tool#required_arg},
+  # {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args} block,
+  # are defined by the {Toys::DSL::PositionalArg} class.
   #
   module DSL
   end
@@ -27,6 +68,9 @@ module Toys
   #
   # Namespace for standard middleware classes.
   #
+  # These middleware are provided by Toys-Core and can be referenced by name
+  # when creating a {Toys::CLI}.
+  #
   module StandardMiddleware
   end
 
@@ -35,6 +79,9 @@ module Toys
   #
   # Namespace for standard mixin classes.
   #
+  # These mixins are provided by Toys-Core and can be included by name by
+  # passing a symbol to {Toys::DSL::Tool#include}.
+  #
   module StandardMixins
   end
 
@@ -44,8 +91,9 @@ module Toys
   # Namespace for common utility classes.
   #
   # These classes are not loaded by default, and must be required explicitly.
-  # For example, before using {Toys::Utils::Exec}, you must
-  # `require "toys/utils/exec"`.
+  # For example, before using {Toys::Utils::Exec}, you must:
+  #
+  #     require "toys/utils/exec"
   #
   module Utils
   end