diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 76312fd..813628a 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-15T13:31:16","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-02-13T19:30:10","documenter_version":"1.8.1"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 3efec93..c4da36c 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,4 +1,4 @@ Introduction · Terminal Pager
GitHub

TerminalPager.jl

This package contains a pager written 100% in Julia. It can be used to scroll through content that does not fit in the screen. It was developed based on the Linux command less.

Installation

julia> using Pkg
 
-julia> Pkg.add("TerminalPager")

Automatically Start with Julia

If you want to automatically load TerminalPager.jl, add the following line to the file .julia/config/startup.jl after you have installed the package:

using TerminalPager

Another way is to compile the package directly into your Julia system image. For more information, see the documentation of the package PackageCompiler.jl.

Manual outline

+julia> Pkg.add("TerminalPager")

Automatically Start with Julia

If you want to automatically load TerminalPager.jl, add the following line to the file .julia/config/startup.jl after you have installed the package:

using TerminalPager

Another way is to compile the package directly into your Julia system image. For more information, see the documentation of the package PackageCompiler.jl.

Manual outline

diff --git a/dev/lib/library/index.html b/dev/lib/library/index.html index 874874c..244840c 100644 --- a/dev/lib/library/index.html +++ b/dev/lib/library/index.html @@ -1,9 +1,9 @@ -Library · Terminal Pager
GitHub

Library

Documentation for TerminalPager.jl.

TerminalPager.Keystroke — Type
struct Keystorke

Structure that defines a keystroke.

Fields

  • raw::String: Raw keystroke code converted to string.
  • value::String: String representing the keystroke.
  • alt::Bool: true if ALT key was pressed (only valid if value != :char).
  • ctrl::Bool: true if CTRL key was pressed (only valid if value != :char).
  • shift::Bool: true if SHIFT key was pressed (only valid if value != :char).
source
TerminalPager.delete_keybinding — Method
delete_keybinding(key::Union{Char, Symbol}; kwargs...) -> Nothing

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

For more information about how specify key see set_keybinding.

source
TerminalPager.drop_preference! — Method
drop_preference!(pref::String, value) -> Nothing

Drop the preference pref.

Examples

julia> TerminalPager.drop_preference!("visual_mode_line_background")
source
TerminalPager.pager — Method
pager(obj; kwargs...)

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

Keywords

Info

Some of the default values shown here can be modified by user-defined preferences.

  • auto::Bool: If true, then the pager is only shown if the output does not fit into 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 = 0: Number of columns to be frozen at startup. (Default = 0)
  • frozen_rows::Int = 0: Number of rows to be frozen at startup. (Default = 0)
  • hashelp::Bool = true: If true, then the user can see the pager help. (Default = true)
  • has_visual_mode::Bool = true: If true, the user can use the visual mode. (Default = true)
  • show_ruler::Bool: If true, a vertical ruler is shown at 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.

Preferences

The user can defined 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)
  • "pager_mode": If it is "vi", some keywords 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!.

source
TerminalPager.set_keybinding — Method
set_keybinding(key::Union{Char, Symbol}, action::Symbol; kwargs...) -> Nothing

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

key can be a Char or a Symbol indicating one of the following special keys:

"<up>", "<down>", "<right>", "<left>", "<home>", "<end>", "<F1>", "<F2>",
+Library · Terminal Pager
GitHub
Library
Documentation for TerminalPager.jl.
TerminalPager.Keystroke — Type
struct Keystorke
Structure that defines a keystroke.
Fields
  • raw::String: Raw keystroke code converted to string.
  • value::String: String representing the keystroke.
  • alt::Bool: true if ALT key was pressed (only valid if value != :char).
  • ctrl::Bool: true if CTRL key was pressed (only valid if value != :char).
  • shift::Bool: true if SHIFT key was pressed (only valid if value != :char).
source
TerminalPager.delete_keybinding — Method
delete_keybinding(key::Union{Char, Symbol}; kwargs...) -> Nothing
Delete the keybinding key. The modifiers keys can be selected using the keywords alt, ctrl, and shift.
For more information about how specify key see set_keybinding.
source
TerminalPager.drop_preference! — Method
drop_preference!(pref::String, value) -> Nothing
Drop the preference pref.
Examples
julia> TerminalPager.drop_preference!("visual_mode_line_background")
source
TerminalPager.pager — Method
pager(obj; kwargs...)
Call the pager to show the output of the object obj.
Keywords
Info
Some of the default values shown here can be modified by user-defined preferences.
  • auto::Bool: If true, then the pager is only shown if the output does not fit into 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 = 0: Number of columns to be frozen at startup. (Default = 0)
  • frozen_rows::Int = 0: Number of rows to be frozen at startup. (Default = 0)
  • hashelp::Bool = true: If true, then the user can see the pager help.   (Default = true)
  • has_visual_mode::Bool = true: If true, the user can use the visual mode.   (Default = true)
  • show_ruler::Bool: If true, a vertical ruler is shown at 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.
Preferences
The user can defined 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)
  • "pager_mode": If it is "vi", some keywords 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!.
