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.

struct ActionHelp

Describe one pager action in the help screen.

Fields

• action::Symbol: Pager action.
• description::String: Short description of the action.
• feature::Union{Nothing, Symbol}: Feature required by the action, or nothing.

ActionHelp(action::Symbol, description::String) -> ActionHelp

Describe the pager action with description when it does not require a feature.

Arguments

• action::Symbol: Pager action.
• description::String: Short description of the action.

DisplayConfig

Store the pager faces rendered into escape sequences for one pager session.

Every field holds a complete SGR sequence that resets the attributes and then selects the ones of the face, except the visual line backgrounds, which hold only the SGR parameters of the background, as textview expects.

Fields

• status_bar::String: Base of the status line.
• status_hint::String: Key hints, feature tags, and hidden text hints of the status line.
• mode_search::String: Name of the search mode on the status line.
• mode_visual::String: Name of the visual mode on the status line.
• message_info::String: Informative message on the status line.
• message_error::String: Error message on the status line.
• search_match::String: Inactive search match.
• search_active_match::String: Active search match.
• visual_line::String: Background of the lines marked in the visual mode.
• visual_active_line::String: Background of the visual line.
• ruler::String: Line number ruler.
• scrollbar_track::String: Track of the scrollbar.
• scrollbar_thumb::String: Thumb of the scrollbar.
• command_status::String: Status shown at the right of the command line.
• help_title::String: Title of the help screen.
• help_section::String: Section titles of the help screen.
• help_description::String: Section descriptions and feature tags of the help screen.
• help_key::String: Keys of the help screen.
• help_action::String: Action names of the help screen.

DisplayConfig() -> DisplayConfig

Construct a display configuration from the built-in default faces.

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.
• start_row::Int: First visible source row when the snapshot was painted.
• start_column::Int: First visible printable column when the snapshot was painted.
• frozen_rows::Int: Number of frozen rows when the snapshot was painted.

struct HelpSection

Group the actions of the help screen under a title.

Fields

• title::String: Section title.
• description::String: Introduction shown under the title, or an empty string.
• feature::Union{Nothing, Symbol}: Feature required by every action in the section, or nothing.
• actions::Vector{ActionHelp}: Actions documented in the section.

Keystroke

Represent one decoded keystroke.

Fields

• raw::String: Raw keystroke code converted to string, or an empty string for the mouse reports.
• 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.
• x::Int: One-based column of a mouse event, or 0 for a keyboard key.
• y::Int: One-based row of a mouse event, or 0 for a keyboard key.

Keystroke(raw::String, value::String, alt::Bool, ctrl::Bool, shift::Bool) -> Keystroke

Create a keyboard keystroke, that is, one without a mouse position.

Arguments

• 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.
• text_width::Int: Printable width of the widest source line, or a negative number if it was not computed yet. Read it with _text_width.
• 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.
• active_search_match_id::Int: Active match index in navigation order.
• redraw::Bool: Whether the viewport needs to be redrawn.
• message::String: Message shown on the command line until the next keystroke, or an empty string.
• message_kind::Symbol: Kind of message, :info or :error.
• 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.
• show_scrollbar::Bool: Whether to show the scrollbar at the right edge of the view.
• scroll_regions::Bool: Whether scrolling may shift the rows already on screen with the terminal scroll region sequences instead of repainting them.
• view_buf::IOBuffer: Reused buffer holding the rendered view before the scrollbar is added to it.
• 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.
• mouse_row::Int: Row of the last mouse event, or 0 if there was none.
• mouse_column::Int: Column of the last mouse event, or 0 if there was none.
• 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_event(action::Union{Nothing, Symbol}, features::Vector{Symbol}) ->
    Union{Nothing, Symbol}

Return the event raised by action, or nothing if it raises none or requires a feature that is not in features.

Arguments

• action::Union{Nothing, Symbol}: Resolved pager action.
• features::Vector{Symbol}: Features enabled for the session.

_action_keys(action::Symbol) -> Vector{String}

Return the human-readable names of the keys bound to action, which must not be modified.

Arguments

• action::Symbol: Pager action.

_action_keys() -> Dict{Symbol, Vector{String}}

Return the human-readable names of the keys bound to every action, keyed by action and sorted from the shortest name to the longest one.

The result is cached until the key bindings change and must not be modified.

_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.

_append_scrollbar!(out::IOBuffer, frame::IOBuffer, rows::Int, column::Int,
    thumb_first::Int, thumb_last::Int, use_color::Bool,
    display_config::DisplayConfig) -> Nothing

