summaryrefslogtreecommitdiff
path: root/docs/guide/ags/utilities.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guide/ags/utilities.md')
-rw-r--r--docs/guide/ags/utilities.md174
1 files changed, 0 insertions, 174 deletions
diff --git a/docs/guide/ags/utilities.md b/docs/guide/ags/utilities.md
deleted file mode 100644
index 42589d3..0000000
--- a/docs/guide/ags/utilities.md
+++ /dev/null
@@ -1,174 +0,0 @@
-# Utilities
-
-## File functions
-
-Import them from `astal` or `astal/file`
-
-```ts
-import {
- readFile,
- readFileAsync,
- writeFile,
- writeFileAsync,
- monitorFile,
-} from "astal"
-```
-
-### Reading files
-
-```ts
-function readFile(path: string): string
-function readFileAsync(path: string): Promise<string>
-```
-
-### Writing files
-
-```ts
-function writeFile(path: string, content: string): void
-function writeFileAsync(path: string, content: string): Promise<void>
-```
-
-### Monitoring files
-
-```ts
-function monitorFile(
- path: string,
- callback: (file: string, event: Gio.FileMonitorEvent) => void,
-): Gio.FileMonitor
-```
-
-## Timeouts and Intervals
-
-Import them from `astal` or `astal/time`
-
-```ts
-import { interval, timeout, idle } from "astal"
-```
-
-You can use javascript native `setTimeout` or `setInterval`
-they return a [GLib.Source](https://docs.gtk.org/glib/struct.Source.html) instance.
-Alternatively you can use these functions provided by Astal,
-which return an [Astal.Time](https://aylur.github.io/libastal/class.Time.html) instance.
-
-`Astal.Time` has a `now` signal and a `cancelled` signal.
-
-### Interval
-
-Will immediately execute the function and every `interval` millisecond.
-
-```ts
-function interval(interval: number, callback?: () => void): Astal.Time
-```
-
-### Timeout
-
-Will execute the `callback` after `timeout` millisecond.
-
-```ts
-function timeout(timeout: number, callback?: () => void): Astal.Time
-```
-
-### Idle
-
-Executes `callback` whenever there are no higher priority events pending.
-
-```ts
-function idle(callback?: () => void): Astal.Time
-```
-
-Example:
-
-```ts
-const timer = interval(1000, () => {
- console.log("optional callback")
-})
-
-timer.connect("now", () => {
- console.log("tick")
-})
-
-timer.connect("cancelled", () => {
- console.log("cancelled")
-})
-
-timer.cancel()
-```
-
-## Process functions
-
-Import them from `astal` or `astal/proc`
-
-```ts
-import { subprocess, exec, execAsync } from "astal"
-```
-
-### Subprocess
-
-You can start a subprocess and run callback functions whenever it outputs to
-stdout or stderr. [Astal.Process](https://aylur.github.io/libastal/class.Process.html) has a `stdout` and `stderr` signal.
-
-```ts
-function subprocess(args: {
- cmd: string | string[]
- out?: (stdout: string) => void
- err?: (stderr: string) => void
-}): Astal.Process
-
-function subprocess(
- cmd: string | string[],
- onOut?: (stdout: string) => void,
- onErr?: (stderr: string) => void,
-): Astal.Process
-```
-
-Example:
-
-```ts
-const proc = subprocess(
- "some-command",
- (out) => console.log(out), // optional
- (err) => console.error(out), // optional
-)
-
-// or with signals
-const proc = subprocess("some-command")
-proc.connect("stdout", (out) => console.log(out))
-proc.connect("stderr", (err) => console.error(err))
-```
-
-### Executing external commands and scripts
-
-```ts
-function exec(cmd: string | string[]): string
-function execAsync(cmd: string | string[]): Promise<string>
-```
-
-Example:
-
-```ts
-try {
- const out = exec("/path/to/script")
- console.log(out)
-} catch (err) {
- console.error(err)
-}
-
-execAsync(["bash", "-c", "/path/to/script.sh"])
- .then((out) => console.log(out))
- .catch((err) => console.error(err))
-```
-
-:::warning
-`subprocess`, `exec`, and `execAsync` 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.
-
-```ts
-exec(["bash", "-c", "command $VAR && command"])
-exec("bash -c 'command $VAR' && command")
-```
-
-:::