Class: Backticks::Runner

Inherits:
Object
  • Object
show all
Defined in:
lib/backticks/runner.rb

Overview

An easy-to-use interface for invoking commands and capturing their output. Instances of Runner can be interactive, which prints the command’s output to the terminal and also allows the user to interact with the command. They can also be unbuffered, which uses a pseudo-tty to capture the command’s output with no delay or

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(buffered: false, cli: Backticks::CLI::Getopt, interactive: false) ⇒ Runner

Create an instance of Runner.

Parameters:

  • cli (#parameters) (defaults to: Backticks::CLI::Getopt) —

    object used to convert Ruby method parameters into command-line parameters



36
37
38
39
40
 
# File 'lib/backticks/runner.rb', line 36

def initialize(buffered:false, cli:Backticks::CLI::Getopt, interactive:false)
  @buffered = buffered
  @cli = cli
  @interactive = interactive
end

Instance Attribute Details

#buffered ⇒ Boolean

If true, commands will be invoked with a pseudo-TTY for stdout in order to capture output as it is generated instead of waiting for pipe buffers to fill.

Returns:

  • (Boolean) 


29
30
31
 
# File 'lib/backticks/runner.rb', line 29

def buffered
  @buffered
end

#cli ⇒ #parameters (readonly)

Returns the CLI-translation object used by this runner.

Returns:

  • (#parameters) —

    the CLI-translation object used by this runner



32
33
34
 
# File 'lib/backticks/runner.rb', line 32

def cli
  @cli
end

#interactive ⇒ Boolean

If true, commands will have their stdio streams tied to the parent process so the user can view their output and send input to them. Commands’ output is still captured normally when they are interactive.

Note that interactivity doesn’t work very well with unbuffered commands; we use pipes to connect to the command’s stdio, and the OS forcibly buffers pipe I/O. If you want to send some input to your command, you may need to send a LOT of input before it receives any; the same problem applies to reading your command’s output. If you set interactive to true, you usually want to set buffered to false!

Returns:

  • (Boolean) 


22
23
24
 
# File 'lib/backticks/runner.rb', line 22

def interactive
  @interactive
end

Instance Method Details

#command(*args) ⇒ Command

Run a command whose parameters are expressed using some Rubyish sugar. This method accepts an arbitrary number of positional parameters; each parameter can be a Hash, an array, or a simple Object. Arrays and simple objects are appended to argv as words of the command; Hashes are translated to command-line options and then appended to argv.

Hashes are processed by @cli, defaulting to Backticks::CLI::Getopt and easily overridden by passing the ‘cli` option to #initialize.

Examples:

Run docker-compose with complex parameters

command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')

Parameters:

  • args (Array) —

    list of command words and options

Returns:

  • (Command) —

    the running command

See Also:



59
60
61
62
63
64
65
66
67
 
# File 'lib/backticks/runner.rb', line 59

def command(*args)
  argv = @cli.parameters(*args)

  if self.buffered
    run_buffered(argv)
  else
    run_unbuffered(argv)
  end
end