Copy the view in frame to out, appending the scrollbar at column to every one of the rows rows.

Rows missing from frame, when the text is shorter than the view, are emitted empty so that the scrollbar always spans the whole view.

Arguments

• out::IOBuffer: Buffer receiving the frame.
• frame::IOBuffer: Rendered view, one row per line.
• rows::Int: Number of rows of the view.
• column::Int: One-based column of the scrollbar.
• thumb_first::Int: First row of the thumb.
• thumb_last::Int: Last row of the thumb.
• use_color::Bool: Decorate the scrollbar with ANSI escape sequences.
• display_config::DisplayConfig: Session display configuration with the scrollbar faces.

_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)

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

Find the matches of regex in pagerd, activate the first one at or after the top of the view, move the view to it, and enter the searching mode.

Arguments

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

_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)

_change_freeze!(pagerd::Pager) -> Nothing

Prompt for the numbers of frozen rows and columns of pagerd, apply them, and request a redraw. An invalid or cancelled number of rows also skips the prompt for the columns.

Arguments

• pagerd::Pager: Pager state to update.

_check_preference_name(pref::String) -> Nothing

Throw an ArgumentError if pref is not a supported preference. The error of a preference replaced by a face names the face and set_face!.

Arguments

• pref::String: Name of the preference to check.

_clamp_viewport!(p::Pager) -> Nothing

Keep the viewport of p inside the text after the display size changed.

A view that ends past the last line or past the last column is pulled back so that the screen stays full, like less does. The first visible row and column never move into the frozen region.

Arguments

• p::Pager: Pager state to update.

_clear_message!(p::Pager) -> Nothing

Remove the command line message of p, if any, and request a redraw in that case.

Arguments

• p::Pager: Pager state to update.

_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.

_clear_status_row(io::IO) -> Nothing

Clear the last row of the display of io, where the status bar was.

Without the alternate screen buffer, the status bar would be left right above the next prompt. Clearing it ends the scrollback with the last page of the text instead.

Arguments

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

_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.

_color_spec(color::SimpleColor) -> String

Convert color into the string format of faces.toml: the name of a named color, or "#rrggbb" for a 24-bit color.

Arguments

• color::SimpleColor: Color to convert.

_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.

_current_face(name::Symbol) -> Face

Return the pager face name, without the prefix, as it is currently registered, merged with the faces it inherits from.

_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_mouse(prefix::Vector{UInt8}) -> Tuple{Symbol, Keystroke, Int}