source
TerminalPager.set_keybinding — Method
set_keybinding(key::Union{Char, Symbol}, action::Symbol; kwargs...) -> Nothing
Set key binding key to the action action. The modifiers keys can be selected using the keywords alt, ctrl, and shift.
key can be a Char or a Symbol indicating one of the following special keys:
"<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>"
action can be one of the following symbols:
:quit, :help, :up, :down, :left, :right, :fastup, :fastdown, :fastleft,
-:fastright :bol, :eol, :pageup, :pagedown, :home, :end
source
TerminalPager.set_preference! — Method
set_preference!(pref::String, value) -> Nothing
Set the preference pref to the value.
Examples
julia> TerminalPager.set_preference!("visual_mode_line_background", "44")
source
TerminalPager.@help — Macro
@help(f)
Open the documentation of the function, macro or other object f in pager.
Examples
julia> @help write
source
TerminalPager.@stdout_to_pager — Macro
@stdout_to_pager(ex_in)
Capture the stdout generated by ex_in and show inside a pager.
Note
The command must write to stdout explicitly. For example, @stdout_to_pager 1 shows a blank screen since 1 does not write to stdout, but returns 1. @stdout_to_pager show(1), on the other hand, shows the number 1 inside the pager.
Note
This macro can also be called using the shorter name @out2pr.
source

+:fastright :bol, :eol, :pageup, :pagedown, :home, :end
source
TerminalPager.set_preference! — Method
set_preference!(pref::String, value) -> Nothing

Set the preference pref to the value.

Examples

julia> TerminalPager.set_preference!("visual_mode_line_background", "44")
source
TerminalPager.@help — Macro
@help(f)

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

Examples

julia> @help write
source
TerminalPager.@stdout_to_pager — Macro
@stdout_to_pager(ex_in)

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

Note

The command must write to stdout explicitly. For example, @stdout_to_pager 1 shows a blank screen since 1 does not write to stdout, but returns 1. @stdout_to_pager show(1), on the other hand, shows the number 1 inside the pager.

Note

This macro can also be called using the shorter name @out2pr.

source
diff --git a/dev/man/customization/index.html b/dev/man/customization/index.html index f8a25a7..67e2d0f 100644 --- a/dev/man/customization/index.html +++ b/dev/man/customization/index.html @@ -1,4 +1,4 @@ Customization · Terminal Pager
GitHub

Customization

The user can customize some preferences in TerminalPager.jl. We handle those customization using Preferences.jl. Thus, they persist between Julia sessions.

To add a new value to a preference, use the function:

TerminalPager.set_preference!(preference, value)

To drop the customized value for the preference, use:

TerminalPager.drop_preference!(preference)

To drop all the customized values, use:

TerminalPager.drop_all_preferences!()

The list of available properties are:

  • "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)
  • "pager_mode": If it is "vi", some keywords 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 example, if the user wants to change the active search decoration to blue, they should do:

julia> using TerminalPager.Crayons
 
-julia> TerminalPager.set_preference!("active_search_decoration", string(crayon"black bg:red"))

The default value can be restored by:

julia> TerminalPager.drop_preference!("active_search_decoration")

Keybindings

The user can also change the default keybindings to perform actions inside the pager. For more information, see the functions: TerminalPager.set_keybinding, TerminalPager.delete_keybinding, and TerminalPager.reset_keybindings. Notice that those modifications do not persist between Julia sessions. Hence, if the user wants a permanent configuration, they should add those commands to the startup.jl script.

+julia> TerminalPager.set_preference!("active_search_decoration", string(crayon"black bg:red"))

The default value can be restored by:

julia> TerminalPager.drop_preference!("active_search_decoration")

Keybindings

The user can also change the default keybindings to perform actions inside the pager. For more information, see the functions: TerminalPager.set_keybinding, TerminalPager.delete_keybinding, and TerminalPager.reset_keybindings. Notice that those modifications do not persist between Julia sessions. Hence, if the user wants a permanent configuration, they should add those commands to the startup.jl script.

diff --git a/dev/man/usage/index.html b/dev/man/usage/index.html index 19a7d5f..15d6c8a 100644 --- a/dev/man/usage/index.html +++ b/dev/man/usage/index.html @@ -1,4 +1,4 @@ Usage · Terminal Pager
GitHub

Usage

Getting started

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

julia> rand(100,100) |> pager

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

julia> @doc(write) |> pager

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

Helpers

The following macros are available to help calling the pager.

@help

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

julia> @help write

@stdout_to_pager

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

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

This macro also works with blocks such as for loops:

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

Note

This macro can also be called using the shorter name @out2pr.

REPL Modes

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

In pager mode, you can also type ? at the beginning of the command line to access the pager help mode. In this case, the prompt is changed to pager?>. Any docstring accessed in this mode is rendered inside a pager. By the default, we use the alternate screen buffer, allowing to keep the screen content after exiting the pager.

+ end

Note

This macro can also be called using the shorter name @out2pr.

REPL Modes

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

In pager mode, you can also type ? at the beginning of the command line to access the pager help mode. In this case, the prompt is changed to pager?>. Any docstring accessed in this mode is rendered inside a pager. By the default, we use the alternate screen buffer, allowing to keep the screen content after exiting the pager.