mirror of https://github.com/sayanarijit/xplr
Auto generate some API docs from init.lua
This is the beginning of the xplr documentation revolution. Closes: https://github.com/sayanarijit/xplr/issues/445pull/455/head
Arijit Basu
2 years ago
committed by
Arijit Basu
parent
0cfeed7660
commit
ca211bb073
@ -0,0 +1,30 @@
|
||||
# Concept
|
||||
|
||||
These are the concepts that make xplr probably the most hackable terminal file
|
||||
explorer.
|
||||
|
||||
- [Key Bindings][1]
|
||||
- [Node Type][2]
|
||||
- [Layout][3]
|
||||
- [Mode][4]
|
||||
- [Message][5]
|
||||
- [Borders][6]
|
||||
- [Style][7]
|
||||
- [Sorting][8]
|
||||
- [Filtering][9]
|
||||
- [Column Renderer][10]
|
||||
- [Lua Function Calls][11]
|
||||
- [Environment Variables and Pipes][12]
|
||||
|
||||
[1]: key-bindings.md
|
||||
[2]: node-type.md
|
||||
[3]: layout.md
|
||||
[4]: mode.md
|
||||
[5]: message.md
|
||||
[6]: borders.md
|
||||
[7]: style.md
|
||||
[8]: sorting.md
|
||||
[9]: filtering.md
|
||||
[10]: column-renderer.md
|
||||
[11]: lua-function-calls.md
|
||||
[12]: environment-variables-and-pipes.md
|
||||
@ -1,41 +1,25 @@
|
||||
# Configuration
|
||||
|
||||
xplr can be configured using [Lua][1] via a special file
|
||||
named `init.lua`
|
||||
([example][2]), which
|
||||
can be placed in `~/.config/xplr/` (user specific) or `/etc/xplr/` (global)
|
||||
depending on the use case.
|
||||
xplr can be configured using [Lua][3] 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 a user specific configuration is available, the global configuration file
|
||||
will be ignored.
|
||||
|
||||
However, it's also possible to place the file anywhere, with any name and use
|
||||
the command-line argument `-c` / `--config` to specify its path explicitely. In
|
||||
that case, both `~/.config/xplr/init.lua` and `/etc/xplr/init.lua` will be
|
||||
ignored.
|
||||
|
||||
## How Config Is Loaded
|
||||
|
||||
When xplr loads, it first executes the built-in
|
||||
[init.lua][2] to set
|
||||
the default values, which is then overwritten by another config file, if found
|
||||
When xplr loads, it first executes the [built-in init.lua][1] to set the
|
||||
default values, which is then overwritten by another config file, if found
|
||||
using the following lookup order:
|
||||
|
||||
**--config /path/to/init.lua** > **~/.config/xplr/init.lua** > **/etc/xplr/init.lua**
|
||||
1. `--config /path/to/init.lua`
|
||||
2. `~/.config/xplr/init.lua`
|
||||
3. `/etc/xplr/init.lua`
|
||||
|
||||
## config
|
||||
The first one found will be loaded by xplr and the lookup will stop.
|
||||
|
||||
The xplr configuration, exposed as `xplr.config` Lua API contains the
|
||||
following fields:
|
||||
The loaded config can be further extended using the `-C` or `--extra-config`
|
||||
command-line option.
|
||||
|
||||
- [general][3]
|
||||
- [modes][4]
|
||||
- [layouts][5]
|
||||
- [node_types][6]
|
||||
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||
> using [docs/script/generate.lua][2].
|
||||
|
||||
[1]: https://www.lua.org/
|
||||
[2]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||
[3]: general-config.md
|
||||
[4]: modes.md
|
||||
[5]: layouts.md
|
||||
[6]: node_types.md
|
||||
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||
[3]: https://www.lua.org
|
||||
|
||||
@ -0,0 +1,129 @@
|
||||
# Environment Variables and Pipes
|
||||
|
||||
Alternative to `CallLua`, `CallLuaSilently` messages that call Lua functions,
|
||||
there are `Call`, `CallSilently`, `BashExec`, `BashExecSilently` messages
|
||||
that call shell commands.
|
||||
|
||||
However, unlike the Lua functions, these shell commands have to read the useful
|
||||
information and send messages via environment variables and temporary files
|
||||
called "pipe"s. These environment variables and files are only available when
|
||||
a command is being executed.
|
||||
|
||||
Visit the [**fzf integration tutorial**][19]
|
||||
for example.
|
||||
|
||||
### Environment variables
|
||||
|
||||
To see the environment variables, invoke the shell by typing `:!` in default
|
||||
mode and run the following command:
|
||||
|
||||
```
|
||||
env | grep ^XPLR_
|
||||
```
|
||||
|
||||
You will see something like:
|
||||
|
||||
```
|
||||
XPLR_FOCUS_INDEX=0
|
||||
XPLR_MODE=action to
|
||||
XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out
|
||||
XPLR_INPUT_BUFFER=
|
||||
XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out
|
||||
XPLR_PID=122278
|
||||
XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in
|
||||
XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out
|
||||
XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out
|
||||
XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out
|
||||
XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book
|
||||
XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278
|
||||
XPLR_APP_VERSION=0.14.3
|
||||
XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out
|
||||
```
|
||||
|
||||
The environment variables starting with `XPLR_PIPE_` are the temporary files
|
||||
called "pipe"s.
|
||||
|
||||
#### Input pipe
|
||||
|
||||
Current there is only one input pipe.
|
||||
|
||||
- [XPLR_PIPE_MSG_IN][20]
|
||||
|
||||
#### Output pipes
|
||||
|
||||
`XPLR_PIPE_*_OUT` are the output pipes that contain data which cannot be
|
||||
exposed directly via environment variables, like multi-line string.
|
||||
|
||||
- [XPLR_PIPE_SELECTION_OUT][21]
|
||||
- [XPLR_PIPE_GLOBAL_HELP_MENU_OUT][22]
|
||||
- [XPLR_PIPE_LOGS_OUT][23]
|
||||
- [XPLR_PIPE_RESULT_OUT][24]
|
||||
- [XPLR_PIPE_HISTORY_OUT][25]
|
||||
- [XPLR_PIPE_DIRECTORY_NODES_OUT][26]
|
||||
|
||||
#### XPLR_PIPE_MSG_IN
|
||||
|
||||
Append new-line delimited messages to this pipe in [YAML][27]
|
||||
(or [JSON][7]) syntax. These messages will be read and
|
||||
handled by xplr after the command execution.
|
||||
|
||||
#### XPLR_PIPE_SELECTION_OUT
|
||||
|
||||
New-line delimited list of selected paths.
|
||||
|
||||
#### XPLR_PIPE_GLOBAL_HELP_MENU_OUT
|
||||
|
||||
The full help menu.
|
||||
|
||||
#### XPLR_PIPE_LOGS_OUT
|
||||
|
||||
New-line delimited list of logs.
|
||||
|
||||
#### XPLR_PIPE_RESULT_OUT
|
||||
|
||||
New-line delimited result (selected paths if any, else the focused path)
|
||||
|
||||
#### XPLR_PIPE_HISTORY_OUT
|
||||
|
||||
New-line delimited list of last visited paths (similar to jump list in vim).
|
||||
|
||||
#### XPLR_PIPE_DIRECTORY_NODES_OUT
|
||||
|
||||
New-line delimited list of paths, filtered and sorted as displayed in the
|
||||
[files table][28].
|
||||
|
||||
### Example: Using Environment Variables and Pipes
|
||||
|
||||
```lua
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
|
||||
help = "ask name and greet",
|
||||
messages = {
|
||||
{
|
||||
BashExec = [===[
|
||||
echo "What's your name?"
|
||||
|
||||
read name
|
||||
greeting="Hello $name!"
|
||||
message="$greeting You are inside $PWD"
|
||||
|
||||
echo LogSuccess: '"'$message'"' >> "${XPLR_PIPE_MSG_IN:?}"
|
||||
]===]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
-- Now, when you press "space" in default mode, you will be prompted for your
|
||||
-- name. Enter your name to receive a nice greeting and to know your location.
|
||||
```
|
||||
|
||||
[7]: https://www.json.org
|
||||
[19]: configure-key-bindings.md#tutorial-adding-a-new-mode
|
||||
[20]: #xplr_pipe_msg_in
|
||||
[21]: #xplr_pipe_selection_out
|
||||
[22]: #xplr_pipe_global_help_menu_out
|
||||
[23]: #xplr_pipe_logs_out
|
||||
[24]: #xplr_pipe_result_out
|
||||
[25]: #xplr_pipe_history_out
|
||||
[26]: #xplr_pipe_directory_nodes_out
|
||||
[27]: https://www.yaml.org
|
||||
[28]: layout.md#table
|
||||
@ -0,0 +1,434 @@
|
||||
# Layout
|
||||
|
||||
#### Example: Defining Custom Layout
|
||||
|
||||
[![layout.png][23]][24]
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
Horizontal = {
|
||||
config = {
|
||||
margin = 1,
|
||||
horizontal_margin = 2,
|
||||
vertical_margin = 3,
|
||||
constraints = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
}
|
||||
},
|
||||
splits = {
|
||||
"Table",
|
||||
"HelpMenu",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A layout can be one of the following:
|
||||
|
||||
- ["Nothing"][8]
|
||||
- ["Table"][9]
|
||||
- ["InputAndLogs"][10]
|
||||
- ["Selection"][11]
|
||||
- ["HelpMenu"][12]
|
||||
- ["SortAndFilter"][13]
|
||||
- { [CustomContent][25] = { [title][33], [body][34] }
|
||||
- { [Horizontal][14] = { [config][15], [splits][17] }
|
||||
- { [Vertical][16] = { [config][15], [splits][17] }
|
||||
|
||||
### Nothing
|
||||
|
||||
This layout contains a blank panel.
|
||||
|
||||
### Table
|
||||
|
||||
This layout contains the table displaying the files and directories in the
|
||||
current directory.
|
||||
|
||||
### InputAndLogs
|
||||
|
||||
This layout contains the panel displaying the input prompt and logs.
|
||||
|
||||
### Selection
|
||||
|
||||
This layout contains the panel displaying the selected paths.
|
||||
|
||||
### HelpMenu
|
||||
|
||||
This layout contains the panel displaying the help menu for the current mode in
|
||||
real-time.
|
||||
|
||||
### SortAndFilter
|
||||
|
||||
This layout contains the panel displaying the pipeline of sorters and filters
|
||||
applied of the list of paths being displayed.
|
||||
|
||||
### Horizontal
|
||||
|
||||
This is a special layout that splits the panel into two horizontal parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config][15]
|
||||
- [splits][17]
|
||||
|
||||
### Vertical
|
||||
|
||||
This is a special layout that splits the panel into two vertical parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config][15]
|
||||
- [splits][17]
|
||||
|
||||
## Layout Config
|
||||
|
||||
A layout config contains the following information:
|
||||
|
||||
- [margin][18]
|
||||
- [horizontal_margin][19]
|
||||
- [vertical_margin][20]
|
||||
- [constraints][21]
|
||||
|
||||
### 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][18] value.
|
||||
|
||||
### vertical_Margin
|
||||
|
||||
Type: nullable integer
|
||||
|
||||
The width of the vertical margins. Overwrites the [margin][18] value.
|
||||
|
||||
### constraints
|
||||
|
||||
Type: nullable list of [Constraint][22]
|
||||
|
||||
The constraints applied on the layout.
|
||||
|
||||
## Constraint
|
||||
|
||||
A constraint 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 }
|
||||
|
||||
TODO: document each constraint.
|
||||
|
||||
## splits
|
||||
|
||||
Type: list of [Layout][3]
|
||||
|
||||
The list of child layouts to fit into the parent layout.
|
||||
|
||||
## Custom Content
|
||||
|
||||
Custom content is a special layout to render something custom.
|
||||
It contains the following information:
|
||||
|
||||
- [title][33]
|
||||
- [body][34]
|
||||
|
||||
### title
|
||||
|
||||
Type: nullable string
|
||||
|
||||
The title of the panel.
|
||||
|
||||
### body
|
||||
|
||||
Type: [Content Body][26]
|
||||
|
||||
The body of the panel.
|
||||
|
||||
## Content Body
|
||||
|
||||
Content body can be one of the following:
|
||||
|
||||
- [StaticParagraph][27]
|
||||
- [DynamicParagraph][28]
|
||||
- [StaticList][29]
|
||||
- [DynamicList][30]
|
||||
- [StaticTable][31]
|
||||
- [DynamicTable][32]
|
||||
|
||||
### Static Paragraph
|
||||
|
||||
A paragraph to render. It contains the following fields:
|
||||
|
||||
- **render** (string): The string to render.
|
||||
|
||||
#### Example: Render a custom static paragraph
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticParagraph = { render = "custom body" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Paragraph
|
||||
|
||||
A [Lua function][35] to render a custom paragraph.
|
||||
It contains the following fields:
|
||||
|
||||
- **render** (string): The [lua function][35] that returns the paragraph to
|
||||
render.
|
||||
|
||||
#### Example: Render a custom dynamic paragraph
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = { DynamicParagraph = { render = "custom.render_layout" } },
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return ctx.app.pwd
|
||||
end
|
||||
```
|
||||
|
||||
### Static List
|
||||
|
||||
A list to render. It contains the following fields:
|
||||
|
||||
- **render** (list of string): The list to render.
|
||||
|
||||
#### Example: Render a custom static list
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticList = { render = { "1", "2", "3" } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic List
|
||||
|
||||
A [Lua function][35] to render a custom list.
|
||||
It contains the following fields:
|
||||
|
||||
- **render** (string): The [lua function][35] that returns the list to render.
|
||||
|
||||
#### Example: Render a custom dynamic list
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = { DynamicList = { render = "custom.render_layout" } },
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return {
|
||||
ctx.app.pwd,
|
||||
ctx.app.version,
|
||||
tostring(ctx.app.pid),
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
### Static Table
|
||||
|
||||
A table to render. It contains the following fields:
|
||||
|
||||
- **widths** (list of [Constraint][22]): Width of the columns.
|
||||
- **col_spacing** (nullable int): Spacing between columns. Defaults to 1.
|
||||
- **render** (list of list of string): The rows and columns to render.
|
||||
|
||||
#### Example: Render a custom static table
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticTable = {
|
||||
widths = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
},
|
||||
col_spacing = 1,
|
||||
render = {
|
||||
{ "a", "b" },
|
||||
{ "c", "d" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Table
|
||||
|
||||
A [Lua function][35] to render a custom table.
|
||||
It contains the following fields:
|
||||
|
||||
- **widths** (list of [Constraint][22]): Width of the columns.
|
||||
- **col_spacing** (nullable int): Spacing between columns. Defaults to 1.
|
||||
- **render** (string): The [lua function][35] that returns the table to render.
|
||||
|
||||
#### Example: Render a custom dynamic table
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
DynamicTable = {
|
||||
widths = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
},
|
||||
col_spacing = 1,
|
||||
render = "custom.render_layout",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return {
|
||||
{ "", "" },
|
||||
{ "Layout height", tostring(ctx.layout_size.height) },
|
||||
{ "Layout width", tostring(ctx.layout_size.width) },
|
||||
{ "", "" },
|
||||
{ "Screen height", tostring(ctx.screen_size.height) },
|
||||
{ "Screen width", tostring(ctx.screen_size.width) },
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
## Content Renderer
|
||||
|
||||
It is a Lua function that receives [a special argument][36] 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][37]
|
||||
- [screen_size][37]
|
||||
- [app][38]
|
||||
|
||||
### 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][39]. In this context, the
|
||||
heavyweight fields like [directory_buffer][50] are omitted for performance
|
||||
reasons.
|
||||
|
||||
Hence, only the following fields are avilable.
|
||||
|
||||
- [version][40]
|
||||
- [pwd][41]
|
||||
- [focused_node][42]
|
||||
- [selection][43]
|
||||
- [mode][44]
|
||||
- [layout][45]
|
||||
- [input_buffer][46]
|
||||
- [pid][47]
|
||||
- [session_path][48]
|
||||
- [explorer_config][49]
|
||||
|
||||
## Also See:
|
||||
|
||||
- [xplr.config.layouts][51]
|
||||
|
||||
[1]: #builtin
|
||||
[2]: #custom
|
||||
[3]: #layout
|
||||
[4]: #default
|
||||
[5]: #no_help
|
||||
[6]: #no_selection
|
||||
[7]: #no_help_no_selection
|
||||
[8]: #nothing
|
||||
[9]: #table
|
||||
[10]: #inputandlogs
|
||||
[11]: #selection
|
||||
[12]: #helpmenu
|
||||
[13]: #sortandfilter
|
||||
[14]: #horizontal
|
||||
[15]: #layout-config
|
||||
[16]: #vertical
|
||||
[17]: #splits
|
||||
[18]: #margin
|
||||
[19]: #horizontal_margin
|
||||
[20]: #vertical_margin
|
||||
[21]: #constraints
|
||||
[22]: #constraint
|
||||
[23]: https://s6.gifyu.com/images/layout.png
|
||||
[24]: https://gifyu.com/image/1X38
|
||||
[25]: #custom-content
|
||||
[26]: #content-body
|
||||
[27]: #static-paragraph
|
||||
[28]: #dynamic-paragraph
|
||||
[29]: #static-list
|
||||
[30]: #dynamic-list
|
||||
[31]: #static-table
|
||||
[32]: #dynamic-table
|
||||
[33]: #title
|
||||
[34]: #body
|
||||
[35]: #content-renderer
|
||||
[36]: #content-renderer-argument
|
||||
[37]: #size
|
||||
[38]: #app
|
||||
[39]: lua-function-calls.md#lua-context
|
||||
[40]: lua-function-calls.md#version
|
||||
[41]: lua-function-calls.md#pwd
|
||||
[42]: lua-function-calls.md#focused_node
|
||||
[43]: lua-function-calls.md#selection
|
||||
[44]: lua-function-calls.md#mode
|
||||
[45]: lua-function-calls.md#layout
|
||||
[46]: lua-function-calls.md#input_buffer
|
||||
[47]: lua-function-calls.md#pid
|
||||
[48]: lua-function-calls.md#session_path
|
||||
[49]: lua-function-calls.md#explorer_config
|
||||
[50]: lua-function-calls.md#directory_buffer
|
||||
[51]: layouts.md
|
||||
@ -1,496 +1,11 @@
|
||||
# Layouts
|
||||
|
||||
#### Example: Defining Custom Layout
|
||||
This configuration is exposed via the `xplr.config.layouts` API.
|
||||
|
||||
[![layout.png][23]][24]
|
||||
For now, kindly refer to [**init.lua**][1]
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
Horizontal = {
|
||||
config = {
|
||||
margin = 1,
|
||||
horizontal_margin = 2,
|
||||
vertical_margin = 3,
|
||||
constraints = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
}
|
||||
},
|
||||
splits = {
|
||||
"Table",
|
||||
"HelpMenu",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||
> using [docs/script/generate.lua][2].
|
||||
|
||||
xplr layouts define the structure of the UI, i.e. how many panel we see,
|
||||
placement and size of the panels, how they look etc.
|
||||
|
||||
This is configuration exposed via the `xplr.config.layouts` API. It contains
|
||||
the following fields:
|
||||
|
||||
- [builtin][1]
|
||||
- [custom][2]
|
||||
|
||||
The users can switch between these layouts at run-time.
|
||||
|
||||
## builtin
|
||||
|
||||
Type: mapping of string and [Layout][3]
|
||||
|
||||
This is exposed by the `xplr.config.layouts.builtin` API.
|
||||
|
||||
xplr by default provides the following builtin layouts:
|
||||
|
||||
- [default][4]
|
||||
- [no_help][5]
|
||||
- [no_selection][6]
|
||||
- [no_help_no_selection][7]
|
||||
|
||||
### default
|
||||
|
||||
Type: [Layout][3]
|
||||
|
||||
This is the default layout we see when we run xplr.
|
||||
|
||||
### no_help
|
||||
|
||||
Type: [Layout][3]
|
||||
|
||||
This layout hides the help menu.
|
||||
|
||||
### no_selection
|
||||
|
||||
Type: [Layout][3]
|
||||
|
||||
This layout hides the selection panel.
|
||||
|
||||
### no_help_no_selection
|
||||
|
||||
Type: [Layout][3]
|
||||
|
||||
This layout hides both the help menu and the selection panel.
|
||||
|
||||
## custom
|
||||
|
||||
Type: mapping of string and [Layout][3]
|
||||
|
||||
This is exposed by the `xplr.config.layouts.custom` API.
|
||||
|
||||
It allows the users to define any custom layout.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.custom.example = "Nothing"
|
||||
xplr.config.general.initial_layout = "example"
|
||||
|
||||
-- when you load xplr, you should see a blank screen
|
||||
```
|
||||
|
||||
## Layout
|
||||
|
||||
A layout can be one of the following:
|
||||
|
||||
- ["Nothing"][8]
|
||||
- ["Table"][9]
|
||||
- ["InputAndLogs"][10]
|
||||
- ["Selection"][11]
|
||||
- ["HelpMenu"][12]
|
||||
- ["SortAndFilter"][13]
|
||||
- { [CustomContent][25] = { [title][33], [body][34] }
|
||||
- { [Horizontal][14] = { [config][15], [splits][17] }
|
||||
- { [Vertical][16] = { [config][15], [splits][17] }
|
||||
|
||||
### Nothing
|
||||
|
||||
This layout contains a blank panel.
|
||||
|
||||
### Table
|
||||
|
||||
This layout contains the table displaying the files and directories in the
|
||||
current directory.
|
||||
|
||||
### InputAndLogs
|
||||
|
||||
This layout contains the panel displaying the input prompt and logs.
|
||||
|
||||
### Selection
|
||||
|
||||
This layout contains the panel displaying the selected paths.
|
||||
|
||||
### HelpMenu
|
||||
|
||||
This layout contains the panel displaying the help menu for the current mode in
|
||||
real-time.
|
||||
|
||||
### SortAndFilter
|
||||
|
||||
This layout contains the panel displaying the pipeline of sorters and filters
|
||||
applied of the list of paths being displayed.
|
||||
|
||||
### Horizontal
|
||||
|
||||
This is a special layout that splits the panel into two horizontal parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config][15]
|
||||
- [splits][17]
|
||||
|
||||
### Vertical
|
||||
|
||||
This is a special layout that splits the panel into two vertical parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config][15]
|
||||
- [splits][17]
|
||||
|
||||
## Layout Config
|
||||
|
||||
A layout config contains the following information:
|
||||
|
||||
- [margin][18]
|
||||
- [horizontal_margin][19]
|
||||
- [vertical_margin][20]
|
||||
- [constraints][21]
|
||||
|
||||
### 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][18] value.
|
||||
|
||||
### vertical_Margin
|
||||
|
||||
Type: nullable integer
|
||||
|
||||
The width of the vertical margins. Overwrites the [margin][18] value.
|
||||
|
||||
### constraints
|
||||
|
||||
Type: nullable list of [Constraint][22]
|
||||
|
||||
The constraints applied on the layout.
|
||||
|
||||
## Constraint
|
||||
|
||||
A constraint 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 }
|
||||
|
||||
TODO: document each constraint.
|
||||
|
||||
## splits
|
||||
|
||||
Type: list of [Layout][3]
|
||||
|
||||
The list of child layouts to fit into the parent layout.
|
||||
|
||||
## Custom Content
|
||||
|
||||
Custom content is a special layout to render something custom.
|
||||
It contains the following information:
|
||||
|
||||
- [title][33]
|
||||
- [body][34]
|
||||
|
||||
### title
|
||||
|
||||
Type: nullable string
|
||||
|
||||
The title of the panel.
|
||||
|
||||
### body
|
||||
|
||||
Type: [Content Body][26]
|
||||
|
||||
The body of the panel.
|
||||
|
||||
## Content Body
|
||||
|
||||
Content body can be one of the following:
|
||||
|
||||
- [StaticParagraph][27]
|
||||
- [DynamicParagraph][28]
|
||||
- [StaticList][29]
|
||||
- [DynamicList][30]
|
||||
- [StaticTable][31]
|
||||
- [DynamicTable][32]
|
||||
|
||||
### Static Paragraph
|
||||
|
||||
A paragraph to render. It contains the following fields:
|
||||
|
||||
- **render** (string): The string to render.
|
||||
|
||||
#### Example: Render a custom static paragraph
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticParagraph = { render = "custom body" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Paragraph
|
||||
|
||||
A [Lua function][35] to render a custom paragraph.
|
||||
It contains the following fields:
|
||||
|
||||
- **render** (string): The [lua function][35] that returns the paragraph to
|
||||
render.
|
||||
|
||||
#### Example: Render a custom dynamic paragraph
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = { DynamicParagraph = { render = "custom.render_layout" } },
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return ctx.app.pwd
|
||||
end
|
||||
```
|
||||
|
||||
### Static List
|
||||
|
||||
A list to render. It contains the following fields:
|
||||
|
||||
- **render** (list of string): The list to render.
|
||||
|
||||
#### Example: Render a custom static list
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticList = { render = { "1", "2", "3" } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic List
|
||||
|
||||
A [Lua function][35] to render a custom list.
|
||||
It contains the following fields:
|
||||
|
||||
- **render** (string): The [lua function][35] that returns the list to render.
|
||||
|
||||
#### Example: Render a custom dynamic list
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = { DynamicList = { render = "custom.render_layout" } },
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return {
|
||||
ctx.app.pwd,
|
||||
ctx.app.version,
|
||||
tostring(ctx.app.pid),
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
### Static Table
|
||||
|
||||
A table to render. It contains the following fields:
|
||||
|
||||
- **widths** (list of [Constraint][22]): Width of the columns.
|
||||
- **col_spacing** (nullable int): Spacing between columns. Defaults to 1.
|
||||
- **render** (list of list of string): The rows and columns to render.
|
||||
|
||||
#### Example: Render a custom static table
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
StaticTable = {
|
||||
widths = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
},
|
||||
col_spacing = 1,
|
||||
render = {
|
||||
{ "a", "b" },
|
||||
{ "c", "d" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Table
|
||||
|
||||
A [Lua function][35] to render a custom table.
|
||||
It contains the following fields:
|
||||
|
||||
- **widths** (list of [Constraint][22]): Width of the columns.
|
||||
- **col_spacing** (nullable int): Spacing between columns. Defaults to 1.
|
||||
- **render** (string): The [lua function][35] that returns the table to render.
|
||||
|
||||
#### Example: Render a custom dynamic table
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
CustomContent = {
|
||||
title = "custom title",
|
||||
body = {
|
||||
DynamicTable = {
|
||||
widths = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
},
|
||||
col_spacing = 1,
|
||||
render = "custom.render_layout",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
xplr.fn.custom.render_layout = function(ctx)
|
||||
return {
|
||||
{ "", "" },
|
||||
{ "Layout height", tostring(ctx.layout_size.height) },
|
||||
{ "Layout width", tostring(ctx.layout_size.width) },
|
||||
{ "", "" },
|
||||
{ "Screen height", tostring(ctx.screen_size.height) },
|
||||
{ "Screen width", tostring(ctx.screen_size.width) },
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
## Content Renderer
|
||||
|
||||
It is a Lua function that receives [a special argument][36] 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][37]
|
||||
- [screen_size][37]
|
||||
- [app][38]
|
||||
|
||||
### 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][39]. In this context, the
|
||||
heavyweight fields like [directory_buffer][50] are omitted for performance
|
||||
reasons.
|
||||
|
||||
Hence, only the following fields are avilable.
|
||||
|
||||
- [version][40]
|
||||
- [pwd][41]
|
||||
- [focused_node][42]
|
||||
- [selection][43]
|
||||
- [mode][44]
|
||||
- [layout][45]
|
||||
- [input_buffer][46]
|
||||
- [pid][47]
|
||||
- [session_path][48]
|
||||
- [explorer_config][49]
|
||||
|
||||
[1]: #builtin
|
||||
[2]: #custom
|
||||
[3]: #layout
|
||||
[4]: #default
|
||||
[5]: #no_help
|
||||
[6]: #no_selection
|
||||
[7]: #no_help_no_selection
|
||||
[8]: #nothing
|
||||
[9]: #table
|
||||
[10]: #inputandlogs
|
||||
[11]: #selection
|
||||
[12]: #helpmenu
|
||||
[13]: #sortandfilter
|
||||
[14]: #horizontal
|
||||
[15]: #layout-config
|
||||
[16]: #vertical
|
||||
[17]: #splits
|
||||
[18]: #margin
|
||||
[19]: #horizontal_margin
|
||||
[20]: #vertical_margin
|
||||
[21]: #constraints
|
||||
[22]: #constraint
|
||||
[23]: https://s6.gifyu.com/images/layout.png
|
||||
[24]: https://gifyu.com/image/1X38
|
||||
[25]: #custom-content
|
||||
[26]: #content-body
|
||||
[27]: #static-paragraph
|
||||
[28]: #dynamic-paragraph
|
||||
[29]: #static-list
|
||||
[30]: #dynamic-list
|
||||
[31]: #static-table
|
||||
[32]: #dynamic-table
|
||||
[33]: #title
|
||||
[34]: #body
|
||||
[35]: #content-renderer
|
||||
[36]: #content-renderer-argument
|
||||
[37]: #size
|
||||
[38]: #app
|
||||
[39]: message.md#lua-context
|
||||
[40]: message.md#version
|
||||
[41]: message.md#pwd
|
||||
[42]: message.md#focused_node
|
||||
[43]: message.md#selection
|
||||
[44]: message.md#mode
|
||||
[45]: message.md#layout
|
||||
[46]: message.md#input_buffer
|
||||
[47]: message.md#pid
|
||||
[48]: message.md#session_path
|
||||
[49]: message.md#explorer_config
|
||||
[50]: message.md#directory_buffer
|
||||
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||
|
||||
@ -0,0 +1,354 @@
|
||||
# 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][14] that
|
||||
contains some useful information. The function can optionally return a list of
|
||||
messages which will be handled by xplr.
|
||||
|
||||
### Lua Context
|
||||
|
||||
This is a special argument passed to the lua functions when called using the
|
||||
`CallLua`, `CallLuaSilently` messages.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [version][29]
|
||||
- [pwd][31]
|
||||
- [focused_node][32]
|
||||
- [directory_buffer][33]
|
||||
- [selection][34]
|
||||
- [mode][35]
|
||||
- [layout][36]
|
||||
- [input_buffer][37]
|
||||
- [pid][38]
|
||||
- [session_path][39]
|
||||
- [explorer_config][40]
|
||||
- [history][41]
|
||||
- [last_modes][42]
|
||||
|
||||
### version
|
||||
|
||||
Type: string
|
||||
|
||||
xplr version. Can be used to test compatibility.
|
||||
|
||||
### pwd
|
||||
|
||||
Type: string
|
||||
|
||||
The present working directory/
|
||||
|
||||
### focused_node
|
||||
|
||||
Type: nullable [Node][44]
|
||||
|
||||
The node under focus.
|
||||
|
||||
### directory_buffer
|
||||
|
||||
Type: nullable [Directory Buffer][62]
|
||||
|
||||
The directory buffer being rendered.
|
||||
|
||||
### selection
|
||||
|
||||
Type: list of selected [Node][44]s
|
||||
|
||||
The selected nodes.
|
||||
|
||||
### mode
|
||||
|
||||
Type: [Mode][8]
|
||||
|
||||
Current mode.
|
||||
|
||||
### layout
|
||||
|
||||
Type: [Layout][11]
|
||||
|
||||
Current layout.
|
||||
|
||||
### input_buffer
|
||||
|
||||
Type: nullable string
|
||||
|
||||
The input buffer.
|
||||
|
||||
### pid
|
||||
|
||||
Type: integer
|
||||
|
||||
The xplr session PID.
|
||||
|
||||
### session_path
|
||||
|
||||
Type: string
|
||||
|
||||
The session path.
|
||||
|
||||
### explorer_config
|
||||
|
||||
[TODO][66]
|
||||
|
||||
### history
|
||||
|
||||
Type: [History][70]
|
||||
|
||||
### last_modes
|
||||
|
||||
Type: list of [Mode][8]
|
||||
|
||||
Last modes, not popped yet.
|
||||
|
||||
### parent
|
||||
|
||||
Type: string
|
||||
|
||||
The parent path of the node.
|
||||
|
||||
### relative_path
|
||||
|
||||
Type: string
|
||||
|
||||
The path relative to the parent, i.e. the file/directory name with extension.
|
||||
|
||||
### absolute_path
|
||||
|
||||
Type: string
|
||||
|
||||
The absolute path (without resolving symlinks) of the node.
|
||||
|
||||
### extension
|
||||
|
||||
Type: string
|
||||
|
||||
The extension of the node.
|
||||
|
||||
### is_symlink
|
||||
|
||||
Type: boolean
|
||||
|
||||
`true` if the node is a symlink.
|
||||
|
||||
### is_broken
|
||||
|
||||
Type: boolean
|
||||
|
||||
`true` if the node is a broken symlink.
|
||||
|
||||
### is_dir
|
||||
|
||||
Type: boolean
|
||||
|
||||
`true` if the node is a directory.
|
||||
|
||||
### is_file
|
||||
|
||||
Type: boolean
|
||||
|
||||
`true` if the node is a file.
|
||||
|
||||
### is_readonly
|
||||
|
||||
Type: boolean
|
||||
|
||||
`true` if the node is real-only.
|
||||
|
||||
### mime_essence
|
||||
|
||||
Type: string
|
||||
|
||||
The mime type of the node. For e.g. `text/csv`, `image/jpeg` etc.
|
||||
|
||||
### size
|
||||
|
||||
Type: integer
|
||||
|
||||
The size of the exact node. The size of a directory won't be calculated
|
||||
recursively.
|
||||
|
||||
### human_size
|
||||
|
||||
Type: string
|
||||
|
||||
Like size but in human readable format.
|
||||
|
||||
### permissions
|
||||
|
||||
Type: [Permission][60]
|
||||
|
||||
The [permissions][60] applied to the node.
|
||||
|
||||
### canonical
|
||||
|
||||
Type: nullable [Resolved Node Metadata][61]
|
||||
|
||||
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][61]
|
||||
|
||||
If the node is a symlink and is not broken, it will hold information about the
|
||||
symlink resolved node. However, it will never hold information about the actual
|
||||
node. It will instead be null.
|
||||
|
||||
### Node
|
||||
|
||||
A node contains the following fields:
|
||||
|
||||
- [parent][45]
|
||||
- [relative_path][46]
|
||||
- [absolute_path][47]
|
||||
- [extension][48]
|
||||
- [is_symlink][49]
|
||||
- [is_broken][50]
|
||||
- [is_dir][51]
|
||||
- [is_file][52]
|
||||
- [is_readonly][53]
|
||||
- [mime_essence][54]
|
||||
- [size][55]
|
||||
- [human_size][56]
|
||||
- [permissions][57]
|
||||
- [canonical][58]
|
||||
- [symlink][59]
|
||||
|
||||
### Directory Buffer
|
||||
|
||||
Directory buffer contains the following fields:
|
||||
|
||||
- [parent][45]
|
||||
- [nodes][63]
|
||||
- [total][64]
|
||||
- [focus][65]
|
||||
|
||||
#### parent
|
||||
|
||||
Type: string
|
||||
|
||||
The parent path of the node.
|
||||
|
||||
#### nodes
|
||||
|
||||
Type: list of [Node][44]s
|
||||
|
||||
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][68]
|
||||
- [paths][69]
|
||||
|
||||
#### loc
|
||||
|
||||
Type: int
|
||||
|
||||
Location of the current path in history.
|
||||
|
||||
#### paths
|
||||
|
||||
Type: list of string
|
||||
|
||||
Visited paths.
|
||||
|
||||
### Example: Using Lua Function Calls
|
||||
|
||||
```lua
|
||||
-- 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.
|
||||
```
|
||||
|
||||
[7]: https://www.json.org
|
||||
[8]: modes.md#mode
|
||||
[9]: modes.md#builtin
|
||||
[10]: modes.md#custom
|
||||
[11]: layouts.md
|
||||
[12]: layouts.md#builtin
|
||||
[13]: layouts.md#custom
|
||||
[14]: #lua-context
|
||||
[15]: filtering.md#filter
|
||||
[16]: filtering.md
|
||||
[17]: sorting.md#sorter
|
||||
[29]: #version
|
||||
[30]: #config
|
||||
[31]: #pwd
|
||||
[32]: #focused_node
|
||||
[33]: #directory_buffer
|
||||
[34]: #selection
|
||||
[35]: #mode
|
||||
[36]: #layout
|
||||
[37]: #input_buffer
|
||||
[38]: #pid
|
||||
[39]: #session_path
|
||||
[40]: #explorer_config
|
||||
[41]: #history
|
||||
[42]: #last_modes
|
||||
[43]: configuration.md#config
|
||||
[44]: #node
|
||||
[45]: #parent
|
||||
[46]: #relative_path
|
||||
[47]: #absolute_path
|
||||
[48]: #extension
|
||||
[49]: #is_symlink
|
||||
[50]: #is_broken
|
||||
[51]: #is_dir
|
||||
[52]: #is_file
|
||||
[53]: #is_readonly
|
||||
[54]: #mime_essence
|
||||
[55]: #size
|
||||
[56]: #human_size
|
||||
[57]: #permissions
|
||||
[58]: #canonical
|
||||
[59]: #symlink
|
||||
[60]: column-renderer.md#permission
|
||||
[61]: column-renderer.md#resolved-node-metadata
|
||||
[62]: #directory-buffer
|
||||
[63]: #nodes
|
||||
[64]: #total
|
||||
[65]: #focus
|
||||
[66]: https://docs.rs/xplr/latest/xplr/app/struct.ExplorerConfig.html
|
||||
[67]: #history
|
||||
[68]: #loc
|
||||
[69]: #paths
|
||||
[70]: #history-1
|
||||
@ -0,0 +1,58 @@
|
||||
# Mode
|
||||
|
||||
A mode contains the following information:
|
||||
|
||||
- [name][5]
|
||||
- [help][6]
|
||||
- [extra_help][7]
|
||||
- [key_bindings][9]
|
||||
- [layout][10]
|
||||
|
||||
### 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][8]
|
||||
|
||||
The key bindings available in that mode.
|
||||
|
||||
### layout
|
||||
|
||||
Type: nullable [Layout][11]
|
||||
|
||||
If specified, this layout will be used to render the UI.
|
||||
|
||||
## Also See:
|
||||
|
||||
- [xplr.config.modes][12]
|
||||
|
||||
[1]: #builtin
|
||||
[2]: #custom
|
||||
[3]: #mode
|
||||
[4]: default-key-bindings.md
|
||||
[5]: #name
|
||||
[6]: #help
|
||||
[7]: #extra_help
|
||||
[8]: configure-key-bindings.md#key-bindings
|
||||
[9]: #key_bindings
|
||||
[10]: #layout
|
||||
[11]: layout.md#layout
|
||||
[12]: modes.md
|
||||
@ -1,130 +1,11 @@
|
||||
# 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.
|
||||
This configuration is exposed via the `xplr.config.modes` API.
|
||||
|
||||
The modes can be configured using the `xplr.config.modes` Lua API.
|
||||
For now, kindly refer to [**init.lua**][1]
|
||||
|
||||
It contains the following fields:
|
||||
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||
> using [docs/script/generate.lua][2].
|
||||
|
||||
- [builtin][1]
|
||||
- [custom][2]
|
||||
|
||||
## builtin
|
||||
|
||||
Type: mapping of string and [Mode][3]
|
||||
|
||||
This is exposed by the `xplr.config.modes.builtin` API.
|
||||
|
||||
xplr by default provides the following builtin modes:
|
||||
|
||||
- default
|
||||
- debug_error
|
||||
- recover
|
||||
- selection_ops
|
||||
- create
|
||||
- create_directory
|
||||
- create_file
|
||||
- number
|
||||
- go_to
|
||||
- rename
|
||||
- delete
|
||||
- duplicate_as
|
||||
- action
|
||||
- search
|
||||
- filter
|
||||
- relative_path_does_contain
|
||||
- relative_path_does_not_contain
|
||||
- sort
|
||||
- switch_layout
|
||||
- quit
|
||||
|
||||
Visit the [Default Key Bindings][4] to see what each mode
|
||||
does.
|
||||
|
||||
## custom
|
||||
|
||||
Type: mapping of string and [Mode][3]
|
||||
|
||||
This is exposed by the `xplr.config.modes.custom` API.
|
||||
|
||||
It allows the users to define custom modes.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.modes.custom.example = {
|
||||
name = "example",
|
||||
key_bindings = {
|
||||
on_key = {
|
||||
enter = {
|
||||
help = "default mode",
|
||||
messages = {
|
||||
"PopMode",
|
||||
{ SwitchModeBuiltin = "default" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
xplr.config.general.initial_mode = "example"
|
||||
|
||||
-- when you load xplr, you should be in the "example" mode,
|
||||
-- pressing "enter" should take you to the "default" mode.
|
||||
```
|
||||
|
||||
## Mode
|
||||
|
||||
A mode contains the following information:
|
||||
|
||||
- [name][5]
|
||||
- [help][6]
|
||||
- [extra_help][7]
|
||||
- [key_bindings][8]
|
||||
- [layout][10]
|
||||
|
||||
### 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][8]
|
||||
|
||||
The key bindings available in that mode.
|
||||
|
||||
### layout
|
||||
|
||||
Type: nullable [Layout][11]
|
||||
|
||||
If specified, this layout will be used to render the UI.
|
||||
|
||||
[1]: #builtin
|
||||
[2]: #custom
|
||||
[3]: #mode
|
||||
[4]: default-key-bindings.md
|
||||
[5]: #name
|
||||
[6]: #help
|
||||
[7]: #extra_help
|
||||
[8]: configure-key-bindings.md#key-bindings
|
||||
[9]: #key-bindings
|
||||
[10]: #layout
|
||||
[11]: layouts.md#layout
|
||||
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||
|
||||
@ -0,0 +1,36 @@
|
||||
# Node Type
|
||||
|
||||
A node-type contains the following fields:
|
||||
|
||||
- [meta][4]
|
||||
- [style][5]
|
||||
|
||||
### 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][1], [file][2], and
|
||||
[symlink][3] nodes.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.file = {
|
||||
meta = {
|
||||
icon = "f",
|
||||
foo = "bar",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Also See:
|
||||
|
||||
- [xplr.config.node_types][6]
|
||||
|
||||
[1]: node_types.md#directory
|
||||
[2]: node_types.md#file
|
||||
[3]: node_types.md#symlink
|
||||
[4]: #meta
|
||||
[5]: style.md
|
||||
[6]: node_types.md
|
||||
@ -1,155 +1,11 @@
|
||||
# Node Types
|
||||
|
||||
This configuration defines how to deal with different kinds of nodes (files,
|
||||
directories, symlinks etc.) in a directory.
|
||||
This configuration is exposed via the `xplr.config.node_types` API.
|
||||
|
||||
This can be configured using the `xplr.config.node_types` Lua API.
|
||||
For now, kindly refer to [**init.lua**][1]
|
||||
|
||||
It contains the following fields:
|
||||
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||
> using [docs/script/generate.lua][2].
|
||||
|
||||
- [directory][1]
|
||||
- [file][2]
|
||||
- [symlink][3]
|
||||
- [mime_essence][4]
|
||||
- [extension][5]
|
||||
- [special][6]
|
||||
|
||||
One node can fall into multiple categories. For example, a node can have the
|
||||
extension `md`, and be a `file`. In that case, the properties from the more
|
||||
specific category i.e. extension will be used.
|
||||
|
||||
The priority is:
|
||||
|
||||
**special** > **extension** > **mime_essence** > **symlink** > **file** > **directory**
|
||||
|
||||
### directory
|
||||
|
||||
Type: [NodeType Config][7]
|
||||
|
||||
Properties related to directories are defined here.
|
||||
|
||||
Contains the following fields:
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.directory.meta.icon = ""
|
||||
xplr.config.node_types.directory.style.add_modifiers = { "Bold" }
|
||||
```
|
||||
|
||||
### file
|
||||
|
||||
Type: [NodeType Config][7]
|
||||
|
||||
Properties related to regular files are defined here.
|
||||
|
||||
Contains the following fields:
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.file.meta.icon = ""
|
||||
xplr.config.node_types.file.style.fg = "White"
|
||||
```
|
||||
|
||||
### symlink
|
||||
|
||||
Type: [NodeType Config][7]
|
||||
|
||||
Properties related to symlink are defined here.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.symlink.meta.icon = ""
|
||||
xplr.config.node_types.symlink.style.add_modifiers = { "Italic" }
|
||||
```
|
||||
|
||||
### mime_essence
|
||||
|
||||
Type: mapping of mime-type and mapping of mime-subtype and [NodeType Config][7]
|
||||
|
||||
Properties related to files with specific mime types are defined here.
|
||||
|
||||
It is possible to use the wildcard `*` to match all mime subtypes. It will be
|
||||
overwritten by the more specific sub types that are defined.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.mime_essence = {
|
||||
application = {
|
||||
-- application/*
|
||||
["*"] = { meta = { icon = "a" } }
|
||||
|
||||
-- application/pdf
|
||||
pdf = { meta = { icon = "" } },
|
||||
|
||||
-- application/zip
|
||||
zip = { meta = { icon = ""} },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### extension
|
||||
|
||||
Type: mapping of extension and [NodeType Config][7]
|
||||
|
||||
Properties related to files with specific extension are defined here.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.extension.md = { meta = { icon = "" } }
|
||||
xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }
|
||||
```
|
||||
|
||||
### special
|
||||
|
||||
Type: mapping of name and [NodeType Config][7]
|
||||
|
||||
Properties related to files and directories with special names are defined
|
||||
here.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
|
||||
xplr.config.node_types.special["Downloads"] = { meta = { icon = "" } }
|
||||
```
|
||||
|
||||
## NodeType Config
|
||||
|
||||
A node-type config contains the following fields:
|
||||
|
||||
- [meta][8]
|
||||
- [style][9]
|
||||
|
||||
### 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][1], [file][2], and
|
||||
[symlink][3] nodes.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.node_types.file = {
|
||||
meta = {
|
||||
icon = "f",
|
||||
foo = "bar",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[1]: #directory
|
||||
[2]: #file
|
||||
[3]: #symlink
|
||||
[4]: #mime_essence
|
||||
[5]: #extension
|
||||
[6]: #special
|
||||
[7]: #nodetype-config
|
||||
[8]: #meta
|
||||
[9]: style.md
|
||||
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||
|
||||
@ -0,0 +1,45 @@
|
||||
-- Configuration documentation generator
|
||||
--
|
||||
-- TODO implement
|
||||
--
|
||||
-- This script generates configuration docs by parsing the comments and
|
||||
-- properties from `src/init.lua`.
|
||||
--
|
||||
-- Usage:
|
||||
--
|
||||
-- ```
|
||||
-- lua ./docs/script/generate.lua
|
||||
-- ```
|
||||
--
|
||||
-- Or
|
||||
--
|
||||
-- ```
|
||||
-- xplr -C ./docs/script/generate.lua --on-load Quit
|
||||
-- ```
|
||||
|
||||
-- Generates ./docs/en/src/configuration.md
|
||||
local function generate_configuration(lines) end
|
||||
|
||||
-- Generates ./docs/en/src/general-config.md
|
||||
local function generate_general_config(lines) end
|
||||
|
||||
-- Generates ./docs/en/src/node_types.md
|
||||
local function generate_node_types(lines) end
|
||||
|
||||
-- Generates ./docs/en/src/general-config.md
|
||||
local function generate_layouts(lines) end
|
||||
|
||||
-- Generates ./docs/en/src/general-config.md
|
||||
local function generate_modes(lines) end
|
||||
|
||||
local function main()
|
||||
local init = io.lines("./src/init.lua")
|
||||
|
||||
generate_configuration(init)
|
||||
generate_general_config(init)
|
||||
generate_node_types(init)
|
||||
generate_layouts(init)
|
||||
generate_modes(init)
|
||||
end
|
||||
|
||||
main()
|
||||
Loading…
Reference in New Issue