1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
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")
```
:::
|
