# Introduction

xplr is a terminal UI based file explorer that aims to increase our terminal productivity by being a flexible, interactive orchestrator for the ever growing awesome command-line utilities that work with the file-system.

To achieve its goal, xplr strives to be a fast, minimal and more importantly, hackable file explorer.

xplr is not meant to be a replacement for the standard shell commands or the GUI file managers. Rather, it aims to integrate them all and expose an intuitive, scriptable, keyboard controlled, real-time visual interface, also being an ideal candidate for further integration, enabling you to achieve insane terminal productivity.

## Concept

### Hackable

xplr is built with configurability in mind. So it allows you to perform a vast set of operations and make it look and behave just the way you want.

A few things you can do with the xplr configuration

- Hacks
- Plugins
- Integrations

### Fast

Although speed is not the primary concern, xplr is already fast enough so that you can take it out for a walk into your `node_modules` or `/nix/store` any time you want, and it will only get faster. Still, if you feel like it's somehow making you slow, just report it. Most probably we're just waiting for someone to complain.

Tip: A quick and easy way to optimize the UI rendering is reducing the number of columns in the table.

### Minimal

xplr is being referred to as a File Explorer, not a File Manager. This is because at the core, xplr is only an explorer, and outsources the file management operations to external commands. This helps xplr stay minimal, and focus only on doing what it does best.

So, just like speed, minimalism isn't as as aggressively pursued as hackability. xplr simply prefers to stay minimal and looks for the opportunity to lose some kb if it makes sense.

## Features

Some of the coolest features xplr provide beside the basic stuff:

- Embedded LuaJIT for portability and extensibility.
- A simple modal system based on message passing to control xplr session using:
  - Keyboard inputs
  - Shell Commands
  - Lua Functions
  - Hooks
- Easy, typesafe message passing with `-m MSG` or `-M MSG` subcommands.
- Readline-like input buffer with customizable behavior to read user inputs.
- Switchable recover mode that saves you from doing unwanted things when in a hurry.
- Customizable layouts with built-in panels. For e.g.
  - Selection list to show you the selected paths in real-time.
  - Help menu to show you the available keys bindings in each mode.
  - Input & logs to read input and display logs.
  - Filter and sort pipeline to show you the applied filters and sorters.
- Custom file properties with custom colors can be displayed in the table.
- FIFO manager to manage a FIFO file that can be used to integrate with previewers.
- Virtual root with `--vroot` and `:v` key bindings.
- Different quit options:
  - Quit with success without any output (`q`).
  - Quit with success and the result printed on stdout (`enter`).
  - Quit with success and the present working directory printed on stdout (`:` `q` `p`).
  - Quit with success and the path under focus printed on stdout (`:` `q` `f`).
  - Quit with success and the selection printed on stdout (`:` `q` `s`).
  - Quit with failure (`ctrl-c`).

Q. What features should be added here? let us know.

# Quickstart

Nice to you have here! Let's quickly start with the following steps:

- Install
- Post Install

# Try in Docker

If you prefer to try it before installing, here's the snippet for your convenience.

    docker run -w / -it --rm ubuntu sh -uec '
      apt-get update -y
      apt-get install -y wget tar vim less
      wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz
      tar -xzvf xplr-linux.tar.gz
      ./xplr
    '

# Install

You can install xplr using one of the following ways. Each has their own advantages and limitations.

For example, the Direct Download, From crates.io, and Build From Source methods allow the users to install the latest possible version of xplr, but they have one common drawback - the user will need to keep an eye on the releases, and manually upgrade xplr when a new version is available.

One way to keep an eye on the releases is to watch the repository.

## Community Maintained Repositories

xplr can be installed from one of the following community maintained repositories:

### Cross-platform

#### Nixpkgs

    nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr

Or

    # configuration.nix or darwin-configuration.nix
    environment.systemPackages = with nixpkgs; [
      xplr
      # ...
    ];

#### Home Manager

    # home.nix
    home.packages = with nixpkgs; [
      xplr
      # ...
    ];

Or

    # home.nix
    programs.xplr = {
      enable = true;

      # Optional params:
      plugins = {
        tree-view = fetchFromGitHub {
          owner = "sayanarijit";
          repo = "tree-view.xplr";
        };
        local-plugin = "/home/user/.config/xplr/plugins/local-plugin";
      };
      extraConfig = ''
        require("tree-view").setup()
        require("local-plugin").setup()
      '';
    };

### Arch Linux

(same for Manjaro Linux)

#### Official Community Repo

    sudo pacman -S xplr

#### AUR

Git version:

    paru -S xplr-git

### Alpine Linux

#### Edge Testing Repo

    # Add the following line in /etc/apk/repositories:
    # https://dl-cdn.alpinelinux.org/alpine/edge/testing

    apk add xplr bash less

### Void Linux

#### void-templates by shubham

### Gentoo

#### Overlay GURU

### macOS

Make sure you have the latest version of GNU core utilities installed.

#### MacPorts

    sudo port selfupdate
    sudo port install xplr

#### Homebrew

Stable branch:

    brew install xplr

HEAD branch:

    brew install --head xplr

### FreeBSD

#### ports

    pkg install xplr

Or

    cd /usr/ports/misc/xplr
    make install clean

### NetBSD

#### pkgsrc

    pkgin install xplr

Or

    cd /usr/pkgsrc/sysutils/xplr
    make install

## Direct Download

One can directly download the standalone binary from the releases.

Currently, the following options are available for direct download:

- GNU/Linux
- Linux musl
- macOS

Command-line instructions:

    platform="linux"  # or "macos" / "linux-musl"

    # Download
    wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-$platform.tar.gz

    # Extract
    tar xzvf xplr-$platform.tar.gz

    # Place in $PATH
    sudo mv xplr /usr/local/bin/

## From crates.io

Prerequisites:

- Rust toolchain,
- gcc
- make

Command-line instructions:

    cargo install --locked --force xplr

## Build From Source

Prerequisites:

- git
- Rust toolchain
- gcc
- make

Command-line instructions:

    # Clone the repository
    git clone https://github.com/sayanarijit/xplr.git
    cd xplr

    # Build
    cargo build --locked --release --bin xplr

    # Place in $PATH
    sudo cp target/release/xplr /usr/local/bin/

## Android

### Termux

    pkg install rust make binutils
    cargo install --locked xplr

    # Run
    ~/.cargo/bin/xplr

> Please note that xplr isn't heavily tested on Termux, hence things might need a little tweaking and fixing for a smooth user experience.

# Post Install

Once installed, use the following steps to setup and run xplr.

## Create the customizable config file

    mkdir -p ~/.config/xplr

    version="$(xplr --version | awk '{print $2}')"

    echo "version = '${version:?}'" > ~/.config/xplr/init.lua

Then copy from here and remove / comment out what you don't want to customize.

## Run

    xplr

# Configuration

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:

1. `--config /path/to/init.lua`
2. `~/.config/xplr/init.lua`
3. `/etc/xplr/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.

## Config

The xplr configuration, exposed via `xplr.config` Lua API contains the following sections.

See:

- xplr.config.general
- xplr.config.node_types
- xplr.config.layouts
- xplr.config.modes

## Function

While `xplr.config` defines all the static parts of the configuration, `xplr.fn` defines all the dynamic parts using functions.

See: Lua Function Calls

As always, `xplr.fn.builtin` is where the built-in functions are defined that can be overwritten.

#### xplr.fn.builtin.try_complete_path

Tries to auto complete the path in the input buffer

#### xplr.fn.builtin.fmt_general_table_row_cols_0

Renders the first column in the table

#### xplr.fn.builtin.fmt_general_table_row_cols_1

Renders the second column in the table

#### xplr.fn.builtin.fmt_general_table_row_cols_2

Renders the third column in the table

#### xplr.fn.builtin.fmt_general_table_row_cols_3

Renders the fourth column in the table

#### xplr.fn.builtin.fmt_general_table_row_cols_4

Renders the fifth column in the table

#### xplr.fn.custom

This is where the custom functions can be added.

There is currently no restriction on what kind of functions can be defined in `xplr.fn.custom`.

You can also use nested tables such as `xplr.fn.custom.my_plugin.my_function` to define custom functions.

## Hooks

This section of the configuration cannot be overwritten by another config file or plugin, since this is an optional lua return statement specific to each config file. It can be used to define things that should be explicit for reasons like performance concerns, such as hooks.

Plugins should expose the hooks, and require users to subscribe to them explicitly.

Example:

    return {
      -- Add messages to send when the xplr loads.
      -- This is similar to the `--on-load` command-line option.
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_load = {
        { LogSuccess = "Configuration successfully loaded!" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_load" },
      },

      -- Add messages to send when the directory changes.
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_directory_change = {
        { LogSuccess = "Changed directory" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_directory_change" },
      },

      -- Add messages to send when the focus changes.
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_focus_change = {
        { LogSuccess = "Changed focus" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_focus_change" },
      }

      -- Add messages to send when the mode is switched.
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_mode_switch = {
        { LogSuccess = "Switched mode" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_mode_switch" },
      }

      -- Add messages to send when the layout is switched
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_layout_switch = {
        { LogSuccess = "Switched layout" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_layout_switch" },
      }

      -- Add messages to send when the selection changes
      --
      -- Type: list of [Message](https://xplr.dev/en/message#message)s
      on_selection_change = {
        { LogSuccess = "Selection changed" },
        { CallLuaSilently = "custom.some_plugin_with_hooks.on_selection_change" },
      }
    }

> Note:

> It's not recommended to copy the entire configuration, unless you want to freeze it and miss out on useful updates to the defaults.

> Instead, you can use this as a reference to overwrite only the parts you want to update.

> If you still want to copy the entire configuration, make sure to put your customization before the return statement.

### General Configuration

The general configuration properties are grouped together in `xplr.config.general`.

#### xplr.config.general.disable_debug_error_mode

Set it to `true` if you want to ignore the startup errors. You can still see the errors in the logs.

Type: boolean

#### xplr.config.general.enable_mouse

Set it to `true` if you want to enable mouse scrolling.

Type: boolean

#### xplr.config.general.show_hidden

Set it to `true` to show hidden files by default.

Type: boolean

#### xplr.config.general.read_only

Set it to `true` to use only a subset of selected operations that forbids executing commands or performing write operations on the file-system.

Type: boolean

#### xplr.config.general.enable_recover_mode

Set it to `true` if you want to enable a safety feature that will save you from yourself when you type recklessly.

Type: boolean

#### xplr.config.general.hide_remaps_in_help_menu

Set it to `true` if you want to hide all remaps in the help menu.

Type: boolean

#### xplr.config.general.enforce_bounded_index_navigation

Set it to `true` if you want the cursor to stay in the same position when the focus is on the first path and you navigate to the previous path (by pressing `up`/`k`), or when the focus is on the last path and you navigate to the next path (by pressing `down`/`j`). The default behavior is to rotate from the last/first path.

Type: boolean

#### xplr.config.general.prompt.format

This is the shape of the prompt for the input buffer.

Type: nullable string

#### xplr.config.general.prompt.style

This is the style of the prompt for the input buffer.

Type: Style

#### xplr.config.general.logs.info.format

The string to indicate an information in logs.

Type: nullable string

#### xplr.config.general.logs.info.style

The style for the information logs.

Type: Style

#### xplr.config.general.logs.success.format

The string to indicate an success in logs.

Type: nullable string

#### xplr.config.general.logs.success.style

The style for the success logs.

Type: Style

#### xplr.config.general.logs.warning.format

The string to indicate an warnings in logs.

Type: nullable string

#### xplr.config.general.logs.warning.style

The style for the warnings logs.

Type: Style

#### xplr.config.general.logs.error.format

The string to indicate an error in logs.

Type: nullable string

#### xplr.config.general.logs.error.style

The style for the error logs.

Type: Style

#### xplr.config.general.table.header.cols

Columns to display in the table header.

Type: nullable list of tables with the following fields:

- format: nullable string
- style: Style

#### xplr.config.general.table.header.style

Style of the table header.

Type: Style

#### xplr.config.general.table.header.height

Height of the table header.

Type: nullable integer

#### xplr.config.general.table.row.cols

Columns to display in each row in the table.

Type: nullable list of tables with the following fields:

- format: nullable string
- style: Style

#### xplr.config.general.table.row.style

Default style of the table.

Type: Style

#### xplr.config.general.table.row.height

Height of the table rows.

Type: nullable integer

#### xplr.config.general.table.style

Default style of the table.

Type: Style

#### xplr.config.general.table.tree

Tree to display in the table.

Type: nullable list of tables with the following fields:

- format: nullable string
- style: Style

#### xplr.config.general.table.col_spacing

Spacing between the columns in the table.

Type: nullable integer

#### xplr.config.general.table.col_widths

Constraint for the column widths.

Type: nullable list of Constraint

#### xplr.config.general.selection.item.format

Renderer for each item in the selection list.

Type: nullable string

#### xplr.config.general.selection.item.style

Style for each item in the selection list.

Type: Style

#### xplr.config.general.search.algorithm

The default search algorithm

Type: Search Algorithm

#### xplr.config.general.search.unordered

The default search ordering

Type: boolean

#### xplr.config.general.default_ui.prefix

The content that is placed before the item name for each row by default.

Type: nullable string

#### xplr.config.general.default_ui.suffix

The content which is appended to each item name for each row by default.

Type: nullable string

#### xplr.config.general.default_ui.style

The default style of each item for each row.

Type: Style

#### xplr.config.general.focus_ui.prefix

The string placed before the item name for a focused row.

Type: nullable string

#### xplr.config.general.focus_ui.suffix

The string placed after the item name for a focused row.

Type: nullable string

#### xplr.config.general.focus_ui.style

Style for focused item. Type: Style

#### xplr.config.general.selection_ui.prefix

The string placed before the item name for a selected row.

Type: nullable string

#### xplr.config.general.selection_ui.suffix

The string placed after the item name for a selected row.

Type: nullable string

#### xplr.config.general.selection_ui.style

Style for selected rows.

Type: Style

#### xplr.config.general.focus_selection_ui.prefix

The string placed before item name for a selected row that gets the focus.

Type: nullable string

#### xplr.config.general.focus_selection_ui.suffix

The string placed after the item name for a selected row that gets the focus.

Type: nullable string

#### xplr.config.general.focus_selection_ui.style

Style for a selected row that gets the focus.

Type: Style

#### xplr.config.general.sort_and_filter_ui.separator.format

The shape of the separator for the Sort & filter panel.

Type: nullable string

#### xplr.config.general.sort_and_filter_ui.separator.style

The style of the separator for the Sort & filter panel.

Type: Style

#### xplr.config.general.sort_and_filter_ui.default_identifier.format

The content of the default identifier in Sort & filter panel.

Type: nullable string

#### xplr.config.general.sort_and_filter_ui.default_identifier.style

Style for the default identifier in Sort & filter panel.

Type: Style

#### xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.format

The shape of the forward direction indicator for sort identifiers in Sort & filter panel.

Type: nullable string

#### xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.style

Style of forward direction indicator in Sort & filter panel.

Type: Style

#### xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.format

The shape of the reverse direction indicator for sort identifiers in Sort & filter panel.

Type: nullable string

#### xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.style

Style of reverse direction indicator in Sort & filter panel.

Type: Style

#### xplr.config.general.sort_and_filter_ui.sorter_identifiers

The identifiers used to denote applied sorters in the Sort & filter panel.

Type: nullable mapping of the following key-value pairs:

- key: Sorter
- value:
  - format: nullable string
  - style: Style

#### xplr.config.general.sort_and_filter_ui.filter_identifiers

The identifiers used to denote applied filters in the Sort & filter panel.

Type: nullable mapping of the following key-value pairs:

- key: Filter
- value:
  - format: nullable string
  - style: Style

#### xplr.config.general.sort_and_filter_ui.search_identifiers

The identifiers used to denote applied search input.

Type: { format = nullable string, style = Style }

#### xplr.config.general.sort_and_filter_ui.search_direction_identifiers.ordered.format

The shape of ordered indicator for search ordering identifiers in Sort & filter panel.

Type: nullable string

#### xplr.config.general.sort_and_filter_ui.search_direction_identifiers.unordered.format

The shape of unordered indicator for search ordering identifiers in Sort & filter panel.

Type: nullable string

#### xplr.config.general.panel_ui.default.title.format

The content for panel title by default.

Type: nullable string

#### xplr.config.general.panel_ui.default.title.style

The style for panel title by default.

Type: Style

#### xplr.config.general.panel_ui.default.style

Style of the panels by default.

Type: Style

#### xplr.config.general.panel_ui.default.borders

Defines where to show borders for the panels by default.

Type: nullable list of Border

#### xplr.config.general.panel_ui.default.border_type

Type of the borders by default.

Type: nullable Border Type

#### xplr.config.general.panel_ui.default.border_style

Style of the panel borders by default.

Type: Style

#### xplr.config.general.panel_ui.table.title.format

The content for the table panel title.

Type: nullable string

#### xplr.config.general.panel_ui.table.title.style

Style of the table panel title.

Type: Style

#### xplr.config.general.panel_ui.table.style

Style of the table panel.

Type: Style

#### xplr.config.general.panel_ui.table.borders

Defines where to show borders for the table panel.

Type: nullable list of Border

#### xplr.config.general.panel_ui.table.border_type

Type of the borders for table panel.

Type: nullable Border Type

#### xplr.config.general.panel_ui.table.border_style

Style of the table panel borders.

Type: Style

#### xplr.config.general.panel_ui.help_menu.title.format

The content for the help menu panel title.

Type: nullable string

#### xplr.config.general.panel_ui.help_menu.title.style

Style of the help menu panel title.

Type: Style

#### xplr.config.general.panel_ui.help_menu.style

Style of the help menu panel.

Type: Style

#### xplr.config.general.panel_ui.help_menu.borders

Defines where to show borders for the help menu panel.

Type: nullable list of Border

#### xplr.config.general.panel_ui.help_menu.border_type

Type of the borders for help menu panel.

Type: nullable Border Type

#### xplr.config.general.panel_ui.help_menu.border_style

Style of the help menu panel borders.

Type: Style

#### xplr.config.general.panel_ui.input_and_logs.title.format

The content for the input & logs panel title.

Type: nullable string

#### xplr.config.general.panel_ui.input_and_logs.title.style

Style of the input & logs panel title.

Type: Style

#### xplr.config.general.panel_ui.input_and_logs.borders

#### xplr.config.general.panel_ui.input_and_logs.style

Style of the input & logs panel.

Type: Style Defines where to show borders for the input & logs panel.

Type: nullable list of Border

#### xplr.config.general.panel_ui.input_and_logs.border_type

Type of the borders for input & logs panel.

Type: nullable Border Type

#### xplr.config.general.panel_ui.input_and_logs.border_style

Style of the input & logs panel borders.

Type: Style

#### xplr.config.general.panel_ui.selection.title.format

The content for the selection panel title.

Type: nullable string

#### xplr.config.general.panel_ui.selection.title.style

Style of the selection panel title.

Type: Style

#### xplr.config.general.panel_ui.selection.borders

#### xplr.config.general.panel_ui.selection.style

Style of the selection panel.

Type: Style Defines where to show borders for the selection panel.

Type: nullable list of Border

#### xplr.config.general.panel_ui.selection.border_type

Type of the borders for selection panel.

Type: nullable Border Type

#### xplr.config.general.panel_ui.selection.border_style

Style of the selection panel borders.

Type: Style

#### xplr.config.general.panel_ui.sort_and_filter.title.format

The content for the sort & filter panel title.

Type: nullable string

#### xplr.config.general.panel_ui.sort_and_filter.title.style

Style of the sort & filter panel title.

Type: Style

#### xplr.config.general.panel_ui.sort_and_filter.style

Style of the sort & filter panel.

Type: Style

#### xplr.config.general.panel_ui.sort_and_filter.borders

Defines where to show borders for the sort & filter panel.

Type: nullable list of Border

#### xplr.config.general.panel_ui.sort_and_filter.border_type

Type of the borders for sort & filter panel.

Type: nullable Border Type

#### xplr.config.general.panel_ui.sort_and_filter.border_style

Style of the sort & filter panel borders.

Type: Style

#### xplr.config.general.initial_sorting

Initial group if sorters applied to the nodes list in the table.

Type: nullable list of Node Sorter

#### xplr.config.general.initial_mode

The name of one of the modes to use when xplr loads. This isn't the default mode. To modify the default mode, overwrite xplr.config.modes.builtin.default.

Type: nullable string

#### xplr.config.general.initial_layout

The name of one of the layouts to use when xplr loads. This isn't the default layout. To modify the default layout, overwrite xplr.config.layouts.builtin.default.

Type: nullable string

#### xplr.config.general.start_fifo

Set it to a file path to start fifo when xplr loads. Generally it is used to integrate with external tools like previewers.

Type: nullable string

#### xplr.config.general.global_key_bindings

Use it to define a set of key bindings that are available by default in every mode. They can be overwritten.

Type: Key Bindings

### Node Types

This section defines how to deal with different kinds of nodes (files, directories, symlinks etc.) based on their properties.

One node can fall into multiple categories. For example, a node can have the extension `md`, and also be a file. In that case, the properties from the more specific category i.e. extension will be used.

This can be configured using the `xplr.config.node_types` Lua API.

#### xplr.config.node_types.directory.style

The style for the directory nodes

Type: Style

#### xplr.config.node_types.directory.meta.icon

Metadata for the directory nodes. You can set as many metadata as you want.

Type: nullable string

Example:

    xplr.config.node_types.directory.meta.foo = "foo"
    xplr.config.node_types.directory.meta.bar = "bar"

#### xplr.config.node_types.file.style

The style for the file nodes.

Type: Style

#### xplr.config.node_types.file.meta.icon

Metadata for the file nodes. You can set as many metadata as you want.

Type: nullable string

Example:

    xplr.config.node_types.file.meta.foo = "foo"
    xplr.config.node_types.file.meta.bar = "bar"

#### xplr.config.node_types.symlink.style

The style for the symlink nodes.

Type: Style

#### xplr.config.node_types.symlink.meta.icon

Metadata for the symlink nodes. You can set as many metadata as you want.

Type: nullable string

Example:

    xplr.config.node_types.symlink.meta.foo = "foo"
    xplr.config.node_types.symlink.meta.bar = "bar"

#### xplr.config.node_types.mime_essence

Metadata and style based on mime types. It is possible to use the wildcard `*` to match all mime sub types. It will be overwritten by the more specific sub types that are defined.

Type: mapping of the following key-value pairs:

- key: string
- value:
  - key: string
  - value: Node Type

Example:

    xplr.config.node_types.mime_essence = {
      application = {
        -- application/*
        ["*"] = { meta = { icon = "a" } },

        -- application/pdf
        pdf = { meta = { icon = "" }, style = { fg = "Blue" } },

        -- application/zip
        zip = { meta = { icon = ""} },
      },
    }

#### xplr.config.node_types.extension

Metadata and style based on extension.

Type: mapping of the following key-value pairs:

- key: string
- value: Node Type

Example:

    xplr.config.node_types.extension.md = { meta = { icon = "" }, style = { fg = "Blue" } }
    xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }

#### xplr.config.node_types.special

Metadata and style based on special file names.

Type: mapping of the following key-value pairs:

- key: string
- value: Node Type

Example:

    xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
    xplr.config.node_types.special["Downloads"] = { meta = { icon = "" }, style = { fg = "Blue" } }

### Layouts

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.

`xplr.config.layouts.builtin` contain some built-in panels which can be overridden, but you can't add or remove panels in it.

You can add new panels in `xplr.config.layouts.custom`.

##### Example: Defining Custom Layout

    xplr.config.layouts.builtin.default = {
      Horizontal = {
        config = {
          margin = 1,
          horizontal_margin = 1,
          vertical_margin = 1,
          constraints = {
            { Percentage = 50 },
            { Percentage = 50 },
          }
        },
        splits = {
          "Table",
          "HelpMenu",
        }
      }
    }

Result:

    ╭ /home ─────────────╮╭ Help [default] ────╮
    │   ╭─── path        ││.    show hidden    │
    │   ├▸[ð Desktop/]   ││/    search         │
    │   ├  ð Documents/  ││:    action         │
    │   ├  ð Downloads/  ││?    global help    │
    │   ├  ð GitHub/     ││G    go to bottom   │
    │   ├  ð Music/      ││V    select/unselect│
    │   ├  ð Pictures/   ││ctrl duplicate as   │
    │   ├  ð Public/     ││ctrl next visit     │
    ╰────────────────────╯╰────────────────────╯

#### xplr.config.layouts.builtin.default

The default layout

Type: Layout

#### xplr.config.layouts.builtin.no_help

The layout without help menu

Type: Layout

#### xplr.config.layouts.builtin.no_selection

The layout without selection panel

Type: Layout

#### xplr.config.layouts.builtin.no_help_no_selection

The layout without help menu and selection panel

Type: Layout

#### xplr.config.layouts.custom

This is where you can define custom layouts

Type: mapping of the following key-value pairs:

- key: string
- value: Layout

Example:

    xplr.config.layouts.custom.example = "Nothing" -- Show a blank screen
    xplr.config.general.initial_layout = "example" -- Load the example layout

### Modes

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.builtin` contain some built-in modes which can be overridden, but you can't add or remove modes in it.

