-
+
diff --git a/en/post-install.html b/en/post-install.html
index 13ffb7e..34785f7 100644
--- a/en/post-install.html
+++ b/en/post-install.html
@@ -75,7 +75,7 @@
diff --git a/en/print.html b/en/print.html
index cf8cdb0..e7fbe82 100644
--- a/en/print.html
+++ b/en/print.html
@@ -76,7 +76,7 @@
@@ -459,6 +459,429 @@ following fields:
layouts node_types
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.
+Key bindings contains the following information:
+
+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.
+Type: nullable Action
+An action to perform if the keyboard input is a number and is not mapped via
+the on_key field.
+Type: nullable Action
+An action to perform if the keyboard input is alphanumeric and is not mapped
+via the on_key , on_alphabet or on_number field.
+Type: nullable Action
+An action to perform if the keyboard input is a special character and is not
+mapped via the on_key field.
+Type: nullable Action
+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.
+Type: nullable Action
+An action to perform if the keyboard input is a navigation key and is not
+mapped via the on_key field.
+Type: nullable Action
+Default action to perform in case if a keyboard input not mapped via any of the
+on_* fields mentioned above.
+A key can be one of the following:
+
+0, 1, ... 9
+a, b, ... z
+A, B, ... Z
+f1, f2, ... f12
+backspace
+left
+right
+up
+down
+home
+end
+page-up
+page-down
+back-tab
+delete
+insert
+enter
+tab
+esc
+ctrl-a, ctrl-b, ... ctrl-z
+ctrl-backspace, ctrl-left, ... ctrl-esc
+alt-a, alt-b, ... alt-z
+
+And finally, the special characters - including space (" ") with their ctrl
+bindings.
+An action contains the following information:
+
+Type: nullable string
+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.
+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" },
+ },
+}
+Now let's try out the new xplr-fzf integration.
+
+Visit Awesome Plugins for more integration options.
+
The default key binding is inspired by vim and slightly
+overlaps with nnn , but it's supposed to be customized as per user
+requirements.
+When you press ? in default mode , you can see the complete list
+of modes and the key mappings for each mode.
+ key remaps action
+. show hidden / ctrl-f search : action ? global help menu G go to bottom V ctrl-a select/unselect all ctrl-c terminate ctrl-i tab next visited path ctrl-o last visited path ctrl-r refresh screen ctrl-u clear selection ctrl-w switch layout d delete down j down enter quit with result f filter g go to h left back k up up l right enter q quit r rename s sort space v toggle selection ~ go home [0-9] input
+key remaps action
+ctrl-c terminate esc escape
+key remaps action
+R relative does not contain ctrl-c terminate ctrl-r reset filters ctrl-u clear filters enter esc done r relative does contain
+key remaps action
+ctrl-c terminate down j to down enter to index esc cancel k up to up [0-9] input
+key remaps action
+ctrl-c terminate esc cancel f follow symlink g top x open in gui
+key remaps action
+ctrl-c terminate ctrl-n down down ctrl-p up up enter esc focus left back right enter tab toggle selection
+key remaps action
+c copy here ctrl-c terminate esc cancel m move here x open in gui
+key remaps action
+! shell c create ctrl-c terminate e open in editor esc cancel l logs m toggle mouse q quit options s selection operations [0-9] go to index
+key remaps action
+ctrl-c terminate d create directory esc cancel f create file
+key remaps action
+ctrl-c terminate enter create file esc cancel
+key remaps action
+ctrl-c terminate enter create directory esc cancel
+key remaps action
+ctrl-c terminate enter rename esc cancel
+key remaps action
+D force delete ctrl-c terminate d delete esc cancel
+key remaps action
+! reverse sorters E by canonical extension reverse M by canonical mime essence reverse N by node type reverse R by relative path reverse S by size reverse backspace remove last sorter ctrl-c terminate ctrl-r reset sorters ctrl-u clear sorters e by canonical extension enter esc done m by canonical mime essence n by node type r by relative path s by size
+key remaps action
+R relative does not contain ctrl-c terminate ctrl-r reset filters ctrl-u clear filters enter esc done r relative does contain
+key remaps action
+ctrl-c terminate enter apply filter esc cancel
+key remaps action
+ctrl-c terminate enter apply filter esc cancel
+key remaps action
+1 default 2 no help menu 3 no selection panel 4 no help or selection ctrl-c terminate esc cancel
+
If you need help debugging or understanding key bindings DYI way, you can
+create a test.lua file with the following script, launch xplr with
+xplr --extra-config text.lua, press # and play around.
+xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
+ help = "test",
+ messages = {
+ "PopMode",
+ { SwitchModeCustom = "test" },
+ },
+}
+
+xplr.config.modes.custom.test = {
+ name = "test",
+ key_bindings = {
+ on_key = {
+ ["1"] = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ a = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ ["`"] = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ f1 = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ tab = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ esc = {
+ messages = {
+ "PopMode",
+ },
+ },
+ ["ctrl-c"] = {
+ messages = {
+ "Terminate",
+ },
+ },
+ },
+ on_alphabet = {
+ messages = {
+ { LogInfo = "on_alphabet called" },
+ },
+ },
+ on_number = {
+ messages = {
+ { LogInfo = "on_number called" },
+ },
+ },
+ -- on_alphanumeric = {
+ -- messages = {
+ -- { LogInfo = "on_alphanumeric called" },
+ -- },
+ -- },
+ on_special_character = {
+ messages = {
+ { LogInfo = "on_special_character called" },
+ },
+ },
+ -- on_character = {
+ -- messages = {
+ -- { LogInfo = "on_character called" },
+ -- },
+ -- },
+ on_navigation = {
+ messages = {
+ { LogInfo = "on_navigation called" },
+ },
+ },
+ default = {
+ messages = {
+ { LogInfo = "default called" },
+ },
+ },
+ },
+}
+
This configuration is exposed via the xplr.config.general API. It contains
the following fields:
@@ -789,13 +1212,13 @@ xplr.config.general.initial_mode = "example"
name help extra_help key_bindings key_bindings layout Type: string
This is the name of the mode visible in the help menu.
-Type: nullable string
If specified, the help menu will display this instead of the auto generated
mappings.
@@ -809,145 +1232,17 @@ help menu.
Type: nullable Layout
If specified, this layout will be used to render the UI.
-Key bindings define how each keyboard input will be handled in a specific mode.
-See the default key bindings for example.
-Key bindings contains the following information:
-
-Type: mapping of Key to nullable Action
-Defines what to do when a specific 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.
-Type: nullable Action
-An action to perform if the keyboard input is a number and is not mapped via
-the on_key field.
-Type: nullable Action
-An action to perform if the keyboard input is a special character and is not
-mapped via the on_key field.
-Type: nullable Action
-Default action to perform in case of a keyboard input not mapped via any of the
-on_key , on_alphabet , on_number or
-on_special_character field.
-A key can be one of the following:
-
-0, 1, ... 9
-a, b, ... z
-A, B, ... Z
-f1, f2, ... f12
-ctrl-a, ctrl-b, ... ctrl-z
-alt-a, alt-b, ... alt-z
-backspace
-left
-right
-up
-down
-home
-end
-page-up
-page-down
-back-tab
-delete
-insert
-enter
-tab
-esc
-
-And finally, the special characters - including space (" ").
-An action contains the following information:
-
-Type: nullable string
-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.
-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" },
- },
-}
-Now let's try out the new xplr-fzf integration.
-
-Visit Awesome Plugins for more integration options.
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:
-To send messages using the key bindings or
+
To send messages using the key bindings or
Lua function calls , messages are represented in
Lua syntax. For example:
@@ -1572,7 +1867,7 @@ that call shell commands.
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
Visit the fzf integration tutorial
To see the environment variables, invoke the shell by typing :! in default
@@ -1691,7 +1986,7 @@ the following fields:
no_selection no_help_no_selection
-Type: Layout
This is the default layout we see when we run xplr.
relative path does not contain xyz (case insens
filter input A filter can be one of the following:
"RelativePathIs"
@@ -2430,207 +2725,6 @@ xplr.config.general.table.col_widths = {
-- With this config, you should only see a single column displaying the
-- relative paths.
-
The default key binding is inspired by vim and slightly
-overlaps with nnn , but it's supposed to be
-customized as per user requirements.
-When you press ? in default mode , you can see the complete list
-of modes and the key mappings for each mode.
-key remaps action
-. show hidden / ctrl-f search : action ? global help menu G go to bottom V ctrl-a select/unselect all ctrl-c terminate ctrl-i tab next visited path ctrl-o last visited path ctrl-r refresh screen ctrl-u clear selection ctrl-w switch layout d delete down j down enter quit with result f filter g go to h left back k up up l right enter q quit r rename s sort space v toggle selection ~ go home [0-9] input
-key remaps action
-ctrl-c terminate esc escape
-key remaps action
-R relative does not contain backspace remove last filter ctrl-c terminate ctrl-r reset filters ctrl-u clear filters enter esc done r relative does contain
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word down j to down enter to index esc cancel k up to up [0-9] input
-key remaps action
-ctrl-c terminate esc cancel f follow symlink g top x open in gui
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-n down down ctrl-p up up ctrl-u remove line ctrl-w remove last word enter esc focus left back right enter tab toggle selection
-key remaps action
-c copy here ctrl-c terminate esc cancel m move here x open in gui
-key remaps action
-! shell c create ctrl-c terminate e open in editor esc cancel l logs m toggle mouse q quit options s selection operations [0-9] go to index
-key remaps action
-ctrl-c terminate d create directory esc cancel f create file
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word enter create file esc cancel
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word enter create directory esc cancel
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word enter rename esc cancel
-key remaps action
-D force delete ctrl-c terminate d delete esc cancel
-key remaps action
-! reverse sorters E by canonical extension reverse M by canonical mime essence reverse N by node type reverse R by relative path reverse S by size reverse backspace remove last sorter ctrl-c terminate ctrl-r reset sorters ctrl-u clear sorters e by canonical extension enter esc done m by canonical mime essence n by node type r by relative path s by size
-key remaps action
-R relative does not contain backspace remove last filter ctrl-c terminate ctrl-r reset filters ctrl-u clear filters enter esc done r relative does contain
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word enter apply filter esc cancel
-key remaps action
-backspace remove last character ctrl-c terminate ctrl-u remove line ctrl-w remove last word enter apply filter esc cancel
-key remaps action
-1 default 2 no help menu 3 no selection panel 4 no help or selection ctrl-c terminate esc cancel
xplr supports pluggable Lua modules that can be used to easily configure or
extend xplr UI and functionalities.
@@ -2706,7 +2800,7 @@ to append .xplr to the name to make them distinguishable. Similar t
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 Tutorial: Adding a New Mode Example: Using Environment Variables and Pipes Example: Using Lua Function Calls Example: Defining Custom Layout .xplr to the name to make them distinguishable. Similar t
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 Tutorial: Adding a New Mode Example: Using Environment Variables and Pipes Example: Using Lua Function Calls Example: Defining Custom Layout Try or Install
