mirror of https://github.com/sayanarijit/xplr
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
445 lines
6.9 KiB
Markdown
445 lines
6.9 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
```
|
|
|
|
Visit the [xplr.util][85] API docs for some useful utility / helper functions
|
|
that you can use in your Lua function calls.
|
|
|
|
## Lua Context
|
|
|
|
This is a special argument passed to the lua functions when called using the
|
|
`CallLua`, `CallLuaSilently` messages.
|
|
|
|
It contains the following information:
|
|
|
|
- [version][29]
|
|
- [pwd][31]
|
|
- [initial_pwd][76]
|
|
- [vroot][75]
|
|
- [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.
|
|
|
|
### initial_pwd
|
|
|
|
Type: string
|
|
|
|
The initial working directory when xplr started.
|
|
|
|
### vroot
|
|
|
|
Type: nullable string
|
|
|
|
The current virtual root.
|
|
|
|
### 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
|
|
|
|
Type: [Explorer Config][66]
|
|
|
|
The configuration for exploring paths.
|
|
|
|
### history
|
|
|
|
Type: [History][70]
|
|
|
|
### last_modes
|
|
|
|
Type: list of [Mode][8]
|
|
|
|
Last modes, not popped yet.
|
|
|
|
## 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]
|
|
- [created][71]
|
|
- [last_modified][72]
|
|
- [uid][73]
|
|
- [gid][74]
|
|
- [canonical][58]
|
|
- [symlink][59]
|
|
|
|
### 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.
|
|
|
|
### created
|
|
|
|
Type: nullable integer
|
|
|
|
Creation time in nanosecond since UNIX epoch.
|
|
|
|
### last_modified
|
|
|
|
Type: nullable integer
|
|
|
|
Last modification time in nanosecond since UNIX epoch.
|
|
|
|
### uid
|
|
|
|
Type: integer
|
|
|
|
User ID of the file owner.
|
|
|
|
### gid
|
|
|
|
Type: integer
|
|
|
|
Group ID of the file owner.
|
|
|
|
### canonical
|
|
|
|
Type: nullable [Resolved Node Metadata][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.
|
|
|
|
## 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.
|
|
|
|
## Explorer Config
|
|
|
|
Explorer config contains the following fields:
|
|
|
|
- [filters][77]
|
|
- [sorters][78]
|
|
- [searcher][79]
|
|
|
|
### filters
|
|
|
|
List of filters to apply.
|
|
|
|
Type: list of [Node Filter Applicable][80]
|
|
|
|
### sorters
|
|
|
|
Add list or sorters to the pipeline.
|
|
|
|
Type: list of [Node Sorter Applicable][81]
|
|
|
|
### searcher
|
|
|
|
The searcher to use (if any).
|
|
|
|
Type: nullable [Node Searcher Applicable][82]
|
|
|
|
## Also See:
|
|
|
|
- [xplr.util][85]
|
|
|
|
[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]: #explorer-config
|
|
[67]: #history
|
|
[68]: #loc
|
|
[69]: #paths
|
|
[70]: #history-1
|
|
[71]: #created
|
|
[72]: #last_modified
|
|
[73]: #uid
|
|
[74]: #gid
|
|
[75]: #vroot
|
|
[76]: #initial_pwd
|
|
[77]: #filters
|
|
[78]: #sorters
|
|
[79]: #searcher
|
|
[80]: filtering.md#node-filter-applicable
|
|
[81]: sorting.md#node-sorter-applicable
|
|
[82]: searching.md#node-searcher-applicable
|
|
[85]: xplr.util.md
|