toys 0.13.1 → 0.14.2

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

@@ -0,0 +1,46 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A mixin that provides a pager.
+    #
+    # This mixin provides an instance of {Toys::Utils::Pager}, which invokes
+    # an external pager for output.
+    #
+    # @example
+    #
+    #   include :pager
+    #
+    #   def run
+    #     pager do |io|
+    #       io.puts "A long string\n"
+    #     end
+    #   end
+    #
+    module Pager
+      include Mixin
+
+      ##
+      # Context key for the Pager object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      ##
+      # Access the Pager.
+      #
+      # If *no* block is given, returns the pager object.
+      #
+      # If a block is given, the pager is executed with the given block, and
+      # the exit code of the pager process is returned.
+      #
+      # @return [Toys::Utils::Pager] if no block is given.
+      # @return [Integer] if a block is given.
+      #
+      def pager(&block)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

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

@@ -12,15 +12,15 @@ module Toys
     # the [XDG Base Directory Spec version
     # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
     #
-    # Example usage:
+    # @example
     #
-    #     include :xdg
+    #   include :xdg
     #
-    #     def run
-    #       # Get config file paths, in order from most to least inportant
-    #       config_files = xdg.lookup_config("my-config.toml")
-    #       config_files.each { |path| read_my_config(path) }
-    #     end
+    #   def run
+    #     # Get config file paths, in order from most to least inportant
+    #     config_files = xdg.lookup_config("my-config.toml")
+    #     config_files.each { |path| read_my_config(path) }
+    #   end
     #
     module XDG
       include Mixin

data/core-docs/toys/tool_definition.rb

@@ -106,6 +106,28 @@ module Toys
       settings_attr :propagate_helper_methods, default: false
     end
 
+    ##
+    # Create a new tool.
+    # Should be created only from the DSL via the Loader.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def initialize(parent, full_name, priority, source_root, middleware_stack, middleware_lookup,
+                   tool_class = nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Reset the definition of this tool, deleting all definition data but
+    # leaving named acceptors, mixins, and templates intact.
+    # Should be called only from the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def reset_definition
+      # Source available in the toys-core gem
+    end
+
     ##
     # Settings for this tool
     #
@@ -922,5 +944,52 @@ module Toys
     def delegate_to(target)
       # Source available in the toys-core gem
     end
+
+    ##
+    # Lookup the custom context directory in this tool and its ancestors.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def lookup_custom_context_directory
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Mark this tool as having at least one module included.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def mark_includes_modules
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Complete definition and run middleware configs. Should be called from
+    # the Loader only.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def finish_definition(loader)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Run all initializers against a context. Called from the Runner.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def run_initializers(context)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Check that the tool can still be defined. Should be called internally
+    # or from the DSL only.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def check_definition_state(is_arg: false, is_method: false)
+      # Source available in the toys-core gem
+    end
   end
 end

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

@@ -50,54 +50,88 @@ module Toys
     # options.
     #
     # Three general strategies are available for custom stream handling. First,
-    # you may redirect to other streams such as files, IO objects, or Ruby
+    # you can redirect to other streams such as files, IO objects, or Ruby
     # strings. Some of these options map directly to options provided by the
-    # `Process#spawn` method. Second, you may use a controller to manipulate
-    # the streams programmatically. Third, you may capture output stream data
+    # `Process#spawn` method. Second, you can use a controller to manipulate
+    # the streams programmatically. Third, you can capture output stream data
     # and make it available in the result.
     #
     # Following is a full list of the stream handling options, along with how
     # to specify them using the `:in`, `:out`, and `:err` options.
     #
-    #  *  **Inherit parent stream:** You may inherit the corresponding stream
+    #  *  **Inherit parent stream:** You can inherit the corresponding stream
     #     in the parent process by passing `:inherit` as the option value. This
     #     is the default if the subprocess is *not* run in the background.
