Implement and expose xplr.util

Closes: #517

docs/en/src/SUMMARY.md

@@ -26,6 +26,7 @@
  - [Filtering][13]
  - [Column Renderer][26]
  - [Lua Function Calls][36]
+ - [xplr.util][40]
  - [Environment Variables and Pipes][37]
 - [Awesome Hacks][30]
 - [Plugin][15]
@@ -77,3 +78,4 @@
 [37]: environment-variables-and-pipes.md
 [38]: messages.md
 [39]: input-operation.md
+[40]: xplr.util.md

docs/en/src/column-renderer.md

@@ -4,6 +4,29 @@ A column renderer is a Lua function that receives a [special argument][1] and
 returns a string that will be displayed in each specific field of the
 [files table][2].
 
+## Example: Customizing Table Renderer
+
+```lua
+xplr.fn.custom.fmt_simple_column = function(m)
+ return m.prefix .. m.relative_path .. m.suffix
+end
+
+xplr.config.general.table.header.cols = {
+ { format = " path" }
+}
+
+xplr.config.general.table.row.cols = {
+ { format = "custom.fmt_simple_column" }
+}
+
+xplr.config.general.table.col_widths = {
+ { Percentage = 100 }
+}
+
+-- With this config, you should only see a single column displaying the
+-- relative paths.
+```
+
 xplr by default provides the following column renderers:
 
 - `xplr.fn.builtin.fmt_general_table_row_cols_0`
@@ -273,29 +296,6 @@ It contains the following fields.
 - [uid][36]
 - [gid][37]
 
-## Example: Customizing Table Renderer
-
-```lua
-xplr.fn.custom.fmt_simple_column = function(m)
- return m.prefix .. m.relative_path .. m.suffix
-end
-
-xplr.config.general.table.header.cols = {
- { format = " path" }
-}
-
-xplr.config.general.table.row.cols = {
- { format = "custom.fmt_simple_column" }
-}
-
-xplr.config.general.table.col_widths = {
- { Percentage = 100 }
-}
-
--- With this config, you should only see a single column displaying the
--- relative paths.
-```
-
 [1]: #table-renderer-argument
 [2]: layout.md#table
 [3]: #parent

docs/en/src/environment-variables-and-pipes.md

@@ -4,13 +4,51 @@ Alternative to `CallLua`, `CallLuaSilently` messages that call Lua functions,
 there are `Call0`, `CallSilently0`, `BashExec0`, `BashExecSilently0` messages
 that call shell commands.
 
+### Example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH
+
+```lua
+xplr.config.modes.builtin.default.key_bindings.on_key["X"] = {
+ help = "open",
+ messages = {
+ {
+ BashExecSilently0 = [===[
+ xdg-open "${XPLR_FOCUS_PATH:?}"
+ ]===],
+ },
+ },
+}
+```
+
 However, unlike the Lua functions, these shell commands have to read the useful
 information and send messages via environment variables and temporary files
 called "pipe"s. These environment variables and files are only available when
 a command is being executed.
 
-Visit the [**fzf integration tutorial**][19]
-for example.
+### Example: Using Environment Variables and Pipes
+
+```lua
+xplr.config.modes.builtin.default.key_bindings.on_key["space"] = {
+ help = "ask name and greet",
+ messages = {
+ {
+ BashExec0 = [===[
+ echo "What's your name?"
+
+ read name
+ greeting="Hello $name!"
+ message="$greeting You are inside $PWD"
+
+ "$XPLR" -m 'LogSuccess: %q' "$message"
+ ]===]
+ }
+ }
+}
+
+-- Now, when you press "space" in default mode, you will be prompted for your
+-- name. Enter your name to receive a nice greeting and to know your location.
+```
+
+Visit the [**fzf integration tutorial**][19] for another example.
 
 To see the environment variables and pipes, invoke the shell by typing `:!` in default
 mode and run the following command:
