class Toys::Utils::Exec

A service that executes subprocesses.

This service provides a convenient interface for controlling spawned processes and their streams. It also provides shortcuts for common cases such as invoking Ruby in a subprocess or capturing output in a string.

This class is not loaded by default. Before using it directly, you should `require “toys/utils/exec”`

### Controlling processes

A process can be started in the foreground or the background. If you start a foreground process, it will “take over” your standard input and output streams by default, and it will keep control until it completes. 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 {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.

When running a process in the foreground, the controller will be yielded to an optional block. For example, the following code starts a process in the foreground and passes its output stream to a controller.

exec_service.exec(["git", "init"], out: :controller) do |controller|
  loop do
    line = controller.out.gets
    break if line.nil?
    puts "Got line: #{line}"
  end
end

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)

### Stream handling

By default, subprocess streams are connected to the corresponding streams in the parent process. You can change this behavior, redirecting streams or providing ways to control them, using the `:in`, `:out`, and `:err` options.

Three general strategies are available for custom stream handling. First, you may 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 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
   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
   `: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
   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
   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
   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
   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
   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
   setting `[:string, "the string"]`. This works only for `:in`.
*  **Capture output stream:** You may 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
   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.

### Result handling

A subprocess result is represented by a {Toys::Utils::Exec::Result} object, which includes the exit code, the content of any captured output streams, and any exeption raised when attempting to run the process. When you run a process in the foreground, the method will return a result object. When you run a process in the background, you can obtain the result from the controller once the process completes.

The following example demonstrates running a process in the foreground and getting the exit code:

result = exec_service.exec(["git", "init"])
puts "exit code: #{result.exit_code}"

The following example demonstrates starting a process in the background, waiting for it to complete, and getting its exit code:

controller = exec_service.exec(["git", "init"], background: true)
result = controller.result(timeout: 1.0)
if result
  puts "exit code: #{result.exit_code}"
else
  puts "timed out"
end

You can also provide a callback that is executed once a process completes. For example:

my_callback = proc do |result|
  puts "exit code: #{result.exit_code}"
end
exec_service.exec(["git", "init"], result_callback: my_callback)

### Configuration options

A variety of options can be used to control subprocesses. These can be provided to any method that starts a subprocess. Youc an also set defaults by calling {Toys::Utils::Exec#configure_defaults}.

Options that affect the behavior of subprocesses:

*  `:env` (Hash) Environment variables to pass to the subprocess.
   Keys represent variable names and should be strings. Values should be
   either strings or `nil`, which unsets the variable.

*  `:background` (Boolean) Runs the process in the background if `true`.

*  `:result_callback` (Proc) Called and passed the result object when
   the subprocess exits.

Options for connecting input and output streams. See the section above on stream handling for info on the values that can be passed.

*  `:in` Connects the input stream of the subprocess. See the section on
   stream handling.

*  `:out` Connects the standard output stream of the subprocess. See the
   section on stream handling.

*  `:err` Connects the standard error stream of the subprocess. See the
   section on stream handling.

Options related to logging and reporting:

*  `:logger` (Logger) Logger to use for logging the actual command. If
   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
   disable logging of the command.

*  `:log_cmd` (String) The string logged for the actual command.
   Defaults to the `inspect` representation of the command.

*  `:name` (Object) An optional object that can be used to identify this
   subprocess. It is available in the controller and result objects.

In addition, the following options recognized by [`Process#spawn`](ruby-doc.org/core/Process.html#method-c-spawn) are supported.

*  `:chdir` (String) Set the working directory for the command.

*  `:close_others` (Boolean) Whether to close non-redirected
   non-standard file descriptors.

*  `:new_pgroup` (Boolean) Create new process group (Windows only).

*  `:pgroup` (Integer,true,nil) The process group setting.

*  `:umask` (Integer) Umask setting for the new process.

*  `:unsetenv_others` (Boolean) Clear environment variables except those
   explicitly set.

Any other option key will result in an `ArgumentError`.

Public Class Methods

new(**opts, &block) click to toggle source

Create an exec service.

@param block [Proc] A block that is called if a key is not found. It is

passed the unknown key, and expected to return a default value
(which can be nil).

@param opts [keywords] Initial default options. See {Toys::Utils::Exec}

for a description of the options.
# File lib/toys/utils/exec.rb, line 213
def initialize(**opts, &block)
  @default_opts = Opts.new(&block).add(opts)
end

Public Instance Methods