#### xplr.config.modes.builtin.default

The builtin default mode. Visit the Default Key Bindings to see what each mode does.

Type: Mode

#### xplr.config.modes.builtin.debug_error

The builtin debug error mode.

Type: Mode

#### xplr.config.modes.builtin.recover

The builtin recover mode.

Type: Mode

#### xplr.config.modes.builtin.go_to_path

The builtin go to path mode.

Type: Mode

#### xplr.config.modes.builtin.move_to

The builtin move_to mode.

Type: Mode

#### xplr.config.modes.builtin.copy_to

The builtin copy_to mode.

Type: Mode

#### xplr.config.modes.builtin.selection_ops

The builtin selection ops mode.

Type: Mode

#### xplr.config.modes.builtin.create

The builtin create mode.

Type: Mode

#### xplr.config.modes.builtin.create_directory

The builtin create directory mode.

Type: Mode

#### xplr.config.modes.builtin.create_file

The builtin create file mode.

Type: Mode

#### xplr.config.modes.builtin.number

The builtin number mode.

Type: Mode

#### xplr.config.modes.builtin.go_to

The builtin go to mode.

Type: Mode

#### xplr.config.modes.builtin.rename

The builtin rename mode.

Type: Mode

#### xplr.config.modes.builtin.duplicate_as

The builtin duplicate as mode.

Type: Mode

#### xplr.config.modes.builtin.delete

The builtin delete mode.

Type: Mode

#### xplr.config.modes.builtin.action

The builtin action mode.

Type: Mode

#### xplr.config.modes.builtin.quit

The builtin quit mode.

Type: Mode

#### xplr.config.modes.builtin.search

The builtin search mode.

Type: Mode

#### xplr.config.modes.builtin.filter

The builtin filter mode.

Type: Mode

#### xplr.config.modes.builtin.relative_path_does_match_regex

The builtin relative_path_does_match_regex mode.

Type: Mode

#### xplr.config.modes.builtin.relative_path_does_not_match_regex

The builtin relative_path_does_not_match_regex mode.

Type: Mode

#### xplr.config.modes.builtin.sort

The builtin sort mode.

Type: Mode

#### xplr.config.modes.builtin.switch_layout

The builtin switch layout mode.

Type: Mode

#### xplr.config.modes.builtin.vroot

The builtin vroot mode.

Type: Mode

#### xplr.config.modes.builtin.edit_permissions

The builtin edit permissions mode.

Type: Mode

#### xplr.config.modes.custom

This is where you define custom modes.

Type: mapping of the following key-value pairs:

- key: string
- value: Mode

Example:

    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"

# Concept

These are the concepts that make xplr probably the most hackable terminal file explorer.

- Key Bindings
- Node Type
- Layout
- Mode
- Message
- Borders
- Style
- Sorting
- Filtering
- Column Renderer
- Lua Function Calls
- Environment Variables and Pipes

# Sum Type

> This section isn't specific to xplr. However, since xplr configuration makes heavy use of this particular data type, even though it isn't available in most of the mainstream programming languages (yet), making it a wild or unfamiliar concept for many, it's worth doing a quick introduction here.

> If you're already familiar with Sum Type / Tagged Union (e.g. Rust's enum), you can skip ahead.

While reading this doc, you'll come across some data types like Layout, Color, Message etc. that says something like "x is a sum type that can be any of the following", and then you'll see a list of strings and/or lua tables just below.

Yes, they are actually sum types, i.e. they can be any of the given set of tagged variants listed there.

Notice the word "be". Unlike classes or structs (aka product types), they can't "have" values, they can only "be" the value, or rather, be one of the possible set of values.

Also notice the word "tagged". Unlike the single variant `null`, or the dual variant `boolean` types, the variants of sum types are tagged (i.e. named), and may further have, or be, value or values of any data type.

A simple example of a sum type is an enum. Many programming languages have them, but only a few modern programming languages allow nesting other types into a sum type.

    #![allow(unused)]
    fn main() {
    enum Color {
        Red,
        Green,
    }
    }

Here, `Color` can be one of two possible set of values: `Red` and `Green`, just like `boolean`, but unlike `boolean`, being tagged allows `Color` to have more than two variants if required, by changing the definition.

e.g.

    #![allow(unused)]
    fn main() {
    enum Color {
        Red,
        Green,
        Blue,
    }
    }

We'd document it here as:

> Result is a sum type that can be one of the following:

> - "Red"
> - "Green"
> - "Blue"

But some languages (like Rust, Haskell, Elm etc.) go even further, allowing us to associate each branch of the enum with further nested types like:

    #![allow(unused)]
    fn main() {
    enum Layout {
        Table,
        HelpMenu,
        Horizontal {
            config: LayoutConfig,  // A product type (similar to class/struct)
            splits: Vec<Layout>  // A list of "Layout"s (i.e. list of sum types)
        },
    }
    }

Here, as we can see, unlike the first example, some of `Layout`'s possible variants can have further nested types associated with them. Note that `Horizontal` here can have a sum type (e.g. enum), or a product type (e.g. class/struct), or both (any number of them actually) nested in it. But the nested values will only exist when `Layout` is `Horizontal`.

We'd document it here as:

> Layout is a sum type that can be one of the following:

