Module: Toys::StandardMixins::Exec

Includes:
Mixin
Defined in:
lib/toys/standard_mixins/exec.rb

Overview

A set of helper methods for invoking subcommands. Provides shortcuts for common cases such as invoking Ruby in a subprocess or capturing output 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 following directive in your tool configuration:

include :exec

This is a frontend for Utils::Exec. More information is available in that class's documentation.

Configuration Options

Subprocesses may be configured using the options in the Utils::Exec class. These include a variety of options supported by Process#spawn, and some options supported by Utils::Exec itself.

In addition, this mixin supports one more option, exit_on_nonzero_status. When set to true, if any subprocess returns a nonzero result code, the tool will immediately exit with that same code, similar to set -e in a bash script.

You can set initial configuration by passing options to the include directive. For example:

include :exec, exit_on_nonzero_status: true

Constant Summary collapse

KEY =

Context key for the executor object.

::Object.new.freeze

Instance Method Summary collapse

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

Yield Parameters:



206
207
208
 
# File 'lib/toys/standard_mixins/exec.rb', line 206

def capture(cmd, opts = {}, &block)
  self[KEY].capture(cmd, Exec._setup_exec_opts(opts, self), &block)
end

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

Execute a proc in a subprocess.

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

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

Yield Parameters:



250
251
252
 
# File 'lib/toys/standard_mixins/exec.rb', line 250

def capture_proc(func, opts = {}, &block)
  self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self), &block)
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 Utils::Exec::Controller will be yielded to it.

Yield Parameters:



228
229
230
 
# File 'lib/toys/standard_mixins/exec.rb', line 228

def capture_ruby(args, opts = {}, &block)
  self[KEY].capture_ruby(args, Exec._setup_exec_opts(opts, self), &block)
end

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

Execute a tool. The command may be given as a single string or an array of strings, representing the tool to run and the arguments to pass.

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

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

Yield Parameters:



273
274
275
276
 
# File 'lib/toys/standard_mixins/exec.rb', line 273

def capture_tool(cmd, opts = {}, &block)
  func = Exec._make_tool_caller(cmd)
  self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self), &block)
end

#configure_exec(opts = {}) ⇒ Object

Set default configuration keys.

All options listed in the Utils::Exec documentation are supported, plus the exit_on_nonzero_status option.



95
96
97
 
# File 'lib/toys/standard_mixins/exec.rb', line 95

def configure_exec(opts = {})
  self[KEY].configure_defaults(Exec._setup_exec_opts(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 Utils::Exec::Controller will be yielded to it.

Yield Parameters:



117
118
119
 
# File 'lib/toys/standard_mixins/exec.rb', line 117

def exec(cmd, opts = {}, &block)
  self[KEY].exec(cmd, Exec._setup_exec_opts(opts, self), &block)
end

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

Execute a proc in a subprocess.

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

Yield Parameters:



160
161
162
 
# File 'lib/toys/standard_mixins/exec.rb', line 160

def exec_proc(func, opts = {}, &block)
  self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
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 Utils::Exec::Controller will be yielded to it.

Yield Parameters:



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

def exec_ruby(args, opts = {}, &block)
  self[KEY].exec_ruby(args, Exec._setup_exec_opts(opts, self), &block)
end

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

Execute a tool. The command may 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 provided, a Utils::Exec::Controller will be yielded to it.

Yield Parameters:



182
183
184
185
 
# File 'lib/toys/standard_mixins/exec.rb', line 182

def exec_tool(cmd, opts = {}, &block)
  func = Exec._make_tool_caller(cmd)
  self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
end

#exit_on_nonzero_status(status) ⇒ Object

Exit if the given status code is nonzero. Otherwise, returns 0.



303
304
305
306
307
308
 
# File 'lib/toys/standard_mixins/exec.rb', line 303

def exit_on_nonzero_status(status)
  status = status.exit_code if status.respond_to?(:exit_code)
  status = status.exitstatus if status.respond_to?(:exitstatus)
  Tool.exit(status) unless status.zero?
  0
end

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

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

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

Yield Parameters:



294
295
296
 
# File 'lib/toys/standard_mixins/exec.rb', line 294

def sh(cmd, opts = {}, &block)
  self[KEY].sh(cmd, Exec._setup_exec_opts(opts, self), &block)
end