docs: utilities

2 files changed, 224 insertions, 53 deletions

diff --git a/docs/src/content/docs/ags/utilities.md b/docs/src/content/docs/ags/utilities.md
index 7c03f50..df5e490 100644
--- a/docs/src/content/docs/ags/utilities.md
+++ b/docs/src/content/docs/ags/utilities.md
@@ -2,7 +2,178 @@
 title: Utilities
 description: Reference of bultin utility functions
 sidebar:
-  order: 5
+    order: 5
 ---
 
-## TODO:
+## File functions
+
+Import them from `astal` or `astal/file`
+
+```js
+import {
+    readFile,
+    readFileAsync,
+    writeFile,
+    writeFileAsync,
+    monitorFile,
+} from "astal"
+```
+
+### Reading files
+
+```typescript
+function readFile(path: string): string
+function readFileAsync(path: string): Promise<string>
+```
+
+### Writing files
+
+```typescript
+function writeFile(path: string, content: string): void
+function writeFileAsync(path: string, content: string): Promise<void>
+```
+
+### Monitoring files
+
+```typescript
+function monitorFile(
+    path: string,
+    callback: (file: string, event: Gio.FileMonitorEvent) => void,
+): Gio.FileMonitor
+```
+
+## Timeouts and Intervals
+
+Import them from `astal` or `astal/time`
+
+```js
+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]() instance.
+
+`Astal.Time` has a `now` signal and a `cancelled` signal.
+
+### Interval
+
+Will immediately execute the function and every `interval` millisecond.
+
+```typescript
+function interval(interval: number, callback?: () => void): Astal.Time
+```
+
+### Timeout
+
+Will execute the `callback` after `timeout` millisecond.
+
+```typescript
+function timeout(timeout: number, callback?: () => void): Astal.Time
+```
+
+### Idle
+
+Executes `callback` whenever there are no higher priority events pending.
+
+```typescript
+function idle(callback?: () => void): Astal.Time
+```
+
+Example:
+
+```typescript
+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`
+
+```js
+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]() has a `stdout` and `stderr` signal.
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+function exec(cmd: string | string[]): string
+function execAsync(cmd: string | string[]): Promise<string>
+```
+
+Example:
+
+```typescript
+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))
+```
+
+:::caution
+`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 to run bash, run them with bash.
+
+```js
+exec(["bash", "-c", "command $VAR && command"])
+exec("bash -c 'command $VAR' && command")
+```
+
+:::
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 17cb867..602662d 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -3,65 +3,65 @@ title: Build Your Own Desktop Shell
 description: The best way to make beautiful and functional widgets on wayland
 template: splash
 banner:
-  content: |
-    🚧 The library and this documentation is still under development. 🚧
+    content: 🚧 The library and this documentation is still under development. 🚧
 hero:
-  tagline: The best way to make <i>beautiful</i> <b>and</b> <i>functional</i> wayland widgets!
-  image:
-    file: ../../assets/front-image.png
-  actions:
-    - text: Get Started
-      link: /astal/getting-started/introduction/
-      icon: right-arrow
-      variant: primary
-    - text: Reference
-      link: /astal/reference/references
-      icon: open-book
-      variant: secondary
-    - text: View on GitHub
-      link: https://github.com/Aylur/Astal
-      icon: github
-      variant: minimal
+    tagline: The best way to make <i>beautiful</i> <b>and</b> <i>functional</i> wayland widgets!
+    image:
+        file: ../../assets/front-image.png
+    actions:
+        - text: Get Started
+          link: /astal/getting-started/introduction/
+          icon: right-arrow
+          variant: primary
+        - text: Reference
+          link: /astal/reference/references
+          icon: open-book
+          variant: secondary
+        - text: View on GitHub
+          link: https://github.com/Aylur/Astal
+          icon: github
+          variant: minimal
 ---
 
-import { Card, CardGrid } from "@astrojs/starlight/components";
-import { showcases } from "../showcases.ts";
-import Showcase from "../../components/Showcase.astro";
+import { Card, CardGrid } from "@astrojs/starlight/components"
+import { showcases } from "../showcases.ts"
+import Showcase from "../../components/Showcase.astro"
 
 <CardGrid>
-  <Card title="Use your preferred language" icon="seti:json">
-    The main focus of Astal is TypeScript using JSX. But you can use the
-    libraries in any language that supports [Gobject
-    Introspection](https://en.wikipedia.org/wiki/List_of_language_bindings_for_GTK).
-  </Card>
-  <Card title="No bash scripts needed" icon="pencil">
-    Includes modules to work with Network, Bluetooth, Battery, Audio and more.
-    See the list of included [Libraries](./libraries/overview).
-  </Card>
-  <Card title="Use any Gtk widget" icon="puzzle">
-    With Astal you work with Gtk directly. You are not limited to only a set of
-    them. See the list of [Widgets](./libraries/widgets) that come bundled.
-  </Card>
-  <Card title="Examples" icon="open-book">
-    Have a look at some simple and not simple [examples](./config/examples). In
-    [TypeScript](https://github.com/Aylur/Astal/tree/main/examples/ts),
-    [Lua](https://github.com/Aylur/Astal/tree/main/examples/lua),
-    [Python](https://github.com/Aylur/Astal/tree/main/examples/python).
-  </Card>
+    <Card title="Use your preferred language" icon="seti:json">
+        The main focus of Astal is TypeScript using JSX. But you can use the
+        libraries in any language that supports [Gobject
+        Introspection](https://en.wikipedia.org/wiki/List_of_language_bindings_for_GTK).
+    </Card>
+    <Card title="No bash scripts needed" icon="pencil">
+        Includes modules to work with Network, Bluetooth, Battery, Audio and
+        more. See the list of included [Libraries](/astal/libraries/overview).
+    </Card>
+    <Card title="Use any Gtk widget" icon="puzzle">
+        With Astal you work with Gtk directly. You are not limited to only a set
+        of them. See the list of [Widgets](/astal/libraries/widgets) that come
+        bundled.
+    </Card>
+    <Card title="Examples" icon="open-book">
+        Have a look at some simple and not simple [examples](./config/examples).
+        In [TypeScript](https://github.com/Aylur/Astal/tree/main/examples/ts),
+        [Lua](https://github.com/Aylur/Astal/tree/main/examples/lua),
+        [Python](https://github.com/Aylur/Astal/tree/main/examples/python).
+    </Card>
 </CardGrid>
 
 ## Showcases
 
 <div class="showcases">
-  {showcases.map((showcase) =>
-    Array.isArray(showcase) ? (
-      <CardGrid>
-        {showcase.map((elem) => (
-          <Showcase {...elem} />
-        ))}
-      </CardGrid>
-    ) : (
-      <Showcase {...showcase} />
-    )
-  )}
+    {showcases.map((showcase) =>
+        Array.isArray(showcase) ? (
+            <CardGrid>
+                {showcase.map((elem) => (
+                    <Showcase {...elem} />
+                ))}
+            </CardGrid>
+        ) : (
+            <Showcase {...showcase} />
+        ),
+    )}
 </div>