Struct minus::Pager

pub struct Pager { /* private fields */ }

A communication bridge between the main application and the pager.

The Pager type which is a bridge between your application and running the running pager. Its the single most important type with which you will be interacting the most while working with minus. It allows you to send data, configure UI settings and also configure the key/mouse bindings.

You can

• send data and
• set configuration options

before or while the pager is running.

Pager also implements the std::fmt::Write trait which means you can directly call write! and writeln! macros on it. For example, you can easily do this

use minus::Pager;
use std::fmt::Write;

const WHO: &str = "World";
let mut pager = Pager::new();

// This appends `Hello World` to the end of minus's buffer
writeln!(pager, "Hello {WHO}").unwrap();
// which is also equivalent to writing this
pager.push_str(format!("Hello {WHO}\n")).unwrap();

Implementations

impl Pager

pub fn new() -> Self

Initialize a new pager

Example

let pager = minus::Pager::new();

pub fn set_text(&self, s: impl Into<String>) -> Result<(), MinusError>

Set the output text to this t

Note that unlike Pager::push_str, this replaces the original text. If you want to append text, use the Pager::push_str function or the write!/writeln! macros

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

let pager = minus::Pager::new();
pager.set_text("This is a line").expect("Failed to send data to the pager");

pub fn push_str(&self, s: impl Into<String>) -> Result<(), MinusError>

Appends text to the pager output.

You can also use write!/writeln! macros to append data to the pager. The implementation basically calls this function internally. One difference between using the macros and this function is that this does not require Pager to be declared mutable while in order to use the macros, you need to declare the Pager as mutable.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use std::fmt::Write;

let mut pager = minus::Pager::new();
pager.push_str("This is some text").expect("Failed to send data to the pager");
// This is same as above
write!(pager, "This is some text").expect("Failed to send data to the pager");

pub fn set_line_numbers(&self, l: LineNumbers) -> Result<(), MinusError>

Set line number configuration for the pager

See LineNumbers for available options

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::{Pager, LineNumbers};

let pager = Pager::new();
pager.set_line_numbers(LineNumbers::Enabled).expect("Failed to communicate with the pager");

pub fn set_prompt(&self, text: impl Into<String>) -> Result<(), MinusError>

Set the text displayed at the bottom prompt

Panics

This function panics if the given text contains newline characters. This is because, the pager reserves only one line for showing the prompt and a newline will cause it to span multiple lines, breaking the display

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

let pager = Pager::new();
pager.set_prompt("my prompt").expect("Failed to send data to the pager");

pub fn send_message(&self, text: impl Into<String>) -> Result<(), MinusError>

Send a message to be displayed the prompt area

The text message is temporary and will get cleared whenever the use rdoes a action on the terminal like pressing a key or scrolling using the mouse.

Panics

This function panics if the given text contains newline characters. This is because, the pager reserves only one line for showing the prompt and a newline will cause it to span multiple lines, breaking the display

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

let pager = Pager::new();
pager.send_message("An error occurred").expect("Failed to send data to the pager");

pub fn set_exit_strategy(&self, es: ExitStrategy) -> Result<(), MinusError>

Set the default exit strategy.

This controls how the pager will behave when the user presses q or Ctrl+C. See ExitStrategy for available options

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

use minus::{Pager, ExitStrategy};

let pager = Pager::new();
pager.set_exit_strategy(ExitStrategy::ProcessQuit).expect("Failed to communicate with the pager");

pub fn set_run_no_overflow(&self, val: bool) -> Result<(), MinusError>

Available on crate feature static_output only.

Set whether to display pager if there’s less data than available screen height

When this is set to false, the pager will simply print all the lines to the main screen and immediately quit if the number of lines to display is less than the available columns in the terminal. Setting this to true will cause a full pager to start and display the data even if there is less number of lines to display than available rows.

This is only available in static output mode as the size of the data is known beforehand. In async output the pager can receive more data anytime

By default this is set to false

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

use minus::Pager;

let pager = Pager::new();
pager.set_run_no_overflow(true).expect("Failed to communicate with the pager");

pub fn horizontal_scroll(&self, value: bool) -> Result<(), MinusError>

Whether to allow scrolling horizontally

Setting this to true implicitly disables line wrapping

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

use minus::Pager;

let pager = Pager::new();
pager.horizontal_scroll(true).expect("Failed to communicate with the pager");

pub fn set_input_classifier( &self, handler: Box<dyn InputClassifier + Send + Sync> ) -> Result<(), MinusError>

Set a custom input classifer type.

An input classifier type is a type that implements the InputClassifier trait. It only has one required function, InputClassifier::classify_input which matches user input events and maps them to a InputEvents. When the pager encounters a user input, it calls the input classifier with the event and PagerState as parameters.

Previously, whenever any application wanted to change the default key/mouse bindings they neededd to create a new type, implement the InputClassifier type by copying and pasting the default minus’s implementation of it available in the DefaultInputClassifier and change the parts they wanted to change. This is not only unergonomic but also extreemely prone to bugs. Hence a newer and much simpler method was developed. This method is still allowed to avoid breaking backwards compatiblity but will be dropped in the next major release.

With the newer method, minus already provides a type called HashedEventRegister which implementing the InputClassifier and is based on a HashMap storing all the key/mouse bindings and its associated callback function. This allows easy addition/updation/deletion of the default bindings with simple functions like HashedEventRegister::add_key_events and HashedEventRegister::add_mouse_events

See the input module for information about implementing it.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

pub fn add_exit_callback( &self, cb: Box<dyn FnMut() + Send + Sync + 'static> ) -> Result<(), MinusError>

Adds a function that will be called when the user quits the pager

Multiple functions can be stored for calling when the user quits. These functions run sequentially in the order they were added

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

fn hello() {
    println!("Hello");
}

let pager = Pager::new();
pager.add_exit_callback(Box::new(hello)).expect("Failed to communicate with the pager");

pub fn set_incremental_search_condition( &self, cb: Box<dyn Fn(&SearchOpts<'_>) -> bool + Send + Sync + 'static> ) -> Result<(), MinusError>

Available on crate feature search only.

Override the condition for running incremental search

See Incremental Search to know more on how this works

Errors

This function will returns a Err(MinusError::Communication) if the data could not be send to the receiver end.

pub fn show_prompt(&self, show: bool) -> Result<(), MinusError>

Control whether to show the prompt

Many applications don’t want the prompt to be displayed at all. This function can be used to completely turn off the prompt. Passing false to this will stops the prompt from displaying and instead a blank line will be displayed.

Note that This merely stop the prompt from being shown. Your application can still update the prompt and send messages to the user but it won’t be shown until the prompt isn’t re-enabled. The prompt section will also be used when user opens the search prompt to type a search query.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the mus’s receiving end

Example

use minus::Pager;

let pager = Pager::new();
pager.show_prompt(false).unwrap();

pub fn follow_output(&self, follow_output: bool) -> Result<(), MinusError>

Configures follow output

When set to true, minus ensures that the user’s screen always follows the end part of the output. By default it is turned off.

This is similar to InputEvent::FollowOutput except that this is used to control it from the application’s side.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the mus’s receiving end

Example

use minus::Pager;

let pager = Pager::new();
pager.follow_output(true).unwrap();

Trait Implementations

impl Clone for Pager

fn clone(&self) -> Pager

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Pager

fn default() -> Self

Returns the “default value” for a type.

impl Write for Pager

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.