Utilities

File functions

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

---@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

---@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

---@param path string
---@param callback fun(file: string, event: Gio.FileMonitorEvent): nil
local function monitor_file(path, callback) end

Timeouts and Intervals

local interval = astal.interval
local timeout = astal.timeout
local idle = astal.idle

Interval

Will immediately execute the function and every interval millisecond.

---@param interval number
---@param callback? function
---@return Astal.Time
local function interval(interval, callback) end

Timeout

Will execute the callback after timeout millisecond.

---@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.

---@param callback? function
---@return Astal.Time
local function idle(callback) end

Example:

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

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 has a stdout and stderr signal.

---@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:

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

---@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:

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.

exec({ "bash", "-c", "command $VAR && command" })
exec("bash -c 'command $VAR' && command")