Class: Toys::Utils::Exec::Controller

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/exec.rb

Overview

Defined in the toys-core gem

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, send signals to the process, and get its result.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#err ⇒ IO? (readonly)

The subcommand's standard error stream (which can be read from).

Returns:

  • (IO) —

    if the command was configured with err: :controller

  • (nil) —

    if the command was not configured with err: :controller



413
414
415
 
# File 'core-docs/toys/utils/exec.rb', line 413

def err
  @err
end

#exception ⇒ Exception? (readonly)

The exception raised when the process failed to start.

Exactly one of #exception and #pid will be non-nil.

Returns:

  • (Exception) —

    if the process failed to start.

  • (nil) —

    if the process start was successful.



433
434
435
 
# File 'core-docs/toys/utils/exec.rb', line 433

def exception
  @exception
end

#in ⇒ IO? (readonly)

The subcommand's standard input stream (which can be written to).

Returns:

  • (IO) —

    if the command was configured with in: :controller

  • (nil) —

    if the command was not configured with in: :controller



395
396
397
 
# File 'core-docs/toys/utils/exec.rb', line 395

def in
  @in
end

#name ⇒ Object (readonly)

The subcommand's name.

Returns:

  • (Object) 


386
387
388
 
# File 'core-docs/toys/utils/exec.rb', line 386

def name
  @name
end

#out ⇒ IO? (readonly)

The subcommand's standard output stream (which can be read from).

Returns:

  • (IO) —

    if the command was configured with out: :controller

  • (nil) —

    if the command was not configured with out: :controller



404
405
406
 
# File 'core-docs/toys/utils/exec.rb', line 404

def out
  @out
end

#pid ⇒ Integer? (readonly)

The process ID.

Exactly one of #exception and #pid will be non-nil.

Returns:

  • (Integer) —

    if the process start was successful

  • (nil) —

    if the process could not be started.



423
424
425
 
# File 'core-docs/toys/utils/exec.rb', line 423

def pid
  @pid
end

Instance Method Details

#capture(which) ⇒ self

Captures the remaining data in the given stream. After calling this, do not read directly from the stream.

Parameters:

  • which (:out, :err) —

    Which stream to capture

Returns:

  • (self) 


442
443
444
 
# File 'core-docs/toys/utils/exec.rb', line 442

def capture(which)
  # Source available in the toys-core gem
end

#capture_err ⇒ self

Captures the remaining data in the standard error stream. After calling this, do not read directly from the stream.

Returns:

  • (self) 


462
463
464
 
# File 'core-docs/toys/utils/exec.rb', line 462

def capture_err
  # Source available in the toys-core gem
end

#capture_out ⇒ self

Captures the remaining data in the standard output stream. After calling this, do not read directly from the stream.

Returns:

  • (self) 


452
453
454
 
# File 'core-docs/toys/utils/exec.rb', line 452

def capture_out
  # Source available in the toys-core gem
end

#executing? ⇒ Boolean

Determine whether the subcommand is still executing

Returns:

  • (Boolean) 


559
560
561
 
# File 'core-docs/toys/utils/exec.rb', line 559

def executing?
  # Source available in the toys-core gem
end

#kill(sig) ⇒ self Also known as: signal

Send the given signal to the process. The signal may be specified by name or number.

Parameters:

  • sig (Integer, String) —

    The signal to send.

Returns:

  • (self) 


549
550
551
 
# File 'core-docs/toys/utils/exec.rb', line 549

def kill(sig)
  # Source available in the toys-core gem
end

#redirect(which, io, *io_args) ⇒ self

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 provide the mode and permissions for the call to File#open. You can also specify the value :null to indicate the null file.

After calling this, do not interact directly with the stream.

Parameters:

  • which (:in, :out, :err) —

    Which stream to redirect

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to/from a file.

Returns:

  • (self) 


482
483
484
 
# File 'core-docs/toys/utils/exec.rb', line 482

def redirect(which, io, *io_args)
  # Source available in the toys-core gem
end

#redirect_err(io, *io_args) ⇒ self

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 provide the mode and permissions for the call to File#open.

After calling this, do not interact directly with the stream.

Parameters:

  • io (IO, StringIO, String) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to a file.

Returns:

  • (self) 


538
539
540
 
# File 'core-docs/toys/utils/exec.rb', line 538

def redirect_err(io, *io_args)
  # Source available in the toys-core gem
end

#redirect_in(io, *io_args) ⇒ self

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 provide the mode and permissions for the call to File#open. You can also specify the value :null to indicate the null file.

After calling this, do not interact directly with the stream.

Parameters:

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting from a file.

Returns:

  • (self) 


501
502
503
 
# File 'core-docs/toys/utils/exec.rb', line 501

def redirect_in(io, *io_args)
  # Source available in the toys-core gem
end

#redirect_out(io, *io_args) ⇒ self

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 provide the mode and permissions for the call to File#open. You can also specify the value :null to indicate the null file.

After calling this, do not interact directly with the stream.

Parameters:

  • io (IO, StringIO, String, :null) —

    Where to redirect the stream

  • io_args (Object...) —

    The mode and permissions for opening the file, if redirecting to a file.

Returns:

  • (self) 


520
521
522
 
# File 'core-docs/toys/utils/exec.rb', line 520

def redirect_out(io, *io_args)
  # Source available in the toys-core gem
end

#result(timeout: nil) ⇒ Toys::Utils::Exec::Result?

Wait for the subcommand to complete, and return a result object.

Closes the control streams if present. The stdin stream is always closed, even if the call times out. The stdout and stderr streams are closed only after the command terminates.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    The timeout in seconds, or nil to wait indefinitely.

Returns:



575
576
577
 
# File 'core-docs/toys/utils/exec.rb', line 575

def result(timeout: nil)
  # Source available in the toys-core gem
end