Class: Toys::Utils::Exec

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/utils/exec.rb

Overview

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.

Configuration options

A variety of options can be used to control subprocesses. These include:

  • :env (Hash) Environment variables to pass to the subprocess
  • :logger (Logger) Logger to use for logging the actual command. If not present, the command is not logged.
  • :log_level (Integer) Log level for logging the actual command. Defaults to Logger::INFO if not present.
  • :background (Boolean) Runs the process in the background, returning a controller object instead of a result object.
  • :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.

In addition, the following options recognized by Process#spawn are supported.

  • :chdir
  • :close_others
  • :new_pgroup
  • :pgroup
  • :umask
  • :unsetenv_others

Any other options are ignored.

Configuration options may be provided to any method that starts a subprocess. You may also modify default values by calling #configure_defaults.

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.

  • 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 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.
  • 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 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 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 #exec, it yields the Controller, giving you access to streams.

Defined Under Namespace

Classes: Controller, Result

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}, &block) ⇒ Exec

Create an exec service.

Parameters:

  • opts (Hash) (defaults to: {}) —

    Initial default options.



138
139
140
 
# File 'lib/toys/utils/exec.rb', line 138

def initialize(opts = {}, &block)
  @default_opts = Opts.new(&block).add(opts)
end

Instance Method Details

#capture(cmd, opts = {}) {|controller| ... } ⇒ String

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 Controller will be yielded to it.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:

  • (String) —

    What was written to standard out.



248
249
250
 
# File 'lib/toys/utils/exec.rb', line 248

def capture(cmd, opts = {}, &block)
  exec(cmd, opts.merge(out: :capture, background: false), &block).captured_out
end

#capture_proc(func, opts = {}) {|controller| ... } ⇒ String

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 Controller will be yielded to it.

Parameters:

  • func (Proc) —

    The proc to call.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:

  • (String) —

    What was written to standard out.



290
291
292
 
# File 'lib/toys/utils/exec.rb', line 290

def capture_proc(func, opts = {}, &block)
  exec_proc(func, opts.merge(out: :capture, background: false), &block).captured_out
end

#capture_ruby(args, opts = {}) {|controller| ... } ⇒ String

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 Controller will be yielded to it.

Parameters:

  • args (String, Array<String>) —

    The arguments to ruby.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:

  • (String) —

    What was written to standard out.



269
270
271
 
# File 'lib/toys/utils/exec.rb', line 269

def capture_ruby(args, opts = {}, &block)
  ruby(args, opts.merge(out: :capture, background: false), &block).captured_out
end

#configure_defaults(opts = {}) ⇒ Object

Set default options

Parameters:

  • opts (Hash) (defaults to: {}) —

    New default options to set



147
148
149
150
 
# File 'lib/toys/utils/exec.rb', line 147

def configure_defaults(opts = {})
  @default_opts.add(opts)
  self
end

#exec(cmd, opts = {}) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

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 Controller will be yielded to it.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/toys/utils/exec.rb', line 169

def exec(cmd, opts = {}, &block)
  exec_opts = Opts.new(@default_opts).add(opts)
  spawn_cmd =
    if cmd.is_a?(::Array)
      if cmd.size == 1 && cmd.first.is_a?(::String)
        [[cmd.first, exec_opts.config_opts[:argv0] || cmd.first]]
      else
        cmd
      end
    else
      [cmd]
    end
  executor = Executor.new(exec_opts, spawn_cmd, block)
  executor.execute
end

#exec_proc(func, opts = {}) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Execute a proc in a fork.

If the process is not set to run in the background, and a block is provided, a Controller will be yielded to it.

Parameters:

  • func (Proc) —

    The proc to call.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:



224
225
226
227
228
 
# File 'lib/toys/utils/exec.rb', line 224

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 = {}) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result Also known as: ruby

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 Controller will be yielded to it.

Parameters:

  • args (String, Array<String>) —

    The arguments to ruby.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:



201
202
203
204
205
 
# File 'lib/toys/utils/exec.rb', line 201

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}"
  exec(cmd, {argv0: "ruby", log_cmd: log_cmd}.merge(opts), &block)
end

#sh(cmd, opts = {}) {|controller| ... } ⇒ Integer

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

Parameters:

  • cmd (String) —

    The shell command to execute.

  • opts (Hash) (defaults to: {}) —

    The command options. See the section on configuration options in the Toys::Utils::Exec module docs.

Yield Parameters:

Returns:

  • (Integer) —

    The exit code



306
307
308
 
# File 'lib/toys/utils/exec.rb', line 306

def sh(cmd, opts = {}, &block)
  exec(cmd, opts.merge(background: false), &block).exit_code
end