Usage

Getting started

The pager is called using the function pager. If the input object is not an AbstractString, then it will be rendered using show with MIME"text/plain". Thus, you can browse a large matrix, for example, using:

julia> rand(100,100) |> pager

It is also possible to use the pager to browse the documentation of a specific function:

julia> @doc(write) |> pager

All the functionalities can be seen in the built-in help system, accessible by typing ? inside the pager.

Inside the Pager

The last row is a status line with the prompt ❯ in the normal mode, the search or the visual mode and its state, the enabled features, the key hints of the current mode, whether the text continues beyond the left or the right edge (‹ and ›), and the position (All, Top, Bot, or a percentage). The row has no background by default; the face status_bar draws it as a bar (see the customization page). The movements follow less and Vi: the arrow keys, j, k, h, l, Space, PgUp, PgDn, Home, End, g, and G. Typing : followed by a line number moves the display to that line, r toggles a line number ruler, s toggles a scrollbar, and q quits.

The mouse wheel scrolls the text, and SHIFT and the wheel scroll it horizontally. Notice that, while the pager reports the mouse, selecting text with the terminal requires holding SHIFT, or OPTION on some terminals. The preference "mouse" disables the reporting.

Typing / searches for a regular expression. The matches are highlighted while the pattern is typed, n and N navigate them, and ESC leaves the search. The search is case-insensitive unless the pattern has an uppercase letter. The up and down keys at the prompt recall the previous patterns of the session.

The visual mode, toggled with v, highlights a visual line that the movements and the mouse move. m marks the visual line, and y copies the marked lines to the clipboard.

Rows and columns can be frozen with f, so that they stay visible while scrolling, and t selects how many frozen rows are titles, which do not scroll horizontally either.

Helpers

The following macros are available to help calling the pager.

@help

This macro calls the help of any function, macro, or other object and redirects it to the pager:

julia> @help write

You can hit <Alt> + h or <F1> on any REPL input to get extended help about the identifier the cursor is currently on. After you exit the pager, you return to the REPL input you had already typed. If you are in a new argument of a method call, the pager prints extended help about the function instead, to help you complete the method's argument list.

@stdout_to_pager

This macro redirects all the stdout to the pager after the command is completed:

julia> @stdout_to_pager show(stdout, MIME"text/plain"(), rand(100,100))

This macro also works with blocks such as for loops:

julia> @stdout_to_pager for i = 1:100
       println("$(mod(i,9))"^i)
       end

REPL Modes

TerminalPager.jl comes with a REPL mode that automatically renders the command output to a pager if it does not fit the screen. To access this mode, just type | at the beginning of the REPL command line. If the mode is loaded correctly, the prompt julia> is changed to pager>.

In pager mode, you can also type ? at the beginning of the command line to access the pager help mode. In this case, the prompt is changed to pager?>. Any docstring accessed in this mode is rendered inside a pager. The pager uses the alternate screen buffer, so the screen content is restored after exiting it.