-    #  *  **Redirect to null:** You may redirect to a null stream by passing
+    #
+    #  *  **Redirect to null:** You can redirect to a null stream by passing
     #     `:null` as the option value. This connects to a stream that is not
     #     closed but contains no data, i.e. `/dev/null` on unix systems. This
     #     is the default if the subprocess is run in the background.
-    #  *  **Close the stream:** You may close the stream by passing `:close` as
+    #
+    #  *  **Close the stream:** You can close the stream by passing `:close` as
     #     the option value. This is the same as passing `:close` to
     #     `Process#spawn`.
-    #  *  **Redirect to a file:** You may redirect to a file. This reads from
+    #
+    #  *  **Redirect to a file:** You can redirect to a file. This reads from
     #     an existing file when connected to `:in`, and creates or appends to a
     #     file when connected to `:out` or `:err`. To specify a file, use the
-    #     setting `[:file, "/path/to/file"]`. You may also, when writing a
+    #     setting `[:file, "/path/to/file"]`. You can also, when writing a
     #     file, append an optional mode and permission code to the array. For
     #     example, `[:file, "/path/to/file", "a", 0644]`.
-    #  *  **Redirect to an IO object:** You may redirect to an IO object in the
-    #     parent process, by passing the IO object as the option value. You may
+    #
+    #  *  **Redirect to an IO object:** You can redirect to an IO object in the
+    #     parent process, by passing the IO object as the option value. You can
     #     use any IO object. For example, you could connect the child's output
     #     to the parent's error using `out: $stderr`, or you could connect to
     #     an existing File stream. Unlike `Process#spawn`, this works for IO
     #     objects that do not have a corresponding file descriptor (such as
     #     StringIO objects). In such a case, a thread will be spawned to pipe
     #     the IO data through to the child process.
-    #  *  **Combine with another child stream:** You may redirect one child
+    #
+    #  *  **Redirect to a pipe:** You can redirect to a pipe created using
+    #     `IO.pipe` (i.e. a two-element array of read and write IO objects) by
+    #     passing the array as the option value. This will connect the
+    #     appropriate IO (either read or write), and close it in the parent.
+    #     Thus, you can connect only one process to each end. If you want more
+    #     direct control over IO closing behavior, pass the IO object (i.e. the
+    #     element of the pipe array) directly.
+    #
+    #  *  **Combine with another child stream:** You can redirect one child
     #     output stream to another, to combine them. To merge the child's error
     #     stream into its output stream, use `err: [:child, :out]`.
-    #  *  **Read from a string:** You may pass a string to the input stream by
+    #
+    #  *  **Read from a string:** You can pass a string to the input stream by
     #     setting `[:string, "the string"]`. This works only for `:in`.
-    #  *  **Capture output stream:** You may capture a stream and make it
+    #
+    #  *  **Capture output stream:** You can capture a stream and make it
     #     available on the {Toys::Utils::Exec::Result} object, using the
     #     setting `:capture`. This works only for the `:out` and `:err`
     #     streams.
-    #  *  **Use the controller:** You may hook a stream to the controller using
+    #
+    #  *  **Use the controller:** You can hook a stream to the controller using
     #     the setting `:controller`. You can then manipulate the stream via the
     #     controller. If you pass a block to {Toys::Utils::Exec#exec}, it
     #     yields the {Toys::Utils::Exec::Controller}, giving you access to
     #     streams.
     #
+    #  *  **Make copies of an output stream:** You can "tee," or duplicate the
+    #     `:out` or `:err` stream and redirect those copies to various
+    #     destinations. To specify a tee, use the setting `[:tee, ...]` where
+    #     the additional array elements include two or more of the following.
+    #     See the corresponding documentation above for more detail.
+    #      *  `:inherit` to direct to the parent process's stream.
+    #      *  `:capture` to capture the stream and store it in the result.
+    #      *  `:controller` to direct the stream to the controller.
+    #      *  `[:file, "/path/to/file"]` to write to a file.
+    #      *  An `IO` or `StringIO` object.
+    #      *  An array of two `IO` objects representing a pipe
+    #
+    #     Additionally, the last element of the array can be a hash of options.
+    #     Supported options include:
+    #      *  `:buffer_size` The size of the memory buffer for each element of
+    #         the tee. Larger buffers may allow higher throughput. The default
+    #         is 65536.
+    #
     # ### Result handling
     #
     # A subprocess result is represented by a {Toys::Utils::Exec::Result}
