Class: Toys::Utils::Pager

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/pager.rb

Overview

Defined in the toys-core gem

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, rescue_broken_pipes: true) ⇒ 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.

  • rescue_broken_pipes (boolean) (defaults to: true) —

    If true (the default), broken pipes are silently rescued. This prevents the exception from propagating out if the pager is interrupted. Set this parameter to false to disable this behavior.



40
41
42
43
 
# File 'core-docs/toys/utils/pager.rb', line 40

def initialize(command: true, exec_service: nil, fallback_io: nil,
               rescue_broken_pipes: true)
  # Source available in the toys-core gem
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) 


72
73
74
 
# File 'core-docs/toys/utils/pager.rb', line 72

def command
  @command
end

#fallback_io ⇒ IO

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

Returns:

  • (IO) 


79
80
81
 
# File 'core-docs/toys/utils/pager.rb', line 79

def fallback_io
  @fallback_io
end

Class Method Details

.start(command: true, exec_service: nil, fallback_io: nil, rescue_broken_pipes: true, &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.

  • rescue_broken_pipes (boolean) (defaults to: true) —

    If true (the default), broken pipes are silently rescued. This prevents the exception from propagating out if the pager is interrupted. Set this parameter to false to disable this behavior.

Returns:

  • (Integer) —

    The exit code of the pager process.



108
109
110
111
112
113
114
 
# File 'core-docs/toys/utils/pager.rb', line 108

def start(command: true,
          exec_service: nil,
          fallback_io: nil,
          rescue_broken_pipes: true,
          &block)
  # Source available in the toys-core gem
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
 
# File 'core-docs/toys/utils/pager.rb', line 60

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