1 files changed, 191 insertions, 0 deletions
diff --git a/docs/guide/lua/utilities.md b/docs/guide/lua/utilities.md
new file mode 100644
index 0000000..1ef70c7
--- /dev/null
+++ b/docs/guide/lua/utilities.md
@@ -0,0 +1,191 @@
+# Utilities
+
+## File functions
+
+```lua
+local read_file = astal.read_file
+local read_file_async = astal.read_file_async
+local write_file = astal.write_file
+local write_file_async = astal.write_file_async
+local monitor_file = astal.monitor_file
+```
+
+### Reading files
+
+```lua
+---@param path string
+---@return string
+local function read_file(path) end
+
+---@param path string
+---@param callback fun(content: string, err: string): nil
+local function read_file_async(path, callback) end
+```
+
+### Writing files
+
+```lua
+---@param path string
+---@param content string
+local function write_file(path, content) end
+
+---@param path string
+---@param content string
+---@param callback? fun(err: string): nil
+local function write_file_async(path, content, callback) end
+```
+
+### Monitoring files
+
+```lua
+---@param path string
+---@param callback fun(file: string, event: Gio.FileMonitorEvent): nil
+local function monitor_file(path, callback) end
+```
+
+## Timeouts and Intervals
+
+```lua
+local interval = astal.interval
+local timeout = astal.timeout
+local idle = astal.idle
+```
+
+### Interval
+
+Will immediately execute the function and every `interval` millisecond.
+
+```lua
+---@param interval number
+---@param callback? function
+---@return Astal.Time
+local function interval(interval, callback) end
+```
+
+### Timeout
+
+Will execute the `callback` after `timeout` millisecond.
+
+```lua
+---@param timeout number
+---@param callback? function
+---@return Astal.Time
+local function timeout(timeout, callback) end
+```
+
+### Idle
+
+Executes `callback` whenever there are no higher priority events pending.
+
+```lua
+---@param callback? function
+---@return Astal.Time
+local function idle(callback) end
+```
+
+Example:
+
+```lua
+local timer = interval(1000, function()
+    print("optional callback")
+end)
+
+timer.on_now = function()
+    print("now")
+end
+
+timer.on_cancelled = function()
+    print("cancelled")
+end
+
+timer:cancel()
+```
+
+## Process functions
+
+```lua
+local subprocess = astal.subprocess
+local exec = astal.exec
+local exec_async = astal.exec_async
+```
+
+### Subprocess
+
+You can start a subprocess and run callback functions whenever it outputs to
+stdout or stderr. [Astal.Process](https://aylur.github.io/libastal/io/class.Process.html) has a `stdout` and `stderr` signal.
+
+```lua
+---@param commandline string | string[]
+---@param on_stdout? fun(out: string): nil
+---@param on_stderr? fun(err: string): nil
+---@return Astal.Process | nil
+local function subprocess(commandline, on_stdout, on_stderr) end
+```
+
+Example:
+
+```lua
+local proc = subprocess(
+    "some-command",
+    function(out) print(out) end,
+    function(err) print(err) end,
+)
+
+-- with signals
+local proc = subprocess("some-command")
+
+proc.on_stdout = function(_, stdout)
+    print(stdout)
+end
+
+proc.on_stderr = function(_, stderr)
+    print(stderr)
+end
+```
+
+### Executing external commands and scripts
+
+```lua
+---@param commandline string | string[]
+---@return string, string
+local function exec(commandline) end
+
+---@param commandline string | string[]
+---@param callback? fun(out: string, err: string): nil
+local function exec_async(commandline, callback) end
+```
+
+Example:
+
+```lua
+local out, err = exec("/path/to/script")
+
+if err ~= nil then
+    print(err)
+else
+    print(out)
+end
+
+exec_async({ "bash", "-c", "/path/to/script.sh" }, function(out, err)
+    if err ~= nil then
+        print(err)
+    else
+        print(out)
+    end
+end)
+```
+
+:::warning
+`subprocess`, `exec`, and `exec_async` executes the passed executable as is.
+They are **not** executed in a shell environment,
+they do **not** expand ENV variables like `$HOME`,
+and they do **not** handle logical operators like `&&` and `||`.
+
+If you want bash, run them with bash.
+
+```lua
+exec({ "bash", "-c", "command $VAR && command" })
+exec("bash -c 'command $VAR' && command")
+```
+
+:::