toys 0.14.6 → 0.15.0

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

@@ -3,7 +3,7 @@ module Toys
     ##
     # **_Defined in the toys-core gem_**
     #
-    # This class defines the DSL for a Toys configuration file.
+    # This module defines the DSL for a Toys configuration file.
     #
     # A Toys configuration defines one or more named tools. It provides syntax
     # for setting the description, defining flags and arguments, specifying
@@ -25,6 +25,9 @@ module Toys
     #       end
     #     end
     #
+    # The DSL directives `tool`, `desc`, `optional_arg`, and others are defined
+    # in this module.
+    #
     # Now you can execute it using:
     #
     #     toys greet
@@ -81,8 +84,8 @@ module Toys
       # ### Example
       #
       # The following example creates an acceptor named "hex" that is defined
-      # via a regular expression. It then uses it to validate values passed to
-      # a flag.
+      # via a regular expression. It uses the acceptor to validate values
+      # passed to a flag.
       #
       #     tool "example" do
       #       acceptor "hex", /[0-9a-fA-F]+/, type_desc: "hex numbers"
@@ -151,16 +154,21 @@ module Toys
       #
       # A template is an object that generates DSL directives. You can use it
       # to build "prefabricated" tools, and then instantiate them in your Toys
-      # files. Generally, a template is a class with an associated `expansion`
-      # procedure. The class defines parameters for the template expansion,
-      # and `expansion` includes DSL directives that should be run based on
-      # those parameters.
-      #
-      # Normally, you provide a block and define the template class in that
-      # block. Most templates will define an `initialize` method that takes any
-      # arguments passed into the template expansion. The template must also
-      # provide an `expansion` block showing how to use the template object to
-      # produce DSL directives.
+      # files.
+      #
+      # A template is an object that defines an `expansion` procedure. This
+      # procedure generates the DSL directives implemented by the template. The
+      # template object typically also includes attributes that are used to
+      # configure the expansion.
+      #
+      # The simplest way to define a template is to pass a block to the
+      # {#template} directive. In the block, define an `initialize` method that
+      # accepts any arguments that may be passed to the template when it is
+      # instantiated and are used to configure the template. Define
+      # `attr_reader`s or other methods to make this configuration accessible
+      # from the object. Then define an `on_expand` block that implements the
+      # template's expansion. The template object is passed as an object to the
+      # `on_expand` block.
       #
       # Alternately, you can create a template class separately and pass it
       # directly. See {Toys::Template} for details on creating a template
@@ -168,7 +176,9 @@ module Toys
       #
       # ### Example
       #
-      # The following example creates and uses a simple template.
+      # The following example creates and uses a simple template. The template
+      # defines a tool, with a configurable name, that simply prints out a
+      # configurable message.
       #
       #     template "hello-generator" do
       #       def initialize(name, message)
@@ -176,7 +186,7 @@ module Toys
       #         @message = message
       #       end
       #       attr_reader :name, :message
-      #       expansion do |template|
+      #       on_expand do |template|
       #         tool template.name do
       #           to_run do
       #             puts template.message
@@ -875,6 +885,12 @@ module Toys
       #     arguments.) Defaults to the empty array.
       # @param display_name [String] A display name for this flag, used in help
       #     text and error messages.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     flag. If omitted or set to nil, uses the default behavior, which
+      #     adds the method if the key is a symbol representing a legal method
+      #     name that starts with a letter and does not override any public
+      #     method in the Ruby Object class or collide with any method directly
+      #     defined in the tool class.
       # @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
       #     directives that can be called in this block.
       # @return [self]
@@ -883,7 +899,7 @@ module Toys
                accept: nil, default: nil, handler: nil,
                complete_flags: nil, complete_values: nil,
                report_collisions: true, group: nil,
-               desc: nil, long_desc: nil, display_name: nil,
+               desc: nil, long_desc: nil, display_name: nil, add_method: nil,
                &block)
         # Source available in the toys-core gem
       end