> - "Table"
> - "HelpMenu"
> - { Horizontal = { config = Layout Config, splits = { Layout, ... } }

And then we'd go on documenting whatever `Layout Config` is.

So, there you go. This is exactly what sum types are - glorified enums that can have nested types in each branch.

If you're still confused about something, or if you found an error in this explanation, feel free to discuss together.

# Key Bindings

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.

# Configure Key Bindings

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.

Try debug key bindings to understand how key bindings actually work.

## Key Bindings

Key bindings contains the following information:

- on_key
- on_alphabet
- on_number
- on_alphanumeric
- on_special_character
- on_character
- on_navigation
- on_function
- default

### on_key

Type: mapping of Key to nullable Action

Defines what to do when an exact key is pressed.

### on_alphabet

Type: nullable Action

An action to perform if the keyboard input is an alphabet and is not mapped via the on_key field.

### on_number

Type: nullable Action

An action to perform if the keyboard input is a number and is not mapped via the on_key field.

### on_alphanumeric

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.

### on_special_character

Type: nullable Action

An action to perform if the keyboard input is a special character and is not mapped via the on_key field.

### on_character

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.

### on_navigation

Type: nullable Action

An action to perform if the keyboard input is a navigation key and is not mapped via the on_key field.

### on_function

Type: nullable Action

An action to perform if the keyboard input is a function key and is not mapped via the on_key field.

### default

Type: nullable Action

Default action to perform in case if a keyboard input not mapped via any of the `on_*` fields mentioned above.

## Key

A key is a sum type 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.

## Action

An action contains the following information:

- help
- messages

### 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 = {
          F = {
            help = "search",
            messages = {
              {
                BashExec = [===[
                  PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf)
                  if [ -d "$PTH" ]; then
                    "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
                  else
                    "$XPLR" -m 'FocusPath: %q' "$PTH"
                  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`, `$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.

# Default Key Bindings

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.

### default

key | remaps | action
--- | --- | ---
( |  | prev deep branch
) |  | next deep branch
. |  | show hidden
/ | ctrl-f | search
: |  | action
? | f1 | global help menu
G |  | go to bottom
V | ctrl-a | select/unselect all
c |  | copy to
ctrl-d |  | duplicate as
ctrl-i | tab | next visited path
ctrl-n |  | next selection
ctrl-o |  | last visited path
ctrl-p |  | prev selection
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
m |  | move to
page-down |  | scroll down
page-up |  | scroll up
q |  | quit
r |  | rename
s |  | sort
space | v | toggle selection
{ |  | scroll up half
} |  | scroll down half
~ |  | go home
[0-9] |  | input

### go_to_path

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### rename

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### recover

key | remaps | action
--- | --- | ---
f1 |  | global help menu

### go_to

key | remaps | action
--- | --- | ---
f |  | follow symlink
f1 |  | global help menu
g |  | top
i |  | initial $PWD
p |  | path
x |  | open in gui

### relative_path_does_match_regex

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu

### action

key | remaps | action
--- | --- | ---
! |  | shell
c |  | create
e |  | open in editor
f1 |  | global help menu
l |  | logs
m |  | toggle mouse
p |  | edit permissions
q |  | quit options
s |  | selection operations
v |  | vroot
[0-9] |  | go to index

### default

key | remaps | action
--- | --- | ---
( |  | prev deep branch
) |  | next deep branch
. |  | show hidden
/ | ctrl-f | search
: |  | action
? | f1 | global help menu
G |  | go to bottom
V | ctrl-a | select/unselect all
c |  | copy to
ctrl-d |  | duplicate as
ctrl-i | tab | next visited path
ctrl-n |  | next selection
ctrl-o |  | last visited path
ctrl-p |  | prev selection
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
m |  | move to
page-down |  | scroll down
page-up |  | scroll up
q |  | quit
r |  | rename
s |  | sort
space | v | toggle selection
{ |  | scroll up half
} |  | scroll down half
~ |  | go home
[0-9] |  | input

### debug_error

key | remaps | action
--- | --- | ---
enter |  | open logs in editor
f1 |  | global help menu
q |  | quit

### create_directory

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### selection_ops

key | remaps | action
--- | --- | ---
c |  | copy here
e |  | edit selection
f1 |  | global help menu
h |  | hardlink here
l |  | list selection
m |  | move here
s |  | softlink here
u |  | clear selection

### relative_path_does_not_match_regex

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu

### create_file

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### quit

key | remaps | action
--- | --- | ---
enter |  | just quit
f |  | quit printing focus
f1 |  | global help menu
p |  | quit printing pwd
r |  | quit printing result
s |  | quit printing selection

### create

key | remaps | action
--- | --- | ---
d |  | create directory
f |  | create file
f1 |  | global help menu

### vroot

key | remaps | action
--- | --- | ---
. |  | vroot $PWD
/ |  | vroot /
ctrl-r |  | reset vroot
ctrl-u |  | unset vroot
f1 |  | global help menu
v |  | toggle vroot
~ |  | vroot $HOME

### search

key | remaps | action
--- | --- | ---
ctrl-a |  | toggle search algorithm
ctrl-f |  | fuzzy search
ctrl-n | down | down
ctrl-p | up | up
ctrl-r |  | regex search
ctrl-s |  | sort (no search order)
ctrl-z |  | toggle ordering
enter |  | submit
esc |  | cancel
f1 |  | global help menu
left |  | back
right |  | enter
tab |  | toggle selection

### switch_layout

key | remaps | action
--- | --- | ---
1 |  | default
2 |  | no help menu
3 |  | no selection panel
4 |  | no help or selection
f1 |  | global help menu

### sort

key | remaps | action
--- | --- | ---
! |  | reverse sorters
C |  | by created reverse
E |  | by canonical extension reverse
L |  | by last modified 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
c |  | by created
ctrl-r |  | reset sorters
ctrl-u |  | clear sorters
e |  | by canonical extension
enter |  | submit
f1 |  | global help menu
l |  | by last modified
m |  | by canonical mime essence
n |  | by node type
r |  | by relative path
s |  | by size

### number

key | remaps | action
--- | --- | ---
down | j | to down
enter |  | to index
f1 |  | global help menu
k | up | to up
[0-9] |  | input

### copy_to

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### edit_permissions

key | remaps | action
--- | --- | ---
G |  | -group
M |  | min
O |  | -other
U |  | -user
ctrl-r |  | reset
enter |  | submit
f1 |  | global help menu
g |  | +group
m |  | max
o |  | +other
u |  | +user

### delete

key | remaps | action
--- | --- | ---
D |  | force delete
d |  | delete
f1 |  | global help menu

### move_to

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

### filter

key | remaps | action
--- | --- | ---
R |  | relative path does not match regex
backspace |  | remove last filter
ctrl-r |  | reset filters
ctrl-u |  | clear filters
f1 |  | global help menu
r |  | relative path does match regex

### duplicate_as

key | remaps | action
--- | --- | ---
enter |  | submit
f1 |  | global help menu
tab |  | try complete

# Debug Key Bindings

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 test.lua`, press `#` and play around.

    -- The global key bindings inherited by all the modes.
    xplr.config.general.global_key_bindings = {
      on_key = {
        esc = {
          help = "escape",
          messages = {
            { LogInfo = "global on_key(esc) called" },
            "PopMode",
          },
        },
        ["ctrl-c"] = {
          help = "terminate",
          messages = {
            "Terminate",
          },
        },
      },
    }

    -- Press `#` to enter the `debug key bindings` mode.
    xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
      help = "test",
      messages = {
        "PopMode",
        { SwitchModeCustom = "debug_key_bindings" },
      },
    }

    -- The `debug key bindings` mode.
    xplr.config.modes.custom.debug_key_bindings = {
      name = "debug key bindings",
      key_bindings = {
        on_key = {
          ["1"] = {
            messages = {
              { LogInfo = "on_key(1) called" },
            },
          },
          a = {
            messages = {
              { LogInfo = "on_key(a) called" },
            },
          },
          ["`"] = {
            messages = {
              { LogInfo = "on_key(`) called" },
            },
          },
          tab = {
            messages = {
              { LogInfo = "on_key(tab) called" },
            },
          },
          f1 = {
            messages = {
              { LogInfo = "on_key(f1) called" },
            },
          },
        },
        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" },
          },
        },
        on_function = {
          messages = {
            { LogInfo = "on_function called" },
          },
        },
        default = {
          messages = {
            { LogInfo = "default called" },
          },
        },
      },
    }

# 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 = 1,
          vertical_margin = 1,
          constraints = {
            { Percentage = 50 },
            { Percentage = 50 },
          }
        },
        splits = {
          "Table",
          "HelpMenu",
        }
      }
    }

Result:

     ╭ /home ─────────────╮╭ Help [default] ────╮
     │   ╭─── path        ││.    show hidden    │
     │   ├▸[ð Desktop/]   ││/    search         │
     │   ├  ð Documents/  ││:    action         │
     │   ├  ð Downloads/  ││?    global help    │
     │   ├  ð GitHub/     ││G    go to bottom   │
     │   ├  ð Music/      ││V    select/unselect│
     │   ├  ð Pictures/   ││ctrl duplicate as   │
     │   ├  ð Public/     ││ctrl next visit     │
     ╰────────────────────╯╰────────────────────╯

A layout is a sum type can be one of the following:

- Nothing
- Table
- InputAndLogs
- Selection
- HelpMenu
- SortAndFilter
- Static
- Dynamic
- Horizontal
- Vertical
- CustomContent (deprecated, use `Static` or `Dynamic`)

### Nothing

This layout contains a blank panel.

Type: "Nothing"

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

Type: "InputAndLogs"

### Selection

This layout contains the panel displaying the selected paths.

Type: "Selection"

### HelpMenu

This layout contains the panel displaying the help menu for the current mode in real-time.

Type: "HelpMenu"

### SortAndFilter

This layout contains the panel displaying the pipeline of sorters and filters applied on the list of paths being displayed.

Type: "SortAndFilter"

### Static

This is a custom layout to render static content.

Type: { Static = Custom Panel }

### Dynamic

This is a custom layout to render dynamic content using a function defined in xplr.fn that takes Content Renderer Argument and returns Custom Panel.

Type: { Dynamic = "Content Renderer" }

### Horizontal

This is a special layout that splits the panel into two horizontal parts.

It contains the following information:

- config
- splits

