toys-core 0.13.1 → 0.14.1

data/lib/toys/utils/exec.rb

@@ -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::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}
@@ -171,7 +205,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.
@@ -227,7 +261,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
@@ -310,7 +344,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.
@@ -400,7 +434,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
@@ -502,8 +536,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.
         #
@@ -540,8 +574,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.
         #
@@ -559,8 +593,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.
         #
@@ -578,8 +612,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.
@@ -594,7 +628,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.
@@ -1091,7 +1125,7 @@ module Toys
             when :close
               :close
             else
-              stream if stream.respond_to?(:write)
+              stream if stream.respond_to?(:read)
             end
           if in_stream == :close
             stdstream.close
@@ -1163,16 +1197,23 @@ module Toys
         end
 
         def interpret_in_array(setting)
-          case setting.first
-          when ::Symbol
+          if setting.first.is_a?(::Symbol)
             setup_in_stream_of_type(setting.first, setting[1..-1])
-          when ::String
+          elsif setting.first.is_a?(::String)
             setup_in_stream_of_type(:file, setting)
+          elsif setting.size == 2 && setting.first.is_a?(::IO) && setting.last.is_a?(::IO)
+            interpret_in_pipe(*setting)
           else
             raise "Unknown value for in: #{setting.inspect}"
           end
         end
 
+        def interpret_in_pipe(reader, writer)
+          @spawn_opts[:in] = reader
+          @child_streams << reader
+          @parent_streams << writer
+        end
+
         def setup_in_stream_of_type(type, args)
           case type
           when :controller
@@ -1199,7 +1240,7 @@ module Toys
         end
 
         def interpret_in_file(args)
-          raise "Expected only file name" unless args.size == 1 && args.first.is_a?(::String)
+          raise "Expected only file name for in" unless args.size == 1 && args.first.is_a?(::String)
           @spawn_opts[:in] = args + [::File::RDONLY]
         end
 
@@ -1230,16 +1271,23 @@ module Toys
         end
 
         def interpret_out_array(key, setting)
-          case setting.first
-          when ::Symbol
+          if setting.first.is_a?(::Symbol)
             setup_out_stream_of_type(key, setting.first, setting[1..-1])
-          when ::String
+          elsif setting.first.is_a?(::String)
             setup_out_stream_of_type(key, :file, setting)
+          elsif setting.size == 2 && setting.first.is_a?(::IO) && setting.last.is_a?(::IO)
+            interpret_out_pipe(key, *setting)
           else
             raise "Unknown value for #{key}: #{setting.inspect}"
           end
         end
 
+        def interpret_out_pipe(key, reader, writer)
+          @spawn_opts[key] = writer
+          @child_streams << writer
+          @parent_streams << reader
+        end
+
         def setup_out_stream_of_type(key, type, args)
           case type
           when :controller
@@ -1260,17 +1308,150 @@ module Toys
             copy_from_out_thread(key, args.first)
           when :file
             interpret_out_file(key, args)
+          when :tee
+            interpret_out_tee(key, args)
           else
             raise "Unknown type for #{key}: #{type.inspect}"
           end
         end
 
         def interpret_out_file(key, args)
-          raise "Expected file name" if args.empty? || !args.first.is_a?(::String)
-          raise "Too many file arguments" if args.size > 3
+          raise "Expected file name for #{key}" if args.empty? || !args.first.is_a?(::String)
+          raise "Too many file arguments for #{key}" if args.size > 3
           @spawn_opts[key] = args.size == 1 ? args.first : args
         end
 
