Skip to main content

Crate minus

Crate minus 

Source
Expand description

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 std::{
    fmt::Write,
    thread::{spawn, sleep},
    time::Duration
};

use minus::dynamic_paging;
use minus::{MinusError, Pager};

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 std::time::Duration;
use std::fmt::Write;

use minus::dynamic_paging;
use minus::{MinusError, Pager};

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::page_all;
use minus::{MinusError, Pager};

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.

ActionDescription
Ctrl+C/qQuit the pager
[n] Arrow Up/kScroll up by n number of line(s). If n is omitted, scroll up by 1 line
[n] Arrow Down/jScroll down by n number of line(s). If n is omitted, scroll down by 1 line
Ctrl+Shift+h/Ctrl+hToggle line wrapping and allow horizontal scrolling
[n] Arrow left/hScroll left by n number of line(s). If n is omitted, scroll left by 1 line
[n] Arrow right/lScroll right by n number of line(s). If n is omitted, scroll right by 1 line
Page UpScroll up by entire page
Page Down/SpaceScroll down by entire page
[n] EnterScroll down by n number of line(s).
Ctrl+U/uScroll up by half a screen
Ctrl+D/dScroll down by half a screen
g/HomeGo to the very top of the output
[n] G/Shift+gGo to the very bottom of the output. If n is present, goes to that line
EndGo to the very bottom of the output
Mouse scroll UpScroll up by 5 lines
Mouse scroll DownScroll down by 5 lines
Mouse left dragSelect text
EscClear the active selection
Ctrl+LToggle line numbers if not forced enabled/disabled
Ctrl+fToggle follow-mode
/Start forward search
?Start backward search
EscCancel search input
nGo to the next search match
p/Shift+nGo to the previous search match
Alt+iToggle smart case (in the search prompt)

The help screen is opt-in: applications that call HashedEventRegister::add_help_key get an Alt+h binding (unless custom keys are given). 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 BindingsDescription
EscCancel the search
EnterConfirm the search query
BackspaceRemove the character before the cursor
DeleteRemove the character under the cursor
Arrow LeftMove cursor towards left
Arrow rightMove cursor towards right
Ctrl+Arrow leftMove cursor towards left word by word
Ctrl+Arrow rightMove cursor towards right word by word
HomeMove cursor at the beginning of the search query
EndMove cursor at the end of the search query
Alt+iToggle smart case

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

Re-exports§

pub use search::SearchMode;search
pub use error::MinusError;
pub use sink::OutputSink;
pub use state::PagerState;

Modules§

error
Provides error types that are used in various places
help
Help text and related definitions for the pager.
hooks
Manages and runs callbacks for events happening in minus.
input
Manage keyboard/mouse-bindings while running minus.
screen
Provides functions for getting analysis of the text data inside minus.
searchsearch
Text searching functionality
sink
Defines the OutputSink trait and its implementations.
state
Contains types that hold run-time information of the pager.

Structs§

ContentStyle
crossterm’s content style type, re-exported so hosts configuring the selection-hint bar (Pager::set_selection_hint_style) need not match crossterm versions themselves.
Pager
A communication bridge between the main application and the pager.

Enums§

Color
crossterm’s content style type, re-exported so hosts configuring the selection-hint bar (Pager::set_selection_hint_style) need not match crossterm versions themselves.
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_pagingdynamic_output
Starts a asynchronously running pager
page_allstatic_output
Display static information to the screen

Type Aliases§

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