@@ -936,6 +952,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     argument. If omitted or set to nil, uses the default behavior,
+      #     which adds the method if the key is a symbol representing a legal
+      #     method name that starts with a letter and does not override any
+      #     public method in the Ruby Object class or collide with any method
+      #     directly defined in the tool class.
       # @param block [Proc] Configures the positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -943,7 +965,7 @@ module Toys
       #
       def required_arg(key,
                        accept: nil, complete: nil, display_name: nil,
-                       desc: nil, long_desc: nil,
+                       desc: nil, long_desc: nil, add_method: nil,
                        &block)
         # Source available in the toys-core gem
       end
@@ -1002,6 +1024,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     argument. If omitted or set to nil, uses the default behavior,
+      #     which adds the method if the key is a symbol representing a legal
+      #     method name that starts with a letter and does not override any
+      #     public method in the Ruby Object class or collide with any method
+      #     directly defined in the tool class.
       # @param block [Proc] Configures the positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -1009,7 +1037,7 @@ module Toys
       #
       def optional_arg(key,
                        default: nil, accept: nil, complete: nil, display_name: nil,
-                       desc: nil, long_desc: nil,
+                       desc: nil, long_desc: nil, add_method: nil,
                        &block)
         # Source available in the toys-core gem
       end
@@ -1068,6 +1096,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for these
+      #     arguments. If omitted or set to nil, uses the default behavior,
+      #     which adds the method if the key is a symbol representing a legal
+      #     method name that starts with a letter and does not override any
+      #     public method in the Ruby Object class or collide with any method
+      #     directly defined in the tool class.
       # @param block [Proc] Configures the positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -1075,14 +1109,14 @@ module Toys
       #
       def remaining_args(key,
                          default: [], accept: nil, complete: nil, display_name: nil,
-                         desc: nil, long_desc: nil,
+                         desc: nil, long_desc: nil, add_method: nil,
                          &block)
         # Source available in the toys-core gem
       end
       alias remaining remaining_args
 
       ##
-      # Set a option values statically and create a helper method.
+      # Set option values statically and create helper methods.
       #
       # If any given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
@@ -1115,7 +1149,7 @@ module Toys
       end
 
       ##
-      # Set a option values statically without creating helper methods.
+      # Set option values statically without creating helper methods.
       #
       # ### Example
       #
@@ -1180,6 +1214,15 @@ module Toys
       # This directive is mutually exclusive with any of the directives that
       # declare arguments or flags.
       #
+      # ### Example
+      #
+      #     tool "mytool" do
+      #       disable_argument_parsing
+      #       def run
+      #         puts "Arguments passed: #{args}"
+      #       end
+      #     end
+      #
       # @return [self]
       #
       def disable_argument_parsing
@@ -1249,27 +1292,53 @@ module Toys
       end
 
       ##
-      # Specify how to run this tool. Typically you do this by defining a
-      # method namd `run`. Alternatively, however, you can pass a block to the
-      # `to_run` method.
+      # Specify how to run this tool.
       #
-      # You may want to do this if your method needs access to local variables
-      # in the lexical scope. However, it is often more convenient to use
-      # {#static} to set the value in the context.)
+      # Typically the entrypoint for a tool is a method named `run`. However,
+      # you can change this by passing a different method name, as a symbol, to
+      # {#to_run}.
       #
-      # ### Example
+      # You can also alternatively pass a block to {#to_run}. You might do this
+      # if your method needs access to local variables in the lexical scope.
+      # However, it is often more convenient to use {#static} to set those
+      # values in the context.
+      #
+      # ### Examples
+      #
+      #     # Set a different method name as the entrypoint:
       #
       #     tool "foo" do
-      #       cur_time = Time.new
+      #       to_run :foo
+      #       def foo
+      #         puts "The fool tool ran!"
+      #       end
+      #     end
+      #
+      #     # Use a block to retain access to the enclosing lexical scope from
+      #     # the run method:
+      #
+      #     tool "foo" do
+      #       cur_time = Time.now
       #       to_run do
       #         puts "The time at tool definition was #{cur_time}"
       #       end
       #     end
       #
