docs: lua docs (#50)

1 files changed, 162 insertions, 0 deletions

diff --git a/docs/guide/lua/variable.md b/docs/guide/lua/variable.md
new file mode 100644
index 0000000..915632c
--- /dev/null
+++ b/docs/guide/lua/variable.md
@@ -0,0 +1,162 @@
+# Variable
+
+```lua
+local Variable = require("astal").Variable
+local Variable = require("astal.variable")
+```
+
+Variable is just a simple object which holds a single value.
+It also has some shortcuts for hooking up subprocesses, intervals and other gobjects.
+
+## Example Usage
+
+```lua
+local my_var = Variable("initial-value")
+
+-- whenever its value changes, callback will be executed
+my_var:subscribe(function(value)
+    print(value)
+end)
+
+-- settings its value
+my_var:set("new value")
+
+-- getting its value
+local value = my_var:get()
+
+-- binding them to widgets
+Widget.Label({
+    label = bind(my_var):as(function(value)
+        return string.format("transformed %s", value)
+    end),
+    -- shorthand for the above
+    label = my_var(function(value)
+        return string.format("transformed %s", value)
+    end)
+})
+```
+
+:::warning
+Make sure to the transform functions you pass 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.
+
+```lua
+local v1 = Variable(1) -- Variable
+local v2 = bind(obj, "prop") -- Binding
+local v3 = { -- Subscribable
+    get = function()
+        return 3
+    end,
+    subscribe = function()
+        return function() end
+    end,
+}
+
+-- 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
+local v4 = Variable.derive({ v1, v2, v3 }, function(v1, v2, v3)
+    return v1 * v2 * v3
+end)
+```
+
+## Subprocess shorthands
+
+Using `:poll` and `:watch` you 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 [exec_async](/guide/lua/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.
+
+```lua
+Variable(""):poll(1000, { "bash", "-c", "command $VAR && command" })
+```
+
+:::
+
+```lua
+local my_var = Variable(0)
+    :poll(1000, "command", function(out, prev)
+        return tonumber(out)
+    end)
+    :poll(1000, { "bash", "-c", "command" }, function(out, prev)
+        return tonumber(out)
+    end)
+    :poll(1000, function(prev)
+        return prev + 1
+    end)
+```
+
+```lua
+local my_var = Variable(0)
+    :watch("command", function(out, prev)
+        return tonumber(out)
+    end)
+    :watch({ "bash", "-c", "command" }, function(out, prev)
+        return tonumber(out)
+    end)
+```
+
+You can temporarily stop them and restart them whenever.
+
+```lua
+my_var:stop_watch() -- this kills the subprocess
+my_var:stop_poll()
+
+my_var:start_listen() -- launches the subprocess again
+my_var:start_poll()
+
+print(my_var:is_listening())
+print(my_var:is_polling())
+```
+
+## Gobject connection shorthands
+
+Using `:observe` you can connect gobject signals and capture their value.
+
+```lua
+local my_var = Variable("")
+    :observe(obj1, "signal", function()
+        return ""
+    end):observe(obj2, "signal", function()
+        return ""
+    end)
+```
+
+## Dispose if no longer needed
+
+This will stop the interval, force exit the subprocess and disconnect gobjects.
+
+```lua
+my_var:drop()
+```
+
+:::warning
+Don't forget to drop derived variables or variables with
+either `:poll`, `:watch` or `:observe` when they are defined inside closures.
+
+```lua
+local function MyWidget()
+    local my_var = Variable():poll()
+
+    return Widget.Box({
+        on_destroy = function()
+            my_var:drop()
+        end
+    })
+end
+```
+
+:::