mirror of
https://github.com/zoriya/astal.git
synced 2026-06-03 10:26:21 +00:00
docs: utilities
This commit is contained in:
Aylur
+12
-13
@@ -1,32 +1,31 @@
|
||||
import { Astal } from "./imports.js"
|
||||
|
||||
type Args<Out = void, Err = void> = {
|
||||
type Args = {
|
||||
cmd: string | string[]
|
||||
out?: (stdout: string) => Out
|
||||
err?: (stderr: string) => Err
|
||||
}
|
||||
|
||||
function args<O, E>(argsOrCmd: Args | string | string[], onOut: O, onErr: E) {
|
||||
const params = Array.isArray(argsOrCmd) || typeof argsOrCmd === "string"
|
||||
return {
|
||||
cmd: params ? argsOrCmd : argsOrCmd.cmd,
|
||||
err: params ? onErr : argsOrCmd.err || onErr,
|
||||
out: params ? onOut : argsOrCmd.out || onOut,
|
||||
}
|
||||
out?: (stdout: string) => void
|
||||
err?: (stderr: string) => void
|
||||
}
|
||||
|
||||
export function subprocess(args: Args): Astal.Process
|
||||
|
||||
export function subprocess(
|
||||
cmd: string | string[],
|
||||
onOut?: (stdout: string) => void,
|
||||
onErr?: (stderr: string) => void,
|
||||
): Astal.Process
|
||||
|
||||
export function subprocess(
|
||||
argsOrCmd: Args | string | string[],
|
||||
onOut: (stdout: string) => void = print,
|
||||
onErr: (stderr: string) => void = printerr,
|
||||
) {
|
||||
const { cmd, err, out } = args(argsOrCmd, onOut, onErr)
|
||||
const args = Array.isArray(argsOrCmd) || typeof argsOrCmd === "string"
|
||||
const { cmd, err, out } = {
|
||||
cmd: args ? argsOrCmd : argsOrCmd.cmd,
|
||||
err: args ? onErr : argsOrCmd.err || onErr,
|
||||
out: args ? onOut : argsOrCmd.out || onOut,
|
||||
}
|
||||
|
||||
const proc = Array.isArray(cmd)
|
||||
? Astal.Process.subprocessv(cmd)
|
||||
: Astal.Process.subprocess(cmd)
|
||||
|
||||
@@ -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")
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
@@ -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>
|
||||
|
||||
Reference in New Issue
Block a user