### Initialize TTY::Pager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Creates a new instance of TTY::Pager, automatically selecting the best available pager on the system. This is the most common way to start using the pager.

```ruby
pager = TTY::Pager.new
```

--------------------------------

### Install TTY::Pager Gem

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Instructions for adding the TTY::Pager gem to your Ruby project's Gemfile or installing it directly using the gem command.

```ruby
gem 'tty-pager'

gem install tty-pager
```

--------------------------------

### Create TTY::Pager Instance

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Demonstrates various ways to initialize a TTY::Pager object, including automatic selection, disabling paging, forcing specific commands, setting width, custom prompts, and custom I/O streams.

```ruby
require 'tty-pager'

# Basic initialization - auto-selects best pager
pager = TTY::Pager.new

# Disable paging (uses NullPager, outputs directly to stdout)
pager = TTY::Pager.new(enabled: false)

# Force a specific pager command
pager = TTY::Pager.new(command: "less -R")

# Multiple fallback commands
pager = TTY::Pager.new(command: ["less -r", "more -r"])

# Set width for BasicPager text wrapping
pager = TTY::Pager.new(width: 80)

# Custom prompt for page breaks (BasicPager only)
custom_prompt = ->(page) { "Page #{page} - Press enter to continue (q to quit)" }
pager = TTY::Pager.new(prompt: custom_prompt)

# Custom I/O streams
pager = TTY::Pager.new(input: $stdin, output: $stdout)
```

--------------------------------

### Instantiate Specific TTY::Pager Implementations

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Allows direct instantiation of specific TTY::Pager implementations like BasicPager, SystemPager, or NullPager, bypassing the automatic detection mechanism.

```ruby
pager = TTY::Pager::BasicPager.new
# or
pager = TTY::Pager::SystemPager.new
# or
pager = TTY::Pager::NullPager.new
```

--------------------------------

### Instantiate and Use System Pager

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Directly instantiate TTY::Pager::SystemPager to use native paging tools. It raises an error if no system pager is available. You can specify a command and content to page. It also provides class methods to check for pager availability and find executables.

```ruby
require 'tty-pager'

try
  # Use system pager with specific command
  pager = TTY::Pager::SystemPager.new(command: "less -R")
  pager.page("Content with ANSI colors: \e[31mred\e[0m \e[32mgreen\e[0m")
rescue TTY::Pager::Error => e
  puts "System pager not available: #{e.message}"
end

# Check if system pager is available before creating
if TTY::Pager::SystemPager.exec_available?
  pager = TTY::Pager::SystemPager.new
  pager.page(path: "/var/log/syslog")
end

# Check for specific pager command
if TTY::Pager::SystemPager.exec_available?("less")
  puts "less is available"
end

# Find available executable from list
executable = TTY::Pager::SystemPager.find_executable("less", "more", "cat")
puts "Found pager: #{executable}"
```

--------------------------------

### Configure TTY::Pager with Options

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Initializes TTY::Pager with custom options such as disabling paging, specifying a command, or setting the terminal width.

```ruby
pager = TTY::Pager.new(enabled: false)
# or
pager = TTY::Pager.new(command: "less -R")
# or
pager = TTY::Pager.new(width: 80)
```

--------------------------------

### Page Text Content

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Use the `page` method to paginate string content. This can be done via a class-level shortcut or an instance method. Extra initialization parameters like `command` can be provided.

```ruby
TTY::Pager.page("Some long text...")
```

```ruby
TTY::Pager.page("Some long text...", command: "less -R")
```

```ruby
pager = TTY::Pager.new(command: "less -R")
pager.page("Some long text...")
```

--------------------------------

### Paginate Content with pager.page (Instance Method)

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Illustrates using the instance method `pager.page` to paginate content through an existing pager instance. This method waits for the user to finish reading before returning. It can paginate strings or file contents.

```ruby
require 'tty-pager'

pager = TTY::Pager.new

# Page a string
pager.page("Long text content to paginate...")

# Page file contents
pager.page(path: "/var/log/application.log")

# The pager waits until user finishes reading (presses 'q' or reaches end)
```

--------------------------------

### Paginate Content with TTY::Pager.page (Class Method)

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Shows how to use the class-level `TTY::Pager.page` method for a quick way to paginate content. It handles pager creation, display, and cleanup automatically. Supports paginating strings, file contents, and streaming via a block.

```ruby
require 'tty-pager'

# Page a string directly
TTY::Pager.page("Very long text content here...")

# Page with specific pager command
TTY::Pager.page("Long text...", command: "less -R")

# Page file contents by path
TTY::Pager.page(path: "/path/to/large_file.txt")

# Block form for streaming content
TTY::Pager.page do |pager|
  File.foreach("large_file.txt") do |line|
    processed_line = line.upcase  # Process each line
    pager.write(processed_line)
  end
end
# Pager automatically closed after block
```

