Class: Toys::Utils::Pager

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

Overview

A class that invokes an external pager.

Examples:

Using a pager for regular output


Toys::Utils::Pager.start do |io|
  io.puts "A long string\n"
end

Piping output from a command


exec_service = Toys::Utils::Exec.new
Toys::Utils::Pager.start(exec_service: exec_service) do |io|
  exec_service.exec(["/bin/ls", "-alF"], out: io)
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(command: true, exec_service: nil, fallback_io: nil) ⇒ Pager

Creates a new pager.

Parameters:

  • command (String, Array<String>, boolean) (defaults to: true) —

    The command to use to invoke the pager. May be specified as a string to be passed to the shell, an array of strings representing a posix command, the value true to use the default (normally less -FIRX), or the value false to disable the pager and write directly to the output stream. Default is true.

  • exec_service (Toys::Utils::Exec) (defaults to: nil) —

    The service to use for executing commands, or nil (the default) to use a default.

  • fallback_io (IO) (defaults to: nil) —

    An IO-like object to write to if the pager is disabled. Defaults to $stdout.



38
39
40
41
42
43
 
# File 'lib/toys/utils/pager.rb', line 38

def initialize(command: true, exec_service: nil, fallback_io: nil)
  @command = command == true ? Pager.default_command : command
  @command ||= nil
  @exec_service = exec_service || Pager.default_exec_service
  @fallback_io = fallback_io || $stdout
end

Instance Attribute Details

#command ⇒ String, ...

The command for running the pager process. May be specified as a string to be passed to the shell, an array of strings representing a posix command, or nil to disable the pager and write directly to an output stream.

Returns:

  • (String, Array<String>, nil) 


79
80
81
 
# File 'lib/toys/utils/pager.rb', line 79

def command
  @command
end

#fallback_io ⇒ IO

The IO stream used if the pager is disabled or could not be executed.

Returns:

  • (IO) 


86
87
88
 
# File 'lib/toys/utils/pager.rb', line 86

def fallback_io
  @fallback_io
end

Class Method Details

.start(command: true, exec_service: nil, fallback_io: nil, &block) ⇒ Integer

A convenience method that creates a pager and runs it once by calling #start.

Examples:


Toys::Utils::Pager.start do |io|
  io.puts "A long string\n"
end

Parameters:

  • command (String, Array<String>, boolean) (defaults to: true) —

    The command to use to invoke the pager. May be specified as a string to be passed to the shell, an array of strings representing a posix command, the value true to use the default (normally less -FIRX), or the value false to disable the pager and write directly to the output stream. Default is true.

  • exec_service (Toys::Utils::Exec) (defaults to: nil) —

    The service to use for executing commands, or nil (the default) to use a default.

  • fallback_io (IO) (defaults to: nil) —

    An IO-like object to write to if the pager is disabled. Defaults to $stdout.

Returns:

  • (Integer) —

    The exit code of the pager process.



110
111
112
113
 
# File 'lib/toys/utils/pager.rb', line 110

def start(command: true, exec_service: nil, fallback_io: nil, &block)
  pager = new(command: command, exec_service: exec_service, fallback_io: fallback_io)
  pager.start(&block)
end

Instance Method Details

#start {|io| ... } ⇒ Integer

Runs the pager. Takes a block and yields an IO-like object that passes text to the pager. Can be called multiple times on the same pager.

Examples:


pager = Toys::Utils::Pager.new
pager.start do |io|
  io.puts "A long string\n"
end

Yield Parameters:

  • io (IO) —

    An object that can be written to, to pass data to the pager.

Returns:

  • (Integer) —

    The exit code of the pager process.



60
61
62
63
64
65
66
67
68
69
 
# File 'lib/toys/utils/pager.rb', line 60

def start
  if @command
    result = @exec_service.exec(@command, in: :controller) do |controller|
      yield controller.in if controller.pid
    end
    return result.exit_code unless result.failed?
  end
  yield @fallback_io
  0
end