Type: { Vertical = { config = Layout Config, splits = { Layout, ... } }

### Vertical

This is a special layout that splits the panel into two vertical parts.

It contains the following information:

- config
- splits

Type: { Vertical = { config = Layout Config, splits = { Layout, ... } }

## Layout Config

A layout config contains the following information:

- margin
- horizontal_margin
- vertical_margin
- constraints

### margin

Type: nullable integer

The width of the margin in all direction.

### horizontal_Margin

Type: nullable integer

The width of the horizontal margins. Overwrites the margin value.

### vertical_Margin

Type: nullable integer

The width of the vertical margins. Overwrites the margin value.

### constraints

Type: nullable list of Constraint

The constraints applied on the layout.

## Constraint

A constraint is a sum type can be one of the following:

- { Percentage = int }
- { Ratio = { int, int } }
- { Length = { int }
- { LengthLessThanScreenHeight = int }
- { LengthLessThanScreenWidth = int }
- { LengthLessThanLayoutHeight = int }
- { LengthLessThanLayoutWidth = int }
- { Max = int }
- { MaxLessThanScreenHeight = int }
- { MaxLessThanScreenWidth = int }
- { MaxLessThanLayoutHeight = int }
- { MaxLessThanLayoutWidth = int }
- { Min = int }
- { MinLessThanScreenHeight = int }
- { MinLessThanScreenWidth = int }
- { MinLessThanLayoutHeight = int }
- { MinLessThanLayoutWidth = int }

## splits

Type: list of Layout

The list of child layouts to fit into the parent layout.

## Custom Panel

Custom panel is a sum type can be one of the following:

- CustomParagraph
- CustomList
- CustomTable
- CustomLayout

### CustomParagraph

A paragraph to render. It contains the following fields:

- ui (nullable Panel UI Config): Optional UI config for the panel.
- body (string): The string to render.

#### Example: Render a custom static paragraph

    xplr.config.layouts.builtin.default = {
      Static = {
        CustomParagraph = {
          ui = { title = { format = " custom title " } },
          body = "custom body",
        },
      },
    }

Result:

    ╭ custom title ────────╮
    │custom body           │
    │                      │
    │                      │
    ╰──────────────────────╯

#### Example: Render a custom dynamic paragraph

    xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

    xplr.fn.custom.render_layout = function(ctx)
      return {
        CustomParagraph = {
          ui = { title = { format = ctx.app.pwd } },
          body = xplr.util.to_yaml(ctx.app.focused_node),
        },
      }
    end

Result:

    ╭/home/sayanarijit───────────────────────────╮
    │mime_essence: inode/directory               │
    │relative_path: Desktop                      │
    │is_symlink: false                           │
    │is_readonly: false                          │
    │parent: /home/sayanarijit                   │
    │absolute_path: /home/sayanarijit/Desktop    │
    │is_broken: false                            │
    │created: 1668087850396758714                │
    │size: 4096                                  │
    │gid: 100                                    │
    ╰────────────────────────────────────────────╯

### CustomList

A list to render. It contains the following fields:

- ui (nullable Panel UI Config): Optional UI config for the panel.
- body (list of string): The list of strings to display.

#### Example: Render a custom static list

    xplr.config.layouts.builtin.default = {
      Static = {
        CustomList = {
          ui = { title = { format = " custom title " } },
          body = { "1", "2", "3" },
        },
      },
    }

Result:

    ╭ custom title ─────────────╮
    │1                          │
    │2                          │
    │3                          │
    │                           │
    ╰───────────────────────────╯

#### Example: Render a custom dynamic list

    xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

    xplr.fn.custom.render_layout = function(ctx)
      return {
        CustomList = {
          ui = { title = { format = ctx.app.pwd } },
          body = {
            (ctx.app.focused_node or {}).relative_path or "",
            ctx.app.version,
            tostring(ctx.app.pid),
          },
        },
      }
    end

Result:

    ╭/home/sayanarijit──────────╮
    │Desktop                    │
    │0.21.2                     │
    │17336                      │
    │                           │
    │                           │
    ╰───────────────────────────╯

## CustomTable

A custom table to render. It contains the following fields:

- ui (nullable Panel UI Config): Optional UI config for the panel.
- widths (list of Constraint): Width of the columns.
- col_spacing (nullable int): Spacing between columns. Defaults to 1.
- body (list of list of string): The rows and columns to render.

#### Example: Render a custom static table

    xplr.config.layouts.builtin.default = {
      Static = {
        CustomTable = {
          ui = { title = { format = " custom title " } },
          widths = {
            { Percentage = 50 },
            { Percentage = 50 },
          },
          body = {
            { "a", "b" },
            { "c", "d" },
          },
        },
      },
    }

Result:

    ╭ custom title ────────────────────╮
    │a                 b               │
    │c                 d               │
    │                                  │
    │                                  │
    │                                  │
    ╰──────────────────────────────────╯

#### Example: Render a custom dynamic table

    xplr.config.layouts.builtin.default = {Dynamic = "custom.render_layout" }

    xplr.fn.custom.render_layout = function(ctx)
      return {
        CustomTable = {
          ui = { title = { format = ctx.app.pwd } },
          widths = {
            { Percentage = 50 },
            { Percentage = 50 },
          },
          body = {
            { "", "" },
            { "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

Result:

    ╭/home/sayanarijit───────────────────────────╮
    │                                            │
    │Layout height          12                   │
    │Layout width           46                   │
    │                                            │
    │Screen height          12                   │
    │Screen width           46                   │
    │                                            │
    │                                            │
    │                                            │
    │                                            │
    ╰────────────────────────────────────────────╯

### CustomLayout

A whole custom layout to render. It doesn't make sense to use it as a Static layout, but can be very useful to render as a Dynamic layout for use cases where the structure of the layout needs to change without having to switch modes.

> WARNING: Rendering the same dynamic custom layout recursively will result in a ugly crash.

#### Example: Render a custom dynamic layout

    xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

    xplr.fn.custom.render_layout = function(ctx)
      local inner = {
        config = {
          constraints = {
            { Percentage = 50 },
            { Percentage = 50 },
          },
        },
        splits = {
          { Static = { CustomParagraph = { body = "Try your luck..." } } },
          { Static = { CustomParagraph = { body = "Press ctrl-r" } } },
        },
      }

      local layout_type = "Vertical"
      if math.random(1, 2) == 1 then
        layout_type = "Horizontal"
      end

      return { CustomLayout = { [layout_type] = inner } }
    end

Result:

    ╭─────────────────────╮╭─────────────────────╮
    │Try your luck...     ││Press ctrl-r         │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    │                     ││                     │
    ╰─────────────────────╯╰─────────────────────╯

Or

    ╭────────────────────────────────────────────╮
    │Try your luck...                            │
    │                                            │
    │                                            │
    │                                            │
    ╰────────────────────────────────────────────╯
    ╭────────────────────────────────────────────╮
    │Press ctrl-r                                │
    │                                            │
    │                                            │
    │                                            │
    ╰────────────────────────────────────────────╯

## Panel UI Config

It contains the following optional fields:

- title ({ format = "string", style = Style }): the title of the panel.
- style (Style): The style of the panel body.
- borders (nullable list of Border): The shape of the borders.
- border_type (Border Type): The type of the borders.
- border_style (Style): The style of the borders.

## 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

It contains the following information:

- layout_size
- screen_size
- app

### Size

It contains the following information:

- x
- y
- height
- width

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

- version
- pwd
- initial_pwd
- vroot
- focused_node
- selection
- mode
- layout
- input_buffer
- pid
- session_path
- explorer_config

## Also See:

- xplr.config.layouts

# Mode

A mode contains the following information:

- name
- help
- extra_help
- key_bindings
- layout
- prompt

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

### prompt

Type: nullable string

If set, this prompt will be displayed in the input buffer when in this mode.

## Also See:

- xplr.config.modes

# Message

You can think of xplr as a server. Just like web servers listen to HTTP requests, xplr listens to messages.

A message is a sum type that can have these possible values.

You can send these messages to an xplr session in the following ways:

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

### Format

To send messages using the key bindings or Lua function calls, messages are represented in Lua syntax.

For example:

- `"Quit"`
- `{ FocusPath = "/path/to/file" }`
- `{ Call = { command = "bash", args = { "-c", "read -p test" } } }`

However, to send messages using the input pipe, they need to be represented using YAML (or JSON) syntax.

For example:

- `Quit`
- `FocusPath: "/path/to/file"`
- `Call: { command: bash, args: ["-c", "read -p test"] }`

Use `"$XPLR" -m TEMPLATE [VALUE]...` command-line option to safely format `TEMPLATE` into a valid message. If uses jf to parse and render the template. And `$XPLR` (rather than `xplr`) makes sure that the correct version of the binary is being used.

For example:

- `"$XPLR" -m Quit`
- `"$XPLR" -m 'FocusPath: %q' "/path/to/file"`
- `"$XPLR" -m 'Call: { command: %q, args: [%*q] }' bash -c "read -p test"`

## Also See:

- Full List of Messages

# Full List of Messages

xplr messages categorized based on their purpose.

## Categories

- Exploring
- Screen
- Navigation
- Virtual Root
- Reading Input
- Switching Mode
- Switching Layout
- Executing Commands
- Calling Lua Functions
- Select Operations
- Filter Operations
- Sort Operations
- Search Operations
- Mouse Operations
- Fifo Operations
- Logging
- Debugging
- Quit Options

### Exploring

#### ExplorePwd

Explore the present working directory and register the filtered nodes. This operation is expensive. So, try to avoid using it too often.

Example:

- Lua: `"ExplorePwd"`
- YAML: `ExplorePwd`

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

Example:

- Lua: `"ExplorePwdAsync"`
- YAML: `ExplorePwdAsync`

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

Example:

- Lua: `"ExploreParentsAsync"`
- YAML: `ExploreParentsAsync`

### Screen

#### ClearScreen

Clear the screen.

Example:

- Lua: `"ClearScreen"`
- YAML: `ClearScreen`

#### Refresh

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.

Example:

- Lua: `"Refresh"`
- YAML: `Refresh`

### Navigation

#### FocusNext

Focus next node.

Example:

- Lua: `"FocusNext"`
- YAML: `FocusNext`

#### FocusNextSelection

Focus on the next selected node.

Example:

- Lua: `"FocusNextSelection"`
- YAML: `FocusNextSelection`

#### FocusNextByRelativeIndex

Focus on the `n`th node relative to the current focus where `n` is a given value.

Type: { FocusNextByRelativeIndex = int }

Example:

- Lua: `{ FocusNextByRelativeIndex = 2 }`
- YAML: `FocusNextByRelativeIndex: 2`

#### FocusNextByRelativeIndexFromInput

Focus on the `n`th node relative to the current focus where `n` is read from the input buffer.

Example:

- Lua: `"FocusNextByRelativeIndexFromInput"`
- YAML: `FocusNextByRelativeIndexFromInput`

#### FocusPrevious

Focus on the previous item.

Example:

- Lua: `"FocusPrevious"`
- YAML: `FocusPrevious`

#### FocusPreviousSelection

Focus on the previous selection item.

Example:

- Lua: `"FocusPreviousSelection"`
- YAML: `FocusPreviousSelection`

#### FocusPreviousByRelativeIndex

Focus on the `-n`th node relative to the current focus where `n` is a given value.

Type: { FocusPreviousByRelativeIndex = int }

Example:

- Lua: `{ FocusPreviousByRelativeIndex = 2 }`
- YAML: `FocusPreviousByRelativeIndex: 2`

#### FocusPreviousByRelativeIndexFromInput

Focus on the `-n`th node relative to the current focus where `n` is read from the input buffer.

Example:

- Lua: `"FocusPreviousByRelativeIndexFromInput"`
- YAML: `FocusPreviousByRelativeIndexFromInput`

#### FocusFirst

Focus on the first node.

Example:

- Lua: `"FocusFirst"`
- YAML: `FocusFirst`

#### FocusLast

Focus on the last node.

Example:

- Lua: `"FocusLast"`
- YAML: `FocusLast`

#### FocusPath

Focus on the given path.

Type: { FocusPath = "string" }

Example:

- Lua: `{ FocusPath = "/path/to/file" }`
- YAML: `FocusPath: /path/to/file`

#### FocusPathFromInput

Focus on the path read from input buffer.

Example:

- Lua: `"FocusPathFromInput"`
- YAML: `FocusPathFromInput`

#### FocusByIndex

Focus on the absolute `n`th node where `n` is a given value.

Type: { FocusByIndex = int }

Example:

- Lua: `{ FocusByIndex = 2 }`
- YAML: `FocusByIndex: 2`

#### FocusByIndexFromInput

Focus on the absolute `n`th node where `n` is read from the input buffer.

Example:

- Lua: `"FocusByIndexFromInput"`
- YAML: `FocusByIndexFromInput`

#### FocusByFileName

Focus on the file by name from the present working directory.

Type: { FocusByFileName = "string" }

Example:

- Lua: `{ FocusByFileName = "filename.ext" }`
- YAML: `FocusByFileName: filename.ext`

#### ScrollUp

Scroll up by terminal height.

Example:

- Lua: `"ScrollUp"`
- YAML: `ScrollUp`

#### ScrollDown

Scroll down by terminal height.

Example:

- Lua: `"ScrollDown"`
- YAML: `ScrollDown`

#### ScrollUpHalf

Scroll up by half of terminal height.

Example:

- Lua: `"ScrollUpHalf"`
- YAML: `ScrollUpHalf`

#### ScrollDownHalf

Scroll down by half of terminal height.

Example:

- Lua: `"ScrollDownHalf"`
- YAML: `ScrollDownHalf`

#### ChangeDirectory

Change the present working directory ($PWD)

Type: { ChangeDirectory = "string" }

Example:

- Lua: `{ ChangeDirectory = "/path/to/directory" }`
- YAML: `ChangeDirectory: /path/to/directory`

#### Enter

Enter into the currently focused path if it's a directory.

Example:

- Lua: `"Enter"`
- YAML: `Enter`

#### Back

Go back to the parent directory.

Example:

- Lua: `"Back"`
- YAML: `Back`

#### LastVisitedPath

Go to the last path visited.

Example:

- Lua: `"LastVisitedPath"`
- YAML: `LastVisitedPath`

#### NextVisitedPath

Go to the next path visited.

Example:

- Lua: `"NextVisitedPath"`
- YAML: `NextVisitedPath`

#### PreviousVisitedDeepBranch

Go to the previous deep level branch.

Example:

- Lua: `"PreviousVisitedDeepBranch"`
- YAML: `PreviousVisitedDeepBranch`

#### NextVisitedDeepBranch

Go to the next deep level branch.

Example:

- Lua: `"NextVisitedDeepBranch"`
- YAML: `NextVisitedDeepBranch`

#### FollowSymlink

Follow the symlink under focus to its actual location.

Example:

- Lua: `"FollowSymlink"`
- YAML: `FollowSymlink`

### Virtual Root

#### SetVroot

Sets the virtual root for isolating xplr navigation, similar to `--vroot`, but temporary (can be reset back to initial value). If the $PWD is outside the vroot, xplr will automatically enter vroot.

Type: { SetVroot = "string" }

Example:

- Lua: `{ SetVroot = "/tmp" }`
- YAML: `SetVroot: /tmp`

#### UnsetVroot

Unset the virtual root temporarily (can be reset back to the initial value).

Example:

- Lua: `"UnsetVroot"`
- YAML: `UnsetVroot`

#### ToggleVroot

Toggle virtual root between unset, initial value and $PWD.

Example:

- Lua: `"ToggleVroot"`
- YAML: `ToggleVroot`

#### ResetVroot

Reset the virtual root back to the initial value.

Example:

- Lua: `"ResetVroot"`
- YAML: `ResetVroot`

### Reading Input

#### SetInputPrompt

Set the input prompt temporarily, until the input buffer is reset.

Type: { SetInputPrompt = string }

Example:

- Lua: `{ SetInputPrompt = "→" }`
- YAML: `SetInputPrompt: →`

#### UpdateInputBuffer

Update the input buffer using cursor based operations.

Type: { UpdateInputBuffer = Input Operation }

Example:

- Lua: `{ UpdateInputBuffer = "GoToPreviousWord" }`
- YAML: `UpdateInputBuffer: GoToPreviousWord`

#### UpdateInputBufferFromKey

Update the input buffer from the key read from keyboard input.

Example:

- Lua: `"UpdateInputBufferFromKey"`
- YAML: `UpdateInputBufferFromKey`

#### BufferInput

Append/buffer the given string into the input buffer.

Type: { BufferInput = "string" }

Example:

- Lua: `{ BufferInput = "foo" }`
- YAML: `BufferInput: foo`

#### BufferInputFromKey

Append/buffer the character read from a keyboard input into the input buffer.

Example:

- Lua: `"BufferInputFromKey"`
- YAML: `BufferInputFromKey`

#### SetInputBuffer

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" }

Example:

- Lua: `{ SetInputBuffer = "foo" }`
- YAML: `SetInputBuffer: foo`

#### RemoveInputBufferLastCharacter

Remove input buffer's last character.

Example:

- Lua: `"RemoveInputBufferLastCharacter"`
- YAML: `RemoveInputBufferLastCharacter`

#### RemoveInputBufferLastWord

Remove input buffer's last word.

Example:

- Lua: `"RemoveInputBufferLastWord"`
- YAML: `RemoveInputBufferLastWord`

#### ResetInputBuffer

Reset the input buffer back to null. It will not show in the UI.

Example:

- Lua: `"ResetInputBuffer"`
- YAML: `ResetInputBuffer`

### Switching Mode

#### SwitchMode

Switch input mode.

Type : { SwitchMode = "string" }

Example:

- Lua: `{ SwitchMode = "default" }`
- YAML: SwitchMode: default

> NOTE: To be specific about which mode to switch to, use `SwitchModeBuiltin` or `SwitchModeCustom` instead.

#### SwitchModeKeepingInputBuffer

Switch input mode. It keeps the input buffer.

Type: { SwitchModeKeepingInputBuffer = "string" }

Example:

- Lua: `{ SwitchModeKeepingInputBuffer = "default" }`
- YAML: `SwitchModeKeepingInputBuffer: default`

> NOTE: To be specific about which mode to switch to, use `SwitchModeBuiltinKeepingInputBuffer` or `SwitchModeCustomKeepingInputBuffer` instead.

#### SwitchModeBuiltin

Switch to a builtin mode. It clears the input buffer.

Type: { SwitchModeBuiltin = "string" }

Example:

- Lua: `{ SwitchModeBuiltin = "default" }`
- YAML: `SwitchModeBuiltin: default`

#### SwitchModeBuiltinKeepingInputBuffer

Switch to a builtin mode. It keeps the input buffer.

Type: { SwitchModeBuiltinKeepingInputBuffer = "string" }

Example:

- Lua: `{ SwitchModeBuiltinKeepingInputBuffer = "default" }`
- YAML: `SwitchModeBuiltinKeepingInputBuffer: default`

#### SwitchModeCustom

Switch to a custom mode. It clears the input buffer.

Type: { SwitchModeCustom = "string" }

Example:

- Lua: `{ SwitchModeCustom = "my_custom_mode" }`
- YAML: `SwitchModeCustom: my_custom_mode`

#### SwitchModeCustomKeepingInputBuffer

Switch to a custom mode. It keeps the input buffer.

Type: { SwitchModeCustomKeepingInputBuffer = "string" }

Example:

- Lua: `{ SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }`
- YAML: `SwitchModeCustomKeepingInputBuffer: my_custom_mode`

#### PopMode

Pop the last mode from the history and switch to it. It clears the input buffer.

Example:

- Lua: `"PopMode"`
- YAML: `PopMode`

#### PopModeKeepingInputBuffer

Pop the last mode from the history and switch to it. It keeps the input buffer.

Example:

- Lua: `PopModeKeepingInputBuffer`
- YAML: `PopModeKeepingInputBuffer`

### Switching Layout

#### SwitchLayout

Switch layout.

Type: { SwitchLayout = "string" }

Example:

- Lua: `{ SwitchLayout = "default" }`
- YAML: `SwitchLayout: default`

> NOTE: To be specific about which layout to switch to, use `SwitchLayoutBuiltin` or `SwitchLayoutCustom` instead.

#### SwitchLayoutBuiltin

Switch to a builtin layout.

Type: { SwitchLayoutBuiltin = "string" }

Example:

- Lua: `{ SwitchLayoutBuiltin = "default" }`
- YAML: `SwitchLayoutBuiltin: default`

#### SwitchLayoutCustom

Switch to a custom layout.

Type: { SwitchLayoutCustom = "string" }

Example:

- Lua: `{ SwitchLayoutCustom = "my_custom_layout" }`
- YAML: `SwitchLayoutCustom: my_custom_layout`

### Executing Commands

#### Call

Like `Call0`, but it uses `\n` as the delimiter in input/output pipes, hence it cannot handle files with `\n` in the name. You may want to use `Call0` instead.

#### Call0

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` depending on the expectation.

Type: { Call0 = { command = "string", args = { "list", "of", "string" } }

Example:

- Lua: `{ Call0 = { command = "bash", args = { "-c", "read -p test" } } }`
- YAML: `Call0: { command: bash, args: ["-c", "read -p test"] }`

#### CallSilently

Like `CallSilently0`, but it uses `\n` as the delimiter in input/output pipes, hence it cannot handle files with `\n` in the name. You may want to use `CallSilently0` instead.

#### CallSilently0

Like `Call0` but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { CallSilently0 = { command = "string", args = {"list", "of", "string"} } }

Example:

- Lua: `{ CallSilently0 = { command = "tput", args = { "bell" } } }`
- YAML: `CallSilently0: { command: tput, args: ["bell"] }`

#### BashExec

Like `BashExec0`, but it uses `\n` as the delimiter in input/output pipes, hence it cannot handle files with `\n` in the name. You may want to use `BashExec0` instead.

#### BashExec0

An alias to `Call: {command: bash, args: ["-c", "{string}"], silent: false}` where `{string}` is the given value.

Type: { BashExec0 = "string" }

Example:

- Lua: `{ BashExec0 = "read -p test" }`
- YAML: `BashExec0: "read -p test"`

#### BashExecSilently

Like `BashExecSilently0`, but it uses `\n` as the delimiter in input/output pipes, hence it cannot handle files with `\n` in the name. You may want to use `BashExecSilently0` instead.

#### BashExecSilently0

Like `BashExec0` but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { BashExecSilently0 = "string" }

Example:

- Lua: `{ BashExecSilently0 = "tput bell" }`
- YAML: `BashExecSilently0: "tput bell"`

### Calling Lua Functions

#### CallLua

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" }

Example:

- Lua: `{ CallLua = "custom.some_custom_funtion" }`
- YAML: `CallLua: custom.some_custom_funtion`

#### CallLuaSilently

Like `CallLua` but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { CallLuaSilently = "string" }

Example:

- Lua: `{ CallLuaSilently = "custom.some_custom_function" }`
- YAML: `CallLuaSilently: custom.some_custom_function`

#### LuaEval

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.

Type: { LuaEval = "string" }

Example:

- Lua: `{ LuaEval = [[return { { LogInfo = io.read() } }]] }`
- Lua: `{ LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }`
- YAML: `LuaEval: "return { { LogInfo = io.read() } }"`
- YAML: `LuaEval: "function(app) return { { LogInfo = app.pwd } } end"`

#### LuaEvalSilently

Like `LuaEval` but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { LuaEvalSilently = "string" }

Example:

- Lua: `{ LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }`
- YAML: `LuaEvalSilently: "return { { LogInfo = 'foo' } }"`

### Select Operations

#### Select

Select the focused node.

Example:

- Lua: `"Select"`
- YAML: `Select`

#### SelectAll

Select all the visible nodes.

Example:

- Lua: `"SelectAll"`
- YAML: `SelectAll`

#### SelectPath

Select the given path.

Type: { SelectPath = "string" }

Example:

- Lua: `{ SelectPath = "/path/to/file" }`
- YAML: `SelectPath: /path/to/file`

#### UnSelect

Unselect the focused node.

Example:

- Lua: `"UnSelect"`
- YAML: `UnSelect`

#### UnSelectAll

Unselect all the visible nodes.

Example:

- Lua: `"UnSelectAll"`
- YAML: `UnSelectAll`

#### UnSelectPath

UnSelect the given path.

Type: { UnSelectPath = "string)" }

Example:

- Lua: `{ UnSelectPath = "/path/to/file" }`
- YAML: `UnSelectPath: /path/to/file`

#### ToggleSelection

Toggle selection on the focused node.

Example:

- Lua: `"ToggleSelection"`
- YAML `ToggleSelection`

#### ToggleSelectAll

Toggle between select all and unselect all. Example:

- Lua: `"ToggleSelectAll"`
- YAML: `ToggleSelectAll`

#### ToggleSelectionByPath

Toggle selection by file path.

Type: { ToggleSelectionByPath = "string" }

Example:

- Lua: `{ ToggleSelectionByPath = "/path/to/file" }`
- YAML: `ToggleSelectionByPath: /path/to/file`

#### ClearSelection

Clear the selection.

Example:

- Lua: `"ClearSelection"`
- YAML: `ClearSelection`

### Filter Operations

#### AddNodeFilter

Add a filter to exclude nodes while exploring directories. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. Filters get automatically cleared when changing directories.

Type: { AddNodeFilter = { filter = Filter, input = "string" }

Example:

- Lua: `{ AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }`
- YAML: `AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`

#### RemoveNodeFilter

Remove an existing filter. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { RemoveNodeFilter = { filter = Filter, input = "string" }

Example:

- Lua: `{ RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }`
- YAML: `RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`

#### ToggleNodeFilter

Remove a filter if it exists, else, add a it. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { ToggleNodeFilter = { filter = Filter, input = "string" }

Example:

- Lua: `{ ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }`
- YAML: `ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }`

#### AddNodeFilterFromInput

Add a node filter reading the input from the buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { AddNodeFilterFromInput = Filter }

Example:

- Lua: `{ AddNodeFilterFromInput = "RelativePathDoesStartWith" }`
- YAML: `AddNodeFilterFromInput: RelativePathDoesStartWith`

#### RemoveNodeFilterFromInput

Remove a node filter reading the input from the buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { RemoveNodeFilterFromInput = Filter }

Example:

- Lua: `{ RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }`
- YAML: `RemoveNodeFilterFromInput: RelativePathDoesStartWith`

#### RemoveLastNodeFilter

Remove the last node filter. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"RemoveLastNodeFilter"`
- YAML: `RemoveLastNodeFilter`

#### ResetNodeFilters

Reset the node filters back to the default configuration. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ResetNodeFilters"`
- YAML: `ResetNodeFilters`

#### ClearNodeFilters

Clear all the node filters. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ClearNodeFilters"`
- YAML: `ClearNodeFilters`

### Sort Operations

#### AddNodeSorter

Add a sorter to sort nodes while exploring directories. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { AddNodeSorter = { sorter = Sorter, reverse = bool } }

Example:

- Lua: `{ AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }`
- YAML: `AddNodeSorter: { sorter: ByRelativePath, reverse: false }`

#### RemoveNodeSorter

Remove an existing sorter. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { RemoveNodeSorter = Sorter }

Example:

- Lua: `{ RemoveNodeSorter = "ByRelativePath" }`
- YAML: `RemoveNodeSorter: ByRelativePath`

#### ReverseNodeSorter

Reverse a node sorter. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { ReverseNodeSorter = Sorter }

Example:

- Lua: `{ ReverseNodeSorter = "ByRelativePath" }`
- YAML: `ReverseNodeSorter: ByRelativePath`

#### ToggleNodeSorter

Remove a sorter if it exists, else, add a it. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Type: { ToggleNodeSorter = { sorter = Sorter, reverse = bool } }

Example:

- Lua: `{ ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }`
- YAML: `ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }`

#### ReverseNodeSorters

Reverse the node sorters. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ReverseNodeSorters"`
- YAML: `ReverseNodeSorters`

#### RemoveLastNodeSorter

Remove the last node sorter. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"RemoveLastNodeSorter"`
- YAML: `RemoveLastNodeSorter`

#### ResetNodeSorters

Reset the node sorters back to the default configuration. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ResetNodeSorters"`
- YAML: `ResetNodeSorters`

#### ClearNodeSorters

Clear all the node sorters. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ClearNodeSorters"`
- YAML: `ClearNodeSorters`

### Search Operations

#### Search

Search files using the current or default (fuzzy) search algorithm. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Type: { Search = "string" }

Example:

- Lua: `{ Search = "pattern" }`
- YAML: `Search: pattern`

#### SearchFromInput

Calls `Search` with the input taken from the input buffer.

Example:

- Lua: `"SearchFromInput"`
- YAML: `SearchFromInput`

#### SearchFuzzy

Search files using fuzzy match algorithm. It keeps the filters, but overrides the sorters. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Type: { SearchFuzzy = "string" }

Example:

- Lua: `{ SearchFuzzy = "pattern" }`
- YAML: `SearchFuzzy: pattern`

#### SearchFuzzyFromInput

Calls `SearchFuzzy` with the input taken from the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Example:

- Lua: `"SearchFuzzyFromInput"`
- YAML: `SearchFuzzyFromInput`

#### SearchFuzzyUnordered

Like `SearchFuzzy`, but doesn't not perform rank based sorting. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Type: { SearchFuzzyUnordered = "string" }

Example:

- Lua: `{ SearchFuzzyUnordered = "pattern" }`
- YAML: `SearchFuzzyUnordered: pattern`

#### SearchFuzzyUnorderedFromInput

Calls `SearchFuzzyUnordered` with the input taken from the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Example:

- Lua: `"SearchFuzzyUnorderedFromInput"`
- YAML: `SearchFuzzyUnorderedFromInput`

#### SearchRegex

Search files using regex match algorithm. It keeps the filters, but overrides the sorters. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Type: { SearchRegex = "string" }

Example:

- Lua: `{ SearchRegex = "pattern" }`
- YAML: `SearchRegex: pattern`

#### SearchRegexFromInput

Calls `SearchRegex` with the input taken from the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Example:

- Lua: `"SearchRegexFromInput"`
- YAML: `SearchRegexFromInput`

#### SearchRegexUnordered

Like `SearchRegex`, but doesn't not perform rank based sorting. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Type: { SearchRegexUnordered = "string" }

Example:

- Lua: `{ SearchRegexUnordered = "pattern" }`
- YAML: `SearchRegexUnordered: pattern`

#### SearchRegexUnorderedFromInput

Calls `SearchRegexUnordered` with the input taken from the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly. It gets reset automatically when changing directory.

Example:

- Lua: `"SearchRegexUnorderedFromInput"`
- YAML: `SearchRegexUnorderedFromInput`

#### ToggleSearchAlgorithm

Toggles between different search algorithms, without changing the input buffer You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"ToggleSearchAlgorithm"`
- YAML: `ToggleSearchAlgorithm`

#### EnableSearchOrder

Enables ranked search without changing the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"EnableOrderedSearch"`
- YAML: `EnableSearchOrder`

#### DisableSearchOrder

Disabled ranked search without changing the input buffer. You need to call `ExplorePwd` or `ExplorePwdAsync` explicitly.

Example:

- Lua: `"DisableSearchOrder"`
- YAML: `DisableSearchOrder`

#### ToggleSearchOrder

Toggles ranked search without changing the input buffer.

Example:

- Lua: `"ToggleSearchOrder"`
- YAML: `ToggleSearchOrder`

#### AcceptSearch

Accepts the search by keeping the latest focus while in search mode. Automatically calls `ExplorePwd`.

Example:

- Lua: `"AcceptSearch"`
- YAML: `AcceptSearch`

#### CancelSearch

Cancels the search by discarding the latest focus and recovering the focus before search. Automatically calls `ExplorePwd`.

Example:

- Lua: `"CancelSearch"`
- YAML: `CancelSearch`

### Mouse Operations

#### EnableMouse

Enable mouse

Example:

- Lua: `"EnableMouse"`
- YAML: `EnableMouse`

#### DisableMouse

Disable mouse

Example:

- Lua: `"DisableMouse"`
- YAML: `DisableMouse`

#### ToggleMouse

Toggle mouse

Example:

- Lua: `"ToggleMouse"`
- YAML: `ToggleMouse`

### Fifo Operations

#### StartFifo

Start piping the focused path to the given fifo path

Type: { StartFifo = "string" }

Example:

- Lua: `{ StartFifo = "/tmp/xplr.fifo }`
- YAML: `StartFifo: /tmp/xplr.fifo`

#### StopFifo

Close the active fifo and stop piping.

Example:

- Lua: `"StopFifo"`
- YAML: `StopFifo`

#### ToggleFifo

Toggle between {Start|Stop}Fifo

Type: { ToggleFifo = "string" }

Example:

- Lua: `{ ToggleFifo = "/path/to/fifo" }`
- YAML: `ToggleFifo: /path/to/fifo`

### Logging

#### LogInfo

Log information message.

Type: { LogInfo = "string" }

Example:

- Lua: `{ LogInfo = "launching satellite" }`
- YAML: `LogInfo: launching satellite`

#### LogSuccess

Log a success message.

Type: { LogSuccess = "String" }

Example:

- Lua: `{ LogSuccess = "satellite reached destination" }`
- YAML: `LogSuccess: satellite reached destination`

#### LogWarning

Log an warning message.

Type: { LogWarning = "string" }

Example:

- Lua: `{ LogWarning = "satellite is heating" }`
- YAML: `LogWarning: satellite is heating`

#### LogError

Log an error message.

Type: { LogError = "string" }

Example:

- Lua: `{ LogError = "satellite crashed" }`
- YAML: `LogError: satellite crashed`

### Debugging

#### Debug

Write the application state to a file, without quitting. Also helpful for debugging.

Type: { Debug = "string" }

Example:

- Lua: `{ Debug = "/path/to/file" }`
- YAML: `Debug: /path/to/file`

### Quit Options

#### Quit

Example:

- Lua: `"Quit"`
- YAML: `Quit`

Quit with returncode zero (success).

#### PrintPwdAndQuit

Print $PWD and quit.

Example:

- Lua: `"PrintPwdAndQuit"`
- YAML: `PrintPwdAndQuit`

#### PrintFocusPathAndQuit

Print the path under focus and quit. It can be empty string if there's nothing to focus.

Example:

- Lua: `"PrintFocusPathAndQuit"`
- YAML: `PrintFocusPathAndQuit`

#### PrintSelectionAndQuit

Print the selected paths and quit. It can be empty is no path is selected.

Example:

- Lua: `"PrintSelectionAndQuit"`
- YAML: `PrintSelectionAndQuit`

#### PrintResultAndQuit

Print the selected paths if it's not empty, else, print the focused node's path.

Example:

- Lua: `"PrintResultAndQuit"`
- YAML: `PrintResultAndQuit`

#### PrintAppStateAndQuit

Print the state of application in YAML format. Helpful for debugging or generating the default configuration file.

Example:

- Lua: `"PrintAppStateAndQuit"`
- YAML: `PrintAppStateAndQuit`

#### Terminate

Terminate the application with a non-zero return code.

Example:

- Lua: `"Terminate"`
- YAML: `Terminate`

## Also See:

- Message

# Input Operation

Cursor based input operation is a sum type can be one of the following:

- { SetCursor = int }
- { InsertCharacter = str }
- "GoToPreviousCharacter"
- "GoToNextCharacter"
- "GoToPreviousWord"
- "GoToNextWord"
- "GoToStart"
- "GoToEnd"
- "DeletePreviousCharacter"
- "DeleteNextCharacter"
- "DeletePreviousWord"
- "DeleteNextWord"
- "DeleteLine"
- "DeleteTillEnd"

## Also See:

- Message
- Full List of Messages

# Borders

xplr allows customizing the shape and style of the borders.

### Border

A border is a sum type that can be one of the following:

- "Top"
- "Right"
- "Bottom"
- "Left"

### Border Type

A border type is a sum type that can be one of the following:

- "Plain"
- "Rounded"
- "Double"
- "Thick"

### Border Style

The style of the borders.

## 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"

# 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 is a sum type that can be one of the following:

- "Reset"
- "Black"
- "Red"
- "Green"
- "Yellow"
- "Blue"
- "Magenta"
- "Cyan"
- "Gray"
- "DarkGray"
- "LightRed"
- "LightGreen"
- "LightYellow"
- "LightBlue"
- "LightMagenta"
- "LightCyan"
- "White"
- { Rgb = { int, int, int } }
- { Indexed = int }

## Modifier

Modifier is a sum type that can be one of the following:

- "Bold"
- "Dim"
- "Italic"
- "Underlined"
- "SlowBlink"
- "RapidBlink"
- "Reversed"
- "Hidden"
- "CrossedOut"

## 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" }

# Searching

xplr supports searching paths using different algorithm. The search mechanism generally appears between filters and sorters in the `Sort & filter` panel.

Example:

    fzy:foo↓

This line means that the nodes visible on the table are being filtered using the fuzzy matching algorithm on the input `foo`. The arrow means that ranking based ordering is being applied, i.e. sorters are being ignored.

## Node Searcher Applicable

Node Searcher contains the following fields:

- pattern
- recoverable_focus
- algorithm
- unordered

### pattern

The patterns used to search.

Type: string

### recoverable_focus

Where to focus when search is cancelled.

Type: nullable string

### algorithm

Search algorithm to use. Defaults to the value set in xplr.config.general.search.algorithm.

It can be one of the following:

- Fuzzy
- Regex

### unordered

Whether to skip ordering the search result by algorithm based ranking. Defaults to the value set in xplr.config.general.search.unordered.

Type: boolean

## Example:

    local searcher = {
      pattern = "pattern to search",
      recoverable_focus = "/path/to/focus/on/cancel",
      algorithm = "Fuzzy",
      unordered = false,
    }

    xplr.util.explore({ searcher = searcher })

See xplr.util.explore.

# 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↑

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:

- sorter
- reverse

### sorter

A sorter is a sum type that can be one of the following:

- "ByRelativePath"
- "ByIRelativePath"
- "ByExtension"
- "ByIsDir"
- "ByIsFile"
- "ByIsSymlink"
- "ByIsBroken"
- "ByIsReadonly"
- "ByMimeEssence"
- "BySize"
- "ByCreated"
- "ByLastModified"
- "ByCanonicalAbsolutePath"
- "ByICanonicalAbsolutePath"
- "ByCanonicalExtension"
- "ByCanonicalIsDir"
- "ByCanonicalIsFile"
- "ByCanonicalIsReadonly"
- "ByCanonicalMimeEssence"
- "ByCanonicalSize"
- "ByCanonicalCreated"
- "ByCanonicalLastModified"
- "BySymlinkAbsolutePath"
- "ByISymlinkAbsolutePath"
- "BySymlinkExtension"
- "BySymlinkIsDir"
- "BySymlinkIsFile"
- "BySymlinkIsReadonly"
- "BySymlinkMimeEssence"
- "BySymlinkSize"
- "BySymlinkCreated"
- "BySymlinkLastModified"

### reverse

Type: boolean

It defined the direction of the order.

## Example

    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.

# 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

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:

- filter
- input

### filter

A filter is a sum type that can be one of the following:

- "RelativePathIs"
- "RelativePathIsNot"
- "IRelativePathIs"
- "IRelativePathIsNot"
- "RelativePathDoesStartWith"
- "RelativePathDoesNotStartWith"
- "IRelativePathDoesStartWith"
- "IRelativePathDoesNotStartWith"
- "RelativePathDoesContain"
- "RelativePathDoesNotContain"
- "IRelativePathDoesContain"
- "IRelativePathDoesNotContain"
- "RelativePathDoesEndWith"
- "RelativePathDoesNotEndWith"
- "IRelativePathDoesEndWith"
- "IRelativePathDoesNotEndWith"
- "RelativePathDoesMatchRegex"
- "RelativePathDoesNotMatchRegex"
- "IRelativePathDoesMatchRegex"
- "IRelativePathDoesNotMatchRegex"
- "AbsolutePathIs"
- "AbsolutePathIsNot"
- "IAbsolutePathIs"
- "IAbsolutePathIsNot"
- "AbsolutePathDoesStartWith"
- "AbsolutePathDoesNotStartWith"
- "IAbsolutePathDoesStartWith"
- "IAbsolutePathDoesNotStartWith"
- "AbsolutePathDoesContain"
- "AbsolutePathDoesNotContain"
- "IAbsolutePathDoesContain"
- "IAbsolutePathDoesNotContain"
- "AbsolutePathDoesEndWith"
- "AbsolutePathDoesNotEndWith"
- "IAbsolutePathDoesEndWith"
- "IAbsolutePathDoesNotEndWith"
- "AbsolutePathDoesMatchRegex"
- "AbsolutePathDoesNotMatchRegex"
- "IAbsolutePathDoesMatchRegex"
- "IAbsolutePathDoesNotMatchRegex"

### input

Type: string

The input for the condition.

## Example:

    ToggleNodeFilter = {
      filter = "RelativePathDoesNotStartWith",
      input = "."
    }

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.

## 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 }
    }

    -- With this config, you should only see a single column displaying the
    -- relative paths.

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

- parent
- relative_path
- absolute_path
- extension
- is_symlink
- is_broken
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- permissions
- created
- last_modified
- uid
- gid
- canonical
- symlink
- index
- relative_index
- is_before_focus
- is_after_focus
- tree
- prefix
- suffix
- is_selected
- is_focused
- total
- style
- meta

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

### created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

### last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

### uid

Type: integer

User ID of the file owner.

### gid

Type: integer

Group ID of the file owner.

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

### style

Type: Style

The applicable style object for the node.

### meta

Type: mapping of string and string

The applicable meta object for the node.

## Permission

Permission contains the following fields:

- user_read
- user_write
- user_execute
- group_read
- group_write
- group_execute
- other_read
- other_write
- other_execute
- sticky
- setgid
- setuid

Each field holds a boolean value.

## Resolved Node Metadata

It contains the following fields.

- absolute_path
- extension
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- created
- last_modified
- uid
- gid

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

## Example: Using Lua Function Calls

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

Visit the xplr.util API docs for some useful utility / helper functions that you can use in your Lua function calls.

## Lua Context

This is a special argument passed to the lua functions when called using the `CallLua`, `CallLuaSilently` messages.

It contains the following information:

- version
- pwd
- initial_pwd
- vroot
- 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.

### initial_pwd

Type: string

The initial working directory when xplr started.

### vroot

Type: nullable string

The current virtual root.

### 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

Type: Explorer Config

The configuration for exploring paths.

### history

Type: History

### last_modes

Type: list of Mode

Last modes, not popped yet.

## 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
- created
- last_modified
- uid
- gid
- canonical
- symlink

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

### created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

### last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

### uid

Type: integer

User ID of the file owner.

### gid

Type: integer

Group ID of the file owner.

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

## Directory Buffer

Directory buffer contains the following fields:

- parent
- nodes
- total
- focus

### 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:

- loc
- paths

### loc

Type: int

Location of the current path in history.

### paths

Type: list of string

Visited paths.

## Explorer Config

Explorer config contains the following fields:

- filters
- sorters
- searcher

### filters

List of filters to apply.

Type: list of Node Filter Applicable

### sorters

Add list or sorters to the pipeline.

Type: list of Node Sorter Applicable

### searcher

The searcher to use (if any).

Type: nullable Node Searcher Applicable

## Also See:

- xplr.util

### xplr.util.version

Get the xplr version details.

Type: function() -> { major: number, minor: number, patch: number }

Example:

    xplr.util.version()
    -- { major = 0, minor = 0, patch = 0 }

### xplr.util.debug

Print the given value to the console, and return it as a string. Useful for debugging.

Type: function( value ) -> string

Example:

    xplr.util.debug({ foo = "bar", bar = function() end })
    -- {
    --   ["bar"] = function: 0x55e5cebdeae0,
    --   ["foo"] = "bar",
    -- }

### xplr.util.clone

Clone/deepcopy a Lua value. Doesn't work with functions.

Type: function( value ) -> value

Example:

    local val = { foo = "bar" }
    local val_clone = xplr.util.clone(val)
    val.foo = "baz"
    print(val_clone.foo)
    -- "bar"

### xplr.util.exists

Check if the given path exists.

Type: function( path:string ) -> boolean

Example:

    xplr.util.exists("/foo/bar")
    -- true

### xplr.util.is_dir

Check if the given path is a directory.

Type: function( path:string ) -> boolean

Example:

    xplr.util.is_dir("/foo/bar")
    -- true

### xplr.util.is_file

Check if the given path is a file.

Type: function( path:string ) -> boolean

Example:

    xplr.util.is_file("/foo/bar")
    -- true

### xplr.util.is_symlink

Check if the given path is a symlink.

Type: function( path:string ) -> boolean

Example:

    xplr.util.is_file("/foo/bar")
    -- true

### xplr.util.is_absolute

Check if the given path is an absolute path.

Type: function( path:string ) -> boolean

Example:

    xplr.util.is_absolute("/foo/bar")
    -- true

### xplr.util.path_split

Split a path into its components.

Type: function( path:string ) -> boolean

Example:

    xplr.util.path_split("/foo/bar")
    -- { "/", "foo", "bar" }

    xplr.util.path_split(".././foo")
    -- { "..", "foo" }

### xplr.util.node

Get Node information of a given path. Doesn't check if the path exists. Returns nil if the path is "/". Errors out if absolute path can't be obtained.

Type: function( path:string ) -> Node|nil

Example:

    xplr.util.node("./bar")
    -- { parent = "/pwd", relative_path = "bar", absolute_path = "/pwd/bar", ... }

    xplr.util.node("/")
    -- nil

### xplr.util.node_type

Get the configured Node Type of a given Node.

Type: function( Node, xplr.config.node_types|nil ) -> Node Type

If the second argument is missing, global config `xplr.config.node_types` will be used.

Example:

    xplr.util.node_type(app.focused_node)
    -- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }

    xplr.util.node_type(xplr.util.node("/foo/bar"), xplr.config.node_types)
    -- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }

### xplr.util.dirname

Get the directory name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

    xplr.util.dirname("/foo/bar")
    -- "/foo"

### xplr.util.basename

Get the base name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

    xplr.util.basename("/foo/bar")
    -- "bar"

### xplr.util.absolute

Get the absolute path of the given path by prepending $PWD. It doesn't check if the path exists.

Type: function( path:string ) -> path:string

Example:

    xplr.util.absolute("foo/bar")
    -- "/tmp/foo/bar"

### xplr.util.relative_to

Get the relative path based on the given base path or current working dir. Will error if it fails to determine a relative path.

Type: function( path:string, options:table|nil ) -> path:string

Options type: { base:string|nil, with_prefix_dots:bookean|nil, without_suffix_dots:boolean|nil }

- If `base` path is given, the path will be relative to it.
- If `with_prefix_dots` is true, the path will always start with dots `..` / `.`
- If `without_suffix_dots` is true, the name will be visible instead of dots `..` / `.`

Example:

    xplr.util.relative_to("/present/working/directory")
    -- "."

    xplr.util.relative_to("/present/working/directory/foo")
    -- "foo"

    xplr.util.relative_to("/present/working/directory/foo", { with_prefix_dots = true })
    -- "./foo"

    xplr.util.relative_to("/present/working/directory", { without_suffix_dots = true })
    -- "../directory"

    xplr.util.relative_to("/present/working")
    -- ".."

    xplr.util.relative_to("/present/working", { without_suffix_dots = true })
    -- "../../working"

    xplr.util.relative_to("/present/working/directory", { base = "/present/foo/bar" })
    -- "../../working/directory"

### xplr.util.shorten

Shorten the given absolute path using the following rules:

- either relative to your home dir if it makes sense
- or relative to the current working directory
- or absolute path if it makes the most sense

Type: Similar to `xplr.util.relative_to`

Example:

    xplr.util.shorten("/home/username/.config")
    -- "~/.config"

    xplr.util.shorten("/present/working/directory")
    -- "."

    xplr.util.shorten("/present/working/directory/foo")
    -- "foo"

    xplr.util.shorten("/present/working/directory/foo", { with_prefix_dots = true })
    -- "./foo"

    xplr.util.shorten("/present/working/directory", { without_suffix_dots = true })
    -- "../directory"

    xplr.util.shorten("/present/working/directory", { base = "/present/foo/bar" })
    -- "../../working/directory"

    xplr.util.shorten("/tmp")
    -- "/tmp"

### xplr.util.explore

Explore directories with the given explorer config.

Type: function( path:string, ExplorerConfig|nil ) -> { Node, ... }

Example:

    xplr.util.explore("/tmp")
    -- { { absolute_path = "/tmp/a", ... }, ... }

    xplr.util.explore("/tmp", app.explorer_config)
    -- { { absolute_path = "/tmp/a", ... }, ... }

### xplr.util.shell_execute

Execute shell commands safely.

Type: function( program:string, args:{ string, ... }|nil ) -> { stdout = string, stderr = string, returncode = number|nil }

Example:

    xplr.util.shell_execute("pwd")
    -- { stdout = "/present/working/directory", stderr = "", returncode = 0 }

    xplr.util.shell_execute("bash", {"-c", "xplr --help"})
    -- { stdout = "xplr...", stderr = "", returncode = 0 }

### xplr.util.shell_quote

Quote commands and paths safely.

Type: function( string ) -> string

Example:

    xplr.util.shell_quote("a'b\"c")
    -- 'a'"'"'b"c'

### xplr.util.shell_escape

Escape commands and paths safely.

Type: function( string ) -> string

Example:

    xplr.util.shell_escape("a'b\"c")
    -- "\"a'b\\\"c\""

### xplr.util.from_json

Load JSON string into Lua value.

Type: function( string ) -> any

Example:

    xplr.util.from_json([[{"foo": "bar"}]])
    -- { foo = "bar" }

### xplr.util.to_json

Dump Lua value into JSON (i.e. also YAML) string.

Type: function( value ) -> string

Example:

    xplr.util.to_json({ foo = "bar" })
    -- [[{ "foo": "bar" }]]

    xplr.util.to_json({ foo = "bar" }, { pretty = true })
    -- [[{
    --   "foo": "bar"
    -- }]]

### xplr.util.from_yaml

Load YAML (i.e. also JSON) string into Lua value.

Type: function( string ) -> value

Example:

    xplr.util.from_yaml([[{foo: bar}]])
    -- { foo = "bar" }

### xplr.util.to_yaml

Dump Lua value into YAML string.

Type: function( value ) -> string

Example:

    xplr.util.to_yaml({ foo = "bar" })
    -- "foo: bar"

### xplr.util.lscolor

Get a Style object for the given path based on the LS_COLORS environment variable.

Type: function( path:string ) -> Style|nil

Example:

    xplr.util.lscolor("Desktop")
    -- { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} }

### xplr.util.paint

Apply style (escape sequence) to string using a given Style object.

Type: function( string, Style|nil ) -> string

Example:

    xplr.util.paint("Desktop", { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} })
    -- "\u001b[31mDesktop\u001b[0m"

### xplr.util.style_mix

Mix multiple Style objects into one.

Type: function( { Style, Style, ... } ) -> Style

Example:

    xplr.util.style_mix({{ fg = "Red" }, { bg = "Blue" }, { add_modifiers = {"Bold"} }})
    -- { fg = "Red", bg = "Blue", add_modifiers = { "Bold" }, sub_modifiers = {} }

### xplr.util.textwrap

Wrap the given text to fit the specified width. It will try to not split words when possible.

Type: function( string, options:number|table ) -> { string, ...}

Options type: { width = number, initial_indent = string|nil, subsequent_indent = string|nil, break_words = boolean|nil }

Example:

    xplr.util.textwrap("this will be cut off", 11)
    -- { "this will', 'be cut off" }

    xplr.util.textwrap(
      "this will be cut off",
      { width = 12, initial_indent = "", subsequent_indent = "    ", break_words = false }
    )
    -- { "this will be", "    cut off" }

### xplr.util.layout_replace

Find the target layout in the given layout and replace it with the replacement layout, returning a new layout.

Type: function( layout:Layout, target:Layout, replacement:Layout ) -> layout:Layout

Example:

    local layout = {
      Horizontal = {
        splits = {
          "Table",  -- Target
          "HelpMenu",
        },
        config = ...,
      }
    }

    xplr.util.layout_replace(layout, "Table", "Selection")
    -- {
    --   Horizontal = {
    --     splits = {
    --       "Selection",  -- Replacement
    --       "HelpMenu",
    --     },
    --     config = ...
    --   }
    -- }

### xplr.util.permissions_rwx

Convert Permission to rwxrwxrwx representation with special bits.

Type: function( Permission ) -> string

Example:

    xplr.util.permissions_rwx({ user_read = true })
    -- "r--------"

    xplr.util.permissions_rwx(app.focused_node.permission)
    -- "rwxrwsrwT"

### xplr.util.permissions_octal

Convert Permission to octal representation.

Type: function( Permission ) -> { number, number, number, number }

Example:

    xplr.util.permissions_octal({ user_read = true })
    -- { 0, 4, 0, 0 }

    xplr.util.permissions_octal(app.focused_node.permission)
    -- { 0, 7, 5, 4 }

# Environment Variables and Pipes

Alternative to `CallLua`, `CallLuaSilently` messages that call Lua functions, there are `Call0`, `CallSilently0`, `BashExec0`, `BashExecSilently0` messages that call shell commands.

### Example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH

    xplr.config.modes.builtin.default.key_bindings.on_key["X"] = {
      help = "open",
      messages = {
        {
          BashExecSilently0 = [===[
            xdg-open "${XPLR_FOCUS_PATH:?}"
          ]===],
        },
      },
    }

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.

### Example: Using Environment Variables and Pipes

    xplr.config.modes.builtin.default.key_bindings.on_key["space"] = {
      help = "ask name and greet",
      messages = {
        {
          BashExec0 = [===[
            echo "What's your name?"

            read name
            greeting="Hello $name!"
            message="$greeting You are inside $PWD"

            "$XPLR" -m 'LogSuccess: %q' "$message"
          ]===]
        }
      }
    }

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

Visit the fzf integration tutorial for another example.

To see the environment variables and pipes, invoke the shell by typing `:!` in default mode and run the following command:

    env | grep ^XPLR

You will see something like:

    XPLR=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.

The other variables are single-line variables containing simple information:

- XPLR
- XPLR_APP_VERSION
- XPLR_FOCUS_INDEX
- XPLR_FOCUS_PATH
- XPLR_INPUT_BUFFER
- XPLR_INITIAL_PWD
- XPLR_MODE
- XPLR_PID
- XPLR_SESSION_PATH
- XPLR_VROOT

### Environment variables

#### XPLR

The binary path of xplr command.

#### XPLR_APP_VERSION

Self-explanatory.

#### XPLR_FOCUS_INDEX

Contains the index of the currently focused item, as seen in column-renderer/index.

#### XPLR_FOCUS_PATH

Contains the full path of the currently focused node.

#### XPLR_INITIAL_PWD

The $PWD then xplr started.

#### XPLR_INPUT_BUFFER

The line currently in displaying in the xplr input buffer. For e.g. the search input while searching. See Reading Input.

#### XPLR_MODE

Contains the mode xplr is currently in, see modes.

#### XPLR_PID

Contains the process ID of the current xplr process.

#### XPLR_SESSION_PATH

Contains the current session path, like /tmp/runtime-"$USER"/xplr/session/"$XPLR_PID"/, you can find temporary files here, such as pipes.

#### XPLR_VROOT

Contains the path of current virtual root, is set.

### Pipes

#### Input pipe

Currently there is only one input pipe.

- XPLR_PIPE_MSG_IN

#### Output pipes

`XPLR_PIPE_*_OUT` are the output pipes that contain data which cannot be exposed directly via environment variables, like multi-line strings. These pipes can be accessed as plain text files located in $XPLR_SESSION_PATH.

Depending on the message (e.g. `Call` or `Call0`), each line will be separated by newline or null character (`\n` or `\0`).

- 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

#### XPLR_PIPE_MSG_IN

Append new messages to this pipe in YAML (or JSON) syntax. These messages will be read and handled by xplr after the command execution.

Depending on the message (e.g. `Call` or `Call0`) you need to separate each message using newline or null character (`\n` or `\0`).

> NOTE: Since version `v0.20.0`, it's recommended to avoid writing directly to this file, as safely escaping YAML strings is a lot of work. Use `xplr -m` / `xplr --pipe-msg-in` to pass messages to xplr in a safer way.

> It uses jf syntax to safely convert an YAML template into a valid message.

> Example: `"$XPLR" -m 'ChangeDirectory: %q' "${HOME:?}"`

#### XPLR_PIPE_SELECTION_OUT

List of selected paths.

#### XPLR_PIPE_GLOBAL_HELP_MENU_OUT

The full help menu.

#### XPLR_PIPE_LOGS_OUT

List of logs.

#### XPLR_PIPE_RESULT_OUT

Result (selected paths if any, else the focused path)

#### XPLR_PIPE_HISTORY_OUT

List of last visited paths (similar to jump list in vim).

#### XPLR_PIPE_DIRECTORY_NODES_OUT

List of paths, filtered and sorted as displayed in the files table.

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

You can try these hacks by writing them to a file, say `hack.lua` and passing it to xplr with `--extra-config` or `-C`.

    xplr -C hack.lua

### cd on quit

Change directory using xplr.

Expand for details

- Author: @sayanarijit
- Tested on: Linux

NOTE: This is a shell hack, rather than Lua config hack. Add this in `.bashrc` or `.profile` file in your home directory.

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

- Author: @lmburns
- Requires: iTerm2
- Tested on: MacOS

    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

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 = {
        {
          BashExecSilently0 = [===[
            PTH="${XPLR_FOCUS_PATH:?}"
            PTH_ESC=$(printf %q "$PTH")
            if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then
              "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
            else
              "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
            fi
          ]===],
        },
      },
    }

    xplr.config.modes.builtin.default.key_bindings.on_key["`"] = {
      help = "go to bookmark",
      messages = {
        {
          BashExec0 = [===[
            PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort)
            PTH_ESC=$(printf %q "$PTH")
            if [ "$PTH" ]; then
              "$XPLR" -m 'FocusPath: %q' "$PTH"
            fi
          ]===],
        },
      },
    }