Decode an SGR mouse report without performing IO. A report is \e[<b;x;yM for a press or a wheel movement and \e[<b;x;ym for a release, where b encodes the button and the modifiers and x and y are the one-based column and row.

The keystroke value is <wheel_up>, <wheel_down>, <wheel_left>, <wheel_right>, <mouse_press>, <mouse_press_middle>, <mouse_press_right>, <mouse_release>, or <mouse_drag>. A malformed report is returned as an undefined key.

Arguments

• prefix::Vector{UInt8}: Buffered bytes beginning with \e[<.

_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.

_default_face(name::Symbol) -> Face

Return the built-in default of the pager face name, without the prefix.

_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(face_of::F = _current_face) -> DisplayConfig where {F <: Function}

Render every pager face into the escape sequences used by a pager session.

The faces are converted by StringManipulation.jl, so that each sequence resets the terminal attributes and then selects the ones set in the face. The visual faces keep only the SGR parameters of their background, like "44", as textview expects for the visual line backgrounds.

Arguments

• face_of::F: Callable object returning the Face of a pager face name without the prefix. (Default: _current_face)

_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.

_face_name(name::AbstractString) -> Symbol

Return the name of the pager face name in the StyledStrings.jl registry, throwing an ArgumentError if name is not a pager face.

_face_preferences() -> Dict{String, Any}

Return a copy of the faces persisted with set_face!, keyed by the face name without the prefix.

_face_spec(face::Face) -> Dict{String, Any}

Convert face into the table format of faces.toml, which is how the faces are persisted with Preferences.jl. The attributes left unset in face are omitted.

Arguments

• face::Face: Face to convert.

_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.

_first_scrollable_row(p::Pager) -> Int

Return the first row of the text of p that scrolls, which is the one after the frozen rows.

Arguments

• p::Pager: Pager state to inspect.

_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 status bar row and the scrollbar column, if it is shown.

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.

_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, display_config::DisplayConfig) ->
    Tuple{String, TextViewLayout}

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

Arguments

• use_color::Bool: Decorate the help screen with ANSI escape sequences.
• display_config::DisplayConfig: Session display configuration with the help faces.

_help_string(use_color::Bool, display_config::DisplayConfig = DisplayConfig()) -> String

Assemble the pager help screen from _HELP_SECTIONS and the current key bindings.

The screen is a cheat sheet with one row per action: the keys, the description, and the action name to use with set_keybinding. Long key lists and descriptions continue on the following rows.

Arguments

• use_color::Bool: Decorate the help screen with ANSI escape sequences.
• display_config::DisplayConfig: Session display configuration with the help faces. (Default: DisplayConfig())

_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.

_init_pager_repl_mode_when_ready(repl::REPL.LineEditREPL) -> Task

Initialize the pager REPL mode in a task that waits for the interface of repl to be set up, which happens when the package is loaded from an atreplinit hook or before run_frontend.

Arguments

• repl::REPL.LineEditREPL: Active REPL that owns the new mode.

_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_face(name::AbstractString) -> Bool

Return whether name is the name of a pager face, without the prefix.

_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.

_is_terminal(io::IO) -> Bool

Return whether io is a terminal, looking through an IOContext.

Arguments

• io::IO: Stream 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.

_join_hints(entries::Tuple{Symbol, String}...) -> String

Join the key hints of entries, each one an action and its label, like n:next, using the shortest key bound to the action and skipping the unbound ones.

Arguments

• entries::Tuple{Symbol, String}...: Actions and their labels.

_keybindings_changed!() -> Nothing

Mark everything derived from _KEYBINDINGS as outdated.

_load_face_preferences!() -> Nothing

Apply the faces persisted with set_face! to the registered faces.

Entries that are not pager faces, or whose specification is not a table, are ignored with a warning instead of breaking the package initialization.

_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.

_movement(action::Union{Nothing, Symbol}, page_rows::Int, half_page_rows::Int) ->
    Tuple{Symbol, Int, Symbol}

Return the axis, the signed step, and the visual cursor policy of the movement action.

The axis is :vertical, :horizontal, or :none when action is not a movement. A step of typemax(Int) or -typemax(Int) moves as far as possible. The policy is :follow when the visual cursor moves by the step and the view scrolls only by the part of the step that crosses its edge, :pin when the view scrolls by the step and the cursor is pinned to the edge in the direction of the movement, or :keep when the view scrolls by the step and the cursor keeps its row. Notice that :follow steps are always finite.

Arguments

• action::Union{Nothing, Symbol}: Resolved pager action.
• page_rows::Int: Number of lines of a page.
• half_page_rows::Int: Number of lines of half a page.

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

Return the axis and the direction of the movement action, which is :vertical_forward, :vertical_backward, :horizontal_forward, or :horizontal_backward, or nothing if action is not a movement. Consecutive movements of the same group are coalesced.

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)
• show_scrollbar::Bool: Show the scrollbar initially. (Default: the value of the preference "show_scrollbar")
• use_alternate_screen_buffer::Bool: Request the terminal's alternate screen buffer. (Default: true)
• input::Union{Nothing, PagerInput}: Input state associated with the terminal input stream, or nothing to create one. (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)
• manage_cursor::Bool: Hide the cursor during the session, and show it and clear the status bar row when the session ends. A nested session must not do this. (Default: true)
• manage_mouse::Bool: Enable the mouse reporting during the session if the preference "mouse" is enabled, and disable it when the session ends. A nested session must not do this. (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 the viewport, the visual cursor, and the pending event of pagerd, 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.

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

Return a short human-readable name for the key binding kb, such as Alt-↑ or Ctrl-D.

Special keys without a dedicated short name, such as the function keys, are shown without their angle brackets.

Arguments

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

_preview_search!(pagerd::Pager, pattern::String, saved::NamedTuple) -> String

Show the matches of pattern while it is typed and return the status shown in the prompt.

The search always starts from the viewport recorded in saved, so that the preview does not drift while the pattern is edited. An empty or invalid pattern restores saved.

Arguments

• pagerd::Pager: Pager state to update.
• pattern::String: Pattern typed so far.
• saved::NamedTuple: State returned by _search_state before the prompt.

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

Return the shortest human-readable name among the keys bound to action, or nothing if the action is unbound.

Arguments

• action::Symbol: Pager action.

_prompt_number!(pagerd::Pager, label::String, current::Int) -> Tuple{Symbol, Int}
_prompt_number!(pagerd::Pager, prefix::String) -> Tuple{Symbol, Int}

Prompt for an integer on the command line of pagerd and return the status and the number typed by the user. The prompt shows label and the current value in brackets, or the raw prefix.

The status is :value when a number was typed, :empty when the prompt was left empty, :cancel when the prompt was cancelled, and :invalid when the input is not a number. In the last case, an error message is shown on the command line until the next keystroke. The number is 0 unless the status is :value.

Arguments

• pagerd::Pager: Pager state whose terminal and input are used.
• label::String: Description of the requested number, shown in the prompt.
• current::Int: Current value, shown in the prompt.
• prefix::String: Prompt displayed before the number.

_push_history!(history::Vector{String}, entry::String) -> Nothing

Append entry to history as its newest element, removing a previous copy of it and the oldest entries beyond _MAX_HISTORY. An empty entry is ignored.

Arguments

• history::Vector{String}: History to update.
• entry::String: Command to record.

_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; kwargs...) -> Union{Nothing, String}

Read and edit one command from the pager input, returning nothing if the user cancels it with ESC or CTRL-C.

The editor supports the cursor keys, Home, End, Backspace, Delete, CTRL-A and CTRL-E to jump to the beginning and to the end of the command, CTRL-W to delete the word before the cursor, CTRL-U to clear the command, and the up and down keys to recall the commands in history.

Arguments

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

Keywords

• prefix::String: Prompt displayed before the command. (Default: "/")
• history::Union{Nothing, Vector{String}}: Previous commands, from the oldest to the newest, or nothing to disable the recall. (Default: nothing)
• on_change::Any: Callable object invoked with the command whenever its text changes, or nothing. It must return a String, which is shown at the right of the prompt row when it fits, for example a live match count. (Default: nothing)

_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.

_record_viewport!(frame_cache::FrameCache, pagerd::Pager) -> Nothing

Record in frame_cache the viewport of pagerd that the snapshot describes.

Arguments

• frame_cache::FrameCache: Cache to update.
• pagerd::Pager: Pager state whose viewport is recorded.

_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_status_bar!(pagerd::Pager) -> Nothing

Redraw the status line of pagerd on the last row of the display.

The row is quiet: nothing is drawn with a background. It begins with the prompt ❯ in the normal mode, or with the colored name of the search or the visual mode, followed by the active match or the number of selected lines. The right side holds, from the left, the tags of the enabled features, the key hints of the current mode, the hints that the text continues beyond the left or the right edge of the view, which keep a slot of two columns so that the key hints do not move while the view scrolls horizontally, and the position, which is All when the whole text is visible, Top, Bot, or the percentage of the text above the bottom of the view. A pending message replaces the left side. When the display is too narrow, the key hints are dropped first, then the feature tags, the hidden text hints, and the mode details, so that the mode name and the position survive longest.

Arguments

• pagerd::Pager: Pager state to redraw.

_register_faces!() -> Nothing

Register the default pager faces with StyledStrings.jl, keeping any customization the user made in faces.toml.

The user faces are loaded lazily by StyledStrings.jl on Julia 1.11 and later. They are loaded here explicitly, so that the precedence is always the same: the built-in defaults, then faces.toml, and then the pager preferences.

_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_object(obj::Any) -> String

Render obj with show and MIME"text/plain" for the color support and display size of stdout, without any limit on the output size.

Arguments

• obj::Any: Object to render.

_render_view(pagerd::Pager, io::IO, 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 io and return the crop counters.

Arguments

• pagerd::Pager: Pager state to render.
• io::IO: Buffer receiving the rendered view.
• 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.

_restore_search_state!(pagerd::Pager, saved::NamedTuple) -> Nothing

Restore the search state and the viewport of pagerd recorded in saved.

Arguments

• pagerd::Pager: Pager state to update.
• saved::NamedTuple: State returned by _search_state.

_restore_step(
    f::F,
    io::IO,
    first_error::Union{Nothing, Exception}
) -> Union{Nothing, Exception} where {F}

Call f(io), one step of the terminal restoration, and return the first error of the restoration so far: first_error if it is not nothing, otherwise the error thrown by f, if any.

Arguments

• f::F: Step to perform.
• io::IO: Terminal output stream to restore.
• first_error::Union{Nothing, Exception}: First error of the previous steps.

_restore_terminal(io::IO; kwargs...) -> Nothing

Undo the changes a pager session made to the terminal io, performing every requested step even if a previous one throws. The first error is thrown again after the last step.

Arguments

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

Keywords

• mouse::Bool: Disable the mouse reporting.
• clear_status_row::Bool: Clear the last row of the display, where the status bar was.
• show_cursor::Bool: Show the cursor.
• alternate_screen::Bool: Leave the alternate screen buffer.
• cursor_key_mode::Bool: Disable the cursor key mode.

_restore_viewport!(pagerd::Pager, saved::NamedTuple) -> Nothing

Restore the viewport of pagerd recorded in saved.

Arguments

• pagerd::Pager: Pager state to update.
• saved::NamedTuple: State returned by _search_state.

_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.

_scroll_horizontal!(pagerd::Pager, step::Int) -> Nothing

Scroll the view of pagerd by step columns, positive rightwards, and request a redraw if the viewport changed.

The view never scrolls past the last cropped column nor before the first non-frozen column, and the number of cropped columns follows the viewport, so that the next movement of a burst sees the boundary without a redraw.

Arguments

• pagerd::Pager: Pager state to update.
• step::Int: Signed number of columns to move.

_scroll_vertical!(pagerd::Pager, step::Int, policy::Symbol) -> Nothing

Scroll the view of pagerd by step lines, positive downwards, and request a redraw if the viewport or the visual cursor changed.

The view never scrolls past the last cropped line nor above the first non-frozen line, and the number of cropped lines follows the viewport, so that the next movement of a burst sees the boundary without a redraw. In visual mode, policy selects how the cursor moves, as described in _movement.

Arguments

• pagerd::Pager: Pager state to update.
• step::Int: Signed number of lines to move.
• policy::Symbol: Visual cursor policy, :follow, :pin, or :keep.

_scrollbar_thumb(pagerd::Pager, rows::Int) -> Tuple{Int, Int}

Return the first and last rows of the scrollbar thumb of pagerd for a bar with rows rows.

The thumb covers the fraction of the scrollable lines that is visible, at a position that follows the first visible line. It always has at least one row.

Arguments

• pagerd::Pager: Pager state to inspect.
• rows::Int: Number of rows of the scrollbar.

_search!(pagerd::Pager) -> Nothing

Prompt for a search pattern and highlight its matches in pagerd.

While the pattern is typed, the matches in a text with up to _INCREMENTAL_SEARCH_MAX_LINES lines are previewed, and the prompt shows the active match. Cancelling the prompt, or leaving it empty, keeps the search state and the viewport from before it. An invalid pattern reports an error.

Arguments

• pagerd::Pager: Pager state to update.

_search_state(pagerd::Pager) -> NamedTuple

Return the search state and the viewport of pagerd, so that they can be restored.

Arguments

• pagerd::Pager: Pager state to record.

_set_message!(p::Pager, message::String; kind::Symbol = :info) -> Nothing

Show message on the command line of p until the next keystroke and request a redraw.

Unlike a modal message, the next keystroke is processed normally instead of being consumed to dismiss the message.

Arguments

• p::Pager: Pager state to update.
• message::String: Message to show.

Keywords

• kind::Symbol: Kind of the message, :info or :error, which selects its decoration. (Default: :info)

_set_mode_keymap!(
    mode::LineEdit.Prompt,
    main::LineEdit.Prompt,
    extra::Union{Nothing, Dict{Any, Any}} = nothing
) -> Nothing

Set the key map of the prompt mode to the one of the main Julia prompt, the prefix history search and the reverse search of the shared history, the extra key map if it is given, and the default key maps of REPL.jl.

Notice that the prefix history search must be created for mode itself. Otherwise, the search transitions to the wrong prompt.

Arguments

• mode::LineEdit.Prompt: Prompt whose key map is set.
• main::LineEdit.Prompt: Main Julia prompt, whose history is shared.
• extra::Union{Nothing, Dict{Any, Any}}: Key map inserted before the defaults. (Default: nothing)

_shift_frame!(out::IOBuffer, frame_cache::FrameCache, pagerd::Pager, max_rows::Int) ->
    Bool

Shift the scrollable rows of the terminal and of the snapshot in frame_cache by the vertical movement of the viewport of pagerd since the snapshot was painted, and return whether the shift was performed.

The shift is performed only for a pure vertical movement smaller than the scrollable region, that is, when the first visible column and the frozen rows are unchanged. The sequences asking the terminal to shift the rows are written to out. The rows the terminal blanks while shifting are recorded as empty in the snapshot, so that the comparison with the new frame repaints exactly the rows that entered the view.

Arguments

• out::IOBuffer: Buffer assembling everything sent to the terminal.
• frame_cache::FrameCache: Cache whose snapshot is shifted.
• pagerd::Pager: Pager state with the current viewport.
• max_rows::Int: Number of rows the screen can show.

_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; kwargs...) -> 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.

Keywords

• raw_function::Any: Callable object used to restore raw mode. (Default: REPL.Terminals.raw!)
• refresh_function::Any: Callable object used to repaint the prompt. (Default: LineEdit.refresh_line)

_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.

_status_hint(mode::Symbol, with_help::Bool) -> String

Return the key hints of the status line for mode, which is :normal, :search, or :visual, like ?:help q:quit or n:next N:prev Esc:clear.

The hints are rebuilt only when the key bindings change, so that the status line does not allocate at every frame.

Arguments

• mode::Symbol: Mode whose hints are returned.
• with_help::Bool: Include the hint of the help action in the normal mode.

_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.

_text_width(p::Pager) -> Int

Return the printable width of the widest line of p, computing and caching it on the first call.

Arguments

• p::Pager: Pager state to inspect.

_toggle_visual_line!(pagerd::Pager) -> Nothing

Mark the visual line of pagerd, or unmark it if it is already marked, and request a redraw. Nothing happens outside the visual mode.

Arguments

• pagerd::Pager: Pager state to update.

_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.

The expression is case-insensitive unless str has an uppercase letter, which is the smart case behavior of less and vim.

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_off_mouse(io::IO) -> Int

Disable the mouse reporting 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.

_turn_on_mouse(io::IO) -> Int

Enable the mouse reporting in io with the SGR encoding.

Arguments

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

_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.

_view_rows(p::Pager) -> Int

Return the number of rows of the display of p that show scrolling text, that is, without the status line and the frozen rows.

Arguments

• p::Pager: Pager state to inspect.

_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.

_wrap_keys(names::Vector{String}, width::Int) -> Vector{String}

Join the key names with commas into rows of at most width columns, breaking only between names. A name wider than width gets a row of its own.

Arguments

• names::Vector{String}: Key names to lay out.
• width::Int: Maximum width of a row.

_wrap_words(text::String, width::Int) -> Vector{String}

Wrap text greedily at the spaces into rows of at most width columns. A word wider than width gets a row of its own. An empty text yields no row.

Arguments

• text::String: Text to wrap.
• width::Int: Maximum width of a row.

_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.

_write_position(
    io::IO,
    num_lines::Int,
    at_top::Bool,
    at_bottom::Bool,
    percentage::Int
) -> Nothing

Write the position of the status line to io, which is always three columns wide: All if the whole text is visible, Top, Bot, or percentage right-aligned before %.

Arguments

• io::IO: Output stream to update.
• num_lines::Int: Number of lines of the text.
• at_top::Bool: Whether the view shows the first scrollable line.
• at_bottom::Bool: Whether the view shows the last line.
• percentage::Int: Percentage of the text above the bottom of the view.

_write_scrollbar_cell!(
    out::IOBuffer,
    column::Int,
    is_thumb::Bool,
    use_color::Bool,
    display_config::DisplayConfig,
) -> Nothing

Write one cell of the scrollbar at column of the current row of out.

Arguments

• out::IOBuffer: Buffer receiving the frame.
• column::Int: One-based column of the scrollbar.
• is_thumb::Bool: Whether the cell belongs to the thumb.
• use_color::Bool: Decorate the cell with ANSI escape sequences.
• display_config::DisplayConfig: Session display configuration with the scrollbar faces.

_write_status_line!(out::IOBuffer, pagerd::Pager, cols::Int, use_color::Bool) -> Nothing

Write the content of the status line of pagerd to out, which must already hold the cursor movement to the last row, the clear, and the base face. The content is cols columns wide, and the faces are written only if use_color is true.

Arguments

• out::IOBuffer: Buffer assembling everything sent to the terminal.
• pagerd::Pager: Pager state to draw.
• cols::Int: Number of columns of the display.
• use_color::Bool: Whether the terminal supports color.

_yank!(pagerd::Pager) -> Nothing

Copy the visual line and the marked lines of pagerd to the system clipboard, leaving a message telling how many lines were copied, or that the clipboard is not available. Nothing happens outside the visual mode.

Arguments

• pagerd::Pager: Pager state to update.

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, including the faces customized with set_face!, which are reset to their built-in defaults.

Examples

julia> TerminalPager.drop_all_preferences!()

drop_face!(name::AbstractString) -> Nothing

Drop the customization of the pager face name, restoring its built-in default.

The persisted preference is removed and the face is reset for the current session, which also discards any customization loaded from faces.toml until Julia is restarted.

All the faces can be restored at once with drop_all_preferences!, which also drops the other preferences of the package. To reset only the faces, remove the tables [TerminalPager.faces.<name>] from the LocalPreferences.toml of the active environment and restart Julia.

See also: set_face! and drop_all_preferences!.

Arguments

• name::AbstractString: Name of a pager face, without the prefix terminalpager_.

Examples

julia> TerminalPager.drop_face!("search_active_match")

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!("show_scrollbar")

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

Show the text in obj using the terminal pager.

If the standard input or output is not a terminal, for example in a script whose output is redirected or in a notebook, the text is printed instead.

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)
• show_scrollbar::Bool: If true, a scrollbar is shown at the right edge of the view. (Default: the value of the preference "show_scrollbar")
• use_alternate_screen_buffer::Bool: If true, the pager will use the alternate screen buffer, which restores the current screen when exiting the pager and lets the mouse wheel scroll the pager in most terminals. Notice, however, that we use the XTerm escape sequences here. Hence, if your terminal is different, this option can lead to rendering problems, in which case it can be disabled globally with the preference "block_alternate_screen_buffer". (Default: true)

