Library

_INCOMPLETE_KEYSTROKE

Sentinel keystroke carried by the result of decoding an incomplete byte prefix.

Returning nothing for the key instead made the decoder return a union of tuple types, which is heap-allocated at the reduced optimization level of this package, costing 80 bytes per keystroke.

DisplayConfig

Store display strings captured from preferences for one pager session.

Fields

• active_search_decoration::String: Decoration for the active search match.
• inactive_search_decoration::String: Decoration for inactive search matches.
• visual_mode_active_line_background::String: Background for the active visual line.
• visual_mode_line_background::String: Background for selected visual lines.

DisplayConfig() -> DisplayConfig

Construct a display configuration with the built-in preference defaults.

FrameCache

Store what was last painted on the screen so that a redraw only emits the rows that changed.

The invariant is that, while valid is true, bytes[row_first[i]:row_last[i]] is exactly what is on screen row i for every i in 1:num_rows. An empty row is represented by row_last[i] < row_first[i].

Fields

• bytes::Vector{UInt8}: Snapshot of the rows currently on screen.
• row_first::Vector{Int}: First index of each snapshot row in bytes.
• row_last::Vector{Int}: Last index of each snapshot row in bytes, inclusive.
• num_rows::Int: Number of rows the snapshot describes.
• new_first::Vector{Int}: First index of each row of the frame being painted.
• new_last::Vector{Int}: Last index of each row of the frame being painted, inclusive.
• out::IOBuffer: Reused buffer assembling everything sent to the terminal.
• valid::Bool: Whether the snapshot describes the screen.

Keystroke

Represent one decoded keystroke.

Fields

• raw::String: Raw keystroke code converted to string.
• value::String: String representing the keystroke.
• alt::Bool: Whether the ALT key was pressed.
• ctrl::Bool: Whether the CTRL key was pressed.
• shift::Bool: Whether the SHIFT key was pressed.

Pager

Store the mutable state for one pager session.

Fields

• term::REPL.Terminals.TTYTerminal: Terminal used by the session.
• buf::IOContext{IOBuffer}: Buffered rendered output.
• display_size::NTuple{2, Int}: Current terminal rows and columns.
• start_row::Int: First visible source row.
• start_column::Int: First visible printable column.
• text_layout::TextViewLayout: Canonical prepared text layout.
• num_lines::Int: Number of source lines.
• cropped_lines::Int: Number of lines cropped below the viewport.
• cropped_columns::Int: Number of columns cropped to the right.
• display_config::DisplayConfig: Display configuration for the session.
• input::PagerInput: Shared input state for the session.
• search_matches::SearchMatches: Search matches grouped by source line.
• ordered_search_matches::Vector{SearchMatch}: Matches in navigation order.
• num_matches::Int: Number of search matches.
• active_search_match_id::Int: Active match index in navigation order.
• redraw::Bool: Whether the viewport needs to be redrawn.
• mode::Symbol: Current pager mode.
• event::Union{Nothing, Symbol}: Pending pager event.
• features::Vector{Symbol}: Features enabled for the session.
• frozen_columns::Int: Number of frozen leading columns.
• frozen_rows::Int: Number of frozen leading rows.
• title_rows::Int: Number of title rows.
• show_ruler::Bool: Whether to show the line-number ruler.
• visual_mode::Bool: Whether visual selection mode is active.
• visual_mode_line::Int: Active visual line relative to the viewport.
• visual_mode_selected_lines::Vector{Int}: Selected source-line indices.
• visual_lines::Vector{Int}: Reused buffer with the lines rendered with a background.
• visual_line_backgrounds::Vector{String}: Reused buffer with the background of each entry of visual_lines.
• frame_cache::FrameCache: State supporting the incremental redraw.

PagerInput

Track shared pager input with a bounded incomplete prefix and one pending keystroke.

Fields

• stream::IO: Input stream that supplies keystroke bytes.
• prefix::Vector{UInt8}: Bytes retained while decoding an incomplete keystroke.
• pending::Union{Nothing, Keystroke}: Keystroke retained at an input boundary.
• can_lookahead::Bool: Whether nonblocking lookahead is supported by stream.

PagerInput(stream::IO) -> PagerInput

Create input state for stream with an empty prefix and no pending keystroke.

Arguments

• stream::IO: Input stream that supplies keystroke bytes.

SearchMatch

Represent a search match location in document and printable-column order.

Fields

• line::Int: One-based source line index.
• index_in_line::Int: One-based match index within the source line.
• column::Int: One-based printable column where the match starts.
• width::Int: Printable width of the match.

__init__() -> Nothing

Apply mode-dependent keybindings and initialize REPL integrations.

_action_keybindings() -> Dict{Symbol, String}

Return a description of the keybindings of every action, keyed by action.

The result is cached until the keybindings change. Without the cache, opening the help screen scanned _KEYBINDINGS once per action, that is, 27 times.

The descriptions of each action are sorted, so that the help screen does not depend on the iteration order of _KEYBINDINGS.

_adjust_search_index(input::String, cursor_pos::Integer) -> Int

Convert the cursor position to the byte index of the token the cursor refers to.

Arguments