### 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

- Author: @lmburns
- Requires: fzf, sd
- Tested on: MacOS

    -- With `export XPLR_BOOKMARK_FILE="$HOME/bookmarks"`
    -- Bookmark: mode binding
    xplr.config.modes.builtin.default.key_bindings.on_key["b"] = {
      help = "bookmark mode",
      messages = {
        { SwitchModeCustom = "bookmark" },
      },
    }
    xplr.config.modes.custom.bookmark = {
      name = "bookmark",
      key_bindings = {
        on_key = {
          m = {
            help = "bookmark dir",
            messages = {
              {
                BashExecSilently0 = [[
                  PTH="${XPLR_FOCUS_PATH:?}"
                  if [ -d "${PTH}" ]; then
                    PTH="${PTH}"
                  elif [ -f "${PTH}" ]; then
                    PTH=$(dirname "${PTH}")
                  fi
                  PTH_ESC=$(printf %q "$PTH")
                  if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then
                    "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
                  else
                    "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
                  fi
                ]],
              },
              "PopMode",
            },
          },
          g = {
            help = "go to bookmark",
            messages = {
              {
                BashExec0 = [===[
                  PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
                  if [ "$PTH" ]; then
                    "$XPLR" -m 'FocusPath: %q' "$PTH"
                  fi
                ]===],
              },
              "PopMode",
            },
          },
          d = {
            help = "delete bookmark",
            messages = {
              {
                BashExec0 = [[
                  PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
                  sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}"
                ]],
              },
              "PopMode",
            },
          },
          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

- Author: @lmburns
- Requires: fzf, exa
- Tested on: MacOS

    xplr.config.modes.builtin.go_to.key_bindings.on_key.b = {
      help = "bookmark jump",
      messages = {
        "PopMode",
        { BashExec0 = [===[
            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
              "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
            fi
          ]===]
        },
      }
    }

### Fuzzy search history

Fuzzy search the last visited directories.

Expand for details

- Author: @sayanarijit
- Requires: fzf
- Tested on: Linux

    xplr.config.modes.builtin.go_to.key_bindings.on_key.h = {
      help = "history",
      messages = {
        "PopMode",
        {
          BashExec0 = [===[
            PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -z -u | fzf --read0)
            if [ "$PTH" ]; then
              "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
            fi
          ]===],
        },
      },
    }

### Batch rename

Batch rename the selected or visible files and directories in $PWD.

Expand for details

- Author: @sayanarijit
- Requires: pipe-rename
- Tested on: Linux

    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
             "$XPLR" -m ExplorePwdAsync
           fi
         ]===],
        },
      },
    }

