toys 0.3.0 → 0.3.1

data/lib/toys/context.rb

@@ -33,6 +33,14 @@ module Toys
   ##
   # The object context in effect during the execution of a tool.
   #
+  # The context is generally a hash of key-value pairs.
+  # Keys that begin with two underscores are reserved common elements of the
+  # context such as the tool being executed, or the verbosity level.
+  # Other keys are available for use by your tool. Generally, they are set
+  # by switches and arguments in your tool. Context values may also be set
+  # by middleware. By convention, middleware-set keys begin with a single
+  # underscore.
+  #
   class Context
     ##
     # Context key for the verbosity value. Verbosity is an integer defaulting
@@ -86,6 +94,15 @@ module Toys
     #
     USAGE_ERROR = :__usage_error
 
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    # @private
+    #
+    # @param [Toys::Context::Base] context_base
+    # @param [Hash] data
+    #
     def initialize(context_base, data)
       @_context_base = context_base
       @_data = data
@@ -94,58 +111,140 @@ module Toys
       @_data[LOGGER] = context_base.logger
     end
 
+    ##
+    # Return the verbosity as an integer.
+    # @return [Integer]
+    #
     def verbosity
       @_data[VERBOSITY]
     end
 
+    ##
+    # Return the tool being executed.
+    # @return [Toys::Tool]
+    #
     def tool
       @_data[TOOL]
     end
 
+    ##
+    # Return the name of the tool being executed, as an array of strings.
+    # @return [Array[String]]
+    #
     def tool_name
       @_data[TOOL_NAME]
     end
 
+    ##
+    # Return the raw arguments passed to the tool, as an array of strings.
+    # This does not include the tool name itself.
+    # @return [Array[String]]
+    #
     def args
       @_data[ARGS]
     end
 
+    ##
+    # Return any usage error detected during argument parsing, or `nil` if
+    # no error was detected.
+    # @return [String,nil]
+    #
     def usage_error
       @_data[USAGE_ERROR]
     end
 
+    ##
+    # Return the logger for this execution.
+    # @return [Logger]
+    #
     def logger
       @_data[LOGGER]
     end
 
+    ##
+    # Return the active loader that can be used to get other tools.
+    # @return [Toys::Loader]
+    #
     def loader
       @_data[LOADER]
     end
 
+    ##
+    # Return the name of the binary that was executed.
+    # @return [String]
+    #
     def binary_name
       @_data[BINARY_NAME]
     end
 
+    ##
+    # Return a piece of raw data by key.
+    #
+    # @param [Symbol] key
+    # @return [Object]
+    #
     def [](key)
       @_data[key]
     end
 
+    ##
+    # Set a piece of data by key.
+    #
+    # Most tools themselves will not need to do this directly. It is generally
+    # used by middleware to modify the context and affect execution of tools
+    # that use it.
+    #
+    # @param [Symbol] key
+    # @param [Object] value
+    #
     def []=(key, value)
       @_data[key] = value
     end
 
+    ##
+    # Return an option value by key.
+    #
+    # @param [Symbol] key
+    # @return [Object]
+    #
+    def option(key)
+      @_data[key]
+    end
+
+    ##
+    # Returns the subset of the context that does not include well-known keys
+    # such as tool and verbosity. Technically, this includes all keys that do
+    # not begin with two underscores.
+    #
+    # @return [Hash]
+    #
     def options
       @_data.select do |k, _v|
         !k.is_a?(::Symbol) || !k.to_s.start_with?("__")
       end
     end
 
+    ##
+    # Execute another tool, given by the provided arguments.
+    #
+    # @param [String...] args Command line arguments defining another tool
+    #     to run, along with parameters and switches.
+    # @param [Boolean] exit_on_nonzero_status If true, exit immediately if the
+    #     run returns a nonzero error code.
+    # @return [Integer] The resulting status code
+    #
     def run(*args, exit_on_nonzero_status: false)
       code = @_context_base.run(args.flatten, verbosity: @_data[VERBOSITY])
       exit(code) if exit_on_nonzero_status && !code.zero?
       code
     end
 
+    ##
+    # Exit immediately with the given status code
+    #
+    # @param [Integer] code The status code, which should be 0 for no error,
+    #     or nonzero for an error condition.
+    #
     def exit(code)
       throw :result, code
     end

data/lib/toys/helpers.rb

