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 can 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



518
519
520
 
# File 'core-docs/toys/utils/exec.rb', line 518

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.



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

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



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

def in
  @in
end

#name ⇒ Object (readonly)

The subcommand's name.

Returns:

  • (Object) 


491
492
493
 
# File 'core-docs/toys/utils/exec.rb', line 491

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



509
510
511
 
# File 'core-docs/toys/utils/exec.rb', line 509

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.



528
529
530
 
# File 'core-docs/toys/utils/exec.rb', line 528

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) —

    if the stream was captured

  • (nil) —

    if the stream was not captured because the process has completed or did not start successfully



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

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) 


570
571
572
 
# File 'core-docs/toys/utils/exec.rb', line 570

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) 


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

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

#executing? ⇒ boolean

Determine whether the subcommand is still executing

Returns:

  • (boolean) 


684
685
686
 
# File 'core-docs/toys/utils/exec.rb', line 684

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 can be specified by name or number.

Parameters:

  • sig (Integer, String) —

    The signal to send.

Returns:

  • (self) 


674
675
676
 
# File 'core-docs/toys/utils/exec.rb', line 674

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 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.

If the stream is redirected to an IO-like object, it is not closed when the process is completed. (If it is redirected to a file specified by path, the file is closed on completion.)

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) —

    if the stream was redirected

  • (nil) —

    if the stream was not redirected because the process has completed or did not start successfully



597
598
599
 
# File 'core-docs/toys/utils/exec.rb', line 597

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 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.

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) —

    if the stream was redirected

  • (nil) —

    if the stream was not redirected because the process has completed or did not start successfully



663
664
665
 
# File 'core-docs/toys/utils/exec.rb', line 663

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 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.

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) —

    if the stream was redirected

  • (nil) —

    if the stream was not redirected because the process has completed or did not start successfully



619
620
621
 
# File 'core-docs/toys/utils/exec.rb', line 619

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 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.

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) —

    if the stream was redirected

  • (nil) —

    if the stream was not redirected because the process has completed or did not start successfully



641
642
643
 
# File 'core-docs/toys/utils/exec.rb', line 641

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.

Parameters:

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

    The timeout in seconds, or nil to wait indefinitely.

Returns:



696
697
698
 
# File 'core-docs/toys/utils/exec.rb', line 696

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