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
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
|
# Configuration
|
||||||
|
|
||||||
xplr can be configured using [Lua][1] via a special file
|
xplr can be configured using [Lua][3] via a special file named `init.lua`,
|
||||||
named `init.lua`
|
which can be placed in `~/.config/xplr/` (local to user) or `/etc/xplr/`
|
||||||
([example][2]), which
|
(global) depending on the use case.
|
||||||
can be placed in `~/.config/xplr/` (user specific) or `/etc/xplr/` (global)
|
|
||||||
depending on the use case.
|
|
||||||
|
|
||||||
When a user specific configuration is available, the global configuration file
|
When xplr loads, it first executes the [built-in init.lua][1] to set the
|
||||||
will be ignored.
|
default values, which is then overwritten by another config file, if found
|
||||||
|
|
||||||
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
|
|
||||||
using the following lookup order:
|
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
|
The loaded config can be further extended using the `-C` or `--extra-config`
|
||||||
following fields:
|
command-line option.
|
||||||
|
|
||||||
- [general][3]
|
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||||
- [modes][4]
|
> using [docs/script/generate.lua][2].
|
||||||
- [layouts][5]
|
|
||||||
- [node_types][6]
|
|
||||||
|
|
||||||
[1]: https://www.lua.org/
|
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||||
[2]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||||
[3]: general-config.md
|
[3]: https://www.lua.org
|
||||||
[4]: modes.md
|
|
||||||
[5]: layouts.md
|
|
||||||
[6]: node_types.md
|
|
||||||
|
@ -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
|
# 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
|
> **NEED HELP:** Auto generate rest of the docs from [src/init.lua][1]
|
||||||
xplr.config.layouts.builtin.default = {
|
> using [docs/script/generate.lua][2].
|
||||||
Horizontal = {
|
|
||||||
config = {
|
|
||||||
margin = 1,
|
|
||||||
horizontal_margin = 2,
|
|
||||||
vertical_margin = 3,
|
|
||||||
constraints = {
|
|
||||||
{ Percentage = 50 },
|
|
||||||
{ Percentage = 50 },
|
|
||||||
}
|
|
||||||
},
|
|
||||||
splits = {
|
|
||||||
"Table",
|
|
||||||
"HelpMenu",
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
xplr layouts define the structure of the UI, i.e. how many panel we see,
|
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||||
placement and size of the panels, how they look etc.
|
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||||
|
|
||||||
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
|
|
||||||
|
@ -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
|
# Modes
|
||||||
|
|
||||||
xplr is a modal file explorer. That means the users switch between different
|
This configuration is exposed via the `xplr.config.modes` API.
|
||||||
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.
|
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]
|
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||||
- [custom][2]
|
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||||
|
|
||||||
## 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
|
|
||||||
|
@ -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
|
# Node Types
|
||||||
|
|
||||||
This configuration defines how to deal with different kinds of nodes (files,
|
This configuration is exposed via the `xplr.config.node_types` API.
|
||||||
directories, symlinks etc.) in a directory.
|
|
||||||
|
|
||||||
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]
|
[1]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua
|
||||||
- [file][2]
|
[2]: https://github.com/sayanarijit/xplr/blob/main/docs/script/generate.lua
|
||||||
- [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
|
|
||||||
|
@ -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