--------------------------------

### Use Pure Ruby Pager

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Utilize TTY::Pager::BasicPager for a platform-independent paging solution written in pure Ruby. It allows customization of width, height, and the page break prompt.

```ruby
require 'tty-pager'

# Basic usage with custom width
pager = TTY::Pager::BasicPager.new(width: 80)
pager.page(path: "large_file.txt")

# Custom page break prompt
custom_prompt = ->(page_num) {
  "\n--- Page #{page_num} --- [Enter] next | [q] quit ---"
}
pager = TTY::Pager::BasicPager.new(
  width: 100,
  height: 25,
  prompt: custom_prompt
)

pager.page("Very long content that spans multiple pages...")
```

--------------------------------

### Page Content with Block (Class)

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Use the class-level `page` method with a block to automatically manage the pager's lifecycle. This is useful for processing file content line by line and writing it to the pager.

```ruby
TTY::Pager.page do |pager|
  File.foreach("filename.txt") do |line|
    # do some work with the line

    pager.write(line) # write line to the pager
  end
end
```

--------------------------------

### Configure Pager via Environment Variables

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Configure the default pager behavior by setting environment variables like `PAGER` or `GIT_PAGER`. The `TTY::Pager.new` will automatically pick up these settings to determine the pager command.

```ruby
require 'tty-pager'

# Set preferred pager via environment
ENV["PAGER"] = "less -R"

# Or use GIT_PAGER for consistency with git
ENV["GIT_PAGER"] = "less -FRX"

# SystemPager checks these in order:
# 1. GIT_PAGER environment variable
# 2. PAGER environment variable
# 3. Git config core.pager setting
# 4. Built-in list: less -r, more -r, most, pg, cat, pager

pager = TTY::Pager.new
pager.page("Content paginated with configured pager...")
```

--------------------------------

### Page Content with Block (Instance)

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Use an instance of `TTY::Pager` with a block for manual control over paging and automatic closing. This pattern ensures the pager is closed even if errors occur.

```ruby
pager = TTY::Pager.new
try
  File.foreach("filename.txt") do |line|
    # do some work with the line

    pager.write(line) # write line to the pager
  end
rescue TTY::Pager::PagerClosed
finally
  pager.close
end
```

--------------------------------

### Configure TTY::Pager with Multiple Commands

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Configures TTY::Pager to use a specific list of paging commands, providing fallback options if the primary commands are not available.

```ruby
pager = TTY::Pager.new(command: ["less -r", "more -r"])
```

--------------------------------

### Manual Paging with TTY::Pager Write and Close

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Manually paginates content by explicitly calling `write` for each line and `close` to finalize. This provides more control over the paging process and allows for error handling.

```ruby
begin
  pager = TTY::Pager.new

  File.open("file_with_lots_of_lines.txt", "r").each_line do |line|
    pager.write(line)
  end
rescue TTY::Pager::PagerClosed
  # the user closed the paginating tool
ensure
  pager.close
end
```

--------------------------------

### Page File Content

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Paginate the content of a file by passing the `:path` option to the `page` method. This is a convenient way to view file contents with pagination.

```ruby
TTY::Pager.page(path: "/path/to/filename.txt")
```

--------------------------------

### Configure BasicPager Width

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Initializes the BasicPager with a specific terminal width for content wrapping. This option is only applicable to the BasicPager and does not affect the SystemPager.

```ruby
pager = TTY::Pager::BasicPager.new(width: 80)
```

--------------------------------

### Safe Write with pager.try_write

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Explains the `pager.try_write` method, which attempts to write content to the pager and returns a boolean indicating success. This is helpful for gracefully handling cases where the user closes the pager early without raising an exception.

```ruby
require 'tty-pager'

pager = TTY::Pager.new

File.foreach("large_dataset.txt") do |line|
  success = pager.try_write(line)

  unless success
    puts "User closed pager, stopping output"
    break
  end
end

pager.close
```

--------------------------------

### Stream Content to Pager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Use the `write` method to stream content to the pager. Multiple arguments can be passed, and they will be concatenated and written.

```ruby
pager.write("Some text")
```

```ruby
pager.write("one", "two", "three")
```

--------------------------------

### Use No-Op Pager

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Employ TTY::Pager::NullPager for scenarios where paging should be disabled, ensuring output goes directly to stdout. This is automatically used when the pager is created with `enabled: false`.

```ruby
require 'tty-pager'

# Explicitly use NullPager
pager = TTY::Pager::NullPager.new
pager.write("This goes directly to stdout")
pager.puts("No pagination, immediate output")
pager.close  # Always returns true

# Created automatically when enabled: false
pager = TTY::Pager.new(enabled: false)
# Uses NullPager internally
```