@@ -167,7 +201,7 @@ module Toys
     #     not present, the command is not logged.
     #
     #  *  `:log_level` (Integer,false) Level for logging the actual command.
-    #     Defaults to Logger::INFO if not present. You may also pass `false` to
+    #     Defaults to Logger::INFO if not present. You can also pass `false` to
     #     disable logging of the command.
     #
     #  *  `:log_cmd` (String) The string logged for the actual command.
@@ -222,7 +256,7 @@ module Toys
       end
 
       ##
-      # Execute a command. The command may be given as a single string to pass
+      # Execute a command. The command can be given as a single string to pass
       # to a shell, or an array of strings indicating a posix command.
       #
       # If the process is not set to run in the background, and a block is
@@ -287,7 +321,7 @@ module Toys
       end
 
       ##
-      # Execute a command. The command may be given as a single string to pass
+      # Execute a command. The command can 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.
@@ -375,7 +409,7 @@ module Toys
       # An object that controls a subprocess. This object is returned from an
       # execution running in the background, or is yielded to a control block
       # for an execution running in the foreground.
-      # You may use this object to interact with the subcommand's streams,
+      # You can use this object to interact with the subcommand's streams,
       # send signals to the process, and get its result.
       #
       class Controller
@@ -466,8 +500,8 @@ module Toys
         ##
         # Redirects the remainder of the given stream.
         #
-        # You may specify the stream as an IO or IO-like object, or as a file
-        # specified by its path. If specifying a file, you may optionally
+        # You can specify the stream as an IO or IO-like object, or as a file
+        # specified by its path. If specifying a file, you can optionally
         # provide the mode and permissions for the call to `File#open`. You can
         # also specify the value `:null` to indicate the null file.
         #
@@ -486,8 +520,8 @@ module Toys
         ##
         # Redirects the remainder of the standard input stream.
         #
-        # You may specify the stream as an IO or IO-like object, or as a file
-        # specified by its path. If specifying a file, you may optionally
+        # You can specify the stream as an IO or IO-like object, or as a file
+        # specified by its path. If specifying a file, you can optionally
         # provide the mode and permissions for the call to `File#open`. You can
         # also specify the value `:null` to indicate the null file.
         #
@@ -505,8 +539,8 @@ module Toys
         ##
         # Redirects the remainder of the standard output stream.
         #
-        # You may specify the stream as an IO or IO-like object, or as a file
-        # specified by its path. If specifying a file, you may optionally
+        # You can specify the stream as an IO or IO-like object, or as a file
+        # specified by its path. If specifying a file, you can optionally
         # provide the mode and permissions for the call to `File#open`. You can
         # also specify the value `:null` to indicate the null file.
         #
@@ -524,8 +558,8 @@ module Toys
         ##
         # Redirects the remainder of the standard error stream.
         #
-        # You may specify the stream as an IO or IO-like object, or as a file
-        # specified by its path. If specifying a file, you may optionally
+        # You can specify the stream as an IO or IO-like object, or as a file
+        # specified by its path. If specifying a file, you can optionally
         # provide the mode and permissions for the call to `File#open`.
         #
         # After calling this, do not interact directly with the stream.
@@ -540,7 +574,7 @@ module Toys
         end
 
         ##
-        # Send the given signal to the process. The signal may be specified
+        # Send the given signal to the process. The signal can be specified
         # by name or number.
         #
         # @param sig [Integer,String] The signal to send.

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