-      # @param block [Proc] The run method.
+      #     # But the following is approximately equivalent:
+      #
+      #     tool "foo" do
+      #       static :cur_time, Time.now
+      #       def run
+      #         puts "The time at tool definition was #{cur_time}"
+      #       end
+      #     end
+      #
+      # @param handler [Proc,Symbol,nil] The run handler as a method name
+      #     symbol or a proc, or nil to explicitly set as non-runnable.
+      # @param block [Proc] The run handler as a block.
       # @return [self]
       #
-      def to_run(&block)
+      def to_run(handler = nil, &block)
         # Source available in the toys-core gem
       end
       alias on_run to_run
@@ -1277,9 +1346,12 @@ module Toys
       ##
       # Specify how to handle interrupts.
       #
-      # You may pass a block to be called, or the name of a method to call. In
-      # either case, the block or method should take one argument, the
-      # Interrupt exception that was raised.
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the Interrupt exception that
+      # was raised.
+      #
+      # Note: this is equivalent to `on_signal("SIGINT")`.
       #
       # ### Example
       #
@@ -1287,7 +1359,7 @@ module Toys
       #       def run
       #         sleep 10
       #       end
-      #       on_interrupt do |e|
+      #       on_interrupt do
       #         puts "I was interrupted."
       #       end
       #     end
@@ -1301,18 +1373,47 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      ##
+      # Specify how to handle the given signal.
+      #
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the SignalException that was
+      # raised.
+      #
+      # ### Example
+      #
+      #     tool "foo" do
+      #       def run
+      #         sleep 10
+      #       end
+      #       on_signal("QUIT") do |e|
+      #         puts "Signal caught: #{e.signm}."
+      #       end
+      #     end
+      #
+      # @param signal [Integer,String,Symbol] The signal name or number
+      # @param handler [Proc,Symbol,nil] The signal callback proc or method
+      #     name. Pass nil to disable signal handling.
+      # @param block [Proc] The signal callback as a block.
+      # @return [self]
+      #
+      def on_signal(signal, handler = nil, &block)
+        # Source available in the toys-core gem
+      end
+
       ##
       # Specify how to handle usage errors.
       #
-      # You may pass a block to be called, or the name of a method to call. In
-      # either case, the block or method should take one argument, the array of
-      # usage errors reported.
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the array of usage errors
+      # reported.
       #
       # ### Example
       #
-      # This tool runs even if a usage error is encountered. You can find info
-      # on the errors from {Toys::Context::Key::USAGE_ERRORS},
-      # {Toys::Context::Key::UNMATCHED_ARGS}, and similar keys.
+      # This tool runs even if a usage error is encountered, by setting the
+      # `run` method as the usage error handler.
       #
       #     tool "foo" do
       #       def run
@@ -1334,7 +1435,7 @@ module Toys
       # Specify that the given module should be mixed into this tool, and its
       # methods made available when running the tool.
       #
-      # You may provide either a module, the string name of a mixin that you
+      # You can provide either a module, the string name of a mixin that you
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
@@ -1365,7 +1466,7 @@ module Toys
       ##
       # Determine if the given module/mixin has already been included.
       #
-      # You may provide either a module, the string name of a mixin that you
+      # You can provide either a module, the string name of a mixin that you
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #

data/core-docs/toys/middleware.rb

@@ -21,8 +21,9 @@ module Toys
   # Generally, a middleware is a class that implements one or more of the
   # methods defined in this module: {Toys::Middleware#config}, and
   # {Toys::Middleware#run}. This module provides default implementations that
-  # do nothing, but using them is not required. Middleware objects need respond
-  # only to methods they care about.
+  # do nothing, but it is not required to include this module, or even to
+  # define both methods. Middleware objects need respond only to methods they
+  # care about.
   #
   module Middleware
     ##

data/core-docs/toys/settings.rb

@@ -221,7 +221,7 @@ module Toys
   #     has a parent, the parent is queried. If that parent also does not have
   #     a value for the field, it may query its parent in turn, and so forth.
   #  *  If we encounter a root settings with no parent, and still no value is
-  #     set for the field, the default is returned.
+  #     set for the field, the default for the *original* setting is returned.
   #
   # Example:
   #