@@ -34,6 +34,17 @@ module Toys
   # Namespace for common helper modules
   #
   module Helpers
+    ##
+    # Return a helper module by name.
+    #
+    # Currently recognized module names are:
+    #
+    # * `:exec` : Methods to help execute subcommands.
+    # * `:file_utils` : The FileUtils standard library methods.
+    #
+    # @param [String,Symbol] name Name of the helper module to return
+    # @return [Module,nil] The module, or `nil` if not found
+    #
     def self.lookup(name)
       Utils::ModuleLookup.lookup(:helpers, name)
     end

data/lib/toys/helpers/exec.rb

@@ -32,14 +32,72 @@ require "logger"
 module Toys
   module Helpers
     ##
-    # A set of helper methods for invoking subcommands
+    # 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.
+    #
+    # ## Configuration options
+    #
+    # A variety of options can be used to control subprocesses. These include:
+    #
+    # *  **:env** (Hash) Environment variables to pass to the subprocess
+    # *  **:log_level** (Integer) If set, the actual command will be logged
+    #    at the given level.
+    # *  **:in_from** (`:controller`,String) Connects the input stream of the
+    #    subprocess. If set to `:controller`, the controller will control the
+    #    input stream. If set to a string, that string will be written to the
+    #    input stream. If not set, the input stream will be connected to the
+    #    STDIN for the Toys process itself.
+    # *  **:out_to** (`:controller`,`:capture`) Connects the standard output
+    #    stream of the subprocess. If set to `:controller`, the controller
+    #    will control the output stream. If set to `:capture`, the output will
+    #    be captured in a string that is available in the
+    #    {Toys::Helpers::Exec::Result} object. If not set, the subprocess
+    #    standard out is connected to STDOUT of the Toys process.
+    # *  **:err_to** (`:controller`,`:capture`) Connects the standard error
+    #    stream of the subprocess. See `:out_to` for more details.
+    # *  **:out_err_to** (`:controller`,`:capture`) Combines the standard out
+    #    and error streams of the subprocess and connects them. See `:out_to`
+    #    for more details.
+    # *  **:exit_on_nonzero_status** (Boolean) If true, a nonzero status code
+    #    will cause the entire tool to terminate. Default is false.
+    #
+    # In addition, any options recognized by `Process#spawn` are supported.
+    # These include `:umask`, `:pgroup`, `:chdir`, and many others.
+    #
+    # Configuration options may be provided to any method that starts a
+    # subprocess. You may also set default values for this tool by calling
+    # {Toys::Helpers::Exec#configure_exec}.
     #
     module Exec
+      ##
+      # Set default configuration keys.
+      #
+      # @param [Hash] opts The default options. See the section on
+      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      #
       def configure_exec(opts = {})
         @exec_config ||= {}
         @exec_config.merge!(opts)
       end
 
+      ##
+      # Execute a command. The command may be given as a single string to pass
+      # to a shell, or an array of strings indicating a posix command.
+      #
+      # If you provide a block, a {Toys::Helpers::Exec::Controller} will be
+      # yielded to it, allowing you to interact with the subprocess streams.
+      #
+      # @param [String,Array<String>] cmd The command to execute.
+      # @param [Hash] opts The command options. See the section on
+      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
+      #     for the subprocess streams.
+      #
+      # @return [Toys::Helpers::Result] The subprocess result, including
+      #     exit code and any captured output.
+      #
       def exec(cmd, opts = {}, &block)
         exec_opts = ExecOpts.new(self)
         exec_opts.add(@exec_config) if defined? @exec_config
@@ -48,6 +106,21 @@ module Toys
         executor.execute(&block)
       end
 
+      ##
+      # Spawn a ruby process and pass the given arguments to it.
+      #
+      # If you provide a block, a {Toys::Helpers::Exec::Controller} will be
+      # yielded to it, allowing you to interact with the subprocess streams.
+      #
+      # @param [String,Array<String>] args The arguments to ruby.
+      # @param [Hash] opts The command options. See the section on
+      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
+      #     for the subprocess streams.
+      #
+      # @return [Toys::Helpers::Result] The subprocess result, including
+      #     exit code and any captured output.
+      #
       def ruby(args, opts = {}, &block)
         cmd =
           if args.is_a?(Array)
@@ -58,22 +131,54 @@ module Toys
         exec(cmd, opts, &block)
       end
 
