Class: Toys::Utils::Exec::Result

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

Overview

The result returned from a subcommand execution. This includes the identifying name of the execution (if any), the result status of the execution, and any captured stream output.

Possible result statuses are:

  • The process failed to start. #failed? will return true, and #exception will return an exception describing the failure (often an errno).
  • The process executed and exited with a normal exit code. Either #success? or #error? will return true, and #exit_code will return the numeric exit code.
  • The process executed but was terminated by an uncaught signal. #signaled? will return true, and #signal_code will return the numeric signal code.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#captured_err ⇒ String? (readonly)

The captured error string.

Returns:

  • (String) —

    The string captured from stderr.

  • (nil) —

    if the command was not configured to capture stderr.



1975
1976
1977
 
# File 'lib/toys/utils/exec.rb', line 1975

def captured_err
  @captured_err
end

#captured_out ⇒ String? (readonly)

The captured output string.

Returns:

  • (String) —

    The string captured from stdout.

  • (nil) —

    if the command was not configured to capture stdout.



1967
1968
1969
 
# File 'lib/toys/utils/exec.rb', line 1967

def captured_out
  @captured_out
end

#exception ⇒ Exception? (readonly)

The exception raised if a process couldn't be started.

Exactly one of #exception and #status will be non-nil. Exactly one of #exception, #exit_code, or #signal_code will be non-nil.

Returns:

  • (Exception) —

    The exception raised from process start.

  • (nil) —

    if the process started successfully.



1999
2000
2001
 
# File 'lib/toys/utils/exec.rb', line 1999

def exception
  @exception
end

#name ⇒ Object (readonly)

The subcommand's name.

Returns:

  • (Object) 


1959
1960
1961
 
# File 'lib/toys/utils/exec.rb', line 1959

def name
  @name
end

#status ⇒ Process::Status? (readonly)

The Ruby process status object, providing various information about the ending state of the process.

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

Returns:

  • (Process::Status) —

    The status, if the process was successfully spawned and terminated.

  • (nil) —

    if the process could not be started.



1987
1988
1989
 
# File 'lib/toys/utils/exec.rb', line 1987

def status
  @status
end

Instance Method Details

#effective_code ⇒ Integer

Returns an "effective" exit code, which is always an integer if the process has terminated for any reason. In general, this code will be:

  • The same as #exit_code if the process terminated normally with an exit code,
  • The convention of 128+signalnum if the process terminated due to a signal,
  • The convention of 126 if the process could not start due to lack of execution permissions,
  • The convention of 127 if the process could not start because the command was not recognized or could not be found, or
  • An undefined value between 1 and 255 for other failures.

Note that the normal exit code and signal number cases are stable, but any other cases are subject to change on future releases.

Returns:

  • (Integer) 


2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
 
# File 'lib/toys/utils/exec.rb', line 2094

def effective_code
  code = exit_code
  return code unless code.nil?
  code = signal_code
  return code + 128 unless code.nil?
  case exception
  when ::Errno::ENOENT
    127
  else
    # This is the intended result for ENOEXEC/EACCES.
    # For now, any other error (e.g. EBADARCH on MacOS) will also map
    # to this result. We can change this in the future since the
    # documentation explicitly allows it.
    126
  end
end

#error? ⇒ boolean

Returns true if the subprocess terminated with a nonzero status, or false if the process failed to start, terminated due to a signal, or returned a zero status.

Returns:

  • (boolean) 


2070
2071
2072
2073
 
# File 'lib/toys/utils/exec.rb', line 2070

def error?
  code = exit_code
  !code.nil? && !code.zero?
end

#exit_code ⇒ Integer?

The numeric status code for a process that exited normally,

Exactly one of #exception, #exit_code, or #signal_code will be non-nil.

Returns:

  • (Integer) —

    the numeric status code, if the process started successfully and exited normally.

  • (nil) —

    if the process did not start successfully, or was terminated by an uncaught signal.



2012
2013
2014
 
# File 'lib/toys/utils/exec.rb', line 2012

def exit_code
  status&.exitstatus
end

#failed? ⇒ boolean

Returns true if the subprocess failed to start, or false if the process was able to execute.

Returns:

  • (boolean) 


2037
2038
2039
 
# File 'lib/toys/utils/exec.rb', line 2037

def failed?
  status.nil?
end

#signal_code ⇒ Integer? Also known as: term_signal

The numeric signal code that caused process termination.

Exactly one of #exception, #exit_code, or #signal_code will be non-nil.

Returns:

  • (Integer) —

    The signal that caused the process to terminate.

  • (nil) —

    if the process did not start successfully, or executed and exited with a normal exit code.



2026
2027
2028
 
# File 'lib/toys/utils/exec.rb', line 2026

def signal_code
  status&.termsig
end

#signaled? ⇒ boolean

Returns true if the subprocess terminated due to an unhandled signal, or false if the process failed to start or exited normally.

Returns:

  • (boolean) 


2047
2048
2049
 
# File 'lib/toys/utils/exec.rb', line 2047

def signaled?
  !signal_code.nil?
end

#success? ⇒ boolean

Returns true if the subprocess terminated with a zero status, or false if the process failed to start, terminated due to a signal, or returned a nonzero status.

Returns:

  • (boolean) 


2058
2059
2060
2061
 
# File 'lib/toys/utils/exec.rb', line 2058

def success?
  code = exit_code
  !code.nil? && code.zero?
end