@@ -0,0 +1,104 @@
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A class that invokes an external pager.
+    #
+    # @example Using a pager for regular output
+    #
+    #   Toys::Utils::Pager.start do |io|
+    #     io.puts "A long string\n"
+    #   end
+    #
+    # @example Piping output from a command
+    #
+    #   exec_service = Toys::Utils::Exec.new
+    #   Toys::Utils::Pager.start(exec_service: exec_service) do |io|
+    #     exec_service.exec(["/bin/ls", "-alF"], out: io)
+    #   end
+    #
+    class Pager
+      ##
+      # Creates a new pager.
+      #
+      # @param command [String,Array<String>,boolean] The command to use to
+      #     invoke the pager. May be specified as a string to be passed to the
+      #     shell, an array of strings representing a posix command, the value
+      #     `true` to use the default (normally `less -FIRX`), or the value
+      #     `false` to disable the pager and write directly to the output
+      #     stream. Default is `true`.
+      # @param exec_service [Toys::Utils::Exec] The service to use for
+      #     executing commands, or `nil` (the default) to use a default.
+      # @param fallback_io [IO] An IO-like object to write to if the pager is
+      #     disabled. Defaults to `$stdout`.
+      #
+      def initialize(command: true, exec_service: nil, fallback_io: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Runs the pager. Takes a block and yields an IO-like object that passes
+      # text to the pager. Can be called multiple times on the same pager.
+      #
+      # @yieldparam io [IO] An object that can be written to, to pass data to
+      #     the pager.
+      # @return [Integer] The exit code of the pager process.
+      #
+      # @example
+      #
+      #   pager = Toys::Utils::Pager.new
+      #   pager.start do |io|
+      #     io.puts "A long string\n"
+      #   end
+      #
+      def start
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # The command for running the pager process. May be specified as a string
+      # to be passed to the shell, an array of strings representing a posix
+      # command, or `nil` to disable the pager and write directly to an output
+      # stream.
+      #
+      # @return [String,Array<String>,nil]
+      #
+      attr_accessor :command
+
+      ##
+      # The IO stream used if the pager is disabled or could not be executed.
+      #
+      # @return [IO]
+      #
+      attr_accessor :fallback_io
+
+      class << self
+        ##
+        # A convenience method that creates a pager and runs it once by calling
+        # {Pager#start}.
+        #
+        # @param command [String,Array<String>,boolean] The command to use to
+        #     invoke the pager. May be specified as a string to be passed to the
+        #     shell, an array of strings representing a posix command, the value
+        #     `true` to use the default (normally `less -FIRX`), or the value
+        #     `false` to disable the pager and write directly to the output
+        #     stream. Default is `true`.
+        # @param exec_service [Toys::Utils::Exec] The service to use for
+        #     executing commands, or `nil` (the default) to use a default.
+        # @param fallback_io [IO] An IO-like object to write to if the pager is
+        #     disabled. Defaults to `$stdout`.
+        # @return [Integer] The exit code of the pager process.
+        #
+        # @example
+        #
+        #   Toys::Utils::Pager.start do |io|
+        #     io.puts "A long string\n"
+        #   end
+        def start(command: true, exec_service: nil, fallback_io: nil, &block)
+          # Source available in the toys-core gem
+        end
+      end
+    end
+  end
+end

data/core-docs/toys/wrappable_string.rb

@@ -4,9 +4,19 @@ module Toys
   #
   # A string intended for word-wrapped display.
   #
+  # A WrappableString is an array of string "fragments" representing the atomic
+  # units that should not be split when word-wrapping. It should be possible to
+  # reconstruct the original string by joining these fragments with whitespace.
+  #
   class WrappableString
     ##
     # Create a wrapped string.
+    #
+    # You can pass either:
+    #
+    #  *  A single String, which will be split into fragments by whitespace.
+    #  *  An array of Strings representing the fragments explicitly.
+    #
     # @param string [String,Array<String>] The string or array of string
     #     fragments
     #
@@ -34,6 +44,7 @@ module Toys
 
     ##
     # Returns true if the string is empty (i.e. has no fragments)
+    #
     # @return [Boolean]
     #
     def empty?
@@ -42,6 +53,7 @@ module Toys
 
     ##
     # Returns the string without any wrapping
+    #
     # @return [String]
     #
     def string