A column renderer is a Lua function that receives a special argument and returns a string that will be displayed in each specific field of the -files table.
xplr by default provides the following column renderers:
xplr.fn.builtin.fmt_general_table_row_cols_0
Type: string
The total number of the nodes.
Type: mapping of string and string
The applicable meta object for the node.
Permission contains the following fields:
xplr can be configured using Lua via a special file -named init.lua -(example), which -can be placed in ~/.config/xplr/ (user specific) or /etc/xplr/ (global) -depending on the use case.
init.lua
~/.config/xplr/
/etc/xplr/
When a user specific configuration is available, the global configuration file -will be ignored.
However, it's also possible to place the file anywhere, with any name and use -the command-line argument -c / --config to specify its path explicitely. In -that case, both ~/.config/xplr/init.lua and /etc/xplr/init.lua will be -ignored.
-c
--config
~/.config/xplr/init.lua
/etc/xplr/init.lua
When xplr loads, it first executes the built-in -init.lua to set -the default values, which is then overwritten by another config file, if found -using the following lookup order:
--config /path/to/init.lua > ~/.config/xplr/init.lua > /etc/xplr/init.lua
The xplr configuration, exposed as xplr.config Lua API contains the -following fields:
xplr.config
These are the concepts that make xplr probably the most hackable terminal file +explorer.
xplr can be configured using Lua via a special file named init.lua, +which can be placed in ~/.config/xplr/ (local to user) or /etc/xplr/ +(global) depending on the use case.
When xplr loads, it first executes the built-in init.lua to set the +default values, which is then overwritten by another config file, if found +using the following lookup order:
--config /path/to/init.lua
The first one found will be loaded by xplr and the lookup will stop.
The loaded config can be further extended using the -C or --extra-config +command-line option.
-C
--extra-config
+NEED HELP: Auto generate rest of the docs from src/init.lua +using docs/script/generate.py. +
NEED HELP: Auto generate rest of the docs from src/init.lua +using docs/script/generate.py.
bash
BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath are messages, $XPLR_PIPE_MSG_IN, $XPLR_PIPE_DIRECTORY_NODES_OUT are -environment variables exported by xplr +environment variables exported by xplr before executing the command. They contain the path to the -input and output pipes that +input and output pipes that allows external tools to interact with xplr.
BashExec
PopMode
SwitchModeBuiltin
ChangeDirectory
FocusPath
$XPLR_PIPE_MSG_IN
$XPLR_PIPE_DIRECTORY_NODES_OUT
xplr
Now that we have our new mode ready, let's add an entry point to this mode via the default mode.
default
Alternative to CallLua, CallLuaSilently messages that call Lua functions, +there are Call, CallSilently, BashExec, BashExecSilently messages +that call shell commands.
CallLua
CallLuaSilently
Call
CallSilently
BashExecSilently
However, unlike the Lua functions, these shell commands have to read the useful +information and send messages via environment variables and temporary files +called "pipe"s. These environment variables and files are only available when +a command is being executed.
Visit the fzf integration tutorial +for example.
To see the environment variables, invoke the shell by typing :! in default +mode and run the following command:
:!
env | grep ^XPLR_ +
You will see something like:
XPLR_FOCUS_INDEX=0 +XPLR_MODE=action to +XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out +XPLR_INPUT_BUFFER= +XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out +XPLR_PID=122278 +XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in +XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out +XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out +XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out +XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book +XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278 +XPLR_APP_VERSION=0.14.3 +XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out +
The environment variables starting with XPLR_PIPE_ are the temporary files +called "pipe"s.
XPLR_PIPE_
Current there is only one input pipe.
XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be +exposed directly via environment variables, like multi-line string.
XPLR_PIPE_*_OUT
Append new-line delimited messages to this pipe in YAML +(or JSON) syntax. These messages will be read and +handled by xplr after the command execution.
New-line delimited list of selected paths.
The full help menu.
New-line delimited list of logs.
New-line delimited result (selected paths if any, else the focused path)
New-line delimited list of last visited paths (similar to jump list in vim).
New-line delimited list of paths, filtered and sorted as displayed in the +files table.
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. +
This configuration is exposed via the xplr.config.general API.
xplr.config.general
For now, kindly refer to init.lua
Cursor based input operation can be one of the following:
xplr.config.layouts.builtin.default = { @@ -161,48 +161,6 @@ } }
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.
This is configuration exposed via the xplr.config.layouts API. It contains -the following fields:
xplr.config.layouts
The users can switch between these layouts at run-time.
Type: mapping of string and Layout
This is exposed by the xplr.config.layouts.builtin API.
xplr.config.layouts.builtin
xplr by default provides the following builtin layouts:
Type: Layout
This is the default layout we see when we run xplr.
This layout hides the help menu.
This layout hides the selection panel.
This layout hides both the help menu and the selection panel.
This is exposed by the xplr.config.layouts.custom API.
xplr.config.layouts.custom
It allows the users to define any custom layout.
Example:
xplr.config.layouts.custom.example = "Nothing" -xplr.config.general.initial_layout = "example" - --- when you load xplr, you should see a blank screen -
A layout can be one of the following:
Every field is of integer type.
This is a lightweight version of the Lua Context. In this context, the -heavyweight fields like directory_buffer are omitted for performance +
This is a lightweight version of the Lua Context. In this context, the +heavyweight fields like directory_buffer are omitted for performance reasons.
Hence, only the following fields are avilable.
Until we figure out a way to auto generate this page from the code, please -refer to the comments in the default init.lua.
This configuration is exposed via the xplr.config.layouts API.
xplr allows you to define lua functions using the xplr.fn.custom Lua API.
xplr.fn.custom
These functions can be called using messages like CallLua, CallLuaSilently.
When called the function receives a special argument that +contains some useful information. The function can optionally return a list of +messages which will be handled by xplr.
This is a special argument passed to the lua functions when called using the +CallLua, CallLuaSilently messages.
It contains the following information:
xplr version. Can be used to test compatibility.
The present working directory/
Type: nullable Node
The node under focus.
Type: nullable Directory Buffer
The directory buffer being rendered.
Type: list of selected Nodes
The selected nodes.
Type: Mode
Current mode.
Current layout.
Type: nullable string
The input buffer.
Type: integer
The xplr session PID.
The session path.
TODO
Type: History
Type: list of Mode
Last modes, not popped yet.
The parent path of the node.
The path relative to the parent, i.e. the file/directory name with extension.
The absolute path (without resolving symlinks) of the node.
The extension of the node.
Type: boolean
true if the node is a symlink.
true
true if the node is a broken symlink.
true if the node is a directory.
true if the node is a file.
true if the node is real-only.
The mime type of the node. For e.g. text/csv, image/jpeg etc.
text/csv
image/jpeg
The size of the exact node. The size of a directory won't be calculated +recursively.
Like size but in human readable format.
Type: Permission
The permissions applied to the node.
Type: nullable Resolved Node Metadata
If the node is a symlink, it will hold information about the symlink resolved +node. Else, it will hold information the actual node. It the symlink is broken, +it will be null.
If the node is a symlink and is not broken, it will hold information about the +symlink resolved node. However, it will never hold information about the actual +node. It will instead be null.
A node contains the following fields:
Directory buffer contains the following fields:
Type: list of Nodes
A list of visible nodes.
Type: int
The count of nodes being rendered.
The index of the node under focus. It can be 0 even when there's no node to +focus on.
0
History contains the following fields:
Location of the current path in history.
Type: list of string
Visited paths.
-- Define the function +xplr.fn.custom.ask_name_and_greet = function(app) + print("What's your name?") + + local name = io.read() + local greeting = "Hello " .. name .. "!" + local message = greeting .. " You are inside " .. app.pwd + + return { + { LogSuccess = message }, + } +end + +-- Map the function to a key (space) +xplr.config.modes.builtin.default.key_bindings.on_key.space = { + help = "ask name and greet", + messages = { + { CallLua = "custom.ask_name_and_greet" } + } +} + +-- 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. +
You can think of xplr as a server. Just like web servers listen to HTTP +requests, xplr listens to messages.
You can send these messages to an xplr session in the following ways:
--on-load
To send messages using the key bindings or +Lua function calls, messages are represented in +Lua syntax. For example:
However, to send messages using the input pipe, they need to be +represented using +YAML (or JSON) syntax. For example:
xplr messages categorized based on their purpose.
Explore the present working directory and register the filtered nodes. +This operation is expensive. So, try to avoid using it too often.
ExplorePwd
Explore the present working directory and register the filtered nodes +asynchronously. This operation happens asynchronously. That means, the +xplr directory buffers won't be updated immediately. Hence, it needs to +be used with care and probably with special checks in place. To explore +$PWD synchronously, use ExplorePwd instead.
ExplorePwdAsync
Explore the present working directory along with its parents and +register the filtered nodes. This operation happens asynchronously. +That means, the xplr directory buffers won't be updated immediately. +Hence, it needs to be used with care and probably with special checks +in place. To explore just the $PWD synchronously, use ExplorePwd +instead.
$PWD
ExploreParentsAsync
Clear the screen.
ClearScreen
Refresh the screen. +But it will not re-explore the directory if the working directory is +the same. If there is some change in the working directory and you want +to re-explore it, use the Explore message instead. +Also, it will not clear the screen. Use ClearScreen for that.
Explore
Refresh
Focus next node.
FocusNext
Focus on the nth node relative to the current focus where n is a +given value.
n
Type: { FocusNextByRelativeIndex = int }
FocusNextByRelativeIndex: 2
Focus on the nth node relative to the current focus where n is read +from the input buffer.
FocusNextByRelativeIndexFromInput
Focus on the previous item.
FocusPrevious
Focus on the -nth node relative to the current focus where n is a +given value.
-n
Type: { FocusPreviousByRelativeIndex = int }
{ FocusPreviousByRelativeIndex = 2 }
FocusPreviousByRelativeIndex: 2
Focus on the -nth node relative to the current focus where n is +read from the input buffer.
FocusPreviousByRelativeIndexFromInput
Focus on the first node.
FocusFirst
Focus on the last node.
FocusLast
Focus on the given path.
Type: { FocusPath = "string" }
{ FocusPath = "/path/to/file" }
FocusPath: /path/to/file
Focus on the path read from input buffer.
FocusPathFromInput
Focus on the absolute nth node where n is a given value.
Type: { FocusByIndex = int }
FocusByIndex: 2
Focus on the absolute nth node where n is read from the input buffer.
FocusByIndexFromInput
YAML: FocusByFileName: string
FocusByFileName: string
Focus on the file by name from the present working directory.
Type: { FocusByFileName = "string" }
FocusByFileName: filename.ext
Change the present working directory ($PWD)
Type: { ChangeDirectory = "string" }
ChangeDirectory: /path/to/directory
Enter into the currently focused path if it's a directory.
Enter
Go back to the parent directory.
Back
Go to the last path visited.
LastVisitedPath
Go to the next path visited.
NextVisitedPath
Follow the symlink under focus to its actual location.
Lua: "FollowSymlink" +YAML: FollowSymlink
FollowSymlink
Update the input buffer using cursor based operations.
Type: { UpdateInputBuffer = Input Opertaion }
UpdateInputBuffer: GoToPreviousWord
Update the input buffer from the key read from keyboard input.
UpdateInputBufferFromKey
Append/buffer the given string into the input buffer.
Type: { BufferInput = "string" }
BufferInput: foo
Append/buffer the characted read from a keyboard input into the +input buffer.
BufferInputFromKey
Set/rewrite the input buffer with the given string. +When the input buffer is not-null (even if empty string) +it will show in the UI.
Type: { SetInputBuffer = "string" }
SetInputBuffer: foo
Remove input buffer's last character.
RemoveInputBufferLastCharacter
Remove input buffer's last word.
RemoveInputBufferLastWord
Reset the input buffer back to null. It will not show in the UI.
ResetInputBuffer
Switch input mode.
Type : { SwitchMode = "string" }
+NOTE: To be specific about which mode to switch to, use +SwitchModeBuiltinKeepingInputBuffer or +SwitchModeCustomKeepingInputBuffer instead. +
NOTE: To be specific about which mode to switch to, use +SwitchModeBuiltinKeepingInputBuffer or +SwitchModeCustomKeepingInputBuffer instead.
SwitchModeBuiltinKeepingInputBuffer
SwitchModeCustomKeepingInputBuffer
Switch input mode. +It keeps the input buffer.
Type: { SwitchModeKeepingInputBuffer = "string" }
SwitchModeKeepingInputBuffer: default
Switch to a builtin mode. +It clears the input buffer.
Type: { SwitchModeBuiltin = "string" }
SwitchModeBuiltin: default
Switch to a builtin mode. +It keeps the input buffer.
Type: { SwitchModeBuiltinKeepingInputBuffer = "string" }
SwitchModeBuiltinKeepingInputBuffer: default
Switch to a custom mode. +It clears the input buffer.
Type: { SwitchModeCustom = "string" }
SwitchModeCustom: my_custom_mode
Switch to a custom mode. +It keeps the input buffer.
Type: { SwitchModeCustomKeepingInputBuffer = "string" }
SwitchModeCustomKeepingInputBuffer: my_custom_mode
Pop the last mode from the history and switch to it. +It clears the input buffer.
Pop the last mode from the history and switch to it. +It keeps the input buffer.
PopModeKeepingInputBuffer
Switch layout.
Type: { SwitchLayout = "string" }
SwitchLayout: default
+NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or +SwitchLayoutCustom instead. +
NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or +SwitchLayoutCustom instead.
SwitchLayoutBuiltin
SwitchLayoutCustom
Switch to a builtin layout.
Type: { SwitchLayoutBuiltin = "string" }
SwitchLayoutBuiltin: default
Switch to a custom layout.
Type: { SwitchLayoutCustom = "string" }
SwitchLayoutCustom: my_custom_layout
Call a shell command with the given arguments. +Note that the arguments will be shell-escaped. +So to read the variables, the -c option of the shell +can be used. +You may need to pass ExplorePwd depening on the expectation.
Type: { Call = "string" }
Call: { command: bash, args: ["-c", "read -p test"] }
Like Call but without the flicker. The stdin, stdout +stderr will be piped to null. So it's non-interactive.
Type: { CallSilently = "string" }
{ CallSilently = { command = "tput", args = { "bell" } } }
CallSilently: { command: tput, args: ["bell"] }
An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false} +where {string} is the given value.
Call: {command: bash, args: ["-c", "{string}"], silent: false}
{string}
Type: { BashExec = "string" }
BashExec: "read -p test"
Like BashExec but without the flicker. The stdin, stdout +stderr will be piped to null. So it's non-interactive.
Type: { BashExecSilently = "string" }
BashExecSilently: "tput bell"
Call a Lua function.
A Lua Context +object will be passed to the function as argument. +The function can optionally return a list of messages for xplr to +handle after the executing the function.
Type: { CallLua = "string" }
CallLua: custom.some_custom_funtion
Like CallLua but without the flicker. The stdin, stdout +stderr will be piped to null. So it's non-interactive.
Type: { CallLuaSilently = "string" }
CallLuaSilently: custom.some_custom_function
Execute Lua code without needing to define a function.
If the string is a callable, xplr will try to call it with with the +Lua Context +argument.
string
Type: { LuaEval = "string" }
LuaEval: "return { { LogInfo = io.read() } }"
LuaEval: "function(app) return { { LogInfo = app.pwd } } end"
Like LuaEval but without the flicker. The stdin, stdout +stderr will be piped to null. So it's non-interactive.
LuaEval
Type: { LuaEvalSilently = "string" }
LuaEvalSilently: "return { { LogInfo = 'foo' } }"
Select the focused node.
Select
Select all the visible nodes.
SelectAll
Select the given path.
Type: { SelectPath = "string" }
SelectPath: /path/to/file
Unselect the focused node.
UnSelect
Unselect all the visible nodes.
UnSelectAll
UnSelect the given path.
Type: { UnSelectPath = "string)" }
UnSelectPath: /path/to/file
Toggle selection on the focused node.
ToggleSelection
Toggle between select all and unselect all. +Example:
ToggleSelectAll
Toggle selection by file path.
Type: { ToggleSelectionByPath = "string" }
ToggleSelectionByPath: /path/to/file
Clear the selection.
ClearSelection
Add a filter to exclude nodes +while exploring directories.
Type: { AddNodeFilter = { filter = Filter, input = "string" }
AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Remove an existing filter.
Type: { RemoveNodeFilter = { filter = Filter, input = "string" }
RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Remove a filter if it exists, +else, add a it.
Type: { ToggleNodeFilter = { filter = Filter, input = "string" }
ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Add a node filter reading the +input from the buffer.
Type: { AddNodeFilterFromInput = Filter }
AddNodeFilterFromInput: RelativePathDoesStartWith
Remove a node filter reading +the input from the buffer.
Type: { RemoveNodeFilterFromInput = Filter }
RemoveNodeFilterFromInput: RelativePathDoesStartWith
Remove the last node filter.
RemoveLastNodeFilter
Reset the node filters back to the +default configuration.
ResetNodeFilters
Clear all the node filters.
ClearNodeFilters
Add a sorter to sort nodes while +exploring directories.
Type: { AddNodeSorter = { sorter = Sorter, reverse = bool } }
AddNodeSorter: { sorter: ByRelativePath, reverse: false }
Remove an existing sorter.
Type: { RemoveNodeSorter = Sorter }
RemoveNodeSorter: ByRelativePath
Reverse a node sorter.
Type: { ReverseNodeSorter = Sorter }
ReverseNodeSorter: ByRelativePath
Remove a sorter if it exists, +else, add a it.
Type: { ToggleNodeSorter = { sorter = Sorter, reverse = bool } }
ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }
Reverse the node sorters.
ReverseNodeSorters
Remove the last node sorter.
RemoveLastNodeSorter
Reset the node sorters back to +the default configuration.
ResetNodeSorters
Clear all the node sorters.
ClearNodeSorters
Enable mouse
EnableMouse
Disable mouse
DisableMouse
Toggle mouse
ToggleMouse
Start piping the focused path to the given fifo path
Type: { StartFifo = "string" }
StartFifo: /tmp/xplr.fifo
Close the active fifo and stop piping.
StopFifo
Toggle betwen {Start|Stop}Fifo
Type: { ToggleFifo = "string" }
ToggleFifo: /path/to/fifo
Log information message.
Type: { LogInfo = "string" }
LogInfo: launching satellite
Log a success message.
Type: { LogSuccess = "String" }
LogSuccess: satellite reached destination
Log an warning message.
Type: { LogWarning = "string" }
LogWarning: satellite is heating
Log an error message.
Type: { LogError = "string" }
LogError: satellite crashed
Write the application state to a file, without quitting. Also helpful +for debugging.
Type: { Debug = "string" }
Debug: /path/to/file
Quit
Quit with returncode zero (success).
Print $PWD and quit.
PrintPwdAndQuit
Print the path under focus and quit. It can be empty string if there's +nothing to focus.
PrintFocusPathAndQuit
Print the selected paths and quit. It can be empty is no path is +selected.
PrintSelectionAndQuit
Print the selected paths if it's not empty, else, print the focused +node's path.
PrintResultAndQuit
Print the state of application in YAML format. Helpful for debugging or +generating the default configuration file.
PrintAppStateAndQuit
Terminate the application with a non-zero return code.
Terminate
xplr is a modal file explorer. That means the users switch between different -modes, each containing a different set of key bindings to avoid clashes. Users -can switch between these modes at run-time.
The modes can be configured using the xplr.config.modes Lua API.
xplr.config.modes
It contains the following fields:
Type: mapping of string and Mode
This is exposed by the xplr.config.modes.builtin API.
xplr.config.modes.builtin
xplr by default provides the following builtin modes:
Visit the Default Key Bindings to see what each mode -does.
This is exposed by the xplr.config.modes.custom API.
xplr.config.modes.custom
It allows the users to define custom modes.
xplr.config.modes.custom.example = { - name = "example", - key_bindings = { - on_key = { - enter = { - help = "default mode", - messages = { - "PopMode", - { SwitchModeBuiltin = "default" } - } - } - } - } -} - -xplr.config.general.initial_mode = "example" - --- when you load xplr, you should be in the "example" mode, --- pressing "enter" should take you to the "default" mode. -
A mode contains the following information:
Type: Key Bindings
The key bindings available in that mode.
Type: nullable Layout
If specified, this layout will be used to render the UI.
This configuration is exposed via the xplr.config.modes API.
A node-type contains the following fields:
A meta field can contain custom metadata about a node. By default, the "icon" +metadata is set for the directory, file, and +symlink nodes.
xplr.config.node_types.file = { + meta = { + icon = "f", + foo = "bar", + } +} +
This configuration is exposed via the xplr.config.node_types API.
xplr.config.node_types
Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy -and paste into your configuration or the appropriate file, that are -too small or too niche for a full fledge plugin.
Do you have something cool to share?
Edit this file or share them here or let us know.
Change directory using xplr.
With this alias set, you can navigate directories using xplr by entering -xcd command, and when you quit by pressing enter, you will enter the -directory.
You can of course, quit with plain Quit (i.e. by pressing q) to -gracefully cancel "cd on quit".
alias xcd='cd "$(xplr --print-pwd-as-result)"' -
Creating a new session that starts with iTerm2.
Key bindings define how each keyboard input will be handled while in a specific +mode.
See the Default key bindings for example.
To configure or work with key bindings, visit Configure Key Bindings.
In case you need help debugging key bindings or to understand the system DYI +way, refer to the Debug Key Bindings guide.
In xplr, each keyboard input passes through a bunch of handlers (e.g. on_key, +on_number, default etc.) in a given order. If any of the handlers is +configured to with an action, it will intercept the key and produce +messages for xplr to handle.
on_key
on_number
Key bindings contains the following information:
xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { - help = "new session", - messages = { - { BashExecSilently = [[ - osascript <<EOF - tell application "iTerm2" - tell current window - create tab with default profile - tell current session to write text "xplr" - end tell - end tell - ]] - }, - }, -} -
Bookmark files using m and fuzzy search bookmarks using backtick.
m
Type: mapping of Key to nullable Action
Defines what to do when an exact key is pressed.
Type: nullable Action
An action to perform if the keyboard input is an alphabet and is not mapped via +the on_key field.
An action to perform if the keyboard input is a number and is not mapped via +the on_key field.
An action to perform if the keyboard input is alphanumeric and is not mapped +via the on_key, on_alphabet or on_number field.
An action to perform if the keyboard input is a special character and is not +mapped via the on_key field.
An action to perform if the keyboard input is a character and is not mapped +via the on_key, on_alphabet, on_number, on_alphanumeric +or on_special_character field.
An action to perform if the keyboard input is a navigation key and is not +mapped via the on_key field.
An action to perform if the keyboard input is a function key and is not mapped +via the on_key field.
Default action to perform in case if a keyboard input not mapped via any of the +on_* fields mentioned above.
on_*
A key can be one of the following:
xplr.config.modes.builtin.default.key_bindings.on_key.m = { - help = "bookmark", - messages = { - { - BashExecSilently = [===[ - PTH="${XPLR_FOCUS_PATH:?}" - if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then - echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" - else - echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===], - }, - }, -} - -xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { - help = "go to bookmark", - messages = { - { - BashExec = [===[ - PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) - if [ "$PTH" ]; then - echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===], - }, - }, -} -
A bookmark mode that allows for a bookmark file to be used throughout multiples -sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A -bookmark can be added, deleted, or jumped to.
$XPLR_BOOKMARK_FILE
And finally, the special characters - including space (" ") with their ctrl +bindings.
" "
ctrl
An action contains the following information:
-- Bookmark: mode binding -xplr.config.modes.custom.bookmark = { - name = "bookmark", +help +Type: nullable string +Description of what it does. If unspecified, it will be excluded from the help +menu. +messages +Type: A list of Message to send. +The list of messages to send when a key is pressed. +Tutorial: Adding a New Mode +Assuming xplr is installed and setup, let's +add our own mode to integrate xplr with fzf. +We'll call it fzxplr mode. +First, let's add a custom mode called fzxplr, and map the key F to an +action that will call fzf to search and focus on a file or enter into a +directory. +xplr.config.modes.custom.fzxplr = { + name = "fzxplr", key_bindings = { on_key = { - m = { - help = "bookmark dir", - messages = { - { BashExecSilently = [[ - PTH="${XPLR_FOCUS_PATH:?}" - if [ -d "${PTH}" ]; then - PTH="${PTH}" - elif [ -f "${PTH}" ]; then - PTH="$(dirname "${PTH}")" - fi - if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then - echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" - else - echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]] - }, - }, - }, - g = { - help = "go to bookmark", + F = { + help = "search", messages = { { BashExec = [===[ - PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) - if [ "$PTH" ]; then - echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi + PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf) + if [ -d "$PTH" ]; then + echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi ]===] }, + "PopMode", }, }, - d = { - help = "delete bookmark", - messages = { - { BashExec = [[ - PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) - sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" - ]] - }, - }, - }, - esc = { - help = "cancel", - messages = { - "PopMode", - }, - }, - }, - }, -} - -
Description of what it does. If unspecified, it will be excluded from the help +menu.
Type: A list of Message to send.
The list of messages to send when a key is pressed.
Assuming xplr is installed and setup, let's +add our own mode to integrate xplr with fzf.
We'll call it fzxplr mode.
fzxplr
First, let's add a custom mode called fzxplr, and map the key F to an +action that will call fzf to search and focus on a file or enter into a +directory.
F
fzf
xplr.config.modes.custom.fzxplr = { + name = "fzxplr", key_bindings = { on_key = { - m = { - help = "bookmark dir", - messages = { - { BashExecSilently = [[ - PTH="${XPLR_FOCUS_PATH:?}" - if [ -d "${PTH}" ]; then - PTH="${PTH}" - elif [ -f "${PTH}" ]; then - PTH="$(dirname "${PTH}")" - fi - if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then - echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" - else - echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]] - }, - }, - }, - g = { - help = "go to bookmark", + F = { + help = "search", messages = { { BashExec = [===[ - PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) - if [ "$PTH" ]; then - echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi + PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf) + if [ -d "$PTH" ]; then + echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi ]===] }, + "PopMode", }, }, - d = { - help = "delete bookmark", - messages = { - { BashExec = [[ - PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) - sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" - ]] - }, - }, - }, - esc = { - help = "cancel", - messages = { - "PopMode", - }, - }, - }, - }, -} -
Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf.
xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { - help = "bookmark jump", - messages = { - "PopMode", - { BashExec = [===[ - field='\(\S\+\s*\)' - esc=$(printf '\033') - N="${esc}[0m" - R="${esc}[31m" - G="${esc}[32m" - Y="${esc}[33m" - B="${esc}[34m" - pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" - PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ - | gsed "${pattern}" \ - | fzf --ansi \ - --height '40%' \ - --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ - --preview-window="right:50%" \ - | sed 's#.*-> ##') - if [ "$PTH" ]; then - echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===] - }, - } -} -
Fuzzy search the last visited directories.
xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { - help = "history", - messages = { - "PopMode", - { - BashExec = [===[ - PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) - if [ "$PTH" ]; then - echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===], }, - }, -} -
Batch rename the selected or visible files and directories in $PWD.
xplr.config.modes.builtin.default.key_bindings.on_key.R = { - help = "batch rename", - messages = { - { - BashExec = [===[ - SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") - NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} - if [ "$NODES" ]; then - echo -e "$NODES" | renamer - echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===], + default = { + messages = { + "PopMode", + }, }, }, }
Serve $PWD using a static web server via LAN.
xplr.config.modes.builtin.default.key_bindings.on_key.S = { - help = "serve $PWD", +As you can see, the key F in mode fzxplr (the name can be anything) +executes a script in bash. +BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath +are messages, $XPLR_PIPE_MSG_IN, +$XPLR_PIPE_DIRECTORY_NODES_OUT are +environment variables exported by xplr +before executing the command. They contain the path to the +input and output pipes that +allows external tools to interact with xplr. +Now that we have our new mode ready, let's add an entry point to this mode via +the default mode. +xplr.config.modes.builtin.default.key_bindings.on_key["F"] = { + help = "fzf mode", messages = { - { - BashExec = [===[ - IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') - echo "IP: ${IP:?}" - read -p "Port (default 5000): " PORT - echo - sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & - sleep 1 && read -p '[press enter to exit]' - kill -9 %1 - ]===], - }, - }, -} - -
As you can see, the key F in mode fzxplr (the name can be anything) +executes a script in bash.
BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath +are messages, $XPLR_PIPE_MSG_IN, +$XPLR_PIPE_DIRECTORY_NODES_OUT are +environment variables exported by xplr +before executing the command. They contain the path to the +input and output pipes that +allows external tools to interact with xplr.
Now that we have our new mode ready, let's add an entry point to this mode via +the default mode.
xplr.config.modes.builtin.default.key_bindings.on_key["F"] = { + help = "fzf mode", messages = { - { - BashExec = [===[ - IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') - echo "IP: ${IP:?}" - read -p "Port (default 5000): " PORT - echo - sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & - sleep 1 && read -p '[press enter to exit]' - kill -9 %1 - ]===], - }, - }, -} -
Key bindings define how each keyboard input will be handled while in a specific -mode.
In case you need help debugging key bindings or to understand the system DYI -way, refer to the Debug Key Bindings guide.
In xplr, each keyboard input passes through a bunch of handlers (e.g. on_key, -on_number, default etc.) in a given order. If any of the handlers is -configured to with an action, it will intercept the key and produce -messages for xplr to handle.
An action to perform if the keyboard input is an alphabet and is not mapped via -the on_key field.
An action to perform if the keyboard input is a number and is not mapped via -the on_key field.
An action to perform if the keyboard input is alphanumeric and is not mapped -via the on_key, on_alphabet or on_number field.
An action to perform if the keyboard input is a special character and is not -mapped via the on_key field.
An action to perform if the keyboard input is a character and is not mapped -via the on_key, on_alphabet, on_number, on_alphanumeric -or on_special_character field.
An action to perform if the keyboard input is a navigation key and is not -mapped via the on_key field.
An action to perform if the keyboard input is a function key and is not mapped -via the on_key field.
Default action to perform in case if a keyboard input not mapped via any of the -on_* fields mentioned above.
And finally, the special characters - including space (" ") with their ctrl -bindings.
Description of what it does. If unspecified, it will be excluded from the help -menu.
Assuming xplr is installed and setup, let's -add our own mode to integrate xplr with fzf.
First, let's add a custom mode called fzxplr, and map the key F to an -action that will call fzf to search and focus on a file or enter into a -directory.
xplr.config.modes.custom.fzxplr = { - name = "fzxplr", - key_bindings = { - on_key = { - F = { - help = "search", - messages = { - { - BashExec = [===[ - PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf) - if [ -d "$PTH" ]; then - echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - else - echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" - fi - ]===] - }, - "PopMode", - }, - }, - }, - default = { - messages = { - "PopMode", - }, - }, - }, -} -
As you can see, the key F in mode fzxplr (the name can be anything) -executes a script in bash.
BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath -are messages, $XPLR_PIPE_MSG_IN, -$XPLR_PIPE_DIRECTORY_NODES_OUT are -environment variables exported by xplr -before executing the command. They contain the path to the -input and output pipes that -allows external tools to interact with xplr.
Now that we have our new mode ready, let's add an entry point to this mode via -the default mode.
xplr.config.modes.builtin.default.key_bindings.on_key["F"] = { - help = "fzf mode", - messages = { - { SwitchModeCustom = "fzxplr" }, + { SwitchModeCustom = "fzxplr" }, }, }
xplr.config.modes.custom.example = { - name = "example", - key_bindings = { - on_key = { - enter = { - help = "default mode", - messages = { - "PopMode", - { SwitchModeBuiltin = "default" } - } +Node Type +A node-type contains the following fields: + +meta +style + +meta +Type: mapping of string and string +A meta field can contain custom metadata about a node. By default, the "icon" +metadata is set for the directory, file, and +symlink nodes. +Example: +xplr.config.node_types.file = { + meta = { + icon = "f", + foo = "bar", + } +} + +Also See: + +xplr.config.node_types + +Layout +Example: Defining Custom Layout + +xplr.config.layouts.builtin.default = { + Horizontal = { + config = { + margin = 1, + horizontal_margin = 2, + vertical_margin = 3, + constraints = { + { Percentage = 50 }, + { Percentage = 50 }, } + }, + splits = { + "Table", + "HelpMenu", } } } - -xplr.config.general.initial_mode = "example" - --- when you load xplr, you should be in the "example" mode, --- pressing "enter" should take you to the "default" mode. -Mode -A mode contains the following information: +A layout can be one of the following: -name -help -extra_help -key_bindings -layout +"Nothing" +"Table" +"InputAndLogs" +"Selection" +"HelpMenu" +"SortAndFilter" +{ CustomContent = { title, body } +{ Horizontal = { config, splits } +{ Vertical = { config, splits } -name -Type: string -This is the name of the mode visible in the help menu. -help -Type: nullable string -If specified, the help menu will display this instead of the auto generated -mappings. -extra_help -Type: nullable string -If specified, the help menu will display this along-side the auto generated -help menu. -key_bindings -Type: Key Bindings -The key bindings available in that mode. -layout -Type: nullable Layout -If specified, this layout will be used to render the UI. -Message -You can think of xplr as a server. Just like web servers listen to HTTP -requests, xplr listens to messages. -You can send these messages to an xplr session in the following ways: +Nothing +This layout contains a blank panel. +Table +This layout contains the table displaying the files and directories in the +current directory. +InputAndLogs +This layout contains the panel displaying the input prompt and logs. +Selection +This layout contains the panel displaying the selected paths. +HelpMenu +This layout contains the panel displaying the help menu for the current mode in +real-time. +SortAndFilter +This layout contains the panel displaying the pipeline of sorters and filters +applied of the list of paths being displayed. +Horizontal +This is a special layout that splits the panel into two horizontal parts. +It contains the following information: -Via command-line (currently during start-up only, using --on-load) -Via key bindings -Via Lua function calls -Via shell command using the input pipe -Via socket (coming soon) +config +splits -Format -To send messages using the key bindings or -Lua function calls, messages are represented in -Lua syntax. For example: +Vertical +This is a special layout that splits the panel into two vertical parts. +It contains the following information: -"Quit" -{ FocusPath = "/path/to/file" } -{ Call = { command = "bash", args = { "-c", "read -p test" } } } +config +splits -However, to send messages using the input pipe, they need to be -represented using -YAML (or JSON) syntax. For example: +Layout Config +A layout config contains the following information: -Quit -FocusPath: "/path/to/file" -Call: { command: bash, args: ["-c", "read -p test"] } +margin +horizontal_margin +vertical_margin +constraints -Full List of Messages -"ExplorePwd" -YAML: ExplorePwd -Explore the present working directory and register the filtered nodes. -This operation is expensive. So, try to avoid using it too often. -"ExplorePwdAsync" -YAML: ExplorePwdAsync -Explore the present working directory and register the filtered nodes asynchronously. -This operation happens asynchronously. That means, the xplr directory buffers won't be updated -immediately. Hence, it needs to be used with care and probably with special checks in place. -To explore $PWD synchronously, use ExplorePwd instead. -"ExploreParentsAsync" -YAML: ExploreParentsAsync -Explore the present working directory along with its parents and register the filtered nodes. -This operation happens asynchronously. That means, the xplr directory buffers won't be updated -immediately. Hence, it needs to be used with care and probably with special checks in place. -To explore just the $PWD synchronously, use ExplorePwd instead. -"Refresh" -YAML: Refresh -Refresh the UI. -But it will not re-explore the directory if the working directory is the same. -If there is some change in the working directory and you want to re-explore it, -use the Explore message instead. -Also, it will not clear the screen. Use ClearScreen for that. -"ClearScreen" -YAML: ClearScreen -Clears the screen. -"FocusNext" -YAML: FocusNext -Focus next node. -{ FocusNextByRelativeIndex = int } -YAML: FocusNextByRelativeIndex: int -Focus on the nth node relative to the current focus where n is a given value. -YAML Example: FocusNextByRelativeIndex: 2 -Lua Example: { FocusNextByRelativeIndex = 2 } -"FocusNextByRelativeIndexFromInput" -YAML: FocusNextByRelativeIndexFromInput -Focus on the nth node relative to the current focus where n is read from -the input buffer. -"FocusPrevious" -YAML: FocusPrevious -Focus on the previous item. -{ FocusPreviousByRelativeIndex = int } -YAML: FocusPreviousByRelativeIndex: int -Focus on the -nth node relative to the current focus where n is a given value. -YAML Example: FocusPreviousByRelativeIndex: 2 -Lua Example: { FocusPreviousByRelativeIndex = 2 } -"FocusPreviousByRelativeIndexFromInput" -YAML: FocusPreviousByRelativeIndexFromInput -Focus on the -nth node relative to the current focus where n is read from -the input buffer. -"FocusFirst" -YAML: FocusFirst -Focus on the first node. -"FocusLast" -YAML: FocusLast -Focus on the last node. -{ FocusPath = "string" } -YAML: FocusPath: string -Focus on the given path. -YAML Example: FocusPath: /path/to/file -Lua Example: { FocusPath = "/path/to/file" } -"FocusPathFromInput" -YAML: FocusPathFromInput -Focus on the path read from input buffer. -{ FocusByIndex = int } -YAML: FocusByIndex: int -Focus on the absolute nth node where n is a given value. -YAML Example: FocusByIndex: 2 -Lua Example: { FocusByIndex = 2 } -"FocusByIndexFromInput" -YAML: FocusByIndexFromInput -Focus on the absolute nth node where n is read from the input buffer. -{ FocusByFileName = "string" } -YAML: FocusByFileName: string -Focus on the file by name from the present working directory. -YAML Example: FocusByFileName: filename.ext -Lua Example: { FocusByFileName = "filename.ext" } -{ ChangeDirectory = "string" } -YAML: ChangeDirectory: string -Change the present working directory ($PWD) -YAML Example: ChangeDirectory: /path/to/directory -Lua Example: { ChangeDirectory = "/path/to/directory" } -"Enter" -YAML: Enter -Enter into the currently focused path if it's a directory. -"Back" -YAML: Back -Go back to the parent directory. -"LastVisitedPath" -YAML: LastVisitedPath -Go to the last path visited. -"NextVisitedPath" -YAML: NextVisitedPath -Go to the next path visited. -"FollowSymlink" -YAML: FollowSymlink -Follow the symlink under focus to its actual location. -{ UpdateInputBuffer = Input Opertaion }
xplr.config.layouts.builtin.default = { + Horizontal = { + config = { + margin = 1, + horizontal_margin = 2, + vertical_margin = 3, + constraints = { + { Percentage = 50 }, + { Percentage = 50 }, } + }, + splits = { + "Table", + "HelpMenu", } } } - -xplr.config.general.initial_mode = "example" - --- when you load xplr, you should be in the "example" mode, --- pressing "enter" should take you to the "default" mode.
This is the name of the mode visible in the help menu.
If specified, the help menu will display this instead of the auto generated -mappings.
If specified, the help menu will display this along-side the auto generated -help menu.
You can think of xplr as a server. Just like web servers listen to HTTP -requests, xplr listens to messages.
This layout contains a blank panel.
This layout contains the table displaying the files and directories in the +current directory.
This layout contains the panel displaying the input prompt and logs.
This layout contains the panel displaying the selected paths.
This layout contains the panel displaying the help menu for the current mode in +real-time.
This layout contains the panel displaying the pipeline of sorters and filters +applied of the list of paths being displayed.
This is a special layout that splits the panel into two horizontal parts.
To send messages using the key bindings or -Lua function calls, messages are represented in -Lua syntax. For example:
This is a special layout that splits the panel into two vertical parts.
However, to send messages using the input pipe, they need to be -represented using -YAML (or JSON) syntax. For example:
A layout config contains the following information:
YAML: ExplorePwd
Explore the present working directory and register the filtered nodes. -This operation is expensive. So, try to avoid using it too often.
YAML: ExplorePwdAsync
Explore the present working directory and register the filtered nodes asynchronously. -This operation happens asynchronously. That means, the xplr directory buffers won't be updated -immediately. Hence, it needs to be used with care and probably with special checks in place. -To explore $PWD synchronously, use ExplorePwd instead.
YAML: ExploreParentsAsync
Explore the present working directory along with its parents and register the filtered nodes. -This operation happens asynchronously. That means, the xplr directory buffers won't be updated -immediately. Hence, it needs to be used with care and probably with special checks in place. -To explore just the $PWD synchronously, use ExplorePwd instead.
YAML: Refresh
Refresh the UI. -But it will not re-explore the directory if the working directory is the same. -If there is some change in the working directory and you want to re-explore it, -use the Explore message instead. -Also, it will not clear the screen. Use ClearScreen for that.
YAML: ClearScreen
Clears the screen.
YAML: FocusNext
YAML: FocusNextByRelativeIndex: int
FocusNextByRelativeIndex: int
Focus on the nth node relative to the current focus where n is a given value.
YAML Example: FocusNextByRelativeIndex: 2
Lua Example: { FocusNextByRelativeIndex = 2 }
{ FocusNextByRelativeIndex = 2 }
YAML: FocusNextByRelativeIndexFromInput
Focus on the nth node relative to the current focus where n is read from -the input buffer.
YAML: FocusPrevious
YAML: FocusPreviousByRelativeIndex: int
FocusPreviousByRelativeIndex: int
Focus on the -nth node relative to the current focus where n is a given value.
YAML Example: FocusPreviousByRelativeIndex: 2
Lua Example: { FocusPreviousByRelativeIndex = 2 }
YAML: FocusPreviousByRelativeIndexFromInput
Focus on the -nth node relative to the current focus where n is read from -the input buffer.
YAML: FocusFirst
YAML: FocusLast
YAML: FocusPath: string
FocusPath: string
YAML Example: FocusPath: /path/to/file
Lua Example: { FocusPath = "/path/to/file" }
YAML: FocusPathFromInput
YAML: FocusByIndex: int
FocusByIndex: int
YAML Example: FocusByIndex: 2
Lua Example: { FocusByIndex = 2 }
{ FocusByIndex = 2 }
YAML: FocusByIndexFromInput
YAML Example: FocusByFileName: filename.ext
Lua Example: { FocusByFileName = "filename.ext" }
{ FocusByFileName = "filename.ext" }
YAML: ChangeDirectory: string
ChangeDirectory: string
YAML Example: ChangeDirectory: /path/to/directory
Lua Example: { ChangeDirectory = "/path/to/directory" }
{ ChangeDirectory = "/path/to/directory" }
YAML: Enter
YAML: Back
YAML: LastVisitedPath
YAML: NextVisitedPath
YAML: FollowSymlink
YAML: BufferInput: Input Operation
BufferInput: Input Operation
YAML Example: UpdateInputBuffer: GoToPreviousWord
Lua Example: { UpdateInputBuffer = "GoToPreviousWord" }
{ UpdateInputBuffer = "GoToPreviousWord" }
YAML: UpdateInputBufferFromKey
YAML: BufferInput: string
BufferInput: string
YAML Example: BufferInput: foo
Lua Example: { BufferInput = "foo" }
{ BufferInput = "foo" }
YAML: BufferInputFromKey
Append/buffer the characted read from a keyboard input into the -input buffer.
YAML: SetInputBuffer: string
SetInputBuffer: string
Set/rewrite the input buffer with the given string. -When the input buffer is not-null (even if empty string) -it will show in the UI.
YAML Example: SetInputBuffer: foo
Lua Example: { SetInputBuffer = "foo" }
{ SetInputBuffer = "foo" }
YAML: RemoveInputBufferLastCharacter
YAML: RemoveInputBufferLastWord
YAML: ResetInputBuffer
YAML: SwitchMode: string
SwitchMode: string
Switch input mode. -It clears the input buffer.
-NOTE: To be specific about which mode to switch to, use SwitchModeBuiltin or -SwitchModeCustom instead. -
NOTE: To be specific about which mode to switch to, use SwitchModeBuiltin or -SwitchModeCustom instead.
SwitchModeCustom
YAML Example: SwitchMode: default
SwitchMode: default
Lua Example: { SwitchMode = "default" }
{ SwitchMode = "default" }
YAML: SwitchModeKeepingInputBuffer: string
SwitchModeKeepingInputBuffer: string
Switch input mode. -It keeps the input buffer.
-NOTE: To be specific about which mode to switch to, use -SwitchModeBuiltinKeepingInputBuffer or -SwitchModeCustomKeepingInputBuffer instead. -
NOTE: To be specific about which mode to switch to, use -SwitchModeBuiltinKeepingInputBuffer or -SwitchModeCustomKeepingInputBuffer instead.
YAML Example: SwitchModeKeepingInputBuffer: default
Lua Example: { SwitchModeKeepingInputBuffer = "default" }
{ SwitchModeKeepingInputBuffer = "default" }
YAML: SwitchModeBuiltin: string
SwitchModeBuiltin: string
Switch to a builtin mode. -It clears the input buffer.
YAML Example: SwitchModeBuiltin: default
Lua Example: { SwitchModeBuiltin = "default" }
{ SwitchModeBuiltin = "default" }
YAML: SwitchModeBuiltinKeepingInputBuffer: string
SwitchModeBuiltinKeepingInputBuffer: string
Switch to a builtin mode. -It keeps the input buffer.
YAML Example: SwitchModeBuiltinKeepingInputBuffer: default
Lua Example: { SwitchModeBuiltinKeepingInputBuffer = "default" }
{ SwitchModeBuiltinKeepingInputBuffer = "default" }
YAML: SwitchModeCustom: string
SwitchModeCustom: string
Switch to a custom mode. -It clears the input buffer.
YAML Example: SwitchModeCustom: my_custom_mode
Lua Example: { SwitchModeCustom = "my_custom_mode" }
{ SwitchModeCustom = "my_custom_mode" }
Switch to a custom mode. -It keeps the input buffer.
YAML Example: SwitchModeCustomKeepingInputBuffer: my_custom_mode
Lua Example: { SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
{ SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
YAML: PopMode
Pop the last mode from the history and switch to it. -It clears the input buffer.
YAML: PopModeKeepingInputBuffer
Pop the last mode from the history and switch to it. -It keeps the input buffer.
YAML: SwitchLayout: string
SwitchLayout: string
-NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or -SwitchLayoutCustom instead. -
NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or -SwitchLayoutCustom instead.
YAML Example: SwitchLayout: default
Lua Example: { SwitchLayout = "default" }
{ SwitchLayout = "default" }
YAML: SwitchLayoutBuiltin: string
SwitchLayoutBuiltin: string
YAML Example: SwitchLayoutBuiltin: default
Lua Example: { SwitchLayoutBuiltin = "default" }
{ SwitchLayoutBuiltin = "default" }
YAML: SwitchLayoutCustom: string
SwitchLayoutCustom: string
YAML Example: SwitchLayoutCustom: my_custom_layout
Lua Example: { SwitchLayoutCustom = "my_custom_layout" }
{ SwitchLayoutCustom = "my_custom_layout" }
YAML: Call: string
Call: string
Call a shell command with the given arguments. -Note that the arguments will be shell-escaped. -So to read the variables, the -c option of the shell -can be used. -You may need to pass ExplorePwd depening on the expectation.
YAML Example: Call: { command: bash, args: ["-c", "read -p test"] }
Lua Example: { Call = { command = "bash", args = { "-c", "read -p test" } } }
{ Call = { command = "bash", args = { "-c", "read -p test" } } }
YAML: CallSilently: string
CallSilently: string
Like Call but without the flicker. The stdin, stdout -stderr will be piped to null. So it's non-interactive.
YAML Example: CallSilently: { command: tput, args: ["bell"] }
Lua Example: { CallSilently = { command = "tput", args = { "bell" } } }
YAML: BashExec: string
BashExec: string
An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false} -where {string} is the given value.
YAML Example: BashExec: "read -p test"
Lua Example: { BashExec = "read -p test" }
{ BashExec = "read -p test" }
YAML: BashExecSilently(String)
BashExecSilently(String)
Like BashExec but without the flicker. The stdin, stdout -stderr will be piped to null. So it's non-interactive.
YAML Example: BashExecSilently: "tput bell"
Lua Example: { BashExecSilently = "tput bell" }
{ BashExecSilently = "tput bell" }
YAML: CallLua: string
CallLua: string
A Lua Context object will be passed to the function as argument. -The function can optionally return a list of messages for xplr to handle -after the executing the function.
YAML Example: CallLua: custom.some_custom_funtion
Lua Example: { CallLua = "custom.some_custom_funtion" }
{ CallLua = "custom.some_custom_funtion" }
YAML: CallLuaSilently: string
CallLuaSilently: string
Like CallLua but without the flicker. The stdin, stdout -stderr will be piped to null. So it's non-interactive.
YAML Example: CallLuaSilently: custom.some_custom_function
Lua Example: { CallLuaSilently = "custom.some_custom_function" }
{ CallLuaSilently = "custom.some_custom_function" }
YAML: LuaEval: string
LuaEval: string
If the string is a callable, xplr will try to call it with with the -Lua Context argument.
YAML Example: LuaEval: "return { { LogInfo = io.read() } }" -YAML Example: LuaEval: "function(app) return { { LogInfo = app.pwd } } end"
Lua Example: { LuaEval = [[return { { LogInfo = io.read() } }]] } -Lua Example: { LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
{ LuaEval = [[return { { LogInfo = io.read() } }]] }
{ LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
YAML: LuaEvalSilently: string
LuaEvalSilently: string
Like LuaEval but without the flicker. The stdin, stdout -stderr will be piped to null. So it's non-interactive.
YAML Example: LuaEvalSilently: "return { { LogInfo = 'foo' } }"
Lua Example: { LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
{ LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
YAML: Select
YAML: SelectAll
YAML: SelectPath: string
SelectPath: string
YAML Example: SelectPath: /path/to/file
Lua Example: { SelectPath = "/path/to/file" }
{ SelectPath = "/path/to/file" }
YAML: UnSelect
YAML: UnSelectAll
YAML: UnSelectPath: string
UnSelectPath: string
YAML Example: UnSelectPath: /path/to/file
Lua Example: { UnSelectPath = "/path/to/file" }
{ UnSelectPath = "/path/to/file" }
YAML: ToggleSelection
YAML: ToggleSelectAll
Toggle between select all and unselect all.
YAML: ToggleSelectionByPath: string
ToggleSelectionByPath: string
YAML Example: ToggleSelectionByPath: /path/to/file
Lua Example: { ToggleSelectionByPath = "/path/to/file" }
{ ToggleSelectionByPath = "/path/to/file" }
YAML: ClearSelection
YAML: AddNodeFilter: { filter = Filter, input = string }
AddNodeFilter: { filter = Filter, input = string }
Add a filter to exclude nodes while exploring directories.
YAML Example: AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
{ AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
YAML: RemoveNodeFilter: { filter = Filter, input = string
RemoveNodeFilter: { filter = Filter, input = string
YAML Example: RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
{ RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
YAML: ToggleNodeFilter: { filter = Filter, input = string }
ToggleNodeFilter: { filter = Filter, input = string }
Remove a filter if it exists, else, add a it.
YAML Example: ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
{ ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
YAML: AddNodeFilterFromInput: Filter
AddNodeFilterFromInput: Filter
Add a node filter reading the input from the buffer.
YAML Example: AddNodeFilterFromInput: RelativePathDoesStartWith
Lua Example: { AddNodeFilterFromInput = "RelativePathDoesStartWith" }
{ AddNodeFilterFromInput = "RelativePathDoesStartWith" }
YAML: RemoveNodeFilterFromInput: Filter
RemoveNodeFilterFromInput: Filter
Remove a node filter reading the input from the buffer.
YAML Example: RemoveNodeFilterFromInput: RelativePathDoesStartWith
Lua Example: { RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
{ RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
YAML: RemoveLastNodeFilter
YAML: ResetNodeFilters
Reset the node filters back to the default configuration.
YAML: ClearNodeFilters
YAML: AddNodeSorter: { sorter: Sorter, reverse = bool }
AddNodeSorter: { sorter: Sorter, reverse = bool }
Add a sorter to sort nodes while exploring directories.
YAML Example: AddNodeSorter: { sorter: ByRelativePath, reverse: false }
YAML Example: { AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
{ AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
YAML: RemoveNodeSorter: Sorter
RemoveNodeSorter: Sorter
YAML Example: RemoveNodeSorter: ByRelativePath
Lua Example: { RemoveNodeSorter = "ByRelativePath" }
{ RemoveNodeSorter = "ByRelativePath" }
YAML: ReverseNodeSorter: Sorter
ReverseNodeSorter: Sorter
YAML Example: ReverseNodeSorter: ByRelativePath
Lua Example: { ReverseNodeSorter = "ByRelativePath" }
{ ReverseNodeSorter = "ByRelativePath" }
YAML: ToggleNodeSorter: { sorter: Sorter, reverse = bool }
ToggleNodeSorter: { sorter: Sorter, reverse = bool }
Remove a sorter if it exists, else, add a it.
YAML Example: ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }
Lua Example: { ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
{ ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
YAML: ReverseNodeSorters
YAML: RemoveLastNodeSorter
YAML: ResetNodeSorters
Reset the node sorters back to the default configuration.
YAML: ClearNodeSorters
YAML: EnableMouse
YAML: DisableMouse
YAML: ToggleMouse
YAML: StartFifo: string
StartFifo: string
YAML Example: StartFifo: /tmp/xplr.fifo
Lua Example: { StartFifo = "/tmp/xplr.fifo }
{ StartFifo = "/tmp/xplr.fifo }
YAML: StopFifo
YAML: ToggleFifo: string
ToggleFifo: string
YAML Example: ToggleFifo: /path/to/fifo
Lua Example: { ToggleFifo = "/path/to/fifo" }
{ ToggleFifo = "/path/to/fifo" }
YAML: LogInfo: string
LogInfo: string
YAML Example: LogInfo: launching satellite
Lua Example: { LogInfo = "launching satellite" }
{ LogInfo = "launching satellite" }
YAML: LogSuccess: string
LogSuccess: string
YAML Example: LogSuccess: satellite reached destination.
Lua Example: { LogSuccess = "satellite reached destination" }.
{ LogSuccess = "satellite reached destination" }
YAML: LogWarning: string
LogWarning: string
YAML Example: LogWarning: satellite is heating
Lua Example: { LogWarning = "satellite is heating" }
{ LogWarning = "satellite is heating" }
YAML: LogError: string
LogError: string
YAML Example: LogError: satellite crashed
Lua Example: { LogError = "satellite crashed" }
{ LogError = "satellite crashed" }
YAML: Quit
YAML: PrintPwdAndQuit
YAML: PrintFocusPathAndQuit
Print the path under focus and quit. It can be empty string if there's nothing to focus.
YAML: PrintSelectionAndQuit
Print the selected paths and quit. It can be empty is no path is selected.
YAML: PrintResultAndQuit
Print the selected paths if it's not empty, else, print the focused node's path.
YAML: PrintAppStateAndQuit
Print the state of application in YAML format. Helpful for debugging or generating -the default configuration file.
YAML: Debug: string
Debug: string
Write the application state to a file, without quitting. Also helpful for debugging.
YAML Example: Debug: /path/to/file
Lua Example: { Debug = "/path/to/file" }
{ Debug = "/path/to/file" }
YAML: Terminate
Type: nullable integer
The width of the margin in all direction.
The width of the horizontal margins. Overwrites the margin value.
The width of the vertical margins. Overwrites the margin value.
Type: nullable list of Constraint
The constraints applied on the layout.
A constraint can be one of the following:
xplr allows users to define lua functions using the xplr.fn.custom Lua API.
When called the function receives a special argument that -contains some useful information. The function can optionally return a list of -messages which will be handled by xplr.
This is a special argument passed to the lua functions when called using the -CallLua, CallLuaSilently messages.
TODO: document each constraint.
Type: list of Layout
The list of child layouts to fit into the parent layout.
Custom content is a special layout to render something custom. +It contains the following information:
The title of the panel.
Type: Content Body
The body of the panel.
Content body can be one of the following:
A paragraph to render. It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { + StaticParagraph = { render = "custom body" }, + }, + }, +} +
A Lua function to render a custom paragraph. +It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { DynamicParagraph = { render = "custom.render_layout" } }, + }, +} + +xplr.fn.custom.render_layout = function(ctx) + return ctx.app.pwd +end +
A list to render. It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { + StaticList = { render = { "1", "2", "3" } }, + }, + }, +} +
A Lua function to render a custom list. +It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { DynamicList = { render = "custom.render_layout" } }, + }, +} + +xplr.fn.custom.render_layout = function(ctx) + return { + ctx.app.pwd, + ctx.app.version, + tostring(ctx.app.pid), + } +end +
A table to render. It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { + StaticTable = { + widths = { + { Percentage = 50 }, + { Percentage = 50 }, + }, + col_spacing = 1, + render = { + { "a", "b" }, + { "c", "d" }, + }, + }, + }, + }, +} +
A Lua function to render a custom table. +It contains the following fields:
xplr.config.layouts.builtin.default = { + CustomContent = { + title = "custom title", + body = { + DynamicTable = { + widths = { + { Percentage = 50 }, + { Percentage = 50 }, + }, + col_spacing = 1, + render = "custom.render_layout", + }, + }, + }, +} + +xplr.fn.custom.render_layout = function(ctx) + return { + { "", "" }, + { "Layout height", tostring(ctx.layout_size.height) }, + { "Layout width", tostring(ctx.layout_size.width) }, + { "", "" }, + { "Screen height", tostring(ctx.screen_size.height) }, + { "Screen width", tostring(ctx.screen_size.width) }, + } +end +
It is a Lua function that receives a special argument as input and +returns some output that can be rendered in the UI. It is used to render +content body for the custom dynamic layouts.
This is a lightweight version of the Lua Context. In this context, the +heavyweight fields like directory_buffer are omitted for performance +reasons.
If specified, the help menu will display this instead of the auto generated +mappings.
If specified, the help menu will display this along-side the auto generated +help menu.
xplr allows customizing the shape and style of the borders.
A border can be one of the following:
xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" } +xplr.config.general.panel_ui.default.border_type = "Thick" +xplr.config.general.panel_ui.default.border_style.fg = "Black" +xplr.config.general.panel_ui.default.border_style.bg = "Gray" +
A style object contains the following information:
Type: nullable Color
The foreground color.
The background color.
Type: nullable list of Modifier
Modifiers to add.
Modifiers to remove.
Color can be one of the following:
Modifier can be one of the following:
xplr.config.general.prompt.style.fg = "Red" +xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } } +xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" } +xplr.config.general.prompt.style.sub_modifiers = { "Hidden" } +
xplr supports sorting paths by different properties. The sorting mechanism +works like a pipeline, which in visible in the Sort & filter panel.
Sort & filter
size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +
This line means that the nodes visible in the table will be first sorted by +it's size, then by case insensitive relative path, then by the +canonical (symlink resolved) type of the node, and finally by whether or not +the node is a symlink.
The arrows denote the order.
Each part of this pipeline is called Node Sorter Applicable.
A sorter can be one of the following:
TODO: document each
It defined the direction of the order.
xplr.config.general.initial_sorting = { + { sorter = "ByCanonicalIsDir", reverse = true }, + { sorter = "ByIRelativePath", reverse = false }, +} +
This snippet defines the initial sorting logic to be applied when xplr loads.
xplr supports filtering paths by different properties. The filtering mechanism +works like a pipeline, which in visible in the Sort & filter panel.
rel!^. › [i]abs=~abc › [i]rel!~xyz +
This line means that the nodes visible on the table will first be filtered by +the condition: relative path does not start with ., then by the condition: +absolute path contains abc (case insensitive), and finally by the +condition: relative path does not contain xyz (case insensitive).
.
abc
xyz
Each part of this pipeline is called Node Filter Applicable.
A filter can be one of the following:
The input for the condition.
ToggleNodeFilter = { + filter = "RelativePathDoesNotStartWith", + input = "." +} +
Here, ToggleNodeFilter is a message that adds or removes +(toggles) the filter applied.
ToggleNodeFilter
A column renderer is a Lua function that receives a special argument and +returns a string that will be displayed in each specific field of the +files table.
xplr.fn.builtin.fmt_general_table_row_cols_1
xplr.fn.builtin.fmt_general_table_row_cols_2
xplr.fn.builtin.fmt_general_table_row_cols_3
xplr.fn.builtin.fmt_general_table_row_cols_4
You can either overwrite these functions, or create new functions in +xplr.fn.custom and point to them.
Terminal colors are supported.
The special argument contains the following fields
The size of the exact node. The size of a directory won't be calculated recursively.
If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.
The index of the node under focus. It can be 0 even when there's no node to -focus on.
-- Define the function -xplr.fn.custom.ask_name_and_greet = function(app) - print("What's your name?") - - local name = io.read() - local greeting = "Hello " .. name .. "!" - local message = greeting .. " You are inside " .. app.pwd - - return { - { LogSuccess = message }, - } -end - --- Map the function to a key (space) -xplr.config.modes.builtin.default.key_bindings.on_key.space = { - help = "ask name and greet", - messages = { - { CallLua = "custom.ask_name_and_greet" } - } -} - --- 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. -
Alternative to CallLua, CallLuaSilently messages that call Lua functions, -there are Call, CallSilently, BashExec, BashExecSilently messages -that call shell commands.
However, unlike the Lua functions, these shell commands have to read the useful -information and send messages via environment variables and temporary files -called "pipe"s. These environment variables and files are only available when -a command is being executed.
Visit the fzf integration tutorial -for example.
To see the environment variables, invoke the shell by typing :! in default -mode and run the following command:
env | grep ^XPLR_ -
XPLR_FOCUS_INDEX=0 -XPLR_MODE=action to -XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out -XPLR_INPUT_BUFFER= -XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out -XPLR_PID=122278 -XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in -XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out -XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out -XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out -XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book -XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278 -XPLR_APP_VERSION=0.14.3 -XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out -
The environment variables starting with XPLR_PIPE_ are the temporary files -called "pipe"s.
XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be -exposed directly via environment variables, like multi-line string.
Append new-line delimited messages to this pipe in YAML -(or JSON) syntax. These messages will be read and -handled by xplr after the command execution.
New-line delimited list of paths, filtered and sorted as displayed in the -files table.
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. -
xplr.config.layouts.builtin.default = { - Horizontal = { - config = { - margin = 1, - horizontal_margin = 2, - vertical_margin = 3, - constraints = { - { Percentage = 50 }, - { Percentage = 50 }, - } - }, - splits = { - "Table", - "HelpMenu", - } - } -} -
This layout contains the table displaying the files and directories in the -current directory.
This layout contains the panel displaying the help menu for the current mode in -real-time.
This layout contains the panel displaying the pipeline of sorters and filters -applied of the list of paths being displayed.
Custom content is a special layout to render something custom. -It contains the following information:
Index (starting from 0) of the node.
Relative index from the focused node (i.e. 0th node).
true if the node is before the focused node.
true if the node is after the focused node.
The tree component based on the node's index.
The prefix applicable for the node.
The suffix applicable for the node.
true if the node is selected.
true if the node is under focus.
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - StaticParagraph = { render = "custom body" }, - }, - }, -} -
A Lua function to render a custom paragraph. -It contains the following fields:
Each field holds a boolean value.
It contains the following fields.
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { DynamicParagraph = { render = "custom.render_layout" } }, - }, -} - -xplr.fn.custom.render_layout = function(ctx) - return ctx.app.pwd +Example: Customizing Table Renderer +xplr.fn.custom.fmt_simple_column = function(m) + return m.prefix .. m.relative_path .. m.suffix end - -Static List -A list to render. It contains the following fields: - -render (list of string): The list to render. - -Example: Render a custom static list -xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - StaticList = { render = { "1", "2", "3" } }, - }, - }, -} - -Dynamic List -A Lua function to render a custom list. -It contains the following fields: - -render (string): The lua function that returns the list to render. - -Example: Render a custom dynamic list -xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { DynamicList = { render = "custom.render_layout" } }, - }, + +xplr.config.general.table.header.cols = { + { format = " path" } } -xplr.fn.custom.render_layout = function(ctx) - return { - ctx.app.pwd, - ctx.app.version, - tostring(ctx.app.pid), - } -end - -Static Table -A table to render. It contains the following fields: - -widths (list of Constraint): Width of the columns. -col_spacing (nullable int): Spacing between columns. Defaults to 1. -render (list of list of string): The rows and columns to render. - -Example: Render a custom static table -xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - StaticTable = { - widths = { - { Percentage = 50 }, - { Percentage = 50 }, - }, - col_spacing = 1, - render = { - { "a", "b" }, - { "c", "d" }, - }, - }, - }, - }, +xplr.config.general.table.row.cols = { + { format = "custom.fmt_simple_column" } } - -Dynamic Table -A Lua function to render a custom table. -It contains the following fields: - -widths (list of Constraint): Width of the columns. -col_spacing (nullable int): Spacing between columns. Defaults to 1. -render (string): The lua function that returns the table to render. - -Example: Render a custom dynamic table -xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - DynamicTable = { - widths = { - { Percentage = 50 }, - { Percentage = 50 }, - }, - col_spacing = 1, - render = "custom.render_layout", - }, - }, - }, + +xplr.config.general.table.col_widths = { + { Percentage = 100 } } -xplr.fn.custom.render_layout = function(ctx) - return { - { "", "" }, - { "Layout height", tostring(ctx.layout_size.height) }, - { "Layout width", tostring(ctx.layout_size.width) }, - { "", "" }, - { "Screen height", tostring(ctx.screen_size.height) }, - { "Screen width", tostring(ctx.screen_size.width) }, - } -end +-- With this config, you should only see a single column displaying the +-- relative paths. -Content Renderer -It is a Lua function that receives a special argument as input and -returns some output that can be rendered in the UI. It is used to render -content body for the custom dynamic layouts. -Content Renderer Argument +Lua Function Calls +xplr allows you to define lua functions using the xplr.fn.custom Lua API. +These functions can be called using messages like CallLua, CallLuaSilently. +When called the function receives a special argument that +contains some useful information. The function can optionally return a list of +messages which will be handled by xplr. +Lua Context +This is a special argument passed to the lua functions when called using the +CallLua, CallLuaSilently messages. It contains the following information: -layout_size -screen_size -app +version +pwd +focused_node +directory_buffer +selection +mode +layout +input_buffer +pid +session_path +explorer_config +history +last_modes + +version +Type: string +xplr version. Can be used to test compatibility. +pwd +Type: string +The present working directory/ +focused_node +Type: nullable Node +The node under focus. +directory_buffer +Type: nullable Directory Buffer +The directory buffer being rendered. +selection +Type: list of selected Nodes +The selected nodes. +mode +Type: Mode +Current mode. +layout +Type: Layout +Current layout. +input_buffer +Type: nullable string +The input buffer. +pid +Type: integer +The xplr session PID. +session_path +Type: string +The session path. +explorer_config +TODO +history +Type: History +last_modes +Type: list of Mode +Last modes, not popped yet. +parent +Type: string +The parent path of the node. +relative_path +Type: string +The path relative to the parent, i.e. the file/directory name with extension. +absolute_path +Type: string +The absolute path (without resolving symlinks) of the node. +extension +Type: string +The extension of the node. +is_symlink +Type: boolean +true if the node is a symlink. +is_broken +Type: boolean +true if the node is a broken symlink. +is_dir +Type: boolean +true if the node is a directory. +is_file +Type: boolean +true if the node is a file. +is_readonly +Type: boolean +true if the node is real-only. +mime_essence +Type: string +The mime type of the node. For e.g. text/csv, image/jpeg etc. +size +Type: integer +The size of the exact node. The size of a directory won't be calculated +recursively. +human_size +Type: string +Like size but in human readable format. +permissions +Type: Permission +The permissions applied to the node. +canonical +Type: nullable Resolved Node Metadata +If the node is a symlink, it will hold information about the symlink resolved +node. Else, it will hold information the actual node. It the symlink is broken, +it will be null. +symlink +Type: nullable Resolved Node Metadata +If the node is a symlink and is not broken, it will hold information about the +symlink resolved node. However, it will never hold information about the actual +node. It will instead be null. +Node +A node contains the following fields: + +parent +relative_path +absolute_path +extension +is_symlink +is_broken +is_dir +is_file +is_readonly +mime_essence +size +human_size +permissions +canonical +symlink -Size -It contains the following information: +Directory Buffer +Directory buffer contains the following fields: -x -y -height -width +parent +nodes +total +focus -Every field is of integer type. -app -This is a lightweight version of the Lua Context. In this context, the -heavyweight fields like directory_buffer are omitted for performance -reasons. -Hence, only the following fields are avilable. +parent +Type: string +The parent path of the node. +nodes +Type: list of Nodes +A list of visible nodes. +total +Type: int +The count of nodes being rendered. +focus +Type: int +The index of the node under focus. It can be 0 even when there's no node to +focus on. +History +History contains the following fields: -version -pwd -focused_node -selection -mode -layout -input_buffer -pid -session_path -explorer_config +loc +paths -Node Types -This configuration defines how to deal with different kinds of nodes (files, -directories, symlinks etc.) in a directory. -This can be configured using the xplr.config.node_types Lua API. -It contains the following fields: - -directory -file -symlink -mime_essence -extension -special - -One node can fall into multiple categories. For example, a node can have the -extension md, and be a file. In that case, the properties from the more -specific category i.e. extension will be used. -The priority is: -special > extension > mime_essence > symlink > file > directory -directory -Type: NodeType Config -Properties related to directories are defined here. -Contains the following fields: -Example: -xplr.config.node_types.directory.meta.icon = "" -xplr.config.node_types.directory.style.add_modifiers = { "Bold" } - -file -Type: NodeType Config -Properties related to regular files are defined here. -Contains the following fields: -Example: -xplr.config.node_types.file.meta.icon = "" -xplr.config.node_types.file.style.fg = "White" - -symlink -Type: NodeType Config -Properties related to symlink are defined here. -Example: -xplr.config.node_types.symlink.meta.icon = "" -xplr.config.node_types.symlink.style.add_modifiers = { "Italic" } - -mime_essence -Type: mapping of mime-type and mapping of mime-subtype and NodeType Config -Properties related to files with specific mime types are defined here. -It is possible to use the wildcard * to match all mime subtypes. It will be -overwritten by the more specific sub types that are defined. -Example: -xplr.config.node_types.mime_essence = { - application = { - -- application/* - ["*"] = { meta = { icon = "a" } } +loc +Type: int +Location of the current path in history. +paths +Type: list of string +Visited paths. +Example: Using Lua Function Calls +-- Define the function +xplr.fn.custom.ask_name_and_greet = function(app) + print("What's your name?") - -- application/pdf - pdf = { meta = { icon = "" } }, + local name = io.read() + local greeting = "Hello " .. name .. "!" + local message = greeting .. " You are inside " .. app.pwd - -- application/zip - zip = { meta = { icon = ""} }, - }, -} - -extension -Type: mapping of extension and NodeType Config -Properties related to files with specific extension are defined here. -Example: -xplr.config.node_types.extension.md = { meta = { icon = "" } } -xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } } - -special -Type: mapping of name and NodeType Config -Properties related to files and directories with special names are defined -here. -Example: -xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } } -xplr.config.node_types.special["Downloads"] = { meta = { icon = "" } } - -NodeType Config -A node-type config contains the following fields: - -meta -style - -meta -Type: mapping of string and string -A meta field can contain custom metadata about a node. By default, the "icon" -metadata is set for the directory, file, and -symlink nodes. -Example: -xplr.config.node_types.file = { - meta = { - icon = "f", - foo = "bar", + return { + { LogSuccess = message }, + } +end + +-- Map the function to a key (space) +xplr.config.modes.builtin.default.key_bindings.on_key.space = { + help = "ask name and greet", + messages = { + { CallLua = "custom.ask_name_and_greet" } } } + +-- 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. -Borders -xplr allows customizing the shape and style of the borders. -Border -A border can be one of the following: - -Top -Right -Bottom -Left - -Border Type -A border can be one of the following: - -Plain -Rounded -Double -Thick - -Example -xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" } -xplr.config.general.panel_ui.default.border_type = "Thick" -xplr.config.general.panel_ui.default.border_style.fg = "Black" -xplr.config.general.panel_ui.default.border_style.bg = "Gray" +Environment Variables and Pipes +Alternative to CallLua, CallLuaSilently messages that call Lua functions, +there are Call, CallSilently, BashExec, BashExecSilently messages +that call shell commands. +However, unlike the Lua functions, these shell commands have to read the useful +information and send messages via environment variables and temporary files +called "pipe"s. These environment variables and files are only available when +a command is being executed. +Visit the fzf integration tutorial +for example. +Environment variables +To see the environment variables, invoke the shell by typing :! in default +mode and run the following command: +env | grep ^XPLR_ -Style -A style object contains the following information: - -fg -bg -add_modifiers -sub_modifiers - -fg -Type: nullable Color -The foreground color. -bg -Type: nullable Color -The background color. -add_modifiers -Type: nullable list of Modifier -Modifiers to add. -sub_modifiers -Type: nullable list of Modifier -Modifiers to remove. -Color -Color can be one of the following: +You will see something like: +XPLR_FOCUS_INDEX=0 +XPLR_MODE=action to +XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out +XPLR_INPUT_BUFFER= +XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out +XPLR_PID=122278 +XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in +XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out +XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out +XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out +XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book +XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278 +XPLR_APP_VERSION=0.14.3 +XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out + +The environment variables starting with XPLR_PIPE_ are the temporary files +called "pipe"s. +Input pipe +Current there is only one input pipe. -"Reset" -"Black" -"Red" -"Green" -"Yellow" -"Blue" -"Magenta" -"Cyan" -"Gray" -"DarkGray" -"LightRed" -"LightGreen" -"LightYellow" -"LightBlue" -"LightMagenta" -"LightCyan" -"White" -{ Rgb = { int, int, int } } -{ Indexed = int } +XPLR_PIPE_MSG_IN -Modifier -Modifier can be one of the following: +Output pipes +XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be +exposed directly via environment variables, like multi-line string. -"Bold" -"Dim" -"Italic" -"Underlined" -"SlowBlink" -"RapidBlink" -"Reversed" -"Hidden" -"CrossedOut" +XPLR_PIPE_SELECTION_OUT +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +XPLR_PIPE_LOGS_OUT +XPLR_PIPE_RESULT_OUT +XPLR_PIPE_HISTORY_OUT +XPLR_PIPE_DIRECTORY_NODES_OUT -Example -xplr.config.general.prompt.style.fg = "Red" -xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } } -xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" } -xplr.config.general.prompt.style.sub_modifiers = { "Hidden" } - -Sorting -xplr supports sorting paths by different properties. The sorting mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +XPLR_PIPE_MSG_IN +Append new-line delimited messages to this pipe in YAML +(or JSON) syntax. These messages will be read and +handled by xplr after the command execution. +XPLR_PIPE_SELECTION_OUT +New-line delimited list of selected paths. +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +The full help menu. +XPLR_PIPE_LOGS_OUT +New-line delimited list of logs. +XPLR_PIPE_RESULT_OUT +New-line delimited result (selected paths if any, else the focused path) +XPLR_PIPE_HISTORY_OUT +New-line delimited list of last visited paths (similar to jump list in vim). +XPLR_PIPE_DIRECTORY_NODES_OUT +New-line delimited list of paths, filtered and sorted as displayed in the +files table. +Example: Using Environment Variables and Pipes +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. -This line means that the nodes visible in the table will be first sorted by -it's size, then by case insensitive relative path, then by the -canonical (symlink resolved) type of the node, and finally by whether or not -the node is a symlink. -The arrows denote the order. -Each part of this pipeline is called Node Sorter Applicable. -Node Sorter Applicable -It contains the following information: +Awesome Hacks +Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your configuration or the appropriate file, that are +too small or too niche for a full fledge plugin. +Do you have something cool to share? +Edit this file or share them here or let us know. +cd on quit +Change directory using xplr. + +Expand for details -sorter -reverse +Author: @sayanarijit +Tested on: Linux -sorter -A sorter can be one of the following: +With this alias set, you can navigate directories using xplr by entering +xcd command, and when you quit by pressing enter, you will enter the +directory. +You can of course, quit with plain Quit (i.e. by pressing q) to +gracefully cancel "cd on quit". +alias xcd='cd "$(xplr --print-pwd-as-result)"' + + +Spawn multiple sessions in different tabs (iTerm2) +Creating a new session that starts with iTerm2. + +Expand for details -"ByRelativePath" -"ByIRelativePath" -"ByExtension" -"ByIsDir" -"ByIsFile" -"ByIsSymlink" -"ByIsBroken" -"ByIsReadonly" -"ByMimeEssence" -"BySize" -"ByCanonicalAbsolutePath" -"ByICanonicalAbsolutePath" -"ByCanonicalExtension" -"ByCanonicalIsDir" -"ByCanonicalIsFile" -"ByCanonicalIsReadonly" -"ByCanonicalMimeEssence" -"ByCanonicalSize" -"BySymlinkAbsolutePath" -"ByISymlinkAbsolutePath" -"BySymlinkExtension" -"BySymlinkIsDir" -"BySymlinkIsFile" -"BySymlinkIsReadonly" -"BySymlinkMimeEssence" -"BySymlinkSize" +Author: @lmburns +Requires: iTerm2 +Tested on: MacOS -TODO: document each -reverse -Type: boolean -It defined the direction of the order. -Example -xplr.config.general.initial_sorting = { - { sorter = "ByCanonicalIsDir", reverse = true }, - { sorter = "ByIRelativePath", reverse = false }, +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, } -This snippet defines the initial sorting logic to be applied when xplr loads. -Filtering -xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -rel!^. › [i]abs=~abc › [i]rel!~xyz + +Bookmark +Bookmark files using m and fuzzy search bookmarks using backtick. + +Expand for details + + +Author: @sayanarijit +Requires: fzf +Tested on: Linux + +xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} -This line means that the nodes visible on the table will first be filtered by -the condition: relative path does not start with ., then by the condition: -absolute path contains abc (case insensitive), and finally by the -condition: relative path does not contain xyz (case insensitive). -Each part of this pipeline is called Node Filter Applicable. -Node Filter Applicable -It contains the following information: + +Persistent, multi-session bookmark +A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A +bookmark can be added, deleted, or jumped to. + +Expand for details -filter -input +Author: @lmburns +Requires: fzf, sd +Tested on: MacOS -filter -A filter can be one of the following: +-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} + + +Another bookmark manager type thing, taken from wfxr's zsh plugin. +Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf. + +Expand for details -"RelativePathIs" -"RelativePathIsNot" -"IRelativePathIs" -"IRelativePathIsNot" -"RelativePathDoesStartWith" -"RelativePathDoesNotStartWith" -"IRelativePathDoesStartWith" -"IRelativePathDoesNotStartWith" -"RelativePathDoesContain" -"RelativePathDoesNotContain" -"IRelativePathDoesContain" -"IRelativePathDoesNotContain" -"RelativePathDoesEndWith" -"RelativePathDoesNotEndWith" -"IRelativePathDoesEndWith" -"IRelativePathDoesNotEndWith" -"AbsolutePathIs" -"AbsolutePathIsNot" -"IAbsolutePathIs" -"IAbsolutePathIsNot" -"AbsolutePathDoesStartWith" -"AbsolutePathDoesNotStartWith" -"IAbsolutePathDoesStartWith" -"IAbsolutePathDoesNotStartWith" -"AbsolutePathDoesContain" -"AbsolutePathDoesNotContain" -"IAbsolutePathDoesContain" -"IAbsolutePathDoesNotContain" -"AbsolutePathDoesEndWith" -"AbsolutePathDoesNotEndWith" -"IAbsolutePathDoesEndWith" -"IAbsolutePathDoesNotEndWith" +Author: @lmburns +Requires: fzf, exa +Tested on: MacOS -TODO: document each -input -Type: string -The input for the condition. -Example: -ToggleNodeFilter = { - filter = "RelativePathDoesNotStartWith", - input = "." +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } } -Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied. -Column Renderer -A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table. -xplr by default provides the following column renderers: - -xplr.fn.builtin.fmt_general_table_row_cols_0 -xplr.fn.builtin.fmt_general_table_row_cols_1 -xplr.fn.builtin.fmt_general_table_row_cols_2 -xplr.fn.builtin.fmt_general_table_row_cols_3 -xplr.fn.builtin.fmt_general_table_row_cols_4 - -You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them. -Terminal colors are supported. -Table Renderer Argument -The special argument contains the following fields + +Fuzzy search history +Fuzzy search the last visited directories. + +Expand for details -parent -relative_path -absolute_path -extension -is_symlink -is_broken -is_dir -is_file -is_readonly -mime_essence -size -human_size -permissions -canonical -symlink -index -relative_index -is_before_focus -is_after_focus -tree -prefix -suffix -is_selected -is_focused -total -meta +Author: @sayanarijit +Requires: fzf +Tested on: Linux -parent -Type: string -The parent path of the node. -relative_path -Type: string -The path relative to the parent, i.e. the file/directory name with extension. -absolute_path -Type: string -The absolute path (without resolving symlinks) of the node. -extension -Type: string -The extension of the node. -is_symlink -Type: boolean -true if the node is a symlink. -is_broken -Type: boolean -true if the node is a broken symlink. -is_dir -Type: boolean -true if the node is a directory. -is_file -Type: boolean -true if the node is a file. -is_readonly -Type: boolean -true if the node is real-only. -mime_essence -Type: string -The mime type of the node. For e.g. text/csv, image/jpeg etc. -size -Type: integer -The size of the exact node. The size of a directory won't be calculated -recursively. -human_size -Type: string -Like size but in human readable format. -permissions -Type: Permission -The permissions applied to the node. -canonical -Type: nullable Resolved Node Metadata -If the node is a symlink, it will hold information about the symlink resolved -node. Else, it will hold information the actual node. It the symlink is broken, -it will be null. -symlink -Type: nullable Resolved Node Metadata -If the node is a symlink and is not broken, it will hold information about the -symlink resolved node. However, it will never hold information about the actual -node. It will instead be null. -index -Type: integer -Index (starting from 0) of the node. -relative_index -Type: integer -Relative index from the focused node (i.e. 0th node). -is_before_focus -Type: boolean -true if the node is before the focused node. -is_after_focus -Type: boolean -true if the node is after the focused node. -tree -Type: string -The tree component based on the node's index. -prefix -Type: string -The prefix applicable for the node. -suffix -Type: string -The suffix applicable for the node. -is_selected -Type: boolean -true if the node is selected. -is_focused -Type: boolean -true if the node is under focus. -total -Type: integer -The total number of the nodes. -meta -Type: mapping of string and string -The applicable meta object for the node. -Permission -Permission contains the following fields: +xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Batch rename +Batch rename the selected or visible files and directories in $PWD. + +Expand for details + -user_read -user_write -user_execute -group_read -group_write -group_execute -other_read -other_write -other_execute -sticky -setgid -setuid +Author: @sayanarijit +Requires: pipe-rename +Tested on: Linux -Each field holds a boolean value. -Resolved Node Metadata -It contains the following fields. +xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Serve $PWD +Serve $PWD using a static web server via LAN. + +Expand for details -absolute_path -extension -is_dir -is_file -is_readonly -mime_essence -size -human_size +Author: @sayanarijit +Requires: sfz, fzf +Tested on: Linux -Example: Customizing Table Renderer -xplr.fn.custom.fmt_simple_column = function(m) - return m.prefix .. m.relative_path .. m.suffix -end - -xplr.config.general.table.header.cols = { - { format = " path" } -} - -xplr.config.general.table.row.cols = { - { format = "custom.fmt_simple_column" } -} - -xplr.config.general.table.col_widths = { - { Percentage = 100 } +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths. + +Also See: + +Awesome Plugins +Awesome Integrations + Plugin xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities. @@ -2898,24 +3165,24 @@ to append .xplr to the name to make them distinguishable. Similar t let us know. Examples Visit Awesome Plugins for xplr plugin examples. -Also See +Also See Tip: A list of hacks yet to make it as Lua plugins Tip: Some UI and themeing tips Tip: A list of handy utility functions Tip: Share tips and tricks working with Lua Tutorial: Adding a New Mode -Example: Using Environment Variables and Pipes -Example: Using Lua Function Calls -Example: Defining Custom Layout +Example: Using Environment Variables and Pipes +Example: Using Lua Function Calls +Example: Defining Custom Layout Example: Customizing Table Renderer -Example: Render a custom dynamic table +Example: Render a custom dynamic table Awesome Plugins Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own. -Extension +Extension sayanarijit/command-mode.xplr The missing command mode for xplr. igorepst/context-switch.xplr Context switch plugin for xplr. @@ -2954,7 +3221,7 @@ using xargs.
xplr.fn.custom.fmt_simple_column = function(m) + return m.prefix .. m.relative_path .. m.suffix end -
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - StaticList = { render = { "1", "2", "3" } }, - }, - }, -} -
A Lua function to render a custom list. -It contains the following fields:
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { DynamicList = { render = "custom.render_layout" } }, - }, + +xplr.config.general.table.header.cols = { + { format = " path" } } -xplr.fn.custom.render_layout = function(ctx) - return { - ctx.app.pwd, - ctx.app.version, - tostring(ctx.app.pid), - } -end -
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - StaticTable = { - widths = { - { Percentage = 50 }, - { Percentage = 50 }, - }, - col_spacing = 1, - render = { - { "a", "b" }, - { "c", "d" }, - }, - }, - }, - }, +xplr.config.general.table.row.cols = { + { format = "custom.fmt_simple_column" } } -
A Lua function to render a custom table. -It contains the following fields:
xplr.config.layouts.builtin.default = { - CustomContent = { - title = "custom title", - body = { - DynamicTable = { - widths = { - { Percentage = 50 }, - { Percentage = 50 }, - }, - col_spacing = 1, - render = "custom.render_layout", - }, - }, - }, + +xplr.config.general.table.col_widths = { + { Percentage = 100 } } -xplr.fn.custom.render_layout = function(ctx) - return { - { "", "" }, - { "Layout height", tostring(ctx.layout_size.height) }, - { "Layout width", tostring(ctx.layout_size.width) }, - { "", "" }, - { "Screen height", tostring(ctx.screen_size.height) }, - { "Screen width", tostring(ctx.screen_size.width) }, - } -end +-- With this config, you should only see a single column displaying the +-- relative paths.
It is a Lua function that receives a special argument as input and -returns some output that can be rendered in the UI. It is used to render -content body for the custom dynamic layouts.
This is a lightweight version of the Lua Context. In this context, the -heavyweight fields like directory_buffer are omitted for performance -reasons.
This configuration defines how to deal with different kinds of nodes (files, -directories, symlinks etc.) in a directory.
This can be configured using the xplr.config.node_types Lua API.
One node can fall into multiple categories. For example, a node can have the -extension md, and be a file. In that case, the properties from the more -specific category i.e. extension will be used.
md
file
The priority is:
special > extension > mime_essence > symlink > file > directory
Type: NodeType Config
Properties related to directories are defined here.
Contains the following fields:
xplr.config.node_types.directory.meta.icon = "" -xplr.config.node_types.directory.style.add_modifiers = { "Bold" } -
Properties related to regular files are defined here.
xplr.config.node_types.file.meta.icon = "" -xplr.config.node_types.file.style.fg = "White" -
Properties related to symlink are defined here.
xplr.config.node_types.symlink.meta.icon = "" -xplr.config.node_types.symlink.style.add_modifiers = { "Italic" } -
Type: mapping of mime-type and mapping of mime-subtype and NodeType Config
Properties related to files with specific mime types are defined here.
It is possible to use the wildcard * to match all mime subtypes. It will be -overwritten by the more specific sub types that are defined.
*
xplr.config.node_types.mime_essence = { - application = { - -- application/* - ["*"] = { meta = { icon = "a" } } +loc +Type: int +Location of the current path in history. +paths +Type: list of string +Visited paths. +Example: Using Lua Function Calls +-- Define the function +xplr.fn.custom.ask_name_and_greet = function(app) + print("What's your name?") - -- application/pdf - pdf = { meta = { icon = "" } }, + local name = io.read() + local greeting = "Hello " .. name .. "!" + local message = greeting .. " You are inside " .. app.pwd - -- application/zip - zip = { meta = { icon = ""} }, - }, -} - -extension -Type: mapping of extension and NodeType Config -Properties related to files with specific extension are defined here. -Example: -xplr.config.node_types.extension.md = { meta = { icon = "" } } -xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } } - -special -Type: mapping of name and NodeType Config -Properties related to files and directories with special names are defined -here. -Example: -xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } } -xplr.config.node_types.special["Downloads"] = { meta = { icon = "" } } - -NodeType Config -A node-type config contains the following fields: - -meta -style - -meta -Type: mapping of string and string -A meta field can contain custom metadata about a node. By default, the "icon" -metadata is set for the directory, file, and -symlink nodes. -Example: -xplr.config.node_types.file = { - meta = { - icon = "f", - foo = "bar", + return { + { LogSuccess = message }, + } +end + +-- Map the function to a key (space) +xplr.config.modes.builtin.default.key_bindings.on_key.space = { + help = "ask name and greet", + messages = { + { CallLua = "custom.ask_name_and_greet" } } } + +-- 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. -Borders -xplr allows customizing the shape and style of the borders. -Border -A border can be one of the following: - -Top -Right -Bottom -Left - -Border Type -A border can be one of the following: - -Plain -Rounded -Double -Thick - -Example -xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" } -xplr.config.general.panel_ui.default.border_type = "Thick" -xplr.config.general.panel_ui.default.border_style.fg = "Black" -xplr.config.general.panel_ui.default.border_style.bg = "Gray" +Environment Variables and Pipes +Alternative to CallLua, CallLuaSilently messages that call Lua functions, +there are Call, CallSilently, BashExec, BashExecSilently messages +that call shell commands. +However, unlike the Lua functions, these shell commands have to read the useful +information and send messages via environment variables and temporary files +called "pipe"s. These environment variables and files are only available when +a command is being executed. +Visit the fzf integration tutorial +for example. +Environment variables +To see the environment variables, invoke the shell by typing :! in default +mode and run the following command: +env | grep ^XPLR_ -Style -A style object contains the following information: - -fg -bg -add_modifiers -sub_modifiers - -fg -Type: nullable Color -The foreground color. -bg -Type: nullable Color -The background color. -add_modifiers -Type: nullable list of Modifier -Modifiers to add. -sub_modifiers -Type: nullable list of Modifier -Modifiers to remove. -Color -Color can be one of the following: +You will see something like: +XPLR_FOCUS_INDEX=0 +XPLR_MODE=action to +XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out +XPLR_INPUT_BUFFER= +XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out +XPLR_PID=122278 +XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in +XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out +XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out +XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out +XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book +XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278 +XPLR_APP_VERSION=0.14.3 +XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out + +The environment variables starting with XPLR_PIPE_ are the temporary files +called "pipe"s. +Input pipe +Current there is only one input pipe. -"Reset" -"Black" -"Red" -"Green" -"Yellow" -"Blue" -"Magenta" -"Cyan" -"Gray" -"DarkGray" -"LightRed" -"LightGreen" -"LightYellow" -"LightBlue" -"LightMagenta" -"LightCyan" -"White" -{ Rgb = { int, int, int } } -{ Indexed = int } +XPLR_PIPE_MSG_IN -Modifier -Modifier can be one of the following: +Output pipes +XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be +exposed directly via environment variables, like multi-line string. -"Bold" -"Dim" -"Italic" -"Underlined" -"SlowBlink" -"RapidBlink" -"Reversed" -"Hidden" -"CrossedOut" +XPLR_PIPE_SELECTION_OUT +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +XPLR_PIPE_LOGS_OUT +XPLR_PIPE_RESULT_OUT +XPLR_PIPE_HISTORY_OUT +XPLR_PIPE_DIRECTORY_NODES_OUT -Example -xplr.config.general.prompt.style.fg = "Red" -xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } } -xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" } -xplr.config.general.prompt.style.sub_modifiers = { "Hidden" } - -Sorting -xplr supports sorting paths by different properties. The sorting mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +XPLR_PIPE_MSG_IN +Append new-line delimited messages to this pipe in YAML +(or JSON) syntax. These messages will be read and +handled by xplr after the command execution. +XPLR_PIPE_SELECTION_OUT +New-line delimited list of selected paths. +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +The full help menu. +XPLR_PIPE_LOGS_OUT +New-line delimited list of logs. +XPLR_PIPE_RESULT_OUT +New-line delimited result (selected paths if any, else the focused path) +XPLR_PIPE_HISTORY_OUT +New-line delimited list of last visited paths (similar to jump list in vim). +XPLR_PIPE_DIRECTORY_NODES_OUT +New-line delimited list of paths, filtered and sorted as displayed in the +files table. +Example: Using Environment Variables and Pipes +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. -This line means that the nodes visible in the table will be first sorted by -it's size, then by case insensitive relative path, then by the -canonical (symlink resolved) type of the node, and finally by whether or not -the node is a symlink. -The arrows denote the order. -Each part of this pipeline is called Node Sorter Applicable. -Node Sorter Applicable -It contains the following information: +Awesome Hacks +Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your configuration or the appropriate file, that are +too small or too niche for a full fledge plugin. +Do you have something cool to share? +Edit this file or share them here or let us know. +cd on quit +Change directory using xplr. + +Expand for details -sorter -reverse +Author: @sayanarijit +Tested on: Linux -sorter -A sorter can be one of the following: +With this alias set, you can navigate directories using xplr by entering +xcd command, and when you quit by pressing enter, you will enter the +directory. +You can of course, quit with plain Quit (i.e. by pressing q) to +gracefully cancel "cd on quit". +alias xcd='cd "$(xplr --print-pwd-as-result)"' + + +Spawn multiple sessions in different tabs (iTerm2) +Creating a new session that starts with iTerm2. + +Expand for details -"ByRelativePath" -"ByIRelativePath" -"ByExtension" -"ByIsDir" -"ByIsFile" -"ByIsSymlink" -"ByIsBroken" -"ByIsReadonly" -"ByMimeEssence" -"BySize" -"ByCanonicalAbsolutePath" -"ByICanonicalAbsolutePath" -"ByCanonicalExtension" -"ByCanonicalIsDir" -"ByCanonicalIsFile" -"ByCanonicalIsReadonly" -"ByCanonicalMimeEssence" -"ByCanonicalSize" -"BySymlinkAbsolutePath" -"ByISymlinkAbsolutePath" -"BySymlinkExtension" -"BySymlinkIsDir" -"BySymlinkIsFile" -"BySymlinkIsReadonly" -"BySymlinkMimeEssence" -"BySymlinkSize" +Author: @lmburns +Requires: iTerm2 +Tested on: MacOS -TODO: document each -reverse -Type: boolean -It defined the direction of the order. -Example -xplr.config.general.initial_sorting = { - { sorter = "ByCanonicalIsDir", reverse = true }, - { sorter = "ByIRelativePath", reverse = false }, +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, } -This snippet defines the initial sorting logic to be applied when xplr loads. -Filtering -xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -rel!^. › [i]abs=~abc › [i]rel!~xyz + +Bookmark +Bookmark files using m and fuzzy search bookmarks using backtick. + +Expand for details + + +Author: @sayanarijit +Requires: fzf +Tested on: Linux + +xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} -This line means that the nodes visible on the table will first be filtered by -the condition: relative path does not start with ., then by the condition: -absolute path contains abc (case insensitive), and finally by the -condition: relative path does not contain xyz (case insensitive). -Each part of this pipeline is called Node Filter Applicable. -Node Filter Applicable -It contains the following information: + +Persistent, multi-session bookmark +A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A +bookmark can be added, deleted, or jumped to. + +Expand for details -filter -input +Author: @lmburns +Requires: fzf, sd +Tested on: MacOS -filter -A filter can be one of the following: +-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} + + +Another bookmark manager type thing, taken from wfxr's zsh plugin. +Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf. + +Expand for details -"RelativePathIs" -"RelativePathIsNot" -"IRelativePathIs" -"IRelativePathIsNot" -"RelativePathDoesStartWith" -"RelativePathDoesNotStartWith" -"IRelativePathDoesStartWith" -"IRelativePathDoesNotStartWith" -"RelativePathDoesContain" -"RelativePathDoesNotContain" -"IRelativePathDoesContain" -"IRelativePathDoesNotContain" -"RelativePathDoesEndWith" -"RelativePathDoesNotEndWith" -"IRelativePathDoesEndWith" -"IRelativePathDoesNotEndWith" -"AbsolutePathIs" -"AbsolutePathIsNot" -"IAbsolutePathIs" -"IAbsolutePathIsNot" -"AbsolutePathDoesStartWith" -"AbsolutePathDoesNotStartWith" -"IAbsolutePathDoesStartWith" -"IAbsolutePathDoesNotStartWith" -"AbsolutePathDoesContain" -"AbsolutePathDoesNotContain" -"IAbsolutePathDoesContain" -"IAbsolutePathDoesNotContain" -"AbsolutePathDoesEndWith" -"AbsolutePathDoesNotEndWith" -"IAbsolutePathDoesEndWith" -"IAbsolutePathDoesNotEndWith" +Author: @lmburns +Requires: fzf, exa +Tested on: MacOS -TODO: document each -input -Type: string -The input for the condition. -Example: -ToggleNodeFilter = { - filter = "RelativePathDoesNotStartWith", - input = "." +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } } -Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied. -Column Renderer -A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table. -xplr by default provides the following column renderers: - -xplr.fn.builtin.fmt_general_table_row_cols_0 -xplr.fn.builtin.fmt_general_table_row_cols_1 -xplr.fn.builtin.fmt_general_table_row_cols_2 -xplr.fn.builtin.fmt_general_table_row_cols_3 -xplr.fn.builtin.fmt_general_table_row_cols_4 - -You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them. -Terminal colors are supported. -Table Renderer Argument -The special argument contains the following fields + +Fuzzy search history +Fuzzy search the last visited directories. + +Expand for details -parent -relative_path -absolute_path -extension -is_symlink -is_broken -is_dir -is_file -is_readonly -mime_essence -size -human_size -permissions -canonical -symlink -index -relative_index -is_before_focus -is_after_focus -tree -prefix -suffix -is_selected -is_focused -total -meta +Author: @sayanarijit +Requires: fzf +Tested on: Linux -parent -Type: string -The parent path of the node. -relative_path -Type: string -The path relative to the parent, i.e. the file/directory name with extension. -absolute_path -Type: string -The absolute path (without resolving symlinks) of the node. -extension -Type: string -The extension of the node. -is_symlink -Type: boolean -true if the node is a symlink. -is_broken -Type: boolean -true if the node is a broken symlink. -is_dir -Type: boolean -true if the node is a directory. -is_file -Type: boolean -true if the node is a file. -is_readonly -Type: boolean -true if the node is real-only. -mime_essence -Type: string -The mime type of the node. For e.g. text/csv, image/jpeg etc. -size -Type: integer -The size of the exact node. The size of a directory won't be calculated -recursively. -human_size -Type: string -Like size but in human readable format. -permissions -Type: Permission -The permissions applied to the node. -canonical -Type: nullable Resolved Node Metadata -If the node is a symlink, it will hold information about the symlink resolved -node. Else, it will hold information the actual node. It the symlink is broken, -it will be null. -symlink -Type: nullable Resolved Node Metadata -If the node is a symlink and is not broken, it will hold information about the -symlink resolved node. However, it will never hold information about the actual -node. It will instead be null. -index -Type: integer -Index (starting from 0) of the node. -relative_index -Type: integer -Relative index from the focused node (i.e. 0th node). -is_before_focus -Type: boolean -true if the node is before the focused node. -is_after_focus -Type: boolean -true if the node is after the focused node. -tree -Type: string -The tree component based on the node's index. -prefix -Type: string -The prefix applicable for the node. -suffix -Type: string -The suffix applicable for the node. -is_selected -Type: boolean -true if the node is selected. -is_focused -Type: boolean -true if the node is under focus. -total -Type: integer -The total number of the nodes. -meta -Type: mapping of string and string -The applicable meta object for the node. -Permission -Permission contains the following fields: +xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Batch rename +Batch rename the selected or visible files and directories in $PWD. + +Expand for details + -user_read -user_write -user_execute -group_read -group_write -group_execute -other_read -other_write -other_execute -sticky -setgid -setuid +Author: @sayanarijit +Requires: pipe-rename +Tested on: Linux -Each field holds a boolean value. -Resolved Node Metadata -It contains the following fields. +xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Serve $PWD +Serve $PWD using a static web server via LAN. + +Expand for details -absolute_path -extension -is_dir -is_file -is_readonly -mime_essence -size -human_size +Author: @sayanarijit +Requires: sfz, fzf +Tested on: Linux -Example: Customizing Table Renderer -xplr.fn.custom.fmt_simple_column = function(m) - return m.prefix .. m.relative_path .. m.suffix -end - -xplr.config.general.table.header.cols = { - { format = " path" } -} - -xplr.config.general.table.row.cols = { - { format = "custom.fmt_simple_column" } -} - -xplr.config.general.table.col_widths = { - { Percentage = 100 } +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths. + +Also See: + +Awesome Plugins +Awesome Integrations + Plugin xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities. @@ -2898,24 +3165,24 @@ to append .xplr to the name to make them distinguishable. Similar t let us know. Examples Visit Awesome Plugins for xplr plugin examples. -Also See +Also See Tip: A list of hacks yet to make it as Lua plugins Tip: Some UI and themeing tips Tip: A list of handy utility functions Tip: Share tips and tricks working with Lua Tutorial: Adding a New Mode -Example: Using Environment Variables and Pipes -Example: Using Lua Function Calls -Example: Defining Custom Layout +Example: Using Environment Variables and Pipes +Example: Using Lua Function Calls +Example: Defining Custom Layout Example: Customizing Table Renderer -Example: Render a custom dynamic table +Example: Render a custom dynamic table Awesome Plugins Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own. -Extension +Extension sayanarijit/command-mode.xplr The missing command mode for xplr. igorepst/context-switch.xplr Context switch plugin for xplr. @@ -2954,7 +3221,7 @@ using xargs.
-- Define the function +xplr.fn.custom.ask_name_and_greet = function(app) + print("What's your name?") - -- application/pdf - pdf = { meta = { icon = "" } }, + local name = io.read() + local greeting = "Hello " .. name .. "!" + local message = greeting .. " You are inside " .. app.pwd - -- application/zip - zip = { meta = { icon = ""} }, - }, -} -
Type: mapping of extension and NodeType Config
Properties related to files with specific extension are defined here.
xplr.config.node_types.extension.md = { meta = { icon = "" } } -xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } } -
Type: mapping of name and NodeType Config
Properties related to files and directories with special names are defined -here.
xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } } -xplr.config.node_types.special["Downloads"] = { meta = { icon = "" } } -
A node-type config contains the following fields:
A meta field can contain custom metadata about a node. By default, the "icon" -metadata is set for the directory, file, and -symlink nodes.
xplr.config.node_types.file = { - meta = { - icon = "f", - foo = "bar", + return { + { LogSuccess = message }, + } +end + +-- Map the function to a key (space) +xplr.config.modes.builtin.default.key_bindings.on_key.space = { + help = "ask name and greet", + messages = { + { CallLua = "custom.ask_name_and_greet" } } } + +-- 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.
xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" } -xplr.config.general.panel_ui.default.border_type = "Thick" -xplr.config.general.panel_ui.default.border_style.fg = "Black" -xplr.config.general.panel_ui.default.border_style.bg = "Gray" +Environment Variables and Pipes +Alternative to CallLua, CallLuaSilently messages that call Lua functions, +there are Call, CallSilently, BashExec, BashExecSilently messages +that call shell commands. +However, unlike the Lua functions, these shell commands have to read the useful +information and send messages via environment variables and temporary files +called "pipe"s. These environment variables and files are only available when +a command is being executed. +Visit the fzf integration tutorial +for example. +Environment variables +To see the environment variables, invoke the shell by typing :! in default +mode and run the following command: +env | grep ^XPLR_ -Style -A style object contains the following information: - -fg -bg -add_modifiers -sub_modifiers - -fg -Type: nullable Color -The foreground color. -bg -Type: nullable Color -The background color. -add_modifiers -Type: nullable list of Modifier -Modifiers to add. -sub_modifiers -Type: nullable list of Modifier -Modifiers to remove. -Color -Color can be one of the following: +You will see something like: +XPLR_FOCUS_INDEX=0 +XPLR_MODE=action to +XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out +XPLR_INPUT_BUFFER= +XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out +XPLR_PID=122278 +XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in +XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out +XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out +XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out +XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book +XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278 +XPLR_APP_VERSION=0.14.3 +XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out + +The environment variables starting with XPLR_PIPE_ are the temporary files +called "pipe"s. +Input pipe +Current there is only one input pipe. -"Reset" -"Black" -"Red" -"Green" -"Yellow" -"Blue" -"Magenta" -"Cyan" -"Gray" -"DarkGray" -"LightRed" -"LightGreen" -"LightYellow" -"LightBlue" -"LightMagenta" -"LightCyan" -"White" -{ Rgb = { int, int, int } } -{ Indexed = int } +XPLR_PIPE_MSG_IN -Modifier -Modifier can be one of the following: +Output pipes +XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be +exposed directly via environment variables, like multi-line string. -"Bold" -"Dim" -"Italic" -"Underlined" -"SlowBlink" -"RapidBlink" -"Reversed" -"Hidden" -"CrossedOut" +XPLR_PIPE_SELECTION_OUT +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +XPLR_PIPE_LOGS_OUT +XPLR_PIPE_RESULT_OUT +XPLR_PIPE_HISTORY_OUT +XPLR_PIPE_DIRECTORY_NODES_OUT -Example -xplr.config.general.prompt.style.fg = "Red" -xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } } -xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" } -xplr.config.general.prompt.style.sub_modifiers = { "Hidden" } - -Sorting -xplr supports sorting paths by different properties. The sorting mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +XPLR_PIPE_MSG_IN +Append new-line delimited messages to this pipe in YAML +(or JSON) syntax. These messages will be read and +handled by xplr after the command execution. +XPLR_PIPE_SELECTION_OUT +New-line delimited list of selected paths. +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +The full help menu. +XPLR_PIPE_LOGS_OUT +New-line delimited list of logs. +XPLR_PIPE_RESULT_OUT +New-line delimited result (selected paths if any, else the focused path) +XPLR_PIPE_HISTORY_OUT +New-line delimited list of last visited paths (similar to jump list in vim). +XPLR_PIPE_DIRECTORY_NODES_OUT +New-line delimited list of paths, filtered and sorted as displayed in the +files table. +Example: Using Environment Variables and Pipes +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. -This line means that the nodes visible in the table will be first sorted by -it's size, then by case insensitive relative path, then by the -canonical (symlink resolved) type of the node, and finally by whether or not -the node is a symlink. -The arrows denote the order. -Each part of this pipeline is called Node Sorter Applicable. -Node Sorter Applicable -It contains the following information: +Awesome Hacks +Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your configuration or the appropriate file, that are +too small or too niche for a full fledge plugin. +Do you have something cool to share? +Edit this file or share them here or let us know. +cd on quit +Change directory using xplr. + +Expand for details -sorter -reverse +Author: @sayanarijit +Tested on: Linux -sorter -A sorter can be one of the following: +With this alias set, you can navigate directories using xplr by entering +xcd command, and when you quit by pressing enter, you will enter the +directory. +You can of course, quit with plain Quit (i.e. by pressing q) to +gracefully cancel "cd on quit". +alias xcd='cd "$(xplr --print-pwd-as-result)"' + + +Spawn multiple sessions in different tabs (iTerm2) +Creating a new session that starts with iTerm2. + +Expand for details -"ByRelativePath" -"ByIRelativePath" -"ByExtension" -"ByIsDir" -"ByIsFile" -"ByIsSymlink" -"ByIsBroken" -"ByIsReadonly" -"ByMimeEssence" -"BySize" -"ByCanonicalAbsolutePath" -"ByICanonicalAbsolutePath" -"ByCanonicalExtension" -"ByCanonicalIsDir" -"ByCanonicalIsFile" -"ByCanonicalIsReadonly" -"ByCanonicalMimeEssence" -"ByCanonicalSize" -"BySymlinkAbsolutePath" -"ByISymlinkAbsolutePath" -"BySymlinkExtension" -"BySymlinkIsDir" -"BySymlinkIsFile" -"BySymlinkIsReadonly" -"BySymlinkMimeEssence" -"BySymlinkSize" +Author: @lmburns +Requires: iTerm2 +Tested on: MacOS -TODO: document each -reverse -Type: boolean -It defined the direction of the order. -Example -xplr.config.general.initial_sorting = { - { sorter = "ByCanonicalIsDir", reverse = true }, - { sorter = "ByIRelativePath", reverse = false }, +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, } -This snippet defines the initial sorting logic to be applied when xplr loads. -Filtering -xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -rel!^. › [i]abs=~abc › [i]rel!~xyz + +Bookmark +Bookmark files using m and fuzzy search bookmarks using backtick. + +Expand for details + + +Author: @sayanarijit +Requires: fzf +Tested on: Linux + +xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} -This line means that the nodes visible on the table will first be filtered by -the condition: relative path does not start with ., then by the condition: -absolute path contains abc (case insensitive), and finally by the -condition: relative path does not contain xyz (case insensitive). -Each part of this pipeline is called Node Filter Applicable. -Node Filter Applicable -It contains the following information: + +Persistent, multi-session bookmark +A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A +bookmark can be added, deleted, or jumped to. + +Expand for details -filter -input +Author: @lmburns +Requires: fzf, sd +Tested on: MacOS -filter -A filter can be one of the following: +-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} + + +Another bookmark manager type thing, taken from wfxr's zsh plugin. +Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf. + +Expand for details -"RelativePathIs" -"RelativePathIsNot" -"IRelativePathIs" -"IRelativePathIsNot" -"RelativePathDoesStartWith" -"RelativePathDoesNotStartWith" -"IRelativePathDoesStartWith" -"IRelativePathDoesNotStartWith" -"RelativePathDoesContain" -"RelativePathDoesNotContain" -"IRelativePathDoesContain" -"IRelativePathDoesNotContain" -"RelativePathDoesEndWith" -"RelativePathDoesNotEndWith" -"IRelativePathDoesEndWith" -"IRelativePathDoesNotEndWith" -"AbsolutePathIs" -"AbsolutePathIsNot" -"IAbsolutePathIs" -"IAbsolutePathIsNot" -"AbsolutePathDoesStartWith" -"AbsolutePathDoesNotStartWith" -"IAbsolutePathDoesStartWith" -"IAbsolutePathDoesNotStartWith" -"AbsolutePathDoesContain" -"AbsolutePathDoesNotContain" -"IAbsolutePathDoesContain" -"IAbsolutePathDoesNotContain" -"AbsolutePathDoesEndWith" -"AbsolutePathDoesNotEndWith" -"IAbsolutePathDoesEndWith" -"IAbsolutePathDoesNotEndWith" +Author: @lmburns +Requires: fzf, exa +Tested on: MacOS -TODO: document each -input -Type: string -The input for the condition. -Example: -ToggleNodeFilter = { - filter = "RelativePathDoesNotStartWith", - input = "." +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } } -Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied. -Column Renderer -A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table. -xplr by default provides the following column renderers: - -xplr.fn.builtin.fmt_general_table_row_cols_0 -xplr.fn.builtin.fmt_general_table_row_cols_1 -xplr.fn.builtin.fmt_general_table_row_cols_2 -xplr.fn.builtin.fmt_general_table_row_cols_3 -xplr.fn.builtin.fmt_general_table_row_cols_4 - -You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them. -Terminal colors are supported. -Table Renderer Argument -The special argument contains the following fields + +Fuzzy search history +Fuzzy search the last visited directories. + +Expand for details -parent -relative_path -absolute_path -extension -is_symlink -is_broken -is_dir -is_file -is_readonly -mime_essence -size -human_size -permissions -canonical -symlink -index -relative_index -is_before_focus -is_after_focus -tree -prefix -suffix -is_selected -is_focused -total -meta +Author: @sayanarijit +Requires: fzf +Tested on: Linux -parent -Type: string -The parent path of the node. -relative_path -Type: string -The path relative to the parent, i.e. the file/directory name with extension. -absolute_path -Type: string -The absolute path (without resolving symlinks) of the node. -extension -Type: string -The extension of the node. -is_symlink -Type: boolean -true if the node is a symlink. -is_broken -Type: boolean -true if the node is a broken symlink. -is_dir -Type: boolean -true if the node is a directory. -is_file -Type: boolean -true if the node is a file. -is_readonly -Type: boolean -true if the node is real-only. -mime_essence -Type: string -The mime type of the node. For e.g. text/csv, image/jpeg etc. -size -Type: integer -The size of the exact node. The size of a directory won't be calculated -recursively. -human_size -Type: string -Like size but in human readable format. -permissions -Type: Permission -The permissions applied to the node. -canonical -Type: nullable Resolved Node Metadata -If the node is a symlink, it will hold information about the symlink resolved -node. Else, it will hold information the actual node. It the symlink is broken, -it will be null. -symlink -Type: nullable Resolved Node Metadata -If the node is a symlink and is not broken, it will hold information about the -symlink resolved node. However, it will never hold information about the actual -node. It will instead be null. -index -Type: integer -Index (starting from 0) of the node. -relative_index -Type: integer -Relative index from the focused node (i.e. 0th node). -is_before_focus -Type: boolean -true if the node is before the focused node. -is_after_focus -Type: boolean -true if the node is after the focused node. -tree -Type: string -The tree component based on the node's index. -prefix -Type: string -The prefix applicable for the node. -suffix -Type: string -The suffix applicable for the node. -is_selected -Type: boolean -true if the node is selected. -is_focused -Type: boolean -true if the node is under focus. -total -Type: integer -The total number of the nodes. -meta -Type: mapping of string and string -The applicable meta object for the node. -Permission -Permission contains the following fields: +xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Batch rename +Batch rename the selected or visible files and directories in $PWD. + +Expand for details + -user_read -user_write -user_execute -group_read -group_write -group_execute -other_read -other_write -other_execute -sticky -setgid -setuid +Author: @sayanarijit +Requires: pipe-rename +Tested on: Linux -Each field holds a boolean value. -Resolved Node Metadata -It contains the following fields. +xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Serve $PWD +Serve $PWD using a static web server via LAN. + +Expand for details -absolute_path -extension -is_dir -is_file -is_readonly -mime_essence -size -human_size +Author: @sayanarijit +Requires: sfz, fzf +Tested on: Linux -Example: Customizing Table Renderer -xplr.fn.custom.fmt_simple_column = function(m) - return m.prefix .. m.relative_path .. m.suffix -end - -xplr.config.general.table.header.cols = { - { format = " path" } -} - -xplr.config.general.table.row.cols = { - { format = "custom.fmt_simple_column" } -} - -xplr.config.general.table.col_widths = { - { Percentage = 100 } +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths. + +Also See: + +Awesome Plugins +Awesome Integrations + Plugin xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities. @@ -2898,24 +3165,24 @@ to append .xplr to the name to make them distinguishable. Similar t let us know. Examples Visit Awesome Plugins for xplr plugin examples. -Also See +Also See Tip: A list of hacks yet to make it as Lua plugins Tip: Some UI and themeing tips Tip: A list of handy utility functions Tip: Share tips and tricks working with Lua Tutorial: Adding a New Mode -Example: Using Environment Variables and Pipes -Example: Using Lua Function Calls -Example: Defining Custom Layout +Example: Using Environment Variables and Pipes +Example: Using Lua Function Calls +Example: Defining Custom Layout Example: Customizing Table Renderer -Example: Render a custom dynamic table +Example: Render a custom dynamic table Awesome Plugins Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own. -Extension +Extension sayanarijit/command-mode.xplr The missing command mode for xplr. igorepst/context-switch.xplr Context switch plugin for xplr. @@ -2954,7 +3221,7 @@ using xargs.
env | grep ^XPLR_
xplr.config.general.prompt.style.fg = "Red" -xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } } -xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" } -xplr.config.general.prompt.style.sub_modifiers = { "Hidden" } -
xplr supports sorting paths by different properties. The sorting mechanism -works like a pipeline, which in visible in the Sort & filter panel.
size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +XPLR_PIPE_MSG_IN +Append new-line delimited messages to this pipe in YAML +(or JSON) syntax. These messages will be read and +handled by xplr after the command execution. +XPLR_PIPE_SELECTION_OUT +New-line delimited list of selected paths. +XPLR_PIPE_GLOBAL_HELP_MENU_OUT +The full help menu. +XPLR_PIPE_LOGS_OUT +New-line delimited list of logs. +XPLR_PIPE_RESULT_OUT +New-line delimited result (selected paths if any, else the focused path) +XPLR_PIPE_HISTORY_OUT +New-line delimited list of last visited paths (similar to jump list in vim). +XPLR_PIPE_DIRECTORY_NODES_OUT +New-line delimited list of paths, filtered and sorted as displayed in the +files table. +Example: Using Environment Variables and Pipes +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. -This line means that the nodes visible in the table will be first sorted by -it's size, then by case insensitive relative path, then by the -canonical (symlink resolved) type of the node, and finally by whether or not -the node is a symlink. -The arrows denote the order. -Each part of this pipeline is called Node Sorter Applicable. -Node Sorter Applicable -It contains the following information: +Awesome Hacks +Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your configuration or the appropriate file, that are +too small or too niche for a full fledge plugin. +Do you have something cool to share? +Edit this file or share them here or let us know. +cd on quit +Change directory using xplr. + +Expand for details -sorter -reverse +Author: @sayanarijit +Tested on: Linux -sorter -A sorter can be one of the following: +With this alias set, you can navigate directories using xplr by entering +xcd command, and when you quit by pressing enter, you will enter the +directory. +You can of course, quit with plain Quit (i.e. by pressing q) to +gracefully cancel "cd on quit". +alias xcd='cd "$(xplr --print-pwd-as-result)"' + + +Spawn multiple sessions in different tabs (iTerm2) +Creating a new session that starts with iTerm2. + +Expand for details -"ByRelativePath" -"ByIRelativePath" -"ByExtension" -"ByIsDir" -"ByIsFile" -"ByIsSymlink" -"ByIsBroken" -"ByIsReadonly" -"ByMimeEssence" -"BySize" -"ByCanonicalAbsolutePath" -"ByICanonicalAbsolutePath" -"ByCanonicalExtension" -"ByCanonicalIsDir" -"ByCanonicalIsFile" -"ByCanonicalIsReadonly" -"ByCanonicalMimeEssence" -"ByCanonicalSize" -"BySymlinkAbsolutePath" -"ByISymlinkAbsolutePath" -"BySymlinkExtension" -"BySymlinkIsDir" -"BySymlinkIsFile" -"BySymlinkIsReadonly" -"BySymlinkMimeEssence" -"BySymlinkSize" +Author: @lmburns +Requires: iTerm2 +Tested on: MacOS -TODO: document each -reverse -Type: boolean -It defined the direction of the order. -Example -xplr.config.general.initial_sorting = { - { sorter = "ByCanonicalIsDir", reverse = true }, - { sorter = "ByIRelativePath", reverse = false }, +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, } -This snippet defines the initial sorting logic to be applied when xplr loads. -Filtering -xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -rel!^. › [i]abs=~abc › [i]rel!~xyz + +Bookmark +Bookmark files using m and fuzzy search bookmarks using backtick. + +Expand for details + + +Author: @sayanarijit +Requires: fzf +Tested on: Linux + +xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} -This line means that the nodes visible on the table will first be filtered by -the condition: relative path does not start with ., then by the condition: -absolute path contains abc (case insensitive), and finally by the -condition: relative path does not contain xyz (case insensitive). -Each part of this pipeline is called Node Filter Applicable. -Node Filter Applicable -It contains the following information: + +Persistent, multi-session bookmark +A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A +bookmark can be added, deleted, or jumped to. + +Expand for details -filter -input +Author: @lmburns +Requires: fzf, sd +Tested on: MacOS -filter -A filter can be one of the following: +-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} + + +Another bookmark manager type thing, taken from wfxr's zsh plugin. +Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf. + +Expand for details -"RelativePathIs" -"RelativePathIsNot" -"IRelativePathIs" -"IRelativePathIsNot" -"RelativePathDoesStartWith" -"RelativePathDoesNotStartWith" -"IRelativePathDoesStartWith" -"IRelativePathDoesNotStartWith" -"RelativePathDoesContain" -"RelativePathDoesNotContain" -"IRelativePathDoesContain" -"IRelativePathDoesNotContain" -"RelativePathDoesEndWith" -"RelativePathDoesNotEndWith" -"IRelativePathDoesEndWith" -"IRelativePathDoesNotEndWith" -"AbsolutePathIs" -"AbsolutePathIsNot" -"IAbsolutePathIs" -"IAbsolutePathIsNot" -"AbsolutePathDoesStartWith" -"AbsolutePathDoesNotStartWith" -"IAbsolutePathDoesStartWith" -"IAbsolutePathDoesNotStartWith" -"AbsolutePathDoesContain" -"AbsolutePathDoesNotContain" -"IAbsolutePathDoesContain" -"IAbsolutePathDoesNotContain" -"AbsolutePathDoesEndWith" -"AbsolutePathDoesNotEndWith" -"IAbsolutePathDoesEndWith" -"IAbsolutePathDoesNotEndWith" +Author: @lmburns +Requires: fzf, exa +Tested on: MacOS -TODO: document each -input -Type: string -The input for the condition. -Example: -ToggleNodeFilter = { - filter = "RelativePathDoesNotStartWith", - input = "." +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } } -Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied. -Column Renderer -A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table. -xplr by default provides the following column renderers: - -xplr.fn.builtin.fmt_general_table_row_cols_0 -xplr.fn.builtin.fmt_general_table_row_cols_1 -xplr.fn.builtin.fmt_general_table_row_cols_2 -xplr.fn.builtin.fmt_general_table_row_cols_3 -xplr.fn.builtin.fmt_general_table_row_cols_4 - -You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them. -Terminal colors are supported. -Table Renderer Argument -The special argument contains the following fields + +Fuzzy search history +Fuzzy search the last visited directories. + +Expand for details -parent -relative_path -absolute_path -extension -is_symlink -is_broken -is_dir -is_file -is_readonly -mime_essence -size -human_size -permissions -canonical -symlink -index -relative_index -is_before_focus -is_after_focus -tree -prefix -suffix -is_selected -is_focused -total -meta +Author: @sayanarijit +Requires: fzf +Tested on: Linux -parent -Type: string -The parent path of the node. -relative_path -Type: string -The path relative to the parent, i.e. the file/directory name with extension. -absolute_path -Type: string -The absolute path (without resolving symlinks) of the node. -extension -Type: string -The extension of the node. -is_symlink -Type: boolean -true if the node is a symlink. -is_broken -Type: boolean -true if the node is a broken symlink. -is_dir -Type: boolean -true if the node is a directory. -is_file -Type: boolean -true if the node is a file. -is_readonly -Type: boolean -true if the node is real-only. -mime_essence -Type: string -The mime type of the node. For e.g. text/csv, image/jpeg etc. -size -Type: integer -The size of the exact node. The size of a directory won't be calculated -recursively. -human_size -Type: string -Like size but in human readable format. -permissions -Type: Permission -The permissions applied to the node. -canonical -Type: nullable Resolved Node Metadata -If the node is a symlink, it will hold information about the symlink resolved -node. Else, it will hold information the actual node. It the symlink is broken, -it will be null. -symlink -Type: nullable Resolved Node Metadata -If the node is a symlink and is not broken, it will hold information about the -symlink resolved node. However, it will never hold information about the actual -node. It will instead be null. -index -Type: integer -Index (starting from 0) of the node. -relative_index -Type: integer -Relative index from the focused node (i.e. 0th node). -is_before_focus -Type: boolean -true if the node is before the focused node. -is_after_focus -Type: boolean -true if the node is after the focused node. -tree -Type: string -The tree component based on the node's index. -prefix -Type: string -The prefix applicable for the node. -suffix -Type: string -The suffix applicable for the node. -is_selected -Type: boolean -true if the node is selected. -is_focused -Type: boolean -true if the node is under focus. -total -Type: integer -The total number of the nodes. -meta -Type: mapping of string and string -The applicable meta object for the node. -Permission -Permission contains the following fields: +xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Batch rename +Batch rename the selected or visible files and directories in $PWD. + +Expand for details + -user_read -user_write -user_execute -group_read -group_write -group_execute -other_read -other_write -other_execute -sticky -setgid -setuid +Author: @sayanarijit +Requires: pipe-rename +Tested on: Linux -Each field holds a boolean value. -Resolved Node Metadata -It contains the following fields. +xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + + +Serve $PWD +Serve $PWD using a static web server via LAN. + +Expand for details -absolute_path -extension -is_dir -is_file -is_readonly -mime_essence -size -human_size +Author: @sayanarijit +Requires: sfz, fzf +Tested on: Linux -Example: Customizing Table Renderer -xplr.fn.custom.fmt_simple_column = function(m) - return m.prefix .. m.relative_path .. m.suffix -end - -xplr.config.general.table.header.cols = { - { format = " path" } -} - -xplr.config.general.table.row.cols = { - { format = "custom.fmt_simple_column" } -} - -xplr.config.general.table.col_widths = { - { Percentage = 100 } +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths. + +Also See: + +Awesome Plugins +Awesome Integrations + Plugin xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities. @@ -2898,24 +3165,24 @@ to append .xplr to the name to make them distinguishable. Similar t let us know. Examples Visit Awesome Plugins for xplr plugin examples. -Also See +Also See Tip: A list of hacks yet to make it as Lua plugins Tip: Some UI and themeing tips Tip: A list of handy utility functions Tip: Share tips and tricks working with Lua Tutorial: Adding a New Mode -Example: Using Environment Variables and Pipes -Example: Using Lua Function Calls -Example: Defining Custom Layout +Example: Using Environment Variables and Pipes +Example: Using Lua Function Calls +Example: Defining Custom Layout Example: Customizing Table Renderer -Example: Render a custom dynamic table +Example: Render a custom dynamic table Awesome Plugins Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own. -Extension +Extension sayanarijit/command-mode.xplr The missing command mode for xplr. igorepst/context-switch.xplr Context switch plugin for xplr. @@ -2954,7 +3221,7 @@ using xargs.
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.
This line means that the nodes visible in the table will be first sorted by -it's size, then by case insensitive relative path, then by the -canonical (symlink resolved) type of the node, and finally by whether or not -the node is a symlink.
Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your configuration or the appropriate file, that are +too small or too niche for a full fledge plugin.
With this alias set, you can navigate directories using xplr by entering +xcd command, and when you quit by pressing enter, you will enter the +directory.
You can of course, quit with plain Quit (i.e. by pressing q) to +gracefully cancel "cd on quit".
alias xcd='cd "$(xplr --print-pwd-as-result)"' +
xplr.config.general.initial_sorting = { - { sorter = "ByCanonicalIsDir", reverse = true }, - { sorter = "ByIRelativePath", reverse = false }, +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, } -This snippet defines the initial sorting logic to be applied when xplr loads. -Filtering -xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel. -Example: -rel!^. › [i]abs=~abc › [i]rel!~xyz +
xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript <<EOF + tell application "iTerm2" + tell current window + create tab with default profile + tell current session to write text "xplr" + end tell + end tell + ]] + }, + }, }
xplr supports filtering paths by different properties. The filtering mechanism -works like a pipeline, which in visible in the Sort & filter panel.
xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +}
This line means that the nodes visible on the table will first be filtered by -the condition: relative path does not start with ., then by the condition: -absolute path contains abc (case insensitive), and finally by the -condition: relative path does not contain xyz (case insensitive).
A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A +bookmark can be added, deleted, or jumped to.
-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} +
ToggleNodeFilter = { - filter = "RelativePathDoesNotStartWith", - input = "." +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } } -Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied. -Column Renderer -A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table. -xplr by default provides the following column renderers: - -xplr.fn.builtin.fmt_general_table_row_cols_0 -xplr.fn.builtin.fmt_general_table_row_cols_1 -xplr.fn.builtin.fmt_general_table_row_cols_2 -xplr.fn.builtin.fmt_general_table_row_cols_3 -xplr.fn.builtin.fmt_general_table_row_cols_4 - -You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them. -Terminal colors are supported. -Table Renderer Argument -The special argument contains the following fields +
xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } }
Here, ToggleNodeFilter is a message that adds or removes -(toggles) the filter applied.
A column renderer is a Lua function that receives a special argument and -returns a string that will be displayed in each specific field of the -files table.
You can either overwrite these functions, or create new functions in -xplr.fn.custom and point to them.
The size of the exact node. The size of a directory won't be calculated -recursively.
If the node is a symlink, it will hold information about the symlink resolved -node. Else, it will hold information the actual node. It the symlink is broken, -it will be null.
If the node is a symlink and is not broken, it will hold information about the -symlink resolved node. However, it will never hold information about the actual -node. It will instead be null.
xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} +
xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} +
xplr.fn.custom.fmt_simple_column = function(m) - return m.prefix .. m.relative_path .. m.suffix -end - -xplr.config.general.table.header.cols = { - { format = " path" } -} - -xplr.config.general.table.row.cols = { - { format = "custom.fmt_simple_column" } -} - -xplr.config.general.table.col_widths = { - { Percentage = 100 } +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths. +
xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, } - --- With this config, you should only see a single column displaying the --- relative paths.
xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities.
.xplr
Visit Awesome Plugins for xplr plugin examples.
Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own.
xargs
xplr.config.node_types.mime_essence = { - application = { - -- application/* - ["*"] = { meta = { icon = "a" } } - - -- application/pdf - pdf = { meta = { icon = "" } }, - - -- application/zip - zip = { meta = { icon = ""} }, - }, -} -
xplr.config.node_types.file = { - meta = { - icon = "f", - foo = "bar", - } -} -