• input::String: REPL input text to inspect.
• cursor_pos::Integer: Character cursor position in input.

_apply_mode_keybindings!(get_preference::F = _get_preference) -> Nothing where
    {F <: Function}

Apply the key bindings that depend on the pager_mode preference to _KEYBINDINGS.

Arguments

• get_preference::F: Callable preference getter used to read pager_mode. (Default: _get_preference)

_ascend(node::SyntaxNode) -> SyntaxNode

Ascend to the most specific SyntaxNode containing all the information needed for @help.

Arguments

• node::SyntaxNode: Syntax node from which to ascend.

_ascii_keystroke(byte::UInt8) -> Keystroke

Convert one ASCII or control byte into a keystroke.

Arguments

• byte::UInt8: ASCII or control byte to convert.

_assemble_repl_command(
    lines::AbstractVector{<:AbstractString},
    first_line::Int,
    last_line::Int
) -> String

Assemble the newline-terminated command spanning lines[first_line:last_line].

Arguments

• lines::AbstractVector{<:AbstractString}: Lines of the whole REPL input.
• first_line::Int: One-based index of the first command line.
• last_line::Int: One-based index of the last command line, inclusive.

_assemble_yank_text(
    lines::AbstractVector{<:AbstractString},
    line_ids::AbstractVector{<:Integer}
) -> Tuple{String, Int}

Assemble sorted, deduplicated, undecorated lines with a trailing newline and return the text and selected-line count.

Arguments

• lines::AbstractVector{<:AbstractString}: Canonical line sequence.
• line_ids::AbstractVector{<:Integer}: One-based line indices to sort and deduplicate.

_build_ascii_keystroke(byte::UInt8) -> Keystroke

Build the keystroke for one ASCII or control byte.

This is only used to fill _ASCII_KEYSTROKES when the package is loaded.

Arguments

• byte::UInt8: ASCII or control byte to convert.

_bytes_equal(a, ai::Int, b, bi::Int, n::Int) -> Bool

Return whether the n bytes of a starting at ai equal those of b starting at bi.

Arguments

• a: First byte storage.
• ai::Int: One-based first index in a.
• b: Second byte storage.
• bi::Int: One-based first index in b.
• n::Int: Number of bytes to compare.

_change_active_match!(pagerd::Pager, forward::Bool = true) -> Nothing

Change the active match forward when forward is true and backward otherwise.

Arguments

• pagerd::Pager: Pager state to update.
• forward::Bool: Whether to select the next match instead of the previous match. (Default: true)

_clear_screen(io::IO) -> Nothing

Clear io and move its cursor to the first row and column.

Notice that the clearing uses a single escape sequence, which adds new lines to the terminal and hence preserves its history.

Arguments

• io::IO: Output stream that represents the terminal screen.

_cmd_cursor_column(chars::Vector{Char}, cursor::Int, prefix_width::Int,
    display_width::Int) -> Int

Return the display column of the command line cursor.

Notice that the column is a display width and not a character count, so that the cursor stays under the insertion point when the command contains wide characters.

Arguments

• chars::Vector{Char}: Characters of the command being edited.
• cursor::Int: One-based insertion index in chars.
• prefix_width::Int: Display width of the prompt.
• display_width::Int: Number of columns the terminal has.

_coalesce_navigation!(pagerd::Pager, first_action::Union{Nothing, Symbol};
    max_actions::Int = 128,
    max_ns::UInt64 = UInt64(4_000_000),
    display_size_function::Any = displaysize) -> Int

Replay already-buffered navigation in the same direction group and retain the first boundary.

Arguments

• pagerd::Pager: Pager state to update.
• first_action::Union{Nothing, Symbol}: First action in the candidate navigation burst.

Keywords

• max_actions::Int: Maximum number of actions to coalesce. (Default: 128)
• max_ns::UInt64: Maximum elapsed nanoseconds spent coalescing. (Default: UInt64(4_000_000))
• display_size_function::Any: Callable object used to detect display-size changes. (Default: displaysize)

Returns

• Int: Number of actions processed, including first_action.

_content_fit_rows(lines::AbstractVector{<:AbstractString}) -> Int

Return the number of terminal rows required to print lines.

Text ending in a newline yields one trailing empty line after splitting, which does not occupy a terminal row when printed. Counting it opened the pager one row too early in automatic mode.

Arguments

• lines::AbstractVector{<:AbstractString}: Lines to measure.

_create_pager_help_repl_mode(
    repl::REPL.AbstractREPL,
    main::LineEdit.Prompt,
    tp_mode::LineEdit.Prompt
) -> LineEdit.Prompt

Create the pager-help REPL mode.

Arguments

• repl::REPL.AbstractREPL: Active REPL that owns the new mode.
• main::LineEdit.Prompt: Main Julia prompt used for history and keymaps.
• tp_mode::LineEdit.Prompt: Pager prompt to which help mode returns.

_create_pager_repl_mode(
    repl::REPL.AbstractREPL,
    main::LineEdit.Prompt
) -> LineEdit.Prompt

Create the pager REPL mode for the active repl and its main prompt.

Arguments

• repl::REPL.AbstractREPL: Active REPL that owns the new mode.
• main::LineEdit.Prompt: Main Julia prompt used for history and keymaps.

