toys-core 0.13.1 → 0.14.1

data/lib/toys/source_info.rb

@@ -140,7 +140,7 @@ module Toys
     ##
     # Create a SourceInfo.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def initialize(parent, priority, context_directory, source_type, source_path, source_proc,
                    git_remote, git_path, git_commit, source_name, data_dir_name, lib_dir_name)
@@ -165,7 +165,7 @@ module Toys
     ##
     # Create a child SourceInfo relative to the parent path.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def relative_child(filename, source_name: nil)
       unless source_type == :directory
@@ -189,7 +189,7 @@ module Toys
     ##
     # Create a child SourceInfo with an absolute path.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def absolute_child(child_path, source_name: nil)
       child_path, type = SourceInfo.check_path(child_path, false)
@@ -201,7 +201,7 @@ module Toys
     ##
     # Create a child SourceInfo with a git source.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def git_child(child_git_remote, child_git_path, child_git_commit, child_path,
                   source_name: nil)
@@ -216,7 +216,7 @@ module Toys
     ##
     # Create a proc child SourceInfo
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def proc_child(child_proc, source_name: nil)
       source_name ||= self.source_name
@@ -228,7 +228,7 @@ module Toys
     ##
     # Create a root source info for a file path.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def self.create_path_root(source_path, priority,
                               context_directory: nil,
@@ -250,7 +250,7 @@ module Toys
     ##
     # Create a root source info for a cached git repo.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def self.create_git_root(git_remote, git_path, git_commit, source_path, priority,
                              context_directory: nil,
@@ -266,7 +266,7 @@ module Toys
     ##
     # Create a root source info for a proc.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def self.create_proc_root(source_proc, priority,
                               context_directory: nil,
@@ -281,7 +281,7 @@ module Toys
     ##
     # Check a path and determine the canonical path and type.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def self.check_path(path, lenient)
       path = ::File.expand_path(path)

data/lib/toys/standard_middleware/show_help.rb

@@ -285,23 +285,11 @@ module Toys
           separate_sources: @separate_sources,
           wrap_width: terminal.width
         )
-        if less_path
-          require "toys/utils/exec"
-          Utils::Exec.new.exec([less_path, "-R"], in: [:string, str])
-        else
-          terminal.puts(str)
-        end
-      end
-
-      def less_path
-        unless defined? @less_path
-          @less_path =
-            if @use_less && @stream.tty?
-              path = `which less`.strip
-              path.empty? ? nil : path
-            end
+        require "toys/utils/pager"
+        use_pager = @use_less && @stream.tty?
+        Utils::Pager.start(command: use_pager, fallback_io: terminal) do |io|
+          io.puts(str)
         end
-        @less_path
       end
 
       def get_help_text(context, use_extra_args)

data/lib/toys/standard_mixins/exec.rb

@@ -8,7 +8,7 @@ module Toys
     # in a string. Also provides an interface for controlling a spawned
     # process's streams.
     #
-    # You may make these methods available to your tool by including the
+    # You can make these methods available to your tool by including the
     # following directive in your tool configuration:
     #
     #     include :exec
@@ -54,54 +54,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::StandardMixins::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}
@@ -191,7 +225,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.
@@ -245,7 +279,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
@@ -352,7 +386,7 @@ module Toys
       ##
       # Execute a tool in the current CLI in a forked process.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If the process is not set to run in the background, and a block is
@@ -390,7 +424,7 @@ module Toys
       ##
       # Execute a tool in a separately spawned process.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If the process is not set to run in the background, and a block is
@@ -435,7 +469,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.
@@ -540,7 +574,7 @@ module Toys
       # Captures standard out and returns it as a string.
       # Cannot be run in the background.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
@@ -578,7 +612,7 @@ module Toys
       # Captures standard out and returns it as a string.
       # Cannot be run in the background.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
@@ -662,6 +696,36 @@ module Toys
         0
       end
 
+      ##
+      # Returns an array of standard verbosity flags needed to replicate the
+      # current verbosity level. This is useful when you want to spawn tools
+      # with the same verbosity level as the current tool.
+      #
+      # @param short [Boolean] Whether to emit short rather than long flags.
+      #     Default is false.
+      # @return [Array<String>]
+      #
+      def verbosity_flags(short: false)
+        verbosity = self[Context::Key::VERBOSITY]
+        if verbosity.positive?
+          if short
+            flag = "v" * verbosity
+            ["-#{flag}"]
+          else
+            ::Array.new(verbosity, "--verbose")
+          end
+        elsif verbosity.negative?
+          if short
+            flag = "q" * -verbosity
+            ["-#{flag}"]
+          else
+            ::Array.new(-verbosity, "--quiet")
+          end
+        else
+          []
+        end
+      end
+
       ##
       # @private
       #

data/lib/toys/standard_mixins/pager.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Toys
+  module StandardMixins
+    ##
+    # 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)
+        pager = self[KEY]
+        return pager unless block
+        self[KEY].start(&block)
+      end
+
+      on_initialize do
+        require "toys/utils/pager"
+        exec_service =
+          if defined?(::Toys::StandardMixins::Exec)
+            self[::Toys::StandardMixins::Exec::KEY]
+          end
+        self[KEY] = Utils::Pager.new(exec_service: exec_service)
+      end
+    end
+  end
+end

data/lib/toys/standard_mixins/xdg.rb

@@ -14,15 +14,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/lib/toys/tool_definition.rb

@@ -136,7 +136,9 @@ module Toys
         tool_name, prefix, fragment = analyze_subtool_fragment(context)
         return unless tool_name
         subtools = context.cli.loader.list_subtools(tool_name,
-                                                    include_hidden: @include_hidden_subtools)
+                                                    include_namespaces: true,
+                                                    include_hidden: @include_hidden_subtools,
+                                                    include_non_runnable: @include_hidden_subtools)
         return if subtools.empty?
         candidates = []
         subtools.each do |subtool|
@@ -214,7 +216,7 @@ module Toys
     # Create a new tool.
     # Should be created only from the DSL via the Loader.
     #
-    # @private
+    # @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)
@@ -241,7 +243,7 @@ module Toys
     # leaving named acceptors, mixins, and templates intact.
     # Should be called only from the DSL.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def reset_definition
       @tool_class = @precreated_class || create_class
@@ -1276,7 +1278,7 @@ module Toys
     ##
     # Lookup the custom context directory in this tool and its ancestors.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def lookup_custom_context_directory
       custom_context_directory || @parent&.lookup_custom_context_directory
@@ -1285,7 +1287,7 @@ module Toys
     ##
     # Mark this tool as having at least one module included.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def mark_includes_modules
       check_definition_state
@@ -1297,7 +1299,7 @@ module Toys
     # Complete definition and run middleware configs. Should be called from
     # the Loader only.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def finish_definition(loader)
       unless @definition_finished
@@ -1319,7 +1321,7 @@ module Toys
     ##
     # Run all initializers against a context. Called from the Runner.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def run_initializers(context)
       @initializers.each do |func, args, kwargs|
@@ -1331,7 +1333,7 @@ module Toys
     # Check that the tool can still be defined. Should be called internally
     # or from the DSL only.
     #
-    # @private
+    # @private This interface is internal and subject to change without warning.
     #
     def check_definition_state(is_arg: false, is_method: false)
       if @definition_finished