Preferences

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

• "always_use_alternate_screen_buffer_in_repl_mode": Deprecated and ignored, because the alternate screen buffer is now used by default. Use "block_alternate_screen_buffer" to disable it. (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)
• "mouse": If true, the pager reports the mouse events: the wheel scrolls the text, SHIFT and the wheel scroll it horizontally, and clicking a line in the visual mode moves the visual line to it or marks it. Notice that, while the mouse is reported, selecting text with the terminal requires holding SHIFT, or OPTION on some terminals. (Default: true)
• "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")
• "show_scrollbar": If true, the pager shows a scrollbar at the right edge of the view unless the keyword show_scrollbar says otherwise. (Default: false)
• "use_scroll_regions": If true, scrolling asks the terminal to shift the rows it already shows and repaints only the new ones, which makes scrolling much cheaper on large windows and slow connections. Disable it if your terminal does not support the XTerm scroll region sequences. (Default: true)

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

Faces

The colors and the text attributes of the pager are faces registered with StyledStrings.jl under the prefix terminalpager_. They can be customized with TerminalPager.set_face!, which persists the change as a preference, or in the file config/faces.toml of the Julia depot under the tables [terminalpager.<name>]. The available faces are listed as follows:

• "status_bar": Base of the status line, which is the last row of the display. It holds the prompt of the normal mode, the position, and the search and visual mode details, and every other element of the row returns to it. Set inverse = true to draw the row as a bar. (Default: no attributes)
• "status_hint": Key hints, feature tags, and the hints that the text continues beyond the edges of the view. (Default: bright black)
• "mode_search": Name of the search mode on the status line. (Default: bold yellow)
• "mode_visual": Name of the visual mode on the status line. (Default: bold magenta)
• "message_info": Informative message on the status line. (Default: green)
• "message_error": Error message on the status line. (Default: red)
• "search_match": Inactive search match. (Default: black on white)
• "search_active_match": Active search match. (Default: black on yellow)
• "visual_line": Lines marked in the visual mode. Only its background is used. (Default: bright black background)
• "visual_active_line": Visual line. Only its background is used. (Default: blue background)
• "ruler": Line number ruler. (Default: bright black)
• "scrollbar_track": Track of the scrollbar. (Default: bright black)
• "scrollbar_thumb": Thumb of the scrollbar. (Default: no attributes)
• "command_status": Status shown at the right of the command line, like the number of matches while searching. (Default: bright black)
• "help_title": Title of the help screen. (Default: bold cyan)
• "help_section": Section titles of the help screen. (Default: bold)
• "help_description": Section descriptions and feature tags of the help screen. (Default: bright black)
• "help_key": Keys of the help screen. (Default: cyan)
• "help_action": Action names of the help screen. (Default: bold yellow)