@@ -162,45 +200,6 @@ List of last visited paths (similar to jump list in vim).
 
 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 = {
- {
- BashExec0 = [===[
- echo "What's your name?"
-
- read name
- greeting="Hello $name!"
- message="$greeting You are inside $PWD"
-
- "$XPLR" -m 'LogSuccess: %q' "$message"
- ]===]
- }
- }
-}
-
--- Now, when you press "space" in default mode, you will be prompted for your
--- name. Enter your name to receive a nice greeting and to know your location.
-```
-
-### Another example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH
-
-```lua
-xplr.config.modes.builtin.default.key_bindings.on_key.X = {
- help = "open",
- messages = {
- {
- BashExecSilently0 = [===[
- xdg-open "${XPLR_FOCUS_PATH:?}"
- ]===],
- },
- },
-}
-```
-
 [7]: https://www.json.org
 [10]: column-renderer.md#index
 [11]: modes.md#modes

docs/en/src/layout.md

@@ -448,5 +448,5 @@ Hence, only the following fields are avilable.
 [49]: lua-function-calls.md#explorer_config
 [50]: lua-function-calls.md#directory_buffer
 [51]: layouts.md
-[52]: lua-function-calls#vroot
-[53]: lua-function-calls#initial_pwd
+[52]: lua-function-calls.md#vroot
+[53]: lua-function-calls.md#initial_pwd

docs/en/src/lua-function-calls.md

@@ -36,6 +36,9 @@ xplr.config.modes.builtin.default.key_bindings.on_key.space = {
 -- 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
@@ -133,7 +136,7 @@ The session path.
 
 ### explorer_config
 
-Type: [ExplorerConfig][66]
+Type: [Explorer Config][66]
 
 The configuration for exploring paths.
 
@@ -386,6 +389,10 @@ Where to focus when search is cancelled.
 
 Type: nullable string
 
+## Also Ssee:
+
+- [xplr.util][85]
+
 [7]: https://www.json.org
 [8]: modes.md#mode
 [9]: modes.md#builtin
@@ -453,3 +460,4 @@ Type: nullable string
 [82]: #node-searcher
 [83]: #pattern
 [84]: #recoverable_focus
+[85]: xplr.util.md

docs/en/src/upgrade-guide.md

@@ -77,6 +77,8 @@ compatibility.
 - Use `$XPLR_INITIAL_PWD` and Lua equivalent to implement workspace like
  features without using virtual root. Use keys `gi` to go to the initial
  working directory from anywhere.
+- Use the convenient `xplr.util` utility functions in your Lua function calls.
+ See xplr.util API docs.
 
 #### [v0.18.0][46] -> [v0.19.4][47]
 

docs/en/src/xplr.util.md

@@ -0,0 +1,86 @@
+### 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.explore
+
+Explore directories with the given explorer config.
+
+Type: function( path:string, config:[Explorer Config][1]|nil )
+-> { node:[Node][2]... }
+
+Example:
+
+```lua
+
+xplr.util.explore("/tmp")
+xplr.util.explore("/tmp", app.extra_config)
+-- { { absolute_path = "/tmp/a", ... }, ... }
+```
+
+[1]: https://xplr.dev/en/lua-function-calls#explorer-config
+[2]: https://xplr.dev/en/lua-function-calls#node
+
+### xplr.util.shell_execute
+
+Execute shell commands safely.
+
+Type: function( program:string, args:{ arg:string... }|nil )
+-> { stdout = string, stderr = string, returncode = number|nil }
+
+Example:
+
+```lua
+xplr.util.shell_execute("pwd"})
+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'
+```

docs/script/generate.py

@@ -135,6 +135,7 @@ def gen_configuration():
  - node_types.md
  - layouts.md
  - modes.md
+ - modes.md
  """
 
  path = "./src/init.lua"
@@ -218,13 +219,56 @@ def gen_configuration():
  print(doc, file=f)
 
 
+# xplr.util -------------------------------------------------------------------
+
+
+@dataclass
+class Function:
+ doc: List[str]
+ name: str
+
+
+def gen_xplr_util():
+
+ path = "./src/lua/util.rs"
+
+ functions: List[Function] = []
+
+ with open(path) as f:
+ lines = iter(f.read().splitlines())
+
+ reading = None
+
+ for line in lines:
+ if line.startswith("///"):
+ if reading:
+ reading.doc.append(line[4:])
+ else:
+ reading = Function(doc=[line[4:]], name="")
+
+ if line.startswith("pub fn") and reading:
+ reading.name = "\n### xplr.util." + line.split("<")[0].split()[-1] + "\n"
+ functions.append(reading)
+ reading = None
+ continue
+
+ with open("./docs/en/src/xplr.util.md", "w") as f:
+ for function in functions:
+ print(function.name)
+ print(function.name, file=f)
+
+ print("\n".join(function.doc))
+ print("\n".join(function.doc), file=f)
+
+
 def format_docs():
  os.system("prettier --write docs/en/src")
 
 
 def main():
  gen_messages()
  gen_configuration()
+ gen_xplr_util()
  format_docs()