### Serve $PWD

Serve $PWD using a static web server via LAN.

Expand for details

- Author: @sayanarijit
- Requires: sfz, fzf
- Tested on: Linux

    xplr.config.modes.builtin.default.key_bindings.on_key.S = {
      help = "serve $PWD",
      messages = {
        {
          BashExec0 = [===[
            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
          ]===],
        },
      },
    }

### Image viewer (imv)

Preview images using imv.

Expand for details

- Author: @sayanarijit
- Requires: imv, xdotool
- Tested on: Linux, FreeBSD 13.1-RELEASE

    xplr.config.modes.builtin.default.key_bindings.on_key.P = {
      help = "preview",
      messages = {
        {
          BashExecSilently0 = [===[
            FIFO_PATH="/tmp/xplr.fifo"

            if [ -e "$FIFO_PATH" ]; then
              "$XPLR" -m StopFifo
              rm -f -- "$FIFO_PATH"
            else
              mkfifo "$FIFO_PATH"
              "$HOME/.local/bin/imv-open.sh" "$FIFO_PATH" "$XPLR_FOCUS_PATH" &
              "$XPLR" -m 'StartFifo: %q' "$FIFO_PATH"
            fi
          ]===],
        },
      },
    }

$HOME/.local/bin/imv-open.sh

    #!/usr/bin/env bash

    FIFO_PATH="$1"
    IMAGE="$2"
    MAINWINDOW="$(xdotool getactivewindow)"
    IMV_PID="$(pgrep imv)"

    if [ ! "$IMV_PID" ]; then
      imv "$IMAGE" &
      IMV_PID=$!
    fi

    sleep 0.5

    xdotool windowactivate "$MAINWINDOW"

    while read -r path; do
      imv-msg "$IMV_PID" close all
      imv-msg "$IMV_PID" open "$path"
    done < "$FIFO_PATH"

    imv-msg "$IMV_PID" quit
    [ -e "$FIFO_PATH" ] && rm -f -- "$FIFO_PATH"

