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.
512 lines
9.6 KiB
Markdown
512 lines
9.6 KiB
Markdown
### xplr.util.version
|
|
|
|
Get the xplr version details.
|
|
|
|
Type: function() -> { major: number, minor: number, patch: number }
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.version()
|
|
-- { major = 0, minor = 0, patch = 0 }
|
|
```
|
|
|
|
### xplr.util.clone
|
|
|
|
Clone/deepcopy a Lua value. Doesn't work with functions.
|
|
|
|
Type: function( value ) -> value
|
|
|
|
Example:
|
|
|
|
```lua
|
|
local val = { foo = "bar" }
|
|
local val_clone = xplr.util.clone(val)
|
|
val.foo = "baz"
|
|
print(val_clone.foo)
|
|
-- "bar"
|
|
```
|
|
|
|
### xplr.util.exists
|
|
|
|
Check if the given path exists.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.exists("/foo/bar")
|
|
-- true
|
|
```
|
|
|
|
### xplr.util.is_dir
|
|
|
|
Check if the given path is a directory.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.is_dir("/foo/bar")
|
|
-- true
|
|
```
|
|
|
|
### xplr.util.is_file
|
|
|
|
Check if the given path is a file.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.is_file("/foo/bar")
|
|
-- true
|
|
```
|
|
|
|
### xplr.util.is_symlink
|
|
|
|
Check if the given path is a symlink.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.is_file("/foo/bar")
|
|
-- true
|
|
```
|
|
|
|
### xplr.util.is_absolute
|
|
|
|
Check if the given path is an absolute path.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.is_absolute("/foo/bar")
|
|
-- true
|
|
```
|
|
|
|
### xplr.util.path_split
|
|
|
|
Split a path into its components.
|
|
|
|
Type: function( path:string ) -> boolean
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.path_split("/foo/bar")
|
|
-- { "/", "foo", "bar" }
|
|
|
|
xplr.util.path_split(".././foo")
|
|
-- { "..", "foo" }
|
|
```
|
|
|
|
### xplr.util.node
|
|
|
|
Get [Node][5] information of a given path.
|
|
Doesn't check if the path exists.
|
|
Returns nil if the path is "/".
|
|
Errors out if absolute path can't be obtained.
|
|
|
|
Type: function( path:string ) -> [Node][5]|nil
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.node("./bar")
|
|
-- { parent = "/pwd", relative_path = "bar", absolute_path = "/pwd/bar", ... }
|
|
|
|
xplr.util.node("/")
|
|
-- nil
|
|
```
|
|
|
|
### xplr.util.node_type
|
|
|
|
Get the configured [Node Type][6] of a given [Node][5].
|
|
|
|
Type: function( [Node][5], [xplr.config.node_types][7]|nil ) -> [Node Type][6]
|
|
|
|
If the second argument is missing, global config `xplr.config.node_types`
|
|
will be used.
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.node_type(app.focused_node)
|
|
-- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }
|
|
|
|
xplr.util.node_type(xplr.util.node("/foo/bar"), xplr.config.node_types)
|
|
-- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }
|
|
```
|
|
|
|
### xplr.util.dirname
|
|
|
|
Get the directory name of a given path.
|
|
|
|
Type: function( path:string ) -> path:string|nil
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.dirname("/foo/bar")
|
|
-- "/foo"
|
|
```
|
|
|
|
### xplr.util.basename
|
|
|
|
Get the base name of a given path.
|
|
|
|
Type: function( path:string ) -> path:string|nil
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.basename("/foo/bar")
|
|
-- "bar"
|
|
```
|
|
|
|
### xplr.util.absolute
|
|
|
|
Get the absolute path of the given path by prepending $PWD.
|
|
It doesn't check if the path exists.
|
|
|
|
Type: function( path:string ) -> path:string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.absolute("foo/bar")
|
|
-- "/tmp/foo/bar"
|
|
```
|
|
|
|
### xplr.util.relative_to
|
|
|
|
Get the relative path based on the given base path or current working dir.
|
|
Will error if it fails to determine a relative path.
|
|
|
|
Type: function( path:string, options:table|nil ) -> path:string
|
|
|
|
Options type: { base:string|nil, with_prefix_dots:bookean|nil, without_suffix_dots:boolean|nil }
|
|
|
|
- If `base` path is given, the path will be relative to it.
|
|
- If `with_prefix_dots` is true, the path will always start with dots `..` / `.`
|
|
- If `without_suffix_dots` is true, the name will be visible instead of dots `..` / `.`
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.relative_to("/present/working/directory")
|
|
-- "."
|
|
|
|
xplr.util.relative_to("/present/working/directory/foo")
|
|
-- "foo"
|
|
|
|
xplr.util.relative_to("/present/working/directory/foo", { with_prefix_dots = true })
|
|
-- "./foo"
|
|
|
|
xplr.util.relative_to("/present/working/directory", { without_suffix_dots = true })
|
|
-- "../directory"
|
|
|
|
xplr.util.relative_to("/present/working")
|
|
-- ".."
|
|
|
|
xplr.util.relative_to("/present/working", { without_suffix_dots = true })
|
|
-- "../../working"
|
|
|
|
xplr.util.relative_to("/present/working/directory", { base = "/present/foo/bar" })
|
|
-- "../../working/directory"
|
|
```
|
|
|
|
### xplr.util.shorten
|
|
|
|
Shorten the given absolute path using the following rules:
|
|
|
|
- either relative to your home dir if it makes sense
|
|
- or relative to the current working directory
|
|
- or absolute path if it makes the most sense
|
|
|
|
Type: Similar to `xplr.util.relative_to`
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.shorten("/home/username/.config")
|
|
-- "~/.config"
|
|
|
|
xplr.util.shorten("/present/working/directory")
|
|
-- "."
|
|
|
|
xplr.util.shorten("/present/working/directory/foo")
|
|
-- "foo"
|
|
|
|
xplr.util.shorten("/present/working/directory/foo", { with_prefix_dots = true })
|
|
-- "./foo"
|
|
|
|
xplr.util.shorten("/present/working/directory", { without_suffix_dots = true })
|
|
-- "../directory"
|
|
|
|
xplr.util.shorten("/present/working/directory", { base = "/present/foo/bar" })
|
|
-- "../../working/directory"
|
|
|
|
xplr.util.shorten("/tmp")
|
|
-- "/tmp"
|
|
```
|
|
|
|
### xplr.util.explore
|
|
|
|
Explore directories with the given explorer config.
|
|
|
|
Type: function( path:string, [ExplorerConfig][1]|nil ) -> { [Node][2], ... }
|
|
|
|
Example:
|
|
|
|
```lua
|
|
|
|
xplr.util.explore("/tmp")
|
|
-- { { absolute_path = "/tmp/a", ... }, ... }
|
|
|
|
xplr.util.explore("/tmp", app.explorer_config)
|
|
-- { { absolute_path = "/tmp/a", ... }, ... }
|
|
```
|
|
|
|
### xplr.util.shell_execute
|
|
|
|
Execute shell commands safely.
|
|
|
|
Type: function( program:string, args:{ string, ... }|nil ) -> { stdout = string, stderr = string, returncode = number|nil }
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.shell_execute("pwd")
|
|
-- "/present/working/directory"
|
|
|
|
xplr.util.shell_execute("bash", {"-c", "xplr --help"})
|
|
-- { stdout = "xplr...", stderr = "", returncode = 0 }
|
|
```
|
|
|
|
### xplr.util.shell_quote
|
|
|
|
Quote commands and paths safely.
|
|
|
|
Type: function( string ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.shell_quote("a'b\"c")
|
|
-- 'a'"'"'b"c'
|
|
```
|
|
|
|
### xplr.util.shell_escape
|
|
|
|
Escape commands and paths safely.
|
|
|
|
Type: function( string ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.shell_escape("a'b\"c")
|
|
-- "\"a'b\\\"c\""
|
|
```
|
|
|
|
### xplr.util.from_json
|
|
|
|
Load JSON string into Lua value.
|
|
|
|
Type: function( string ) -> any
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.from_json([[{"foo": "bar"}]])
|
|
-- { foo = "bar" }
|
|
```
|
|
|
|
### xplr.util.to_json
|
|
|
|
Dump Lua value into JSON (i.e. also YAML) string.
|
|
|
|
Type: function( value ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.to_json({ foo = "bar" })
|
|
-- [[{ "foo": "bar" }]]
|
|
|
|
xplr.util.to_json({ foo = "bar" }, { pretty = true })
|
|
-- [[{
|
|
-- "foo": "bar"
|
|
-- }]]
|
|
```
|
|
|
|
### xplr.util.from_yaml
|
|
|
|
Load YAML (i.e. also JSON) string into Lua value.
|
|
|
|
Type: function( string ) -> value
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.from_yaml([[{foo: bar}]])
|
|
-- { foo = "bar" }
|
|
```
|
|
|
|
### xplr.util.to_yaml
|
|
|
|
Dump Lua value into YAML string.
|
|
|
|
Type: function( value ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.to_yaml({ foo = "bar" })
|
|
-- "foo: bar"
|
|
```
|
|
|
|
### xplr.util.lscolor
|
|
|
|
Get a [Style][3] object for the given path based on the LS_COLORS
|
|
environment variable.
|
|
|
|
Type: function( path:string ) -> [Style][3]|nil
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.lscolor("Desktop")
|
|
-- { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} }
|
|
```
|
|
|
|
### xplr.util.paint
|
|
|
|
Apply style (escape sequence) to string using a given [Style][3] object.
|
|
|
|
Type: function( string, [Style][3]|nil ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.paint("Desktop", { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} })
|
|
-- "\u001b[31mDesktop\u001b[0m"
|
|
```
|
|
|
|
### xplr.util.style_mix
|
|
|
|
Mix multiple [Style][3] objects into one.
|
|
|
|
Type: function( { [Style][3], [Style][3], ... } ) -> [Style][3]
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.style_mix({{ fg = "Red" }, { bg = "Blue" }, { add_modifiers = {"Bold"} }})
|
|
-- { fg = "Red", bg = "Blue", add_modifiers = { "Bold" }, sub_modifiers = {} }
|
|
```
|
|
|
|
### xplr.util.textwrap
|
|
|
|
Wrap the given text to fit the specified width.
|
|
It will try to not split words when possible.
|
|
|
|
Type: function( string, options:number|table ) -> { string, ...}
|
|
|
|
Options type: { width = number, initial_indent = string|nil, subsequent_indent = string|nil, break_words = boolean|nil }
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.textwrap("this will be cut off", 11)
|
|
-- { "this will', 'be cut off" }
|
|
|
|
xplr.util.textwrap(
|
|
"this will be cut off",
|
|
{ width = 12, initial_indent = "", subsequent_indent = " ", break_words = false }
|
|
)
|
|
-- { "this will be", " cut off" }
|
|
```
|
|
|
|
### xplr.util.layout_replace
|
|
|
|
Find the target layout in the given layout and replace it with the replacement layout,
|
|
returning a new layout.
|
|
|
|
Type: function( layout:[Layout][4], target:[Layout][4], replacement:[Layout][4] ) -> layout:[Layout][4]
|
|
|
|
Example:
|
|
|
|
```lua
|
|
local layout = {
|
|
Horizontal = {
|
|
splits = {
|
|
"Table", -- Target
|
|
"HelpMenu",
|
|
},
|
|
config = ...,
|
|
}
|
|
}
|
|
|
|
xplr.util.layout_replace(layout, "Table", "Selection")
|
|
-- {
|
|
-- Horizontal = {
|
|
-- splits = {
|
|
-- "Selection", -- Replacement
|
|
-- "HelpMenu",
|
|
-- },
|
|
-- config = ...
|
|
-- }
|
|
-- }
|
|
```
|
|
|
|
### xplr.util.permissions_rwx
|
|
|
|
Convert [Permission][8] to rwxrwxrwx representation with special bits.
|
|
|
|
Type: function( [Permission][8] ) -> string
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.permissions_rwx({ user_read = true })
|
|
-- "r--------"
|
|
|
|
xplr.util.permissions_rwx(app.focused_node.permission)
|
|
-- "rwxrwsrwT"
|
|
```
|
|
|
|
### xplr.util.permissions_octal
|
|
|
|
Convert [Permission][8] to octal representation.
|
|
|
|
Type: function( [Permission][8] ) -> { number, number, number, number }
|
|
|
|
Example:
|
|
|
|
```lua
|
|
xplr.util.permissions_octal({ user_read = true })
|
|
-- { 0, 4, 0, 0 }
|
|
|
|
xplr.util.permissions_octal(app.focused_node.permission)
|
|
-- { 0, 7, 5, 4 }
|
|
```
|
|
|
|
[1]: https://xplr.dev/en/lua-function-calls#explorer-config
|
|
[2]: https://xplr.dev/en/lua-function-calls#node
|
|
[3]: https://xplr.dev/en/style
|
|
[4]: https://xplr.dev/en/layout
|
|
[5]: https://xplr.dev/en/lua-function-calls#node
|
|
[6]: https://xplr.dev/en/node-type
|
|
[7]: https://xplr.dev/en/node_types
|
|
[8]: https://xplr.dev/en/column-renderer#permission
|