_cursor_character_position(s::Any) -> Int

Return the cursor position of a REPL line-edit state as a character index.

IOBuffer.ptr is a one-based byte pointer, whereas _extract_identifier expects a character position. Passing the byte pointer directly made F1 and ALT-h show the help of the wrong token whenever the input contained non-ASCII characters.

Arguments

• s::Any: Current REPL line-edit state.

_decode_escape(prefix::Vector{UInt8}) -> Tuple{Symbol, Keystroke, Int}

Decode an escape-sequence prefix without performing IO.

Arguments

• prefix::Vector{UInt8}: Buffered bytes beginning with an escape byte.

_decode_keystroke(prefix::Vector{UInt8}) -> Tuple{Symbol, Keystroke, Int}

Decode one package-owned byte prefix without reading from an input stream. The status is :complete or :incomplete; the integer is the number of bytes consumed by one key. An incomplete result carries the sentinel _INCOMPLETE_KEYSTROKE and zero consumed bytes.

Arguments

• prefix::Vector{UInt8}: Buffered bytes beginning with the next keystroke.

_decode_scalar(prefix::Vector{UInt8}, offset::Int) -> Tuple{Symbol, Keystroke, Int}

Decode one ASCII/control or UTF-8 scalar beginning at offset.

Arguments

• prefix::Vector{UInt8}: Buffered bytes containing the scalar.
• offset::Int: One-based byte index where decoding starts.

_descend(node::SyntaxNode, search_index::Integer) -> SyntaxNode

Descend to the most specific syntax node containing search_index.

Arguments

• node::SyntaxNode: Root syntax node to search.
• search_index::Integer: Byte index that the result must contain.

_display_config(get_preference::F = _get_preference) -> DisplayConfig where
    {F <: Function}

Capture the display string preferences for a new pager session.

Arguments

• get_preference::F: Callable preference getter used to capture each display value. (Default: _get_preference)

_eval_helpmode(io::IO, f::AbstractString, mod::Module) -> Any

Run REPL.helpmode for f and evaluate its result in mod.

Arguments

• io::IO: Output context passed to REPL.helpmode.
• f::AbstractString: Help query to evaluate.
• mod::Module: Module in which to evaluate the generated expression.

_extract_identifier(input::AbstractString, cursor_pos::Integer) -> String

Extract identifier from the input line using the cursor position.

If the cursor is on an identifier (including module hierarchy like A.B.C) or on the character behind it, return that identifier. If the cursor is not on an identifier, but in the argument/parameter list of a valid callable, return the callable name.

Extraction works even for invalid (i.e. incomplete) input.

Arguments

• input::AbstractString: REPL input text to inspect.
• cursor_pos::Integer: Character cursor position in input.

_find_matches!(pagerd::Pager, regex::Regex) -> Nothing

Find every match of regex and store the search metadata in pagerd.

Arguments

• pagerd::Pager: Pager state to update.
• regex::Regex: Regular expression to search for.

_flush_screen!(pagerd::Pager) -> Nothing

Send everything assembled in the reusable screen buffer to the terminal in a single write.

Writing each piece separately would issue one system call per piece, which can cause tearing.

Arguments

• pagerd::Pager: Pager state to flush.

_frame_bytes(io::IOBuffer) -> Tuple{Any, Int}

Return the storage backing the bytes written to io and how many of them are valid.

The storage is a Vector{UInt8} up to Julia 1.11 and a Memory{UInt8} afterwards. In both cases, pointer(storage, i) is valid, which is all the redraw path needs. Notice that we must not use take! here, because it hands over the storage and forces io to allocate a new one for the next frame.

Arguments

• io::IOBuffer: Buffer holding a rendered frame.

_get_help(f::AbstractString, mod::Module = Base.active_module()) -> String

Render help for f in mod, falling back to Main when the binding is not found.

Arguments

• f::AbstractString: Help query to render.
• mod::Module: Module in which to evaluate the help query first. (Default: Base.active_module())

_get_pager_display_size(p::Pager) -> Tuple{Int, Int}

Return the available pager rows and columns after reserving the command line.

Arguments

• p::Pager: Pager state whose display size is queried.

_get_preference(pref::String) -> Union{Bool, String}

Return the configured value for pref, or its built-in default when it is not set.

Arguments

• pref::String: Name of a supported preference.

_getkb(action::Symbol) -> String

Return a comma-separated description of every keybinding assigned to action.

Arguments

• action::Symbol: Pager action whose keybindings are described.

_help!(pagerd::Pager) -> Nothing

Open a new pager with the help.

Arguments

• pagerd::Pager: Parent pager state whose terminal and input are reused.

_help_render_io(buf::IOBuffer) -> IOContext

Wrap buf with the stream properties used to evaluate and render help.

Arguments

• buf::IOBuffer: Buffer that receives the help output.

_help_screen(use_color::Bool) -> Tuple{String, TextViewLayout}

Return the help text and its prepared layout, rebuilding them only when the keybindings change.

Arguments

• use_color::Bool: Decorate the help screen with ANSI escape sequences.

_help_string(use_color::Bool) -> String

Assemble the pager help screen from the current key bindings.