For more information, see: TerminalPager.set_face! and TerminalPager.drop_face!.

reset_keybindings() -> Nothing

Reset the key bindings to the original ones.

set_face!(name::AbstractString, face::Face) -> Nothing
set_face!(name::AbstractString; kwargs...) -> Nothing

Customize the pager face name with the attributes set in face, or with the keywords accepted by StyledStrings.Face. The attributes and the available faces are listed in the extended help.

The attributes are merged into the current face, so that the ones left unset keep their values, and they are persisted with Preferences.jl in the same format as faces.toml. The change applies to the next pager session, without restarting Julia. An unknown face or attribute is rejected with an error.

See also: drop_face!.

Arguments

• name::AbstractString: Name of a pager face, without the prefix terminalpager_.
• face::Face: Attributes to merge into the face.

Keywords

• kwargs...: Attributes to merge into the face, as accepted by StyledStrings.Face.

Extended help

Attributes

• foreground and background: Color, which can be the name of one of the 16 terminal colors (:black, :red, :green, :yellow, :blue, :magenta, :cyan, :white, and their :bright_ variants, with :grey and :gray as aliases of :bright_black), the default color of the terminal (:default up to StyledStrings.jl 1.12, and :foreground or :background since 1.13), a 24-bit color written as a "#rrggbb" string or a UInt32 like 0x005f87, or the name of another face, whose foreground is used. The 24-bit colors are approximated on terminals without true color support.
• weight: :thin, :extralight, :light, :semilight, :normal, :medium, :semibold, :bold, :extrabold, or :black. The weights above :normal are shown in bold, and the ones below it are shown faint.
• slant: :normal, :italic, or :oblique. The last two are shown in italics.
• underline: true or false. A color or a style, like (:red, :curly), is accepted and persisted, but the pager only underlines the text.
• strikethrough: true or false.
• inverse: true or false to swap the foreground and the background. Notice that the terminal swaps the colors after applying them. Hence, a face with inverse = true shows its background as the foreground and vice versa.
• inherit: Name of a face, or a vector of names, whose attributes fill the ones left unset, like :bold or :terminalpager_help_key.
• font and height: Accepted and persisted, but they have no effect in the terminal.