### Text preview pane

Preview text files in a native xplr pane (should be fast enough).

Expand for details

- Author: @sayanarijit
- Requires: none
- Tested on: Linux, FreeBSD 13.1-RELEASE

    local function stat(node)
      return xplr.util.to_yaml(xplr.util.node(node.absolute_path))
    end

    local function read(path, height)
      local p = io.open(path)

      if p == nil then
        return nil
      end

      local i = 0
      local res = ""
      for line in p:lines() do
        if line:match("[^ -~\n\t]") then
          p:close()
          return
        end

        res = res .. line .. "\n"
        if i == height then
          break
        end
        i = i + 1
      end
      p:close()

      return res
    end

    xplr.fn.custom.preview_pane = {}
    xplr.fn.custom.preview_pane.render = function(ctx)
      local title = nil
      local body = ""
      local n = ctx.app.focused_node
      if n and n.canonical then
        n = n.canonical
      end

      if n then
        title = { format = n.absolute_path, style = xplr.util.lscolor(n.absolute_path) }
        if n.is_file then
          body = read(n.absolute_path, ctx.layout_size.height) or stat(n)
        else
          body = stat(n)
        end
      end

      return { CustomParagraph = { ui = { title = title }, body = body } }
    end

    local preview_pane = { Dynamic = "custom.preview_pane.render" }
    local split_preview = {
      Horizontal = {
        config = {
          constraints = {
            { Percentage = 60 },
            { Percentage = 40 },
          },
        },
        splits = {
          "Table",
          preview_pane,
        },
      },
    }

    xplr.config.layouts.builtin.default =
        xplr.util.layout_replace(xplr.config.layouts.builtin.default, "Table", split_preview)

### Tere Navigation

Navigate using the tere file explorer (defaults to type-to-nav system).

Expand for details

- Author: @sayanarijit
- Requires: tere
- Tested on: Linux

    xplr.config.modes.builtin.default.key_bindings.on_key.T = {
      help = "tere nav",
      messages = {
        { BashExec0 = [["$XPLR" -m 'ChangeDirectory: %q' "$(tere)"]] },
      },
    }

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

- Installing Plugins
- Writing Plugins
- Awesome Plugins

# Installing Plugins

One way to install plugins is to use a plugin manager like dtomvan/xpm.xplr.

But you can also install and manage plugins manually.

## Install Manually

- Add the following line in `~/.config/xplr/init.lua`

      local home = os.getenv("HOME")
      package.path = home
      .. "/.config/xplr/plugins/?/init.lua;"
      .. home
      .. "/.config/xplr/plugins/?.lua;"
      .. package.path

- Clone the plugin

      mkdir -p ~/.config/xplr/plugins

      git clone https://github.com/sayanarijit/material-landscape2.xplr ~/.config/xplr/plugins/material-landscape2

- Require the module in `~/.config/xplr/init.lua`

      require("material-landscape2").setup()

      -- The setup arguments might differ for different plugins.
      -- Visit the project README for setup instructions.

## Luarocks Support

Some plugins may require luarocks to work.

Setup luarocks with the following steps:

- Install luarocks (via your package managers or follow the official guide).

- Add `eval "$(luarocks path --lua-version 5.1)"` in your `.bashrc` or `.zshrc`.

- Add the following lines in `~/.config/xplr/init.lua`

      package.path = os.getenv("LUA_PATH") .. ";" .. package.path
      package.cpath = os.getenv("LUA_CPATH") .. ";" .. package.cpath

  Now you can install packages using luarocks. Be sure to append `--lua-version`.

Example:

    luarocks install luafilesystem --local --lua-version 5.1

# Writing Plugins

Anyone who can write Lua code, can write xplr plugins.

Just follow the instructions and best practices:

## Naming

xplr plugins are named using hiphen (`-`) separated words that may also include integers. They will be plugged using the `require()` function in Lua.

## Structure

A minimal plugin should confirm to the following structure:

    .
    ├── README.md
    └── init.lua

You can also use this template.

### README.md

This is where you document what the plugin does, how to use it, etc.

### init.lua

This file is executed to load the plugin. It should expose a `setup()` function, which will be used by the users to setup the plugin.

Example:

    local function setup(args)
      local xplr = xplr
      -- do stuff with xplr
    end

    return { setup = setup }

## Publishing

When publishing plugins on GitHub or other repositories, it's a best practice to append `.xplr` to the name to make them distinguishable. Similar to the `*.nvim` naming convention for Neovim plugins.

Finally, after publishing, don't hesitate to let us know.

## Best practices

- Try not to execute a lot of commands at startup, it may make xplr slow to start.
- When executing commands, prefer `Call0` over `Call`, `BashExec0` over `BashExec` and so on. File names may contain newline characters (e.g. `foo$'\n'bar`).
- File names may also contain quotes. Avoid writing directly to `$XPLR_PIPE_MSG_IN`. Use `xplr -m` / `xplr --pipe-msg-in` instead.
- Check for empty variables using the syntax `${FOO:?}` or use a default value `${FOO:-defaultvalue}`.

## Examples

Visit Awesome Plugins for xplr plugin examples.

## 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: Customizing Table Renderer
- Example: Render a custom dynamic table
- Example: Implementing a directory visit counter

# 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

- sayanarijit/command-mode.xplr The missing command mode for xplr.
- igorepst/context-switch.xplr Context switch plugin for xplr.
- sayanarijit/dual-pane.xplr Implements support for dual-pane navigation into xplr.
- sayanarijit/map.xplr Visually inspect and interactively execute batch commands using xplr.
- sayanarijit/offline-docs.xplr Fetch the appropriate version of xplr docs and browse offline.
- sayanarijit/regex-search.xplr Bring back the regex based search in xplr.
- sayanarijit/registers.xplr Use multiple registers to store the selected paths.
- sayanarijit/tree-view.xplr Hackable tree view for xplr
- sayanarijit/tri-pane.xplr xplr plugin that implements ranger-like three pane layout.
- sayanarijit/type-to-nav.xplr Inspired by nnn's type-to-nav mode for xplr, with some tweaks.
- dtomvan/term.xplr Terminal integration for xplr.
- sayanarijit/wl-clipboard.xplr Copy and paste with system clipboard using wl-clipboard
- dtomvan/xpm.xplr The XPLR Plugin Manager.
- emsquid/style.xplr Helper plugin that allows you to integrate xplr's Style anywhere.

### Integration

- sayanarijit/alacritty.xplr Alacritty integration for xplr.
- sayanarijit/dragon.xplr Drag and drop files using dragon.
- sayanarijit/dua-cli.xplr Get the disk usage using dua-cli with selection support.
- sayanarijit/fzf.xplr Fuzzy search using fzf to focus on a file or enter.
- sayanarijit/find.xplr An interactive finder plugin to complement map.xplr.
- Junker/nuke.xplr Open files in apps by file type or mime.
- sayanarijit/nvim-ctrl.xplr Send files to running Neovim sessions using nvim-ctrl.
- dtomvan/ouch.xplr This plugin uses ouch to compress and decompress files.
- dtomvan/paste-rs.xplr Use this plugin to paste your files to paste.rs, and open/delete them later using fzf.
- sayanarijit/preview-tabbed.xplr Preview paths using suckless tabbed and nnn preview-tabbed.
- sayanarijit/qrcp.xplr Send and receive files via QR code using qrcp.
- sayanarijit/scp.xplr Integrate xplr with scp.
- sayanarijit/trash-cli.xplr Trash files and directories using trash-cli.
- sayanarijit/xclip.xplr Copy and paste with system clipboard using xclip.
- sayanarijit/zoxide.xplr Change directory using the zoxide database.

### Theme

- sayanarijit/material-landscape.xplr Material Landscape
- sayanarijit/material-landscape2.xplr Material Landscape 2
- sayanarijit/zentable.xplr A clean, distraction free xplr table UI
- dy-sh/dysh-style.xplr Complements xplr theme with icons and highlighting.
- prncss-xyz/icons.xplr An icon theme for xplr.
- dtomvan/extra-icons.xplr Adds more icons to icons.xplr, compatible with zentable.xplr.
- hartan/web-devicons.xplr Adds nvim-web-devicons to xplr with optional coloring
- duganchen/one-table-column.xplr Moves file stats to a status bar.
- dy-sh/get-rid-of-index.xplr Removes the index column.

## Also See:

- Awesome Hacks
- Awesome Integrations

# Integration

xplr is designed to integrate well with other tools and commands. It can be used as a file picker or a pluggable file manager.

- Awesome Integrations

# Awesome Integrations

Here's a list of awesome xplr integrations that you might want to check out.

If none of the following integrations work for you, you can create your own and let us know.

### Editor

- fm-nvim Neovim plugin that lets you use your favorite terminal file managers from within Neovim.
- vim-floaterm xplr integrated in vim-floaterm (Neo)vim plugin.
- xplr.vim Pick files in Vim using xplr.

### Github

- gh-xplr Explore GitHub repos using xplr via GitHub CLI.

### Shell

- powerlevel10k Powerlevel10k prompt for xplr shell.

### Security Tools

- gpg-tui Import GPG certificates using xplr.

## Also See:

- Awesome Hacks
- Awesome Plugins

# Alternatives

These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).

- nnn
- vifm
- ranger
- lf
- joshuto
- fff
- mc
- broot
- hunter
- noice
- clifm
- clifm (non curses)
- felix

add more

# Upgrade Guide

When you upgrade xplr, you might see an error like this

    Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide

All you need to do is follow the instructions starting from your config version, all the way to the required version.

Expand for more information

With every update, we either implement a `major` breaking change (e.g. deprecating or replacing messages), or a `minor` feature addition (e.g. adding new messages) or `patch`, fixes, and optimization (e.g. performance optimization).

Knowing that we use the `{major}.{minor}.{patch}` versioning format,

- Major version mismatch are generally incompatible. xplr will fail with error.
- Minor version upgrades (not downgrades) and patch fixes are backwards compatible. You might get notified by log a message which you can disable by updating the version in your config file.
- However, if the config file has a higher value for the minor version than the app, then also xplr will fail with error, suggesting you to visit this page. Though in that case, you will be downgrading your config file based on your app version.

e.g.

- `1.0.0` -> `1.0.x`: Patch (fully compatible).
- `1.0.0` -> `1.x.x`: Only backwards compatible. You can't generally use for e.g. `app-1.0.0` with `config-1.1.0`. But vice versa is fine.
- `1.0.0` -> `x.x.x`: Not compatible at all.

Note that until we're `v1`, we'll be using the `{minor}` version number as `{major}`, and the `{patch}` number as `{minor}` to determine compatibility.

### Instructions

#### v0.20.2 -> v0.21.7

- Some plugins might stop rendering colors. Wait for them to update.
- Rename `xplr.config.general.sort_and_filter_ui.search_identifier` to `xplr.config.general.sort_and_filter_ui.search_identifiers`.
- Resolved Node API will not contain the `permissions` field anymore. Use the utility function `xplr.util.node` to get its permissions.
- Layout `CustomContent` has been undocumented. It will stay for compatibility, but you should prefer using the following new layouts, because they support custom title:
  - Static
  - Dynamic
- Use the new messages for improved search operations:
  - Search
  - SearchFromInput
  - SearchFuzzyUnordered
  - SearchFuzzyUnorderedFromInput
  - SearchRegex
  - SearchRegexFromInput
  - SearchRegexUnordered
  - SearchRegexUnorderedFromInput
  - ToggleSearchAlgorithm
  - EnableSearchOrder
  - DisableSearchOrder
  - ToggleSearchOrder
- Use skim's search syntax to customize the search.
- Set your preferred search algorithm and ordering: `xplr.config.general.search.algorithm = "Fuzzy" -- or "Regex"`. `xplr.config.general.search.unordered = false -- or true`
- You need to clear the selection list manually after performing batch operation like copy, softlink creation etc.
- Use the following new key bindings:
  - `:sl` to list selection in a $PAGER.
  - `:ss` to create softlink of the selected items.
  - `:sh` to create hardlink of the selected items.
  - `:se` to edit selection list in your $EDITOR.
  - Better conflict handling: prompt for action.
- Navigate between the selected paths using the following messages:
  - FocusPreviousSelection (`ctrl-p`)
  - FocusNextSelection (`ctrl-n`)
- Use `LS_COLORS` environment variable, along with the following utility
- functions for applying better styling/theaming.
  - xplr.util.lscolor
  - xplr.util.paint
  - xplr.util.textwrap
  - xplr.util.style_mix
- Use new the fields in Column Renderer Argument:
  - style
  - permissions
- Use the following config to specify how the paths in selection list should be rendered:
  - xplr.config.general.selection.item.format
  - xplr.config.general.selection.item.style
- Use the following utility functions to work with the file permissions:
  - xplr.util.permissions_rwx
  - xplr.util.permissions_octal
- Type `:p` to edit file permissions interactively.
- Also check out the following utility functions:
  - xplr.util.layout_replace
  - xplr.util.relative_to
  - xplr.util.shorthand
  - xplr.util.clone
  - xplr.util.exists
  - xplr.util.is_dir
  - xplr.util.is_file
  - xplr.util.is_symlink
  - xplr.util.is_absolute
  - xplr.util.path_split
  - xplr.util.node
  - xplr.util.node_type
  - xplr.util.shell_escape
- Executables will me marked with the mime type: `application/x-executable`.
- macOS legacy coreutils will be generally supported, but please update it.
- Since v0.21.2 you can use the on_selection_change hook.
- Since v0.21.4 you can use function keys upto F24 and the following new messages:
  - NextVisitedDeepBranch (bound to `)` key)
  - PreviousVisitedDeepBranch (bound to `(` key)
- Since v0.21.6:
  - You can use `c` and `m` keys in default mode to quickly copy and move focused or selected files, without having to change directory.
  - Use `xplr.util.debug()` to debug lua values.

Thanks to @noahmayr for contributing to a major part of this release.

#### v0.19.4 -> v0.20.2