capture(cmd, **opts, &block) click to toggle source

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. Cannot be run in the background.

If a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [String] What was written to standard out.

# File lib/toys/utils/exec.rb, line 330
def capture(cmd, **opts, &block)
  opts = opts.merge(out: :capture, background: false)
  exec(cmd, **opts, &block).captured_out
end
capture_proc(func, **opts, &block) click to toggle source

Execute a proc in a fork.

Captures standard out and returns it as a string. Cannot be run in the background.

If a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param func [Proc] The proc to call. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [String] What was written to standard out.

# File lib/toys/utils/exec.rb, line 374
def capture_proc(func, **opts, &block)
  opts = opts.merge(out: :capture, background: false)
  exec_proc(func, **opts, &block).captured_out
end
capture_ruby(args, **opts, &block) click to toggle source

Spawn a ruby process and pass the given arguments to it.

Captures standard out and returns it as a string. Cannot be run in the background.

If a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param args [String,Array<String>] The arguments to ruby. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [String] What was written to standard out.

# File lib/toys/utils/exec.rb, line 352
def capture_ruby(args, **opts, &block)
  opts = opts.merge(out: :capture, background: false)
  ruby(args, **opts, &block).captured_out
end
configure_defaults(**opts) click to toggle source

Set default options. See {Toys::Utils::Exec} for a description of the options.

@param opts [keywords] New default options to set @return [self]

# File lib/toys/utils/exec.rb, line 224
def configure_defaults(**opts)
  @default_opts.add(opts)
  self
end
exec(cmd, **opts, &block) click to toggle source

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 the process is not set to run in the background, and a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# File lib/toys/utils/exec.rb, line 247
def exec(cmd, **opts, &block)
  exec_opts = Opts.new(@default_opts).add(opts)
  spawn_cmd =
    if cmd.is_a?(::Array)
      if cmd.size > 1
        binary = canonical_binary_spec(cmd.first, exec_opts)
        [binary] + cmd[1..-1].map(&:to_s)
      else
        [canonical_binary_spec(Array(cmd.first), exec_opts)]
      end
    else
      [cmd.to_s]
    end
  executor = Executor.new(exec_opts, spawn_cmd, block)
  executor.execute
end
exec_proc(func, **opts, &block) click to toggle source

Execute a proc in a fork.

If the process is not set to run in the background, and a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param func [Proc] The proc to call. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# File lib/toys/utils/exec.rb, line 306
def exec_proc(func, **opts, &block)
  exec_opts = Opts.new(@default_opts).add(opts)
  executor = Executor.new(exec_opts, func, block)
  executor.execute
end
exec_ruby(args, **opts, &block) click to toggle source

Spawn a ruby process and pass the given arguments to it.

If the process is not set to run in the background, and a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param args [String,Array<String>] The arguments to ruby. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# File lib/toys/utils/exec.rb, line 281
def exec_ruby(args, **opts, &block)
  cmd = args.is_a?(::Array) ? [::RbConfig.ruby] + args : "#{::RbConfig.ruby} #{args}"
  log_cmd = args.is_a?(::Array) ? ["ruby"] + args : "ruby #{args}"
  opts = {argv0: "ruby", log_cmd: log_cmd}.merge(opts)
  exec(cmd, **opts, &block)
end
Also aliased as: ruby
ruby(args, **opts, &block)
Alias for: exec_ruby
sh(cmd, **opts, &block) click to toggle source

Execute the given string in a shell. Returns the exit code. Cannot be run in the background.

If a block is provided, a {Toys::Utils::Exec::Controller} will be yielded to it.

@param cmd [String] The shell command to execute. @param opts [keywords] The command options. See the section on

configuration options in the {Toys::Utils::Exec} class docs.

@yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Integer] The exit code

# File lib/toys/utils/exec.rb, line 394
def sh(cmd, **opts, &block)
  opts = opts.merge(background: false)
  exec(cmd, **opts, &block).exit_code
end

Private Instance Methods

canonical_binary_spec(cmd, exec_opts) click to toggle source
# File lib/toys/utils/exec.rb, line 1316
def canonical_binary_spec(cmd, exec_opts)
  config_argv0 = exec_opts.config_opts[:argv0]
  return cmd.to_s if !config_argv0 && !cmd.is_a?(::Array)
  cmd = Array(cmd)
  actual_cmd = cmd.first
  argv0 = cmd[1] || config_argv0 || actual_cmd
  [actual_cmd.to_s, argv0.to_s]
end