--------------------------------

### Paginate Text Content with TTY::Pager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Paginates a given string content using the TTY::Pager. The pager will launch in the background and wait for the user to finish interacting with it.

```ruby
pager = TTY::Pager.new
pager.page("Very long text...")
```

--------------------------------

### Paginate File Content with TTY::Pager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Paginates the content of a specified file using TTY::Pager by providing the file path. This is useful for displaying large log files or configuration files.

```ruby
pager = TTY::Pager.new
pager.page(path: "/path/to/filename.txt")
```

--------------------------------

### Check Write Success

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

The `try_write` method checks if writing content to the pager was successful. It returns `true` if the write operation succeeded and `false` otherwise.

```ruby
pager.try_write("Some text")
# => true
```

--------------------------------

### Customize Pager Prompt

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Change the prompt displayed by the `BasicPager` using the `:prompt` option. This allows for custom messages and page numbers to be shown to the user.

```ruby
prompt = -> (page) { "Page -#{page_num}- Press enter to continue" }
pager = TTY::Pager.new(prompt: prompt)
```

--------------------------------

### Write Line with Newline

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Use the `puts` method to write a line of text to the pager, automatically appending a newline character at the end.

```ruby
pager.puts("Single line of content")
```

--------------------------------

### Configure Pager Command via ENV

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Set the `PAGER` environment variable to specify a preferred pager command. This can be done in the shell or directly within a Ruby script.

```bash
PAGER=less -R
export PAGER
```

```ruby
ENV["PAGER"]="less -R"
```

--------------------------------

### Stream Content with pager.write

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Demonstrates the `pager.write` method for sending text to the pager without automatically closing it. This is useful for streaming large amounts of data or building content incrementally. It supports multiple calls and the `<<` alias.

```ruby
require 'tty-pager'

pager = TTY::Pager.new

begin
  # Write multiple chunks
  pager.write("Header information\n")
  pager.write("=" * 40, "\n")

  # Process and stream data
  1000.times do |i|
    pager.write("Line #{i}: #{Time.now}\n")
  end

  # Chainable calls using << alias
  pager << "Footer " << "information\n"

rescue TTY::Pager::PagerClosed
  # User closed pager early (pressed 'q')
  puts "Pager was closed by user"
ensure
  pager.close
end
```

--------------------------------

### Handle Pager Errors Gracefully

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Implement robust error handling for pager operations, specifically catching `TTY::Pager::PagerClosed` when a user quits the pager, and other general `TTY::Pager::Error` exceptions.

```ruby
require 'tty-pager'

pager = TTY::Pager.new

try
  # Long-running output operation
  10_000.times do |i|
    pager.write("Processing item #{i}...\n")
  end
rescue TTY::Pager::PagerClosed
  # User pressed 'q' or closed the pager
  $stderr.puts "Output interrupted by user"
rescue TTY::Pager::InvalidArgument => e
  # Invalid argument combination
  $stderr.puts "Invalid arguments: #{e.message}"
rescue TTY::Pager::Error => e
  # General pager error
  $stderr.puts "Pager error: #{e.message}"
finally
  pager.close
end
```

--------------------------------

### Paginate Long-Running Operations with TTY::Pager Block

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Paginates output from a long-running operation using a block form. The pager automatically handles writing lines to the pager and closing it upon completion.

```ruby
TTY::Pager.page do |pager|
  File.open("file_with_lots_of_lines.txt", "r").each_line do |line|
    pager.write(line)
  end
end
```

--------------------------------

### Force System Pager with TTY::Pager::SystemPager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Forces TTY::Pager to always use the system pager, bypassing automatic detection and providing a specific command for the system pager.

```ruby
TTY::Pager::SystemPager.new(command: "less -R")
```

--------------------------------

### Close Pager with pager.close

Source: https://context7.com/piotrmurach/tty-pager/llms.txt

Describes the `pager.close` method, which finalizes the paging process and performs necessary cleanup. It should be called when manual write operations are complete, typically within an `ensure` block to guarantee execution.

```ruby
require 'tty-pager'

pager = TTY::Pager.new

begin
  pager.write("Content to display...")
  pager.write("More content...")
rescue TTY::Pager::PagerClosed
  puts "Pager closed early"
ensure
  # Always close the pager in ensure block
  success = pager.close
  puts "Pager closed successfully: #{success}"
end
```

--------------------------------

### Manually Close Pager

Source: https://github.com/piotrmurach/tty-pager/blob/master/README.md

Call the `close` method when manual streaming of content is complete. It's recommended to wrap pager interactions in a `begin...rescue...ensure` block to guarantee closure.

```ruby
pager = TTY::Pager.new

begin
  # ... perform pager writes
rescue TTY::Pager::PagerClosed
  # the user closed the paginating tool
ensure
  pager.close
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.