Faces

• "status_bar": Base of the status line, which is the last row of the display. It holds the prompt of the normal mode, the position, and the search and visual mode details, and every other element of the row returns to it. Set inverse = true to draw the row as a bar. (Default: no attributes)
• "status_hint": Key hints, feature tags, and the hints that the text continues beyond the edges of the view. (Default: bright black)
• "mode_search": Name of the search mode on the status line. (Default: bold yellow)
• "mode_visual": Name of the visual mode on the status line. (Default: bold magenta)
• "message_info": Informative message on the status line. (Default: green)
• "message_error": Error message on the status line. (Default: red)
• "search_match": Inactive search match. (Default: black on white)
• "search_active_match": Active search match. (Default: black on yellow)
• "visual_line": Lines marked in the visual mode. Only its background is used. (Default: bright black background)
• "visual_active_line": Visual line. Only its background is used. (Default: blue background)
• "ruler": Line number ruler. (Default: bright black)
• "scrollbar_track": Track of the scrollbar. (Default: bright black)
• "scrollbar_thumb": Thumb of the scrollbar. (Default: no attributes)
• "command_status": Status shown at the right of the command line, like the number of matches while searching. (Default: bright black)
• "help_title": Title of the help screen. (Default: bold cyan)
• "help_section": Section titles of the help screen. (Default: bold)
• "help_description": Section descriptions and feature tags of the help screen. (Default: bright black)
• "help_key": Keys of the help screen. (Default: cyan)
• "help_action": Action names of the help screen. (Default: bold yellow)

Throws

• ArgumentError: If name is not a pager face, or if a keyword is not a face attribute.

Examples

julia> TerminalPager.set_face!("search_active_match"; background = :red)

julia> TerminalPager.set_face!("mode_search"; foreground = "#ffffff", background = 0x005f87)

julia> TerminalPager.set_face!("status_bar"; inverse = true)

julia> TerminalPager.set_face!("help_key", StyledStrings.Face(; weight = :bold, inherit = :terminalpager_help_title))

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>", "<wheel_up>", "<wheel_down>",
"<wheel_left>", "<wheel_right>", "<mouse_press>", "<mouse_press_middle>",
"<mouse_press_right>", "<mouse_release>", "<mouse_drag>"

"<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). The mouse keys are reported when the preference "mouse" is enabled.

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, :wheel_up, :wheel_down, :goto_line, :search,
:next_match, :previous_match, :quit_search, :change_freeze,
:change_title_rows, :toggle_ruler, :toggle_scrollbar, :toggle_visual_mode,
:select_visual_mode_line, :mouse_select, :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!("show_scrollbar", true)

@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.