+      ##
+      # Execute the given string in a shell. Returns the exit code.
+      #
+      # @param [String] cmd The shell command to execute.
+      # @param [Hash] opts The command options. See the section on
+      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
+      #     for the subprocess streams.
+      #
+      # @return [Integer] The exit code
+      #
       def sh(cmd, opts = {})
         exec(cmd, opts).exit_code
       end
 
+      ##
+      # Execute a command. The command may be given as a single string to pass
+      # to a shell, or an array of strings indicating a posix command.
+      #
+      # Captures standard out and returns it as a string.
+      #
+      # @param [String,Array<String>] cmd The command to execute.
+      # @param [Hash] opts The command options. See the section on
+      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
+      #     for the subprocess streams.
+      #
+      # @return [String] What was written to standard out.
+      #
       def capture(cmd, opts = {})
         exec(cmd, opts.merge(out_to: :capture)).captured_out
       end
 
+      ##
+      # Returns the paty to the Ruby binary
+      # @return [String] Path to the Ruby binary
+      #
       def self.ruby_binary
         ::File.join(::RbConfig::CONFIG["bindir"], ::RbConfig::CONFIG["ruby_install_name"])
       end
 
       ##
-      # The object passed to a subcommand control block
+      # An object of this type is passed to a subcommand control block.
+      # You may use this object to interact with the subcommand's streams,
+      # and/or send signals to the process.
       #
       class Controller
+        ## @private
         def initialize(ins, out, err, out_err, pid)
           @in = ins
           @out = out
@@ -82,12 +187,50 @@ module Toys
           @pid = pid
         end
 
+        ##
+        # Return the subcommand's standard input stream (which can be written
+        # to), if the command was configured with `in_from: :controller`.
+        # Returns `nil` otherwise.
+        # @return [IO,nil]
+        #
         attr_reader :in
+
+        ##
+        # Return the subcommand's standard output stream (which can be read
+        # from), if the command was configured with `out_to: :controller`.
+        # Returns `nil` otherwise.
+        # @return [IO,nil]
+        #
         attr_reader :out
+
+        ##
+        # Return the subcommand's standard error stream (which can be read
+        # from), if the command was configured with `err_to: :controller`.
+        # Returns `nil` otherwise.
+        # @return [IO,nil]
+        #
         attr_reader :err
+
+        ##
+        # Return the subcommand's combined standard output and error stream
+        # (which can be read from), if the command was configured with
+        # `out_err_to: :controller`. Returns `nil` otherwise.
+        # @return [IO,nil]
+        #
         attr_reader :out_err
+
+        ##
+        # Returns the process ID.
+        # @return [Integer]
+        #
         attr_reader :pid
 
+        ##
+        # Send the given signal to the process. The signal may be specified
+        # by name or number.
+        #
+        # @param [Integer,String] signal The signal to send.
+        #
         def kill(signal)
           ::Process.kill(signal, pid)
         end
@@ -97,6 +240,7 @@ module Toys
       # The return result from a subcommand
       #
       class Result
+        ## @private
         def initialize(out, err, out_err, status)
           @captured_out = out
           @captured_err = err
@@ -104,19 +248,53 @@ module Toys
           @status = status
         end
 
+        ##
+        # Returns the captured output string, if the command was configured
+        # with `out_to: :capture`. Returns `nil` otherwise.
+        # @return [String,nil]
+        #
         attr_reader :captured_out
+
+        ##
+        # Returns the captured error string, if the command was configured
+        # with `err_to: :capture`. Returns `nil` otherwise.
+        # @return [String,nil]
+        #
         attr_reader :captured_err
+
+        ##
+        # Returns the captured combined output and error string, if the command
+        # was configured with `out_err_to: :capture`. Returns `nil` otherwise.
+        # @return [String,nil]
+        #
         attr_reader :captured_out_err
+
+        ##
+        # Returns the status code object.
+        # @return [Process::Status]
+        #
         attr_reader :status
 
+        ##
+        # Returns the numeric status code.
+        # @return [Integer]
+        #
         def exit_code
           status.exitstatus
         end
 
+        ##
+        # Returns true if the subprocess terminated with a zero status.
+        # @return [Boolean]
+        #
         def success?
           exit_code.zero?
         end
 
+        ##
+        # Returns true if the subprocess terminated with a nonzero status.
+        # @return [Boolean]
+        #
         def error?
           !exit_code.zero?
         end