From 800af1021c67ffe0ddcaed37ab09179d33102e35 Mon Sep 17 00:00:00 2001 From: Aylur Date: Thu, 10 Oct 2024 15:11:46 +0000 Subject: docs: gobject, variable, binding page --- docs/guide/ags/variable.md | 72 +++++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 30 deletions(-) (limited to 'docs/guide/ags/variable.md') diff --git a/docs/guide/ags/variable.md b/docs/guide/ags/variable.md index 96e8d38..4207f61 100644 --- a/docs/guide/ags/variable.md +++ b/docs/guide/ags/variable.md @@ -4,17 +4,17 @@ import { Variable } from "astal" ``` -Variable is just a simple `GObject` that holds a value. -And has shortcuts for hooking up subprocesses. +Variable is just a simple object which holds a single value. +It also has some shortcuts for hooking up subprocesses, intervals and other gobjects. :::info The `Variable` object imported from the `"astal"` package is **not** [Astal.Variable](https://aylur.github.io/libastal/class.Variable.html). ::: -## Variable as state +## Example Usage ```typescript -const myvar = Variable("initial-value") +const myvar = Variable("initial-value") // whenever its value changes, callback will be executed myvar.subscribe((value: string) => { @@ -35,43 +35,49 @@ Widget.Label({ ``` :::warning -Make sure to make the transform functions pure. The `.get()` function can be called -anytime by `astal` especially when `deriving`, so make sure there are no sideeffects. +Make sure to make the transform functions passed to `.as()` are pure. +The `.get()` function can be called anytime by `astal` especially when `deriving`, +so make sure there are no sideeffects. ::: -## Composing variables +## Variable Composition -Using `Variable.derive` we can compose both Variables and Bindings. +Using `Variable.derive` any `Subscribable` object can be composed. ```typescript -const v1: Variable = Variable(2) -const v2: Variable = Variable(3) +const v1: Variable = Variable(1) +const v2: Binding = bind(obj, "prop") +const v3: Subscribable = { + get: () => 3, + subscribe: () => () => {}, +} // first argument is a list of dependencies // second argument is a transform function, // where the parameters are the values of the dependencies in the order they were passed -const v3: Variable = Variable.derive([v1, v2], (v1, v2) => { - return v1 * v2 -}) - -const b1: Binding = bind(obj, "prop") -const b2: Binding = bind(obj, "prop") - -const b3: Variable = Variable.derive([b1, b2], (b1, b2) => { - return `${b1}-${b2}` -}) +const v4: Variable = Variable.derive( + [v1, v2, v3], + (v1: number, v2: number, v3: number) => { + return v1 * v2 * v3 + } +) ``` +:::info +The types are only for demonstration purposes, you do not have to declare +the type of a Variable, they will be inferred from their initial value. +::: + ## Subprocess shorthands -Using `.poll` and `.watch` we can start subprocess and capture their -output in `Variables`. They can poll and watch at the same time, but they -can only poll/watch one subprocess. +Using `.poll` and `.watch` we can start subprocesses and capture their +output. They can poll and watch at the same time, but they +can only poll/watch once. :::warning The command parameter is passed to [execAsync](/guide/ags/utilities#executing-external-commands-and-scripts) which means they are **not** executed in a shell environment, -they do **not** expand env variables like `$HOME`, +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. @@ -83,14 +89,14 @@ Variable("").poll(1000, ["bash", "-c", "command $VAR && command"]) ::: ```typescript -const myVar = Variable(0) +const myVar = Variable(0) .poll(1000, "command", (out: string, prev: number) => parseInt(out)) .poll(1000, ["bash", "-c", "command"], (out, prev) => parseInt(out)) .poll(1000, (prev) => prev + 1) ``` ```typescript -const myVar = Variable(0) +const myVar = Variable(0) .watch("command", (out: string, prev: number) => parseInt(out)) .watch(["bash", "-c", "command"], (out, prev) => parseInt(out)) ``` @@ -127,14 +133,20 @@ myVar.drop() ``` :::warning -Don't forget to drop them when they are defined inside widgets -with either `.poll`, `.watch` or `.observe` +Don't forget to drop derived variables or variables with +either `.poll`, `.watch` or `.observe` when they are defined inside closures. ```tsx function MyWidget() { const myvar = Variable().poll() - - return myvar.drop()} /> + const derived = Variable.derive() + + return { + myvar.drop() + derived.drop() + }} + /> } ``` -- cgit v1.2.3 From ede8890a08b3fbbb1f6df3b8c277ab6424d1befd Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 15 Oct 2024 01:22:24 +0000 Subject: docs: better explain ags --- docs/guide/ags/variable.md | 153 --------------------------------------------- 1 file changed, 153 deletions(-) delete mode 100644 docs/guide/ags/variable.md (limited to 'docs/guide/ags/variable.md') diff --git a/docs/guide/ags/variable.md b/docs/guide/ags/variable.md deleted file mode 100644 index 4207f61..0000000 --- a/docs/guide/ags/variable.md +++ /dev/null @@ -1,153 +0,0 @@ -# Variable - -```js -import { Variable } from "astal" -``` - -Variable is just a simple object which holds a single value. -It also has some shortcuts for hooking up subprocesses, intervals and other gobjects. - -:::info -The `Variable` object imported from the `"astal"` package is **not** [Astal.Variable](https://aylur.github.io/libastal/class.Variable.html). -::: - -## Example Usage - -```typescript -const myvar = Variable("initial-value") - -// whenever its value changes, callback will be executed -myvar.subscribe((value: string) => { - console.log(value) -}) - -// settings its value -myvar.set("new value") - -// getting its value -const value = myvar.get() - -// binding them to widgets -Widget.Label({ - label: bind(myvar).as((value) => `transformed ${value}`), - label: myvar((value) => `transformed ${value}`), // shorthand for the above -}) -``` - -:::warning -Make sure to make the transform functions passed to `.as()` are pure. -The `.get()` function can be called anytime by `astal` especially when `deriving`, -so make sure there are no sideeffects. -::: - -## Variable Composition - -Using `Variable.derive` any `Subscribable` object can be composed. - -```typescript -const v1: Variable = Variable(1) -const v2: Binding = bind(obj, "prop") -const v3: Subscribable = { - get: () => 3, - subscribe: () => () => {}, -} - -// first argument is a list of dependencies -// second argument is a transform function, -// where the parameters are the values of the dependencies in the order they were passed -const v4: Variable = Variable.derive( - [v1, v2, v3], - (v1: number, v2: number, v3: number) => { - return v1 * v2 * v3 - } -) -``` - -:::info -The types are only for demonstration purposes, you do not have to declare -the type of a Variable, they will be inferred from their initial value. -::: - -## Subprocess shorthands - -Using `.poll` and `.watch` we can start subprocesses and capture their -output. They can poll and watch at the same time, but they -can only poll/watch once. - -:::warning -The command parameter is passed to [execAsync](/guide/ags/utilities#executing-external-commands-and-scripts) -which means 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. - -```js -Variable("").poll(1000, ["bash", "-c", "command $VAR && command"]) -``` - -::: - -```typescript -const myVar = Variable(0) - .poll(1000, "command", (out: string, prev: number) => parseInt(out)) - .poll(1000, ["bash", "-c", "command"], (out, prev) => parseInt(out)) - .poll(1000, (prev) => prev + 1) -``` - -```typescript -const myVar = Variable(0) - .watch("command", (out: string, prev: number) => parseInt(out)) - .watch(["bash", "-c", "command"], (out, prev) => parseInt(out)) -``` - -You can temporarily stop them and restart them whenever. - -```js -myvar.stopWatch() // this kills the subprocess -myvar.stopPoll() - -myvar.startListen() // launches the subprocess again -myvar.startPoll() - -console.log(myvar.isListening()) -console.log(myvar.isPolling()) -``` - -## Gobject connection shorthands - -Using `.observe` you can connect gobject signals and capture their value. - -```typescript -const myvar = Variable("") - .observe(obj1, "signal", () => "") - .observe(obj2, "signal", () => "") -``` - -## Dispose if no longer needed - -This will stop the interval and force exit the subprocess and disconnect gobjects. - -```js -myVar.drop() -``` - -:::warning -Don't forget to drop derived variables or variables with -either `.poll`, `.watch` or `.observe` when they are defined inside closures. - -```tsx -function MyWidget() { - const myvar = Variable().poll() - const derived = Variable.derive() - - return { - myvar.drop() - derived.drop() - }} - /> -} -``` - -::: -- cgit v1.2.3