Module: Philiprehberger::TaskRunner

Defined in:
lib/philiprehberger/task_runner.rb,
lib/philiprehberger/task_runner/result.rb,
lib/philiprehberger/task_runner/version.rb

Defined Under Namespace

Classes: CommandError, Error, Result, TimeoutError

Constant Summary collapse

VERSION = 
'0.6.0'

Class Method Summary collapse

Class Method Details

.run(cmd, *args, timeout: nil, env: nil, chdir: nil, signal: :TERM, kill_after: 5, stdin: nil) {|line, stream| ... } ⇒ Result

Run a shell command with output capture, optional timeout, streaming, signal handling, and stdin piping.

When a block is given, each line of stdout/stderr is yielded as it arrives. If the block accepts two arguments, it receives (line, stream) where stream is :stdout or :stderr. If the block accepts one argument, it receives only the line (stdout lines only, for backward compatibility).

Parameters:

  • cmd (String) —

    the command to execute

  • args (Array<String>) —

    additional command arguments

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

    maximum seconds to wait (nil for no timeout)

  • env (Hash, nil) (defaults to: nil) —

    environment variables to set

  • chdir (String, nil) (defaults to: nil) —

    working directory for the command

  • signal (Symbol) (defaults to: :TERM) —

    signal to send on timeout (default :TERM)

  • kill_after (Numeric) (defaults to: 5) —

    seconds to wait before sending SIGKILL after initial signal (default 5)

  • stdin (String, IO, nil) (defaults to: nil) —

    data to pipe to the process’s stdin

Yields:

  • (line, stream) —

    each line as it arrives (streaming mode)

Yield Parameters:

  • line (String) —

    a line of output

  • stream (Symbol) —

    :stdout or :stderr (only if block accepts 2 params)

Returns:

  • (Result) —

    the command result

Raises:



44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/philiprehberger/task_runner.rb', line 44

def self.run(cmd, *args, timeout: nil, env: nil, chdir: nil, signal: :TERM, kill_after: 5, stdin: nil, &block)
  full_cmd = args.empty? ? cmd : [cmd, *args]
  spawn_opts = {}
  spawn_opts[:chdir] = chdir if chdir

  env_hash = env || {}
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)

  if block
    run_streaming(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin, &block)
  else
    run_capture(env_hash, full_cmd, spawn_opts, timeout, start_time, signal, kill_after, stdin)
  end
end

.run!(cmd) ⇒ Result

Run a shell command, raising CommandError on non-zero exit.

Accepts the same arguments as run.

Returns:

  • (Result) —

    the command result

Raises:



66
67
68
69
70
71
 
# File 'lib/philiprehberger/task_runner.rb', line 66

def self.run!(cmd, ...)
  result = run(cmd, ...)
  raise CommandError, result unless result.success?

  result
end

.run?(cmd) ⇒ Boolean

Boolean convenience — run the command and return whether it succeeded (exit code 0). Swallows ‘TimeoutError` (reported as false). Accepts the same arguments as run.

Returns:

  • (Boolean) —

    true if the command exited with status 0



78
79
80
81
82
 
# File 'lib/philiprehberger/task_runner.rb', line 78

def self.run?(cmd, ...)
  run(cmd, ...).success?
rescue TimeoutError
  false
end

.which(cmd) ⇒ String?

Find the absolute path of an executable on PATH.

Behaves like the ‘which` shell builtin: walks each entry in `ENV` and returns the first directory that contains an executable file matching `cmd`. On Windows, also tries each suffix in `ENV`. Returns `nil` when nothing is found.

Parameters:

  • cmd (String) —

    the executable name to search for

Returns:

  • (String, nil) —

    the absolute path, or nil when not found

Raises:

  • (ArgumentError) —

    if ‘cmd` is nil or empty



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/philiprehberger/task_runner.rb', line 94

def self.which(cmd)
  raise ArgumentError, 'cmd cannot be nil or empty' if cmd.nil? || cmd.to_s.empty?

  exts = if Gem.win_platform?
           (ENV['PATHEXT'] || '.COM;.EXE;.BAT;.CMD').split(';')
         else
           ['']
         end

  ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
    next if dir.empty?

    exts.each do |ext|
      candidate = File.join(dir, "#{cmd}#{ext}")
      return File.expand_path(candidate) if File.file?(candidate) && File.executable?(candidate)
    end
  end

  nil
end