data/core-docs/toys/standard_mixins/bundler.rb

@@ -5,6 +5,21 @@ module Toys
     #
     # Ensures that a bundle is installed and set up when this tool is run.
     #
+    # This is the normal recommended way to use [bundler](https://bundler.io)
+    # with Toys. Including this mixin in a tool will cause Toys to ensure that
+    # the bundle is installed and available during tool execution. For example:
+    #
+    #     tool "run-rails" do
+    #       include :bundler
+    #       def run
+    #         # Note: no "bundle exec" required because Toys has already
+    #         # installed and loaded the bundle.
+    #         exec "rails s"
+    #       end
+    #     end
+    #
+    # ### Customization
+    #
     # The following parameters can be passed when including this mixin:
     #
     #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
@@ -39,7 +54,7 @@ module Toys
     #     Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
     #
     #  *  `:toys_gemfile_names` (Array\<String\>) File names that are
-    #     recognized as Gemfiles when wearching in Toys directories.
+    #     recognized as Gemfiles when searching in Toys directories.
     #     Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
     #
     #  *  `:on_missing` (Symbol) What to do if a needed gem is not installed.

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

@@ -3,10 +3,10 @@ module Toys
     ##
     # **_Defined in the toys-core gem_**
     #
-    # A set of helper methods for invoking subcommands. Provides shortcuts for
-    # common cases such as invoking Ruby in a subprocess or capturing output
-    # in a string. Also provides an interface for controlling a spawned
-    # process's streams.
+    # The `:exec` mixin provides set of helper methods for executing processes
+    # and subcommands. It provides shortcuts for common cases such as invoking
+    # a Ruby script in a subprocess or capturing output in a string. It also
+    # provides an interface for controlling a spawned process's streams.
     #
     # You can make these methods available to your tool by including the
     # following directive in your tool configuration:
@@ -16,6 +16,25 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
+    # ### Mixin overview
+    #
+    # The mixin provides a number of methods for spawning processes. The most
+    # basic are {#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 mixin
+    # also provides convenience methods for common cases such as spawning a
+    # Ruby process, spawning a shell script, or capturing output.
+    #
+    # The mixin also stores default configuration that it applies to processes
+    # it spawns. You can change these defaults by calling {#configure_exec}.
+    #
+    # Underlying the mixin is a service object of type {Toys::Utils::Exec}.
+    # Normally you would use the mixin methods to access this functionality,
+    # but you can also retrieve the service object itself by calling
+    # {Toys::Context#get} with the key {Toys::StandardMixins::Exec::KEY}.
+    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -24,7 +43,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.
@@ -44,7 +63,7 @@ module Toys
     # When running a process in the background, the controller is returned from
     # the method that starts the process:
     #
-    #     controller = exec_service.exec(["git", "init"], background: true)
+    #     controller = exec(["git", "init"], background: true)
     #
     # ### Stream handling
     #

data/core-docs/toys/standard_mixins/gems.rb

@@ -10,11 +10,24 @@ module Toys
     # tool DSL itself, so you can also ensure a gem is present when defining a
     # tool.
     #
-    # You may make these methods available to your tool by including the
-    # following directive in your tool configuration:
+    # ### Usage
+    #
+    # Make these methods available to your tool by including this mixin in your
+    # tool:
     #
     #     include :gems
     #
+    # You can then call the mixin method {#gem} to ensure that a gem is
+    # installed and in the load path. For example:
+    #
+    #     tool "my_tool" do
+    #       include :gems
+    #       gem "nokogiri", "~> 1.15"
+    #       def run
+    #         # Do stuff with Nokogiri
+    #       end
+    #     end
+    #
     # If you pass additional options to the include directive, those are used
     # to initialize settings for the gem install process. For example:
     #
@@ -34,7 +47,8 @@ module Toys
       end
 
       ##
-      # Activate the given gem.
+      # Activate the given gem. If it is not present, attempt to install it (or
+      # inform the user to update the bundle).
       #
       # @param name [String] Name of the gem
       # @param requirements [String...] Version requirements