Arguments

• use_color::Bool: Decorate the help screen with ANSI escape sequences.

_helpmode_attempt(f::AbstractString, mod::Module) -> Tuple{String, Any}

Run REPL.helpmode for f in mod and return the printed preamble and the response.

REPL.helpmode writes a preamble, such as the search suggestions, to the passed stream as a side effect. Every attempt uses its own buffer here. Rendering all the attempts into one shared buffer duplicated the preamble whenever the help fell back to Main.

Arguments

• f::AbstractString: Help query to evaluate.
• mod::Module: Module in which to evaluate the help query.

_helpstring(x::SyntaxNode) -> String

Extract the string from syntax node x to be provided for @help.

Arguments

• x::SyntaxNode: Syntax node to convert to a help query.

_hide_cursor(io::IO) -> Int

Hide the cursor in io.

Arguments

• io::IO: Terminal output stream to update.

_init_pager_repl_mode(repl::AbstractREPL) -> Nothing

Initialize pager and pager-help modes in repl.

Arguments

• repl::AbstractREPL: REPL whose interface receives the pager modes.

_invalidate_frame!(pagerd::Pager) -> Nothing

Discard the frame snapshot, forcing the next redraw to repaint every row.

This must be called whenever something other than _redraw! writes to the rows above the command line.

Arguments

• pagerd::Pager: Pager state to update.

_invalidate_preference_cache!() -> Nothing

Drop every cached preference value.

_is_not_found_response(response::Any) -> Bool

Return whether response is the missing-documentation result produced by REPL.helpmode.

Arguments

• response::Any: Help-mode response to inspect.

_is_printable_keystroke(k::Keystroke) -> Bool

Return whether k represents a single printable character that can be typed into a command.

Arguments

• k::Keystroke: Keystroke to inspect.

_jlgetch(stream::IO) -> Keystroke

Compatibility wrapper that waits for one keystroke from stream.

Arguments

• stream::IO: Input stream from which to read the keystroke.

_kbtostr(kb::Tuple{String, Bool, Bool, Bool}) -> String

Convert a keybinding tuple to a human-readable description.

Arguments

• kb::Tuple{String, Bool, Bool, Bool}: Key value and ALT, CTRL, and SHIFT flags.

_keybindings_changed!() -> Nothing

Mark everything derived from _KEYBINDINGS as outdated.

_move_cursor(io::IO, i::Int, j::Int) -> Int

Move the cursor in io to row i and column j.

Arguments

• io::IO: Terminal output stream to update.
• i::Int: One-based destination row.
• j::Int: One-based destination column.

_move_view_to_match!(pagerd::Pager) -> Nothing

Move the viewport so that the active search match is visible.

Arguments

• pagerd::Pager: Pager state to update.

_navigation_axis(action::Union{Nothing, Symbol}) -> Union{Nothing, Symbol}

Return the navigation axis for a pure movement action.

Arguments

• action::Union{Nothing, Symbol}: Resolved pager action.

_navigation_group(action::Union{Nothing, Symbol}) -> Union{Nothing, Symbol}

Return the monotonic axis-and-direction group for a pure movement action.

Arguments

• action::Union{Nothing, Symbol}: Resolved pager action.

_ordered_search_matches(search_matches::SearchMatches, num_lines::Int) ->
    Vector{SearchMatch}

Build search-navigation metadata in document and within-line order.

Arguments

• search_matches::SearchMatches: Search matches grouped by source line.
• num_lines::Int: Number of source lines to traverse.

_pack_keycode(bytes, len::Int) -> UInt64

Pack the first len bytes of bytes and len itself into a single integer.

Arguments

• bytes: Byte storage holding an escape sequence.
• len::Int: Number of leading bytes to pack, at most _MAX_KEYCODE_BYTES.

_pager!(term::REPL.Terminals.TTYTerminal, str::String; kwargs...) -> Nothing

Run the interactive pager for str using a terminal that is already in raw mode.

Arguments

• term::REPL.Terminals.TTYTerminal: Terminal used by the pager session.
• str::String: Text to display.

Keywords

• auto::Bool: Print fitting text without opening the interactive pager. (Default: false)
• change_freeze::Bool: Enable commands that change frozen rows and columns. (Default: true)
• display_config::Union{Nothing, DisplayConfig}: Prepared session display configuration, or nothing to load one. (Default: nothing)
• frozen_columns::Int: Number of leading columns to freeze. (Default: 0)
• frozen_rows::Int: Number of leading rows to freeze. (Default: 0)
• title_rows::Int: Number of leading title rows. (Default: 0)
• hashelp::Bool: Enable pager help. (Default: true)
• has_visual_mode::Bool: Enable visual selection mode. (Default: true)
• show_ruler::Bool: Show the line-number ruler initially. (Default: false)
• use_alternate_screen_buffer::Bool: Request the terminal's alternate screen buffer. (Default: false)
• input::Union{Nothing, PagerInput}: Input state associated with the terminal input stream, or nothing to create one. (Default: nothing)
• lines::Union{Nothing, AbstractVector{<:AbstractString}}: Raw lines used when no layout is supplied. (Default: nothing)
• text_layout::Union{Nothing, TextViewLayout}: Prepared layout used directly when supplied, or nothing to construct one. (Default: nothing)
• _layout_factory::Any: Callable object that creates a layout from raw lines. (Default: TextViewLayout)
• manage_cursor_key_mode::Bool: Enable and restore terminal cursor-key mode. (Default: true)

