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) ⇒ 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.



36
37
38
 
# File 'core-docs/toys/utils/pager.rb', line 36

def initialize(command: true, exec_service: nil, fallback_io: nil)
  # 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) 


67
68
69
 
# File 'core-docs/toys/utils/pager.rb', line 67

def command
  @command
end

#fallback_io ⇒ IO

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

Returns:

  • (IO) 


74
75
76
 
# File 'core-docs/toys/utils/pager.rb', line 74

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.



98
99
100
 
# File 'core-docs/toys/utils/pager.rb', line 98

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



55
56
57
 
# File 'core-docs/toys/utils/pager.rb', line 55

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