|Sep 22, 2022
|Jul 19, 2021
|Mar 18, 2021
|May 13, 2020
|Jan 19, 2020
#408 in Text processing
385 downloads per month
A pager for command output or large files.
streampager is a library that implements a general-purpose pager for browsing streams of data one page at a time.
Its main program, sp, accepts streamed input on stdin for paging. It can also accept input from additional streams for separate presentation of the output of multiple commands and their error streams. It can also display the contents of files.
It also provides spp, which runs its arguments as a command, capturing its output and error streams for paging.
Press h from within streampager to display the keyboard shortcuts. Press q to exit.
Basic Usage for sp
If invoked with no arguments, sp reads from stdin, expecting to be invoked as the final command in a pipeline:
my_command | sp
By default, streampager will immediately enter fullscreen mode and page the input.
This can be customized:
This behaviour can be customized:
-Xoption prevents fullscreen mode. Instead, output will be displayed directly to the terminal until either a full screen of input is received, or
-D <SEC>option causes streampager to wait for a number of seconds to see if the input stream terminates early with less than a full screen of output. If it does, streampager displays this directly to the terminal and exits. If the input stream produces more than a full screen of data, the delay expires, or
Spaceis pressed, streampager enters full screen mode.
-Foption re-enables immediate fullscreen mode if a different mode has been selected in the streampager configuration file.
An indicator at the bottom right of the screen shows if the input stream is still connected, and whether new data is being loaded.
sp can also be used to display files by providing their file names as command line arguments.
sp can page multiple input streams from different file descriptors
on separate screens. These additional streams can be passed in using the
Error Streams and Progress Indicators
Input streams that are the error output for a stream can also be provided using
--error-fd option. As well as being shown on their own screen, the last
8 lines of an error stream are also shown at the bottom of the screen belonging
to the corresponding main stream.
An additional stream for progress indicators can be provided with the
--progress-fd option. This input stream expects to receive progress updates
(e.g. progress bars) terminated by ASCII form-feed characters (
sp will display the most recently received progress indicator at the bottom
of the screen.
Progress indicator pages should not contain control codes that are used for moving the cursor or clearing parts of the display. Control codes that affect the color or style of output are accepted and passed through to the terminal.
Calling processes that are using sp to page their own output can also provide
the file descriptor for these streams by setting the
PAGER_PROGRESS_FD environment variables.
-c option causes sp to invoke the specified command, and capture its
standard output and standard error streams as separate streams.
sp -c "grep -r foo /path"
will run grep, and page its output. Errors from grep will be paged separately from the main output.
-c option can be specified multiple times to run multiple commands
and page all of their outputs as separate streams.
The spp program runs the rest of its command line arguments as a single command. For example:
spp grep -r foo /path
is equivalent to the previous example.
streampager can be configured by a configuration file at
$CONFIG_DIR/streampager/streampager.toml. The configuration directory
varies by platform; on Linux it is typically
interface_mode = "delayed"
scroll_past_eof = true
read_ahead_lines = 20000
startup_poll_input = true
wrapping_mode = "word"
keymap = "mykeymap"
streampager provides various shortcuts for common operations, many of which
are compatible with
less. See the help screen for a full list. The most
common ones are listed below.
The keymap can be overridden by setting
keymap in the streampager
configuration file. Keymap files should be located in
F1Show the help screen.
Esc: Close help or any open prompt.
- Cursor Keys: Move one line or four columns.
Shift+ Cursor Keys: Move one quarter of the screen.
Space: Move a full page down.
Backspace: Move a full page up.
End: Move to the top or bottom of the file.
:: Go to a line number or percentage through the file.
]: Switch to the previous or next file.
#: Toggle display of line numbers.
\: Toggle line and word wrapping.
Things Left To Do
- Line ending detection and handling (display
<CR>in files with mixed line endings).
- Support composing character sequences (e.g. "لآ")
- Saving content to a file on disk (Key: