Class: TTY::Pager::SystemPager

Inherits:
Abstract
  • Object
show all
Defined in:
lib/tty/pager/system.rb

Overview

A system pager is used on systems where native pagination exists

Defined Under Namespace

Classes: PagerIO

Constant Summary

Constants inherited from Abstract

Abstract::UndefinedMethodError

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Abstract

#enabled?, page, #page, #try_write

Constructor Details

#initialize(command: nil, **options) ⇒ SystemPager

Create a system pager

Parameters:

  • :command (String)

    the command to use for paging


113
114
115
116
117
118
119
120
121
122
123
124
125
# File 'lib/tty/pager/system.rb', line 113

def initialize(command: nil, **options)
  super(**options)
  @pager_io = nil
  @pager_command = nil
  pager_command(*Array(command))

  if pager_command.nil?
    raise TTY::Pager::Error,
          "#{self.class.name} cannot be used on your system due to " \
          "lack of appropriate pager executable. Install `less` like " \
          "pager or try using `BasicPager` instead."
  end
end

Class Method Details

.command_exist?(command) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if command exists

Examples:

command_exist?("less") # => true

Parameters:

  • command (String)

    the command to check

Returns:

  • (Boolean)

25
26
27
28
29
30
31
# File 'lib/tty/pager/system.rb', line 25

def self.command_exist?(command)
  exts = ENV.fetch("PATHEXT", "").split(::File::PATH_SEPARATOR)
  ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
    file = ::File.join(dir, command)
    ::File.exist?(file) || exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
  end
end

.exec_available?(*commands) ⇒ Boolean

Check if command is available

Examples:

Basic usage

available?  # => true

Usage with command

available?("less") # => true

Returns:

  • (Boolean)

103
104
105
# File 'lib/tty/pager/system.rb', line 103

def self.exec_available?(*commands)
  !find_executable(*commands).nil?
end

.executablesArray[String]

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

List possible executables for output paging

The UNIX systems often come with “pg” and “more” but no “less” utility. The Linux usually provides “less” and “more” pager, but often no “pg”. MacOS comes with “less” and “more” pager and no “pg”. Windows provides “more”. The “more” pager is the oldest utility and thus most compatible with many systems.

Returns:

  • (Array[String])

58
59
60
61
# File 'lib/tty/pager/system.rb', line 58

def self.executables
  [ENV["GIT_PAGER"], ENV["PAGER"], git_pager,
   "less -r", "more -r", "most", "pg", "cat", "pager"].compact
end

.find_executable(*commands) ⇒ String?

Find first available termainal pager program executable

Examples:

Basic usage

find_executable # => "less"

Usage with commands

find_executable("less", "cat")  # => "less"

Parameters:

  • commands (Array[String])

Returns:

  • (String, nil)

    the found executable or nil when not found


85
86
87
88
89
90
# File 'lib/tty/pager/system.rb', line 85

def self.find_executable(*commands)
  execs = commands.empty? ? executables : commands
  execs
    .compact.map(&:strip).reject(&:empty?).uniq
    .find { |cmd| command_exist?(cmd.split.first) }
end

.run_command(*args) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Run pager command silently with no input and capture output

Returns:

  • (Boolean)

    true if command runs successfully, false otherwise


39
40
41
42
43
44
# File 'lib/tty/pager/system.rb', line 39

def self.run_command(*args)
  _, err, status = Open3.capture3(*args)
  err.empty? && status.success?
rescue Errno::ENOENT
  false
end

Instance Method Details

#closeBoolean

Stop the pager, wait for the process to finish. If no pager has been started, returns true.

Returns:

  • (Boolean)

    the exit status of the child process


166
167
168
169
170
171
172
# File 'lib/tty/pager/system.rb', line 166

def close
  return true unless @pager_io

  success = @pager_io.close
  @pager_io = nil
  success
end

#puts(text) ⇒ SystemPager

Send a line of text, ending in a newline, to the pager process. Starts a new process if it hasn't been started yet.

Returns:

Raises:


153
154
155
156
157
# File 'lib/tty/pager/system.rb', line 153

def puts(text)
  @pager_io ||= spawn_pager
  @pager_io.puts(text)
  self
end

#write(*args) ⇒ Object Also known as: <<

Send text to the pager process. Starts a new process if it hasn't been started yet.

Parameters:

  • *args (Array<String>)

    strings to send to the pager

Raises:


137
138
139
140
141
# File 'lib/tty/pager/system.rb', line 137

def write(*args)
  @pager_io ||= spawn_pager
  @pager_io.write(*args)
  self
end