_pager(str::String; kwargs...) -> Nothing

Open an interactive pager for str, or print it directly when automatic mode fits.

Arguments

• str::String: Text to display.

Keywords

• auto::Bool: Print fitting text without creating a layout or terminal session. (Default: false)
• _display_config_loader::Any: Callable object that creates the session display configuration. (Default: _display_config)
• _input_factory::Any: Callable object that creates input state for a stream. (Default: PagerInput)
• _layout_factory::Any: Callable object that creates a prepared text layout. (Default: TextViewLayout)
• _terminal_factory::Any: Callable object that creates the terminal. By default, create a REPL.Terminals.TTYTerminal connected to the standard streams. (Default: () -> REPL.Terminals.TTYTerminal("", stdin, stdout, stderr))
• _raw_runner::Any: Callable object that runs the pager callback in raw mode. (Default: _with_raw_mode)
• kwargs...: Additional keywords forwarded to _pager!.

_pager_action(k::Keystroke) -> Union{Nothing, Symbol}

Resolve the configured pager action for keystroke k.

Arguments

• k::Keystroke: Keystroke to resolve.

_pager_content_fits(
    lines::AbstractVector{<:AbstractString},
    display_size::Tuple{Int, Int}
) -> Bool

Return whether lines fit without opening a pager, reserving two terminal rows.

Arguments

• lines::AbstractVector{<:AbstractString}: Lines to measure.
• display_size::Tuple{Int, Int}: Available terminal rows and columns.

_pager_event_process!(pagerd::Pager) -> Bool

Process the pending pager event and return whether the application should continue.

Arguments

• pagerd::Pager: Pager state whose pending event is processed.

_pager_key_process!(pagerd::Pager, k::Keystroke) -> Union{Nothing, Symbol}

Process k, update pager state, and return the resolved action.

Arguments

• pagerd::Pager: Pager state to update.
• k::Keystroke: Keystroke to process.

_pkg_version() -> VersionNumber

Return the version of this package.

Notice that this must not be stored in a constant. pkgversion evaluated while the package is precompiled captures the version that was current at that moment, so the help screen kept showing a stale one after a new version was released.

_print_cmd_message!(pagerd::Pager, msg::String;
    crayon::Crayon = Crayon()) -> Nothing

Print msg on the pager command line.

Arguments

• pagerd::Pager: Pager state whose terminal receives the message.
• msg::String: Message to print.

Keywords

• crayon::Crayon: Formatting applied when the terminal supports color. (Default: Crayon())

_push_line_matches!(ordered_matches::Vector{SearchMatch}, line::Int,
    matches::Vector{Tuple{Int, Int}}) -> Nothing

Append every match of one source line, in within-line order.

Arguments

• ordered_matches::Vector{SearchMatch}: Vector to append to.
• line::Int: One-based source line index.
• matches::Vector{Tuple{Int, Int}}: Column and width of each match in the line.

_quit_search!(pagerd::Pager) -> Nothing

Clear all search state in pagerd.

Arguments

• pagerd::Pager: Pager state to clear.

_raw_bytes(bytes::Vector{UInt8}) -> String

Format bytes using the legacy raw-keystroke representation.

Arguments

• bytes::Vector{UInt8}: Bytes to format.

_read_cmd!(pagerd::Pager; prefix::String = "/") -> String

Read and edit one command from the pager input.

Arguments

• pagerd::Pager: Pager state whose terminal and input are used.

Keywords

• prefix::String: Prompt displayed before the command. (Default: "/")

_read_keystroke!(input::PagerInput) -> Keystroke

Read one keystroke, blocking one byte at a time and honoring pending boundary input.

Arguments

• input::PagerInput: Input state to consume.

_redraw!(pagerd::Pager) -> Nothing

Write the rows of the prepared view buffer that changed to the terminal.

Arguments

• pagerd::Pager: Pager state to redraw.

_redraw_cmd_line!(pagerd::Pager) -> Nothing

Redraw the pager command line and status information.

Arguments

• pagerd::Pager: Pager state to redraw.

_register_help_shortcuts(repl::Any) -> Task

Register the <Alt> + h and <F1> shortcuts in the REPL to show extended help for the identifier under the cursor.

Arguments

• repl::Any: REPL instance whose keymaps are updated asynchronously.

_register_shortcuts(f::Any, repl::Any) -> Task

Register escape shortcuts in the REPL by calling f(escapes) to register them.

Arguments

• f::Any: Callable object that adds entries to an escape keymap.
• repl::Any: REPL instance whose keymaps are updated asynchronously.

_render_view(pagerd::Pager, rows::Int, cols::Int,
    active_match_location::NTuple{2, Int}, visual_lines::Union{Nothing, Vector{Int}},
    visual_line_backgrounds::Union{String, Vector{String}}) -> Tuple{Int, Int}

Render the viewport of pagerd into its view buffer and return the crop counters.

Arguments