+        def interpret_out_tee(key, args)
+          opts = args.last.is_a?(::Hash) ? args.pop : {}
+          reader = make_out_pipe(key)
+          sinks = interpret_out_tee_arguments(key, args)
+          tee_runner(key, reader, sinks, opts[:buffer_size] || 65_536)
+        end
+
+        def interpret_out_tee_arguments(key, args)
+          args.map do |arg|
+            case arg
+            when :inherit
+              [key == :err ? $stderr : $stdout, nil]
+            when :capture
+              [::StringIO.new, :capture]
+            when :controller
+              tee_sink_for_controller(key)
+            when ::IO, ::StringIO
+              [arg, nil]
+            when ::String
+              [::File.open(arg, "w"), :close]
+            when ::Array
+              tee_sink_for_array(key, arg)
+            else
+              raise "Unknown value for #{key} tee argument: #{arg.inspect}"
+            end
+          end
+        end
+
+        def tee_sink_for_controller(key)
+          @controller_streams[key], writer = ::IO.pipe
+          writer.sync = true
+          [writer, :close]
+        end
+
+        def tee_sink_for_array(key, arg)
+          if arg.size == 2 &&
+             arg.last.is_a?(::IO) &&
+             (arg.first == :autoclose || arg.first.is_a?(::IO))
+            [arg.last, :close]
+          else
+            arg = arg[1..-1] if arg.first == :file
+            if arg.empty? || !arg.first.is_a?(::String)
+              raise "Expected file name for #{key} tee argument"
+            end
+            raise "Too many file arguments for #{key} tee argument" if arg.size > 3
+            arg += ["w"] if arg.size == 1
+            [::File.open(*arg), :close]
+          end
+        end
+
+        def tee_runner(key, reader, sinks, buffer_size)
+          @join_threads << ::Thread.new do
+            sinks.map! { |io, on_done| [io, ::String.new, :write_nonblock, on_done] }
+            until sinks.empty?
+              tee_wait_for_streams(reader, sinks)
+              reader = tee_read_stream(reader, sinks, buffer_size)
+              tee_write_streams(sinks, key, reader.nil?)
+            end
+          end
+        end
+
+        def tee_wait_for_streams(reader, sinks)
+          read_select = reader && [reader]
+          write_select = []
+          sinks.each do |io, buffer, _write_method, _on_done|
+            write_select << io unless buffer.empty?
+          end
+          ::IO.select(read_select, write_select)
+        end
+
+        def tee_read_stream(reader, sinks, buffer_size)
+          return nil if reader.nil?
+          max = tee_amount_to_read(sinks, buffer_size)
+          return reader unless max.positive?
+          begin
+            data = reader.read_nonblock(max)
+            unless data.empty?
+              sinks.each { |_io, buffer, _write_method, _on_done| buffer << data }
+            end
+            reader
+          rescue ::IO::WaitReadable
+            reader
+          rescue ::StandardError
+            reader.close rescue nil # rubocop:disable Style/RescueModifier
+            nil
+          end
+        end
+
+        def tee_write_streams(sinks, key, read_complete)
+          sinks.delete_if do |sink|
+            io, buffer, write_method, on_done = sink
+            done, write_method = tee_write_one_stream(io, buffer, write_method, read_complete)
+            sink[2] = write_method
+            if done
+              case on_done
+              when :close
+                io.close rescue nil # rubocop:disable Style/RescueModifier
+              when :capture
+                @mutex.synchronize do
+                  @captures[key] = io.string
+                end
+              end
+            end
+            done
+          end
+        end
+
+        def tee_write_one_stream(io, buffer, write_method, read_complete)
+          return [read_complete, write_method] if buffer.empty?
+          begin
+            bytes = io.send(write_method, buffer)
+            buffer.slice!(0, bytes)
+            [false, write_method]
+          rescue ::IO::WaitWritable, ::Errno::EINTR
+            [false, write_method]
+          rescue ::Errno::EBADF, ::NoMethodError
+            raise if write_method == :write
+            [false, :write]
+          rescue ::StandardError
+            [true, write_method]
+          end
+        end
+
+        def tee_amount_to_read(sink_info, buffer_size)
+          maxbuff = 0
+          sink_info.each do |_sink, buffer, _meth|
+            maxbuff = buffer.size if buffer.size > maxbuff
+          end
+          buffer_size - maxbuff
+        end
+
         def make_null_stream(key, mode)
           f = ::File.open(::File::NULL, mode)
           @spawn_opts[key] = f

data/lib/toys/utils/help_text.rb

@@ -171,7 +171,10 @@ module Toys
         ([@tool] + @delegates).each do |tool|
           name_len = tool.full_name.length
           subtools = @loader.list_subtools(tool.full_name,
-                                           recursive: recursive, include_hidden: include_hidden)
+                                           recursive: recursive,
+                                           include_hidden: include_hidden,
+                                           include_namespaces: include_hidden,
+                                           include_non_runnable: include_hidden)
           subtools.each do |subtool|
             local_name = subtool.full_name.slice(name_len..-1).join(" ")
             subtools_by_name[local_name] = subtool

data/lib/toys/utils/pager.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "toys/utils/exec"
+
+module Toys
+  module Utils
+    ##
+    # 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)
+        @command = command == true ? Pager.default_command : command
+        @command ||= nil
+        @exec_service = exec_service || Pager.default_exec_service
+        @fallback_io = fallback_io || $stdout
+      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
+        if @command
+          result = @exec_service.exec(@command, in: :controller) do |controller|
+            yield controller.in if controller.pid
+          end
+          return result.exit_code unless result.failed?
+        end
+        yield @fallback_io
+        0
+      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)
+          pager = new(command: command, exec_service: exec_service, fallback_io: fallback_io)
+          pager.start(&block)
+        end
+
+        ##
+        # @private
+        #
+        def default_command
+          unless defined? @default_command
+            @default_command = ::ENV["PAGER"]
+            unless @default_command
+              path = `which less`.strip
+              @default_command = [path, "-FIRX"] unless path.empty?
+            end
+          end
+          @default_command
+        end
+
+        ##
+        # @private
+        #
+        def default_exec_service
+          @default_exec_service ||= Exec.new
+        end
+      end
+    end
+  end
+end

data/lib/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
     #
@@ -35,6 +45,7 @@ module Toys
 
     ##
     # Returns true if the string is empty (i.e. has no fragments)
+    #
     # @return [Boolean]
     #
     def empty?
@@ -43,6 +54,7 @@ module Toys
 
     ##
     # Returns the string without any wrapping
+    #
     # @return [String]
     #
     def string

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.1
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-01 00:00:00.000000000 Z
+date: 2022-10-03 00:00:00.000000000 Z
 dependencies: []
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
@@ -60,6 +60,7 @@ files:
 - lib/toys/standard_mixins/gems.rb
 - lib/toys/standard_mixins/git_cache.rb
 - lib/toys/standard_mixins/highline.rb
+- lib/toys/standard_mixins/pager.rb
 - lib/toys/standard_mixins/terminal.rb
 - lib/toys/standard_mixins/xdg.rb
 - lib/toys/template.rb
@@ -69,6 +70,7 @@ files:
 - lib/toys/utils/gems.rb
 - lib/toys/utils/git_cache.rb
 - lib/toys/utils/help_text.rb
+- lib/toys/utils/pager.rb
 - lib/toys/utils/terminal.rb
 - lib/toys/utils/xdg.rb
 - lib/toys/wrappable_string.rb
@@ -76,10 +78,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.13.1/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.14.1/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.13.1
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.14.1
 post_install_message: 
 rdoc_options: []
 require_paths: