ajet/clojure-tui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Adam Jeniski
2026-01-22 10:50:26 -05:00
parent 95b53f7533
commit 0e40fe01d7
14 changed files with 57 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference.md
+5 -63
View File
@@ -4,8 +4,7 @@ Complete API documentation for Clojure TUI.
## Table of Contents
- [tui.core](#tuicore) - Full async runtime
- [tui.simple](#tuisimple) - Sync runtime (Babashka)
- [tui.core](#tuicore) - Main runtime
- [tui.render](#tuirender) - Hiccup rendering
- [tui.input](#tuiinput) - Key input parsing
- [tui.terminal](#tuiterminal) - Terminal control
@@ -15,7 +14,7 @@ Complete API documentation for Clojure TUI.
## tui.core
Full-featured async runtime using core.async. Use this when you need timers, async commands, or background operations.
Main runtime using core.async. Provides timers, async commands, background operations, and responsive layout support.
### run
@@ -31,7 +30,7 @@ Run a TUI application synchronously (blocks until quit).
|-----|------|----------|-------------|
| `:init` | any | Yes | Initial model value |
| `:update` | function | Yes | `(fn [model msg] [new-model cmd])` |
| `:view` | function | Yes | `(fn [model] hiccup)` |
| `:view` | function | Yes | `(fn [model size] hiccup)` where size is `{:width w :height h}` |
| `:init-cmd` | command | No | Initial command to execute |
| `:fps` | integer | No | Frames per second (default: 60) |
| `:alt-screen` | boolean | No | Use alternate screen (default: true) |
@@ -48,7 +47,7 @@ Run a TUI application synchronously (blocks until quit).
(if (tui/key= msg "q")
[model tui/quit]
[model nil]))
:view (fn [{:keys [count]}]
:view (fn [{:keys [count]} _size]
[:text (str "Count: " count)])
:fps 30
:alt-screen true})
@@ -238,62 +237,6 @@ Re-exported from `tui.render`. Render hiccup to ANSI string.
---
## tui.simple
Synchronous runtime compatible with Babashka. Same API as `tui.core` but without async commands.
### run
```clojure
(run options)
```
Run a TUI application synchronously.
**Parameters:**
| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `:init` | any | Yes | Initial model value |
| `:update` | function | Yes | `(fn [model msg] [new-model cmd])` |
| `:view` | function | Yes | `(fn [model] hiccup)` |
| `:alt-screen` | boolean | No | Use alternate screen (default: true) |
**Returns:** Final model value after quit
**Example:**
```clojure
(require '[tui.simple :as tui])
(tui/run {:init 0
:update (fn [model msg]
(cond
(tui/key= msg "q") [model tui/quit]
(tui/key= msg "k") [(inc model) nil]
:else [model nil]))
:view (fn [count]
[:text (str "Count: " count)])})
```
### quit
Same as `tui.core/quit`.
### key=
Same as `tui.core/key=`.
### key-str
Same as `tui.core/key-str`.
### render
Re-exported from `tui.render`.
---
## tui.render
Converts hiccup data structures to ANSI-formatted strings.
@@ -715,8 +658,7 @@ The function must:
| Namespace | Purpose |
|-----------|---------|
| `tui.core` | Full async runtime with all features |
| `tui.simple` | Sync runtime for Babashka |
| `tui.core` | Main runtime with Elm architecture and async commands |
| `tui.render` | Hiccup to ANSI rendering |
| `tui.input` | Key input parsing |
| `tui.terminal` | Low-level terminal control |
docs/examples.md
+4 -4
View File
@@ -5,7 +5,7 @@ Detailed walkthroughs of the example applications included with Clojure TUI.
## Running Examples
```bash
# With Babashka (simple sync runtime)
# With Babashka (recommended - fast startup)
bb counter
bb timer
bb list
@@ -13,7 +13,7 @@ bb spinner
bb views
bb http
# With Clojure (full async support)
# With full Clojure
clojure -A:dev -M -m examples.counter
clojure -A:dev -M -m examples.timer
clojure -A:dev -M -m examples.list-selection
@@ -263,7 +263,7 @@ A multi-select list demonstrating cursor navigation and selection.
```clojure
(ns examples.list-selection
(:require [tui.simple :as tui]))
(:require [tui.core :as tui]))
(def items
["Apple" "Banana" "Cherry" "Date" "Elderberry"
@@ -519,7 +519,7 @@ A multi-view application demonstrating state machine navigation.
```clojure
(ns examples.views
(:require [tui.simple :as tui]))
(:require [tui.core :as tui]))
(def menu-items
[{:id :profile :label "View Profile" :desc "See your user information"}
docs/getting-started.md
+10 -27
View File
@@ -14,8 +14,7 @@ Add the library to your `deps.edn`:
### Requirements
- **Clojure 1.11+** for full async runtime (`tui.core`)
- **Babashka** for simple sync runtime (`tui.simple`)
- **Babashka** (recommended) or **Clojure 1.11+**
- A terminal that supports ANSI escape codes (most modern terminals)
## Your First Application
@@ -41,7 +40,7 @@ Create `src/myapp/core.clj`:
```clojure
(ns myapp.core
(:require [tui.simple :as tui]))
(:require [tui.core :as tui]))
;; 1. Model - the application state
(def initial-model
@@ -58,8 +57,8 @@ Create `src/myapp/core.clj`:
:else
[model nil]))
;; 3. View - render the model as hiccup
(defn view [{:keys [message]}]
;; 3. View - render the model as hiccup (receives model and terminal size)
(defn view [{:keys [message]} _size]
[:col
[:text {:fg :cyan :bold true} message]
[:space {:height 1}]
@@ -120,7 +119,7 @@ Clojure TUI uses the [Elm Architecture](https://guide.elm-lang.org/architecture/
2. **Update**: A pure function that takes the current model and a message, returning a vector of `[new-model command]`.
3. **View**: A pure function that takes the model and returns a hiccup data structure representing the UI.
3. **View**: A pure function that takes the model and terminal size, returning a hiccup data structure representing the UI.
### The Flow
@@ -198,7 +197,7 @@ Let's build something more interactive: a counter.
```clojure
(ns myapp.counter
(:require [tui.simple :as tui]))
(:require [tui.core :as tui]))
(defn update-fn [model msg]
(cond
@@ -220,7 +219,7 @@ Let's build something more interactive: a counter.
:else [model nil]))
(defn view [count]
(defn view [count _size]
[:col
[:box {:border :rounded :padding [0 2]}
[:row
@@ -315,7 +314,7 @@ Commands are returned as the second element of the update function's return vect
:else
[model nil]))
(defn view [{:keys [count done]}]
(defn view [{:keys [count done]} _size]
[:col
(if done
[:text {:fg :green :bold true} "Time's up!"]
@@ -329,22 +328,6 @@ Commands are returned as the second element of the update function's return vect
:init-cmd (tui/tick 1000)})) ;; Start first tick
```
## Choosing a Runtime
### `tui.simple` - For Babashka and Simple Apps
- Works with Babashka
- Synchronous (blocking) input
- No async commands (tick, batch, etc.)
- Lower resource usage
### `tui.core` - For Complex Applications
- Requires full Clojure with core.async
- Async input handling
- Full command support (tick, batch, sequentially)
- Better for animations and background tasks
## Configuration Options
The `run` function accepts these options:
@@ -353,9 +336,9 @@ The `run` function accepts these options:
|--------|-------------|---------|
| `:init` | Initial model (required) | - |
| `:update` | Update function (required) | - |
| `:view` | View function (required) | - |
| `:view` | View function `(fn [model size] hiccup)` (required) | - |
| `:init-cmd` | Initial command to run | `nil` |
| `:fps` | Frames per second (core only) | `60` |
| `:fps` | Frames per second | `60` |
| `:alt-screen` | Use alternate screen buffer | `true` |
### Alternate Screen