@ -118,7 +118,10 @@
< a href = "print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/sayanarijit/xplr" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< / div >
< / div >
@ -182,7 +185,7 @@ repositories:</p>
< pre > < code > paru -S xplr-bin
< / code > < / pre >
< p > Git version:< / p >
< pre > < code > paru -S xplr-git # git version
< pre > < code > paru -S xplr-git
< / code > < / pre >
< h3 id = "void-linux" > < a class = "header" href = "#void-linux" > Void Linux< / a > < / h3 >
< h4 id = "a-hrefhttpsgithubcomshubham-cppvoid-pkg-templatesvoid-templates-by-shubhama" > < a class = "header" href = "#a-hrefhttpsgithubcomshubham-cppvoid-pkg-templatesvoid-templates-by-shubhama" > < a href = "https://github.com/shubham-cpp/void-pkg-templates" > void-templates by shubham< / a > < / a > < / h4 >
@ -339,10 +342,10 @@ will be ignored.</p>
the command-line argument < code > -c< / code > / < code > --config< / code > to specify its path explicitely. In
that case, both < code > ~/.config/xplr/init.lua< / code > and < code > /etc/xplr/init.lua< / code > will be
ignored.< / p >
< h2 id = " loading-order "> < a class = "header" href = "# loading-order"> Loading Order < / a > < / h2 >
< h2 id = " how-config-is-loaded "> < a class = "header" href = "# how-config-is-loaded"> How Config is Loaded < / a > < / h2 >
< p > When xplr loads, it first executes the built-in
< a href = "https://github.com/sayanarijit/xplr/blob/main/src/init.lua" > init.lua< / a > to set
the default values. It is then overwritten by another config file, if found
the default values, which is then overwritten by another config file, if found
using the following lookup order:< / p >
< p > < strong > --config /path/to/init.lua< / strong > > < strong > ~/.config/xplr/init.lua< / strong > > < strong > /etc/xplr/init.lua< / strong > < / p >
< div style = "break-before: page; page-break-before: always;" > < / div > < h1 id = "general-config" > < a class = "header" href = "#general-config" > General Config< / a > < / h1 >
@ -374,14 +377,15 @@ action.</p>
< p > The name of one of the defined < a href = "layouts.html" > layouts< / a > to use when xplr loads.< / p >
< p > TODO: Continue documentation< / p >
< div style = "break-before: page; page-break-before: always;" > < / div > < h1 id = "modes" > < a class = "header" href = "#modes" > Modes< / a > < / h1 >
< p > xplr is a modal application. That means the users switch between different
modes, each containing a different set to key binding to avoid classes. The
modes can be configured using the < code > xplr.config.modes< / code > Lua API.< / p >
< p > xplr is a modal file explorer. That means the users switch between different
modes, each containing a different set to key bindings to avoid clashes. Users
can switch between these modes at run-time.< / p >
< p > The modes can be configured using the < code > xplr.config.modes< / code > Lua API.< / p >
< p > It contains the following fields:< / p >
< ul >
< li > < a href = "modes.html#builtin" > builtin< / a > < / li >
< li > < a href = "modes.html#custom" > custom< / a > < / li >
< / ul >
< p > The users can switch between these modes at run-time.< / p >
< h2 id = "builtin" > < a class = "header" href = "#builtin" > builtin< / a > < / h2 >
< p > Type: mapping of string and < a href = "modes.html#mode" > Mode< / a > < / p >
< p > This is exposed by the < code > xplr.config.modes.builtin< / code > API.< / p >
@ -411,7 +415,7 @@ does.</p>
< h2 id = "custom" > < a class = "header" href = "#custom" > custom< / a > < / h2 >
< p > Type: mapping of string and < a href = "modes.html#mode" > Mode< / a > < / p >
< p > This is exposed by the < code > xplr.config.layouts.custom< / code > API.< / p >
< p > It allows the users to define any custom layout .< / p >
< p > It allows the users to define custom modes .< / p >
< p > Example:< / p >
< pre > < code class = "language-lua" > xplr.config.modes.custom.example = {
name = " example" ,
@ -565,11 +569,11 @@ that xplr can handle.</p>
< ul >
< li > Via < a href = "modes.html#key-bindings" > key bindings< / a > < / li >
< li > Via < a href = "message.html#lua-function-calls" > Lua function calls< / a > < / li >
< li > Via shell using the < a href = "message.html#input-pipe" > input pipe< / a > < / li >
< li > Via shell command using the < a href = "message.html#input-pipe" > input pipe< / a > < / li >
< / ul >
< h2 id = "format" > < a class = "header" href = "#format" > Format< / a > < / h2 >
< p > To send messages using < a href = "modes.html#key-bindings" > key bindings< / a > or
< a href = "message.html#lua-functions-calls" > Lua functions calls< / a > , these are represented in
< p > To send messages using the < a href = "modes.html#key-bindings" > key bindings< / a > or
< a href = "message.html#lua-functions-calls" > Lua functions calls< / a > , messages are represented in
< a href = "https://www.lua.org/" > Lua< / a > syntax. For example:< / p >
< ul >
< li > " Quit" < / li >
@ -580,7 +584,7 @@ that xplr can handle.</p>
represented using
< a href = "http://yaml.org/" > YAML< / a > (or < a href = "https://www.json.org" > JSON< / a > ) syntax. For example:< / p >
< ul >
< li > Foo < / li >
< li > Quit < / li >
< li > FocusPath: " /path/to/file" < / li >
< li > Call: { command: bash, args: [" -c" , " read -p test" ] }< / li >
< / ul >
@ -590,7 +594,29 @@ represented using
< p > When called the function receives a < a href = "message.html#calllua-argument" > special argument< / a > that
contains some useful information. The function can optionally return a list of
messages which will be handled by xplr.< / p >
< p > Example:< / p >
< h3 id = "calllua-argument" > < a class = "header" href = "#calllua-argument" > CallLua Argument< / a > < / h3 >
< p > This is a special argument passed to the lua functions when called using the
< code > CallLua< / code > , < code > CallLuaSilently< / code > messages.< / p >
< p > It contains the following information:< / p >
< ul >
< li > version< / li >
< li > config< / li >
< li > pwd< / li >
< li > focused_node< / li >
< li > directory_buffer< / li >
< li > selection< / li >
< li > mode< / li >
< li > layout< / li >
< li > input_buffer< / li >
< li > pid< / li >
< li > session_path< / li >
< li > explorer_config< / li >
< li > history< / li >
< li > last_modes< / li >
< / ul >
< p > TODO: Document each. For now, refer to the
< a href = "https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields" > rust doc< / a > .< / p >
< h3 id = "example" > < a class = "header" href = "#example" > Example:< / a > < / h3 >
< pre > < code class = "language-lua" > -- Define the function
xplr.fn.custom.ask_name_and_greet = function(app)
print(" What's your name?" )
@ -606,7 +632,7 @@ end
-- Map the function to a key (space)
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
help = " and & greet" ,
help = " ask name and greet" ,
messages = {
{ CallLua = " custom.ask_name_and_greet" }
}
@ -615,28 +641,6 @@ xplr.config.modes.builtin.default.key_bindings.on_key.space = {
-- Now, when you press " space" in default mode, you will be prompted for your
-- name. Enter your name to receive a nice greeting and to know your location.
< / code > < / pre >
< h3 id = "calllua-argument" > < a class = "header" href = "#calllua-argument" > CallLua Argument< / a > < / h3 >
< p > This is a special argument passed to the lua functions when called using the
< code > CallLua< / code > , < code > CallLuaSilently< / code > messages.< / p >
< p > It contains the following information:< / p >
< ul >
< li > version< / li >
< li > config< / li >
< li > pwd< / li >
< li > focused_node< / li >
< li > directory_buffer< / li >
< li > selection< / li >
< li > mode< / li >
< li > layout< / li >
< li > input_buffer< / li >
< li > pid< / li >
< li > session_path< / li >
< li > explorer_config< / li >
< li > history< / li >
< li > last_modes< / li >
< / ul >
< p > TODO: Document each. For now, refer to the
< a href = "https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields" > rust doc< / a > .< / p >
< h2 id = "environment-variables-and-pipes" > < a class = "header" href = "#environment-variables-and-pipes" > Environment Variables and Pipes< / a > < / h2 >
< p > Alternative to < code > CallLua< / code > , < code > CallLuaSilently< / code > messages that call Lua functions,
there are < code > Call< / code > , < code > CallLuaSilently< / code > , < code > BashExec< / code > , < code > BashExecSilently< / code > messages
@ -670,12 +674,12 @@ XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_
< / code > < / pre >
< p > The environment variables starting with < code > XPLR_PIPE_< / code > are the temporary files
called " pipe" s.< / p >
< h 3 id = "input-pipe" > < a class = "header" href = "#input-pipe" > Input pipe< / a > < / h 3 >
< h 4 id = "input-pipe" > < a class = "header" href = "#input-pipe" > Input pipe< / a > < / h 4 >
< p > Current there is only one input pipe.< / p >
< ul >
< li > < a href = "message.html#xplr_pipe_msg_in" > XPLR_PIPE_MSG_IN< / a > < / li >
< / ul >
< h 3 id = "output-pipes" > < a class = "header" href = "#output-pipes" > Output pipes< / a > < / h 3 >
< h 4 id = "output-pipes" > < a class = "header" href = "#output-pipes" > Output pipes< / a > < / h 4 >
< p > < code > XPLR_PIPE_*_OUT< / code > are the output pipes that contain data which cannot be
exposed directly via environment variables, like multi-line string.< / p >
< ul >
@ -686,23 +690,44 @@ exposed directly via environment variables, like multi-line string.</p>
< li > < a href = "message.html#xplr_pipe_history_out" > XPLR_PIPE_HISTORY_OUT< / a > < / li >
< li > < a href = "message.html#xplr_pipe_directory_nodes_out" > XPLR_PIPE_DIRECTORY_NODES_OUT< / a > < / li >
< / ul >
< h 3 id = "xplr_pipe_msg_in" > < a class = "header" href = "#xplr_pipe_msg_in" > XPLR_PIPE_MSG_IN< / a > < / h 3 >
< h 4 id = "xplr_pipe_msg_in" > < a class = "header" href = "#xplr_pipe_msg_in" > XPLR_PIPE_MSG_IN< / a > < / h 4 >
< p > Append new-line delimited messages to this pipe in < a href = "www.yaml.org" > YAML< / a > (or
< a href = "www.json.org" > JSON< / a > ) syntax. These messages will be read and handled by xplr
after the command execution.< / p >
< h 3 id = "xplr_pipe_selection_out" > < a class = "header" href = "#xplr_pipe_selection_out" > XPLR_PIPE_SELECTION_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_selection_out" > < a class = "header" href = "#xplr_pipe_selection_out" > XPLR_PIPE_SELECTION_OUT< / a > < / h 4 >
< p > New-line delimited list of selected paths.< / p >
< h 3 id = "xplr_pipe_global_help_menu_out" > < a class = "header" href = "#xplr_pipe_global_help_menu_out" > XPLR_PIPE_GLOBAL_HELP_MENU_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_global_help_menu_out" > < a class = "header" href = "#xplr_pipe_global_help_menu_out" > XPLR_PIPE_GLOBAL_HELP_MENU_OUT< / a > < / h 4 >
< p > The full help menu.< / p >
< h 3 id = "xplr_pipe_logs_out" > < a class = "header" href = "#xplr_pipe_logs_out" > XPLR_PIPE_LOGS_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_logs_out" > < a class = "header" href = "#xplr_pipe_logs_out" > XPLR_PIPE_LOGS_OUT< / a > < / h 4 >
< p > New-line delimited list of logs.< / p >
< h 3 id = "xplr_pipe_result_out" > < a class = "header" href = "#xplr_pipe_result_out" > XPLR_PIPE_RESULT_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_result_out" > < a class = "header" href = "#xplr_pipe_result_out" > XPLR_PIPE_RESULT_OUT< / a > < / h 4 >
< p > New-line delimited result (selected paths if any, else the focused path)< / p >
< h 3 id = "xplr_pipe_history_out" > < a class = "header" href = "#xplr_pipe_history_out" > XPLR_PIPE_HISTORY_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_history_out" > < a class = "header" href = "#xplr_pipe_history_out" > XPLR_PIPE_HISTORY_OUT< / a > < / h 4 >
< p > New-line delimited list of last visited paths (similar to jump list in vim).< / p >
< h 3 id = "xplr_pipe_directory_nodes_out" > < a class = "header" href = "#xplr_pipe_directory_nodes_out" > XPLR_PIPE_DIRECTORY_NODES_OUT< / a > < / h 3 >
< h 4 id = "xplr_pipe_directory_nodes_out" > < a class = "header" href = "#xplr_pipe_directory_nodes_out" > XPLR_PIPE_DIRECTORY_NODES_OUT< / a > < / h 4 >
< p > New-line delimited list of paths, filtered and sorted as displayed in the
< a href = "layouts.html#table" > files table< / a > .< / p >
< h3 id = "example-1" > < a class = "header" href = "#example-1" > Example:< / a > < / h3 >
< pre > < code class = "language-lua" > xplr.config.modes.builtin.default.key_bindings.on_key.space = {
help = " ask name and greet" ,
messages = {
{
BashExec = [===[
echo " What's your name?"
read name
greeting=" Hello $name!"
message=" $greeting You are inside $PWD"
echo LogSuccess: '" '$message'" ' > > " ${XPLR_PIPE_MSG_IN:?}"
]===]
}
}
}
-- Now, when you press " space" in default mode, you will be prompted for your
-- name. Enter your name to receive a nice greeting and to know your location.
< / code > < / pre >
< div style = "break-before: page; page-break-before: always;" > < / div > < h1 id = "layouts" > < a class = "header" href = "#layouts" > Layouts< / a > < / h1 >
< p > xplr layouts define the structure of the UI, i.e. how many panel we see,
placement and size of the panels, how they look etc.< / p >
@ -831,7 +856,7 @@ applied of the list of paths being displayed.</p>
< h2 id = "splits" > < a class = "header" href = "#splits" > splits< / a > < / h2 >
< p > Type: list of < a href = "layouts.html#layout" > Layout< / a > < / p >
< p > The list of child layouts to fit into the parent layout.< / p >
< h2 id = "example "> < a class = "header" href = "#example "> Example< / a > < / h2 >
< h2 id = "example -2 "> < a class = "header" href = "#example -2 "> Example< / a > < / h2 >
< p > < a href = "https://gifyu.com/image/1X38" > < img src = "https://s6.gifyu.com/images/layout.png" alt = "layout.png" / > < / a > < / p >
< pre > < code class = "language-lua" > xplr.config.layouts.builtin.default = {
Horizontal = {
@ -907,7 +932,7 @@ applied of the list of paths being displayed.</p>
< li > " Hidden" < / li >
< li > " CrossedOut" < / li >
< / ul >
< h2 id = "example- 1 "> < a class = "header" href = "#example- 1 "> Example< / a > < / h2 >
< h2 id = "example- 3 "> < a class = "header" href = "#example- 3 "> Example< / a > < / h2 >
< pre > < code class = "language-lua" > xplr.config.general.cursor.style.fg = " Red"
xplr.config.general.cursor.style.bg = { Rgb = { 100, 150, 200 } }
xplr.config.general.cursor.style.add_modifiers = { " Bold" , " Italic" }
sayanarijit
3 years ago