• pagerd::Pager: Pager state to render.
• rows::Int: Number of available view rows.
• cols::Int: Number of available view columns.
• active_match_location::NTuple{2, Int}: Line and in-line index of the active match.
• visual_lines::Union{Nothing, Vector{Int}}: Lines rendered with a visual background.
• visual_line_backgrounds::Union{String, Vector{String}}: Background of each entry of visual_lines.

_request_redraw!(p::Pager) -> Bool

Mark p for redraw and return the assigned value, true.

Arguments

• p::Pager: Pager state to mark for redraw.

_ruler_width(num_lines::Int) -> Int

Return the number of columns the line-number ruler occupies for num_lines lines.

Arguments

• num_lines::Int: Number of lines in the pager text.

_scan_frame_rows!(frame_cache::FrameCache, data, num_bytes::Int, max_rows::Int) -> Int

Fill the scratch row table of frame_cache from the newline positions in data.

Return the number of rows found, which is at most max_rows.

Arguments

• frame_cache::FrameCache: Cache whose scratch row table is filled.
• data: Byte storage holding the rendered frame.
• num_bytes::Int: Number of valid bytes in data.
• max_rows::Int: Maximum number of rows the screen can show.

_screen_buffer!(pagerd::Pager) -> IOBuffer

Return the reusable buffer that assembles everything sent to the terminal, after resetting it.

Arguments

• pagerd::Pager: Pager state whose buffer is returned.

_show_cursor(io::IO) -> Int

Show the cursor in io.

Arguments

• io::IO: Terminal output stream to update.

_show_extended_help(identifier::AbstractString, mod::Module) -> Nothing

Route an identifier to extended help in mod.

Arguments

• identifier::AbstractString: Identifier whose extended help is displayed.
• mod::Module: Module in which to evaluate the help query.

_show_help(f::AbstractString, mod::Module = Base.active_module()) -> Nothing

Show help for f in a pager, reporting errors in the same way as the public @help macro.

Arguments

• f::AbstractString: Help query to display.
• mod::Module: Module in which to evaluate the help query first. (Default: Base.active_module())

_show_pager_cursor(f::Any, s::Any) -> Symbol

Show information about the identifier under the cursor in the REPL by calling f.

Arguments

• f::Any: Callable object invoked with the identifier under the cursor.
• s::Any: Current REPL line-edit state.

_show_pager_help(s::Any, _key::Any, _context::Any) -> Symbol

Show the extended inline help for the identifier under the cursor in the REPL.

Arguments

• s::Any: Current REPL line-edit state.
• _key::Any: Keybinding callback key, which is ignored.
• _context::Any: Keybinding callback context, which is ignored.

_store_frame!(frame_cache::FrameCache, data, num_bytes::Int, num_rows::Int) -> Nothing

Record the frame in data as what is currently on screen.

Arguments

• frame_cache::FrameCache: Cache to update.
• data: Byte storage holding the rendered frame.
• num_bytes::Int: Number of valid bytes in data.
• num_rows::Int: Number of rows that were painted.

_take_decoded!(input::PagerInput, key::Keystroke, consumed::Int) -> Keystroke

Clear the consumed prefix and return key.

Arguments

• input::PagerInput: Input state whose prefix is updated.
• key::Keystroke: Decoded keystroke to return.
• consumed::Int: Number of leading prefix bytes to remove.

_tp_help_mode_do_cmd(repl::REPL.AbstractREPL, input::String) -> Nothing

Display help for input from pager-help REPL mode.

Arguments

• repl::REPL.AbstractREPL: Active REPL used to report errors.
• input::String: Help query to display.

_tp_help_mode_prompt() -> String

Return the pager-help-mode prompt.

_tp_mode_do_cmd(repl::REPL.AbstractREPL, input::String) -> Nothing

Execute input in pager REPL mode and display its standard output.

Arguments

• repl::REPL.AbstractREPL: Active REPL used to evaluate the command.
• input::String: Command text to evaluate.

_tp_mode_prompt() -> String

Return the pager-mode prompt.

_try_append_available!(input::PagerInput) -> Bool

Append exactly one advertised byte without blocking. Unsupported lookahead is disabled.

Arguments

• input::PagerInput: Input state to update.

_try_read_keystroke!(input::PagerInput) -> Union{Nothing, Keystroke}

Read one already-buffered keystroke without blocking, retaining incomplete prefixes.

Arguments

• input::PagerInput: Input state to inspect and consume.

_try_regex(str::AbstractString) -> Union{Nothing, Regex}

Compile str into a regular expression, returning nothing if it is not valid.

Arguments

• str::AbstractString: Pattern typed by the user.

_tryparsestmt(x::String) -> SyntaxNode

Try to parse x into a SyntaxNode. If there are errors or warnings, they are ignored.

Arguments

• x::String: Julia source text to parse.

_turn_off_alternate_screen_buffer(io::IO) -> Int

Disable the alternate screen buffer in io and restore the previous buffer.

Arguments

• io::IO: Terminal output stream to update.

_turn_off_cursor_key_mode(io::IO) -> Int

Disable cursor-key mode in io.

Arguments

• io::IO: Terminal output stream to update.