- BREAKING: xplr shell (`:!`) will default to null (`\0`) delimited pipes, as opposed to newline (`\n`) delimited ones (i.e. will use `Call0` instead of `Call`).
- Use new messages for safer file path handling (`\0` delimited):
  - Call0
  - CallSilently0
  - BashExec0
  - BashExecSilently0
- Use new sub-commands for safer message passing:
  - `-m FORMAT [ARGUMENT]...` / `--pipe-msg-in FORMAT [ARGUMENT]...`
  - `-M FORMAT [ARGUMENT]...` / `--print-msg-in FORMAT [ARGUMENT]...` Where FORMAT is a YAML string that may contain `%s`, `%q` and `%%` placeholders and ARGUMENT is the value per placeholder. See `init.lua`.
- Following hooks can be defined in the config files using an optional `return { on_* = { list, of, messages }, ... }` statement at the end.
  - on_load
  - on_focus_change
  - on_directory_change
  - on_mode_switch (since v0.20.2)
  - on_layout_switch (since v0.20.2)
- Use `--vroot` to isolate navigation of an xplr session inside a specific directory. Interaction still requires passing full path, and shell, lua functions etc still can access paths outside vroot.
- Use the following messages to switch vroot at runtime, or the use key bindings available in the new builtin mode "vroot" (mapped to `:` `v`).
  - SetVroot
  - UnsetVroot
  - ToggleVroot
  - ResetVroot
- Use `$XPLR_INITIAL_PWD` and Lua equivalent to implement workspace like features without using virtual root. Use keys `gi` to go to the initial working directory from anywhere.
- Use the convenient `xplr.util` utility functions in your Lua function calls. See xplr.util API docs.

#### v0.18.0 -> v0.19.4

- BREAKING: The builtin modes cannot be accessed using space separated names anymore. Use underscore separated mode names. For e.g. `SwitchModeBuiltin: create file` becomes `SwitchModeBuiltin: create_file` and so on. Kindly go through your config, find and update them, or copy from the latest `init.lua`.
- Now you can use `xplr.config.general.global_key_bindings` to define a set of key bindings that are available by default in every mode. e.g. `esc` and `ctrl-c`, and remove boilerplate code from your config.
- You can use the new builtin mode `go_to_path` which can be used for typing or pasting paths to enter into or to focus on. Type `g` `p` to enter this mode.
- Now you can use basic tab completion in the `go_to_path`, `create_file`, `create_directory`, `rename` and `duplicate_as` modes.
- Use the builtin function `xplr.fn.builtin.try_complete_path` to add easy tab completion support into your own configuration.
- Now you can open OSC 7 compatible terminals into the `xplr`'s current working directory by spawning new terminal sessions via the terminal supported key bindings.
- Use `NO_COLOR` environment variable to disable OSC 7 compliance along with colors.
- If you have fully copied the default `init.lua` locally, you might want to go through the latest improvements in `init.lua`. Specifically the `search`, `filter` and `sort` modes. Also, search for `SetInputPrompt` and the `tab` key bindings.
- Since version 0.19.1, you can access uid and gid of the file owner in the Lua API.
- The input buffer will support more readline-like keys. Also, added "DeleteTillEnd" as another cursor based "InputOperation" option.
- Fixed applying regex based filters via the CLI and `$XPLR_PIPE_MSG_IN` pipe.
- You can use the `prompt` field to define input prompt for each mode, instead of using the `SetInputPrompt` message.
- Since version v0.19.4, the native search will default to skim-v2 based fuzzy matching. `esc` while in search mode will recover the initial focus. People who prefer the regex based search, can use the `regex-search.xplr` plugin. The following messages will be available for search based operations:
  - SearchFuzzy
  - SearchFuzzyFromInput
  - AcceptSearch
  - CancelSearch
- Since version v0.19.4, quick scrolling operations are supported using the following messages and keys:
  - ScrollUp -------- page-up
  - ScrollDown ------ page-down
  - ScrollUpHalf ---- {
  - ScrollDownHalf -- }

Like this project so far? Please consider contributing.

#### v0.17.6 -> v0.18.0

- Key binding `f` `r` and `f` `R` will now filter using regex.
- Key binding `f` `backspace` will now remove the last filter.
- Search mode now defaults to regex search.
- `Node` metadata in the Lua API will contain two new fields:
  - `created`
  - `last_modified`
- The last column in the files table now displays the last modification time.
- You can now use `--read0`, `--write0` and `-0`/`--null` to read and/or print null character delimited paths.
- You can now the following regex filters:
  - `RelativePathDoesMatchRegex`
  - `RelativePathDoesNotMatchRegex`
  - `IRelativePathDoesMatchRegex`
  - `IRelativePathDoesNotMatchRegex`
  - `AbsolutePathDoesMatchRegex`
  - `AbsolutePathDoesNotMatchRegex`
  - `IAbsolutePathDoesMatchRegex`
  - `IAbsolutePathDoesNotMatchRegex`
- You can use a new `SetInputPrompt` to set the input prompt dynamically.
- You can now use the following timestamp based sorters:
  - "ByCreated"
  - "ByLastModified"
  - "ByCanonicalCreated"
  - "ByCanonicalLastModified"
  - "BySymlinkCreated"
  - "BySymlinkLastModified"

#### v0.16.4 -> v0.17.6

- Deprecated `app.directory_buffer`, `app.history`, and `app.last_modes` in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. While `app.history` and `app.last_modes` can be re-added upon request (with justification), `app.directory_buffer` has been deprecated for good. However, there's no change in the `CallLua*` context.
- Set `xplr.config.general.hide_remaps_in_help_menu` to `true` to hide the remaps in help menu.
- `None` will be serialized to `nil` in Lua.
- `LuaEval` can now return a function that will be called with the Lua Context argument. Refer to the `Full List of Messages` doc for example.
- From version v0.17.1, set `xplr.config.general.disable_debug_error_mode` to `true` to disable switching to the "debug error" mode when startup errors occur.
- From version v0.17.2, you can use CLI argument `--print-pwd-as-result` for cd on quit, and key binding `ctrl-d` to duplicate a path in the same directory with a different name.
- Since version v0.17.3, you can use `border_type`, `border_style` to customize borders, and `enforce_bounded_index_navigation` to customize up/down navigation behavior when focus is on the top or bottom node.

#### v0.15.2 -> v0.16.4

- Deprecated `config.general.cursor`. The default terminal cursor will be used for the time being.
- Opening xplr inside a symlink will not resolve the path.
- You can now replace most boilerplate configuration handling keys to send `BufferInputFromKey`, `RemoveInputBufferLastCharacter`, `RemoveInputBufferLastWord`, `SetInputBuffer = ""` etc. messages with a single `UpdateInputBufferFromKey` message.
- You can now pass multiple paths as command-line arguments or via stdin to select paths, e.g. `xplr -- $PWD /path/to/select/1 /path/to/select/2`.
- Pass `--force-focus` to focus on the first path even if it's a directory, e.g. `xplr . --force-focus`.
- Use new messages `LuaEval` and `LuaEvalSilently` to run Lua code without needing to define a function. However, the `app` context won't be available.
- You can now use new key handlers in the config:
  - on_alphanumeric
  - on_character
  - on_navigation
  - on_function

#### v0.14.7 -> v0.15.2

- Deprecated `config` field from `CallLua` argument. Use the globally available `xplr.config` instead.
- `xplr.config.general.disable_recover_mode` has been deprecated. Use `xplr.config.general.enable_recover_mode` instead.
- Use `xplr.config.general.focus_selection_ui` to highlight selected files under focus differently than files under focus that are not selected.
- Use `PopModeKeepingInputBuffer`, and SwitchMode alternatives to switching to different modes without resetting the input buffer.
- Use the new `CustomContent` layout option to render custom content.
- Use the new `layout` field in a mode to define custom layout for a specific mode.
- Library users please refer to the latest API docs and examples.

#### v0.13.7 -> v0.14.7

- macOS users need to place their config file (`init.lua`) in `$HOME/.config/xplr/` or `/etc/xplr/`.
- Library users please refer to the latest API docs.
- Check out the new messages: `{Start|Stop|Toggle}Fifo`. These enable support for FIFO based file previews.
- You can disable the recover mode using `config.general.disable_recover_mode = true`.
- Try running `xplr --help`. Yes, CLI has been implemented.
- Since version `v0.14.3`, `StartFifo` and `ToggleFifo` will write to the FIFO path when called. So, there's no need to pipe the focus path explicitly.
- Since version `v0.14.3`, general config `xplr.config.start_fifo` is available which can be set to a file path to start a fifo when xplr starts.
- Since version `v0.14.4`, `$XPLR_SESSION_PATH` can be used to dump session related data.
- Since version `v0.14.6`, the `-C` or `--extra-config` CLI argument is available.

#### v0.12.1 -> v0.13.7

- Lua functions called using `CallLua` and `CallLuaSilently` messages will receive `CallLuaArg` object as the function argument (instead of the `App` object).
- Each `node_types` config will inherit defaults from matching less specific `node_types` config and overwrite them.
- Since version `v0.13.2`, you don't need to use/send `Refresh` anymore. It will be auto-handled by xplr.

#### v0.11.1 -> v0.12.1

- `xplr.config.node_types.mime_essence` has split into type and subtype. Hence, instead of `xplr.config.node_types.mime_essence["text/plain"] = ..` use `xplr.config.node_types.mime_essence["text"] = { plain = .. }`.
- You can also define `xplr.config.node_types.mime_essence["text"]["*"]` that will match all text types (`text/*`).

#### v0.10.2 -> v0.11.1

- `remaps:` has been removed to avoid confusion. Use lua assignments instead. For e.g.

      xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space

#### v0.9.1 -> v0.10.2

- `config.yml` has been fully replaced with `init.lua`. If you have a lot of customization in your `config.yml`, xplr-yml2lua can help you with migrating it to `init.lua`.
- `Handlebars` templates has been replaced with Lua functions. You can either remove the customizations or overwrite the functions accordingly.
- Added new messages `CallLua` and `CallLuaSilently` to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. `CallLua` and `CallLuaSilently` are more flexible (and probably faster) alternatives to `Call`, `CallSilently`, `BashExec` and `BashExecSilently`. e.g.

#### v0.9.0 -> v0.9.1

- You can now set `remaps: {key: null}` to un-map a key.
- `gx` will open the item under focus.
- New key map `:sx` will open the selected items.

#### v0.8.0 -> v0.9.0

Your previous config should mostly work fine. However, in case you are using `SwitchMode` heavily in your custom config, follow along.

- Introduced new message `PopMode`. You might want to use this message instead of `SwitchMode*` when returning back to the previous mode.
- After using (the group of) `PopMode` and `SwitchMode*` messages, you are now required to `Refresh` manually to avoid the UI lag.
- Pressing any invalid key will now lead you to the `recover` mode and will protect you from typing further invalid keys. Press `esc` to escape the `recover` mode.
- Introduced new message `LogWarning`, similar to other `Log*` messages.
- Creating files and directories has been optimized for batch creation.

#### v0.7.2 -> v0.8.0

If you have made changes to the config file,

- Replace message `Explore` with `ExplorePwd` or `ExplorePwdAsync` or probably `ExploreParentsAsync`.
- Pipe `$XPLR_PIPE_FOCUS_OUT` has been removed. Use `$XPLR_FOCUS_PATH` env var instead.
- You might want to review your path escaping logics. For e.g. use `echo FocusPath: "'"$PWD"'" >> $PIPE` instead of `echo "FocusPath: $PWD" >> $PIPE`.

#### v0.7.0 -> v0.7.2

- Just update the `version` in your config file.
- For version >= `v0.7.1`, you might want to free up or remap the `tab` key in `search` mode to enable easy selection during search.

#### v0.6.0 -> v0.7.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

- You can make the `Table: ...`, `InputAndLogs: ...` layout values null and define the common properties in the `general.panel_ui` instead.

#### v0.5.13 -> v0.6.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

- Rename `add_modifier: {bits: 1}` to `add_modifiers: [Bold]`, `sub_modifier: {bits: 1}` to `sub_modifiers: [Bold]` and so on.
- Rename `percentage: 10` to `Percentage: 10`, `ratio: 1` to `Ratio: 1` and so on.
- You might want to free up or remap the `ctrl-w` key binding in `default` mode to enable layout switching.

Optionally, checkout this new theme to learn more about what's new.

#### v0.5.0 -> v0.5.13

- Just update the `version` in your config file.
- For versions >= `v0.5.8`, you can set `$OPENER` env var to declare a global GUI file opener (to open files using keys `gx`).
- You might also want to update other mappings to handle files with names starting with `-` (hiphen). For example, instead of `rm ${filename}` use `rm -- ${filename}`. Same goes for `cp`, `mv`, `cat`, `touch` etc.
- For version >= `v0.5.13`, you might want to use the more specific `SwitchModeBuiltin` and `SwitchModeCustom` messages instead of the general `SwitchMode` message.

#### v0.4.3 -> v0.5.0

If you haven't have any changes in the config file, you should be fine just updating the version number.

Else do the following

- Replace `{RelativePathIs, case_sensitive: true}` with `RelativePathIs`.
- Replace `{RelativePathIs, case_sensitive: false}` with `IRelativePathIs`.
- Do the same with other filters you are using.
- You might want to update your `backspace` handling to use the `RemoveInputBufferLastCharacter` message.
- You might want to free-up `f`, `s`, `ctrl-r` and `ctrl-u` key bindings in the default mode, or remap them.
- You might want to use the new UI variables.
- Update your config version to `v0.5.0`.

#### v0.4.2 -> v0.4.3

If you have customized `general.table.row.cols`, you might want to update it to use the new variables with better symlink support.

#### v0.4.1 -> v0.4.2

In case you have mapped the keys `q`, `ctrl-i` and `ctrl-o`, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.

#### v0.3.13 -> v0.4.1

A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to @maximbaz's valuable inputs and code reviews).

So, to start with the upgrade, let's remove everything from your config file except the `version` field and your custom modifications. If `version` is the only thing remaining, update it to `v0.4.1` and you are done.

Else, do the following

- Rename `general.focused_ui` to `general.focus_ui` (see here).
- Rename `filetypes` to `node_types`. (see here)
- Rename `custom` field to `meta`. (see here)
- Move `icon` to `meta.icon`. (see here)
- Rename `normal_ui` to `default_ui`. (see here)
- Split `modes` into `modes.builtin` and `modes.custom` (see here). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`.
- Finally, update the `version` to `v0.4.1`.

#### v0.3.8 -> v0.3.13

Your current config should work fine. However, you might want to replace some `Call` and `BashExec` messages with `CallSilently` and `BashExecSilently` to remove the flickering of the screen.

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else, do the following

- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
- Search for `Call` and `BashExec` in the new config.
- Compare and probably replace the associated actions in your current config

#### v0.3.0 -> v0.3.8

Your current config should work fine. However, you might want to replace some `ResetNodeFilters` messages with `RemoveNodeFilter` and `RemoveNodeFilterFromInput` to get a better search and filter experience.

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else, do the following

- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
- Search for `RemoveNodeFilterFromInput` in the new config.
- Compare and probably replace the associated actions in your current config.

#### v0.2.14 -> v0.3.0

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else do the following:

- `$XPLR_APP_YAML` has been removed. You can use `Debug` to export the app state.
- `$XPLR_RESULT` has been ported to file `$XPLR_PIPE_RESULT_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
- `$XPLR_GLOBAL_HELP_MENU` has been ported to file `$XPLR_PIPE_GLOBAL_HELP_MENU_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
- `$XPLR_DIRECTORY_NODES` has been ported to file `$XPLR_PIPE_DIRECTORY_NODES_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
- `$XPLR_LOGS` has been ported to file `$XPLR_PIPE_LOGS_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
- `$XPLR_PIPE_RESULT` has been ported to file `$XPLR_PIPE_RESULT_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
- Finally, update the `version` in your config file.

# Community

Building an active community of awesome people and learning stuff together is one of my reasons to publish this tool and maintain it. Hence, please feel free to reach out via your preferred way.

- Real-time chat lovers can join our matrix room or discord channel.
- Forum discussion veterans can start a new GitHub discussion.

If you like xplr, and want to contribute, that would be really awesome.

You can contribute to this project in the following ways

- Contribute your time and expertise (read CONTRIBUTING.md for instructions).

  - Developers: You can help me improve my code, fix things, implement features etc.
  - Repository maintainers: You can save the users from the pain of managing xplr in their system manually.
  - Code Reviewers: Teach me your ways of code.
  - Designers: You can make the logo even more awesome, donate stickers and blog post worthy pictures.
  - Bloggers, YouTubers & broadcasters: You can help spread the word.

- Contribute by donating or sponsoring me via any of the following ways.

  - GitHub Sponsors
  - Open Collective
  - ko-fi
  - liberapay
  - PayPal

For further queries or concern related to `xplr`, just ask us.

### Backers