Crate minus

minus: A library for asynchronous terminal paging, written in Rust.

If you want to learn about its motivation and features, please take a look into it’s README.

Overview

When getting started with minus, the two most important concepts to get familier with are:

• The Pager type: which acts as a bridge between your application and minus. It is used to pass data and configure minus before and after starting the pager.
• Initialization functions: This includes the dynamic_paging and page_all functions which take a Pager as argument. They are responsible for generating the initial state and starting the pager.

See the docs for the respective items to learn more on its usage.

Examples

Threads

use minus::{dynamic_paging, MinusError, Pager};
use std::{
    fmt::Write,
    thread::{spawn, sleep},
    time::Duration
};

fn main() -> Result<(), MinusError> {
    // Initialize the pager
    let mut pager = Pager::new();
    // Run the pager in a separate thread
    let pager2 = pager.clone();
    let pager_thread = spawn(move || dynamic_paging(pager2));

    for i in 0..=100_u32 {
        writeln!(pager, "{}", i);
        sleep(Duration::from_millis(100));
    }
    pager_thread.join().unwrap()?;
    Ok(())
}

tokio

use minus::{dynamic_paging, MinusError, Pager};
use std::time::Duration;
use std::fmt::Write;
use tokio::{join, task::spawn_blocking, time::sleep};

#[tokio::main]
async fn main() -> Result<(), MinusError> {
    // Initialize the pager
    let mut pager = Pager::new();
    // Asynchronously send data to the pager
    let increment = async {
        let mut pager = pager.clone();
        for i in 0..=100_u32 {
            writeln!(pager, "{}", i);
            sleep(Duration::from_millis(100)).await;
        }
        Result::<_, MinusError>::Ok(())
    };
    // spawn_blocking(dynamic_paging(...)) creates a separate thread managed by the tokio
    // runtime and runs the async_paging inside it
    let pager = pager.clone();
    let (res1, res2) = join!(spawn_blocking(move || dynamic_paging(pager)), increment);
    // .unwrap() unwraps any error while creating the tokio task
    //  The ? mark unpacks any error that might have occurred while the
    // pager is running
    res1.unwrap()?;
    res2?;
    Ok(())
}

Static output

use std::fmt::Write;
use minus::{MinusError, Pager, page_all};

fn main() -> Result<(), MinusError> {
    // Initialize a default static configuration
    let mut output = Pager::new();
    // Push numbers blockingly
    for i in 0..=30 {
        writeln!(output, "{}", i)?;
    }
    // Run the pager
    minus::page_all(output)?;
    // Return Ok result
    Ok(())
}

Note: In static mode, minus doesn’t start the pager and just prints the content if the current terminal size can display all lines. You can of course change this behaviour.

Default keybindings

Here is the list of default key/mouse actions handled by minus.

A [n] key means that you can precede the key by an integer.

Action	Description
Ctrl+C/q	Quit the pager
[n] Arrow Up/k	Scroll up by n number of line(s). If n is omitted, scroll up by 1 line
[n] Arrow Down/j	Scroll down by n number of line(s). If n is omitted, scroll down by 1 line
Ctrl+h	Turn off line wrapping and allow horizontal scrolling
[n] Arrow left/h	Scroll left by n number of line(s). If n is omitted, scroll up by 1 line
[n] Arrow right/l	Scroll right by n number of line(s). If n is omitted, scroll down by 1 line
Page Up	Scroll up by entire page
Page Down	Scroll down by entire page
[n] Enter	Scroll down by n number of line(s).
Space	Scroll down by one page
Ctrl+U/u	Scroll up by half a screen
Ctrl+D/d	Scroll down by half a screen
g	Go to the very top of the output
[n] G	Go to the very bottom of the output. If n is present, goes to that line
Mouse scroll Up	Scroll up by 5 lines
Mouse scroll Down	Scroll down by 5 lines
Ctrl+L	Toggle line numbers if not forced enabled/disabled
Ctrl+f	Toggle follow-mode
/	Start forward search
?	Start backward search
Esc	Cancel search input
n	Go to the next search match
p	Go to the next previous match

End-applications are free to change these bindings to better suit their needs. See docs for Pager::set_input_classifier function and input module.

Key Bindings Available at Search Prompt

Key Bindings	Description
Esc	Cancel the search
Enter	Confirm the search query
Backspace	Remove the character before the cursor
Delete	Remove the character under the cursor
Arrow Left	Move cursor towards left
Arrow right	Move cursor towards right
Ctrl+Arrow left	Move cursor towards left word by word
Ctrl+Arrow right	Move cursor towards right word by word
Home	Move cursor at the beginning pf search query
End	Move cursor at the end pf search query

Currently these cannot be changed by applications but this may be supported in the future.

Re-exports

• pub use search::SearchMode;
• pub use error::MinusError;
• pub use state::PagerState;

Modules

• error
  Provides error types that are used in various places
• input
  Manage keyboard/mouse-bindings while running minus.
• screen
  Provides functions for getting analysis of the text data inside minus.
• searchsearch
  Text searching functionality
• state
  Contains types that hold run-time information of the pager.

Structs

• Pager
  A communication bridge between the main application and the pager.

Enums

• ExitStrategy
  Behaviour that happens when the pager is exited
• LineNumbers
  Enum indicating whether to display the line numbers or not.
• RunMode
  Define the modes in which minus can run

Functions

• dynamic_paging
  Starts a asynchronously running pager
• page_all
  Display static information to the screen

Type Aliases

• ExitCallbacks
  A convenient type for Vec<Box<dyn FnMut() + Send + Sync + 'static>>