_turn_on_alternate_screen_buffer(io::IO) -> Int

Enable and clear the alternate screen buffer in io.

Arguments

• io::IO: Terminal output stream to update.

_turn_on_cursor_key_mode(io::IO) -> Int

Enable cursor-key mode in io.

Arguments

• io::IO: Terminal output stream to update.

_update_crop_after_action!(
    pagerd::Pager,
    old_row::Int,
    old_column::Int,
    action::Union{Nothing, Symbol}
) -> Nothing

Update crop metrics by the signed viewport delta after one navigation action.

Arguments

• pagerd::Pager: Pager state to update.
• old_row::Int: Viewport row before the action.
• old_column::Int: Viewport column before the action.
• action::Union{Nothing, Symbol}: Resolved pager action.

_update_display_size!(p::Pager) -> Nothing

Update the recorded display size and request a redraw when the terminal size changes.

Arguments

• p::Pager: Pager state to update.

_valid_utf8(bytes::Vector{UInt8}) -> Bool

Return whether bytes is one valid two- to four-byte UTF-8 scalar.

Arguments

• bytes::Vector{UInt8}: Candidate encoded scalar.

_validate_preference(pref::String, value::Any) -> Union{Bool, String}

Validate a known preference against the type of its built-in default.

Arguments

• pref::String: Name of a supported preference.
• value::Any: Candidate preference value.

_view!(pagerd::Pager) -> Nothing

Render the current pager viewport into its view buffer.

Arguments

• pagerd::Pager: Pager state to render and update.

_warn_repl_mode_noninteractive!(interactive::Bool = isinteractive()) -> Nothing

Warn once per session that the pager REPL mode is not meant for non-interactive use.

Arguments

• interactive::Bool: Whether the current session is interactive. (Default: isinteractive())

_with_raw_mode(f::Any, term::Any; raw_function::Any = REPL.Terminals.raw!) -> Any

Enable raw mode on term while executing f and restore it after normal return or an exception.

Arguments

• f::Any: Callable object to execute in raw mode.
• term::Any: Object passed to raw_function as the terminal.

Keywords

• raw_function::Any: Callable object used to enable and disable raw mode. (Default: REPL.Terminals.raw!)

Returns

• Any: Result returned by f.

_with_raw_restoration(f::Any, terminal::Any;
    raw_function::Any = REPL.Terminals.raw!) -> Any

Call f and restore terminal to raw mode even if the callback throws.

Arguments

• f::Any: Callable object to invoke while raw-mode restoration is guarded.
• terminal::Any: REPL terminal object passed to raw_function.

Keywords

• raw_function::Any: Callable object used to restore raw mode. (Default: REPL.Terminals.raw!)

Returns

• Any: Result returned by f.

_write_all(io::IO, data, num_bytes::Int) -> Nothing

Write the first num_bytes bytes of data to io.

Notice that this function returns nothing. TTYTerminal declares its streams as IO, so a write to them is a dynamic dispatch whose Int return value would have to be boxed.

Arguments

• io::IO: Output stream to update.
• data: Byte storage to write from.
• num_bytes::Int: Number of bytes to write.

_write_blanks(io::IO, n::Int) -> Int

Write n spaces to io without allocating.

Arguments

• io::IO: Output stream to update.
• n::Int: Number of spaces to write.

_write_decimal(io::IO, n::Int) -> Int

Write the decimal representation of n to io without allocating for common values.

Arguments

• io::IO: Terminal output stream to update.
• n::Int: Number to write.

debug_keycode() -> Nothing

Read and print decoded keystrokes in raw terminal mode until the user presses q.

delete_keybinding(key::String; alt::Bool = false, ctrl::Bool = false,
    shift::Bool = false) -> Nothing

Delete the keybinding key. The modifier keys can be selected using the keywords alt, ctrl, and shift.

For more information about how to specify key, see set_keybinding.

Arguments

• key::String: Key value whose binding is deleted.

Keywords

• alt::Bool: Select a binding that requires ALT. (Default: false)
• ctrl::Bool: Select a binding that requires CTRL. (Default: false)
• shift::Bool: Select a binding that requires SHIFT. (Default: false)

drop_all_preferences!() -> Nothing

Drop all preferences.

Examples

julia> TerminalPager.drop_all_preferences!()

drop_preference!(pref::String) -> Nothing

Drop the preference pref.

Arguments

• pref::String: Name of a supported preference.

Examples

julia> TerminalPager.drop_preference!("visual_mode_line_background")

pager(obj::AbstractString; kwargs...) -> Nothing

Show the text in obj using the terminal pager.

Arguments

• obj::AbstractString: Text to display without applying plain-text object rendering.

Keywords

• kwargs...: Pager options documented by pager(::Any; kwargs...).

pager(obj::Any; kwargs...) -> Nothing

Call the pager to show the output of the object obj.

Arguments

• obj::Any: Object to render and display.

Keywords

• auto::Bool: Show the pager only when the output does not fit in the display. (Default: false)
• change_freeze::Bool: If true, then the user can change the number of frozen rows and columns inside the pager. (Default: true)
• frozen_columns::Int: Number of columns to freeze at startup. (Default: 0)
• frozen_rows::Int: Number of rows to freeze at startup. (Default: 0)
• title_rows::Int: Number of frozen rows treated as horizontally fixed titles. (Default: 0)
• hashelp::Bool: Allow the user to open pager help. (Default: true)
• has_visual_mode::Bool: Allow the user to use visual mode. (Default: true)
• show_ruler::Bool: If true, a vertical ruler is shown in the pager with the line numbers. (Default: false)
• use_alternate_screen_buffer::Bool: If true, the pager will use the alternate screen buffer, which keeps the current screen when exiting the pager. Notice, however, that we use the XTerm escape sequences here. Hence, if your terminal is different, this option can lead to rendering problems. (Default: false)

Preferences

The user can define custom preferences using the function TerminalPager.set_preference!. The available preferences are listed as follows:

• "active_search_decoration": String with the ANSI escape sequence to decorate the active search element. One can easily obtain this sequence by converting a Crayon to string. (Default: string(crayon"black bg:yellow"))
• "inactive_search_decoration": String with the ANSI escape sequence to decorate the inactive search element. One can easily obtain this sequence by converting a Crayon to string. (Default: string(crayon"black bg:light_gray"))
• "always_use_alternate_screen_buffer_in_repl_mode": If true, we will always use the alternate screen buffer when showing the pager in REPL mode. (Default: false)
• "block_alternate_screen_buffer": If true, the alternate screen buffer support will be globally blocked, regardless of the keyword options. This modification is helpful when the terminal is not compatible with XTerm. (Default: false)
• "copy_stdout_to_clipboard_in_repl_mode": If true, the output shown in the pager in REPL mode is also copied to the system clipboard, without any decoration. (Default: false)
• "pager_mode": If it is "vi", some keybindings are modified to match the behavior of Vi. Notice that this change only takes effect when a new Julia session is initialized. (Default: "default")
• "visual_mode_line_background": String with the ANSI code of the background for the selected lines in the visual mode. (Default: "100")
• "visual_mode_active_line_background": String with the ANSI code of the background for the active line in the visual mode. (Default: "44")

For more information, see: TerminalPager.set_preference!, TerminalPager.drop_preference!, and TerminalPager.drop_all_preferences!.

reset_keybindings() -> Nothing

Reset the key bindings to the original ones.

set_keybinding(key::String, action::Symbol; alt::Bool = false,
    ctrl::Bool = false, shift::Bool = false) -> Nothing

Set key binding key to the action action. The modifier keys can be selected using the keywords alt, ctrl, and shift.

key can contain a character or one of the following special key names:

"<up>", "<down>", "<right>", "<left>", "<home>", "<end>", "<F1>", "<F2>",
"<F3>", "<F4>", "<F5>", "<F6>", "<F7>", "<F8>", "<F9>", "<F10>", "<F11>",
"<F12>", "<keypad_dot>", "<keypad_enter>", "<keypad_asterisk>",
"<keypad_plus>", "<keypad_minus>", "<keypad_slash>", "<keypad_equal>",
"<keypad_0>", "<keypad_1>", "<keypad_2>", "<keypad_3>", "<keypad_4>",
"<keypad_5>", "<keypad_6>", "<keypad_7>", "<keypad_8>", "<keypad_9>",
"<delete>", "<pageup>", "<pagedown>", "<tab>", "<enter>", "<esc>",
"<backspace>", "<eot>", "<shiftin>"

"<eot>" is CTRL-D and "<shiftin>" is CTRL-U. Every other CTRL combination with a letter must be selected with the keyword ctrl instead, for example set_keybinding("a", :quit; ctrl = true).

action can be one of the following symbols:

:quit, :quit_eot, :help, :up, :down, :left, :right, :fastup, :fastdown,
:fastleft, :fastright, :bol, :eol, :pageup, :pagedown, :halfpageup,
:halfpagedown, :home, :end, :search, :next_match, :previous_match,
:quit_search, :change_freeze, :change_title_rows, :toggle_ruler,
:toggle_visual_mode, :select_visual_mode_line, :yank

Arguments

• key::String: Key value whose binding is set.
• action::Symbol: Pager action assigned to the key.

Keywords

• alt::Bool: Require ALT for the binding. (Default: false)
• ctrl::Bool: Require CTRL for the binding. (Default: false)
• shift::Bool: Require SHIFT for the binding. (Default: false)

set_preference!(pref::String, value::Any) -> Nothing

Set the preference pref to the value.

Arguments

• pref::String: Name of a supported preference.
• value::Any: Value whose type must match the built-in default.

Examples

julia> TerminalPager.set_preference!("visual_mode_line_background", "44")

@help(f)

Open the documentation of the function, macro, or other object f in the pager.

Arguments

• f: Expression that identifies the documented binding.

Examples

julia> @help write

@out2pr(ex)

Capture the standard output generated by ex and show it in a pager.

Arguments

• ex: Expression whose standard output is captured.

@stdout_to_pager(ex_in, pager_args...)

Capture the stdout generated by ex_in and show inside a pager.

pager_args are the keyword arguments of the pager function.

Arguments

• ex_in: Expression whose standard output is captured.
• pager_args...: Pager keyword assignments forwarded to pager.

See also pager.