# Deft Deft is a TCL-meets-Clojure programming language. It pairs TCL's shell-friendly command syntax with Clojure's data abstractions: immutable persistent data structures, lazy sequences, transducers, protocols, and a rich functional core. The runtime is written in Zig and compiles to a single self-contained binary with no external dependencies. Scripts are parsed to S-expressions, compiled to bytecode, and executed on a stack-based VM with tail-call optimisation. ## A 60-Second Tour

 # Three call forms — pick the one that reads best in context
set name "Alice"
echo "hello $name"                    # bare (top-level statement)
set length $name(len)                 # postfix (single-arg on a variable)
set mid $name(1..3)                   # postfix range slice — chars 1..2
set total ($price * $quantity)        # infix (arithmetic / comparison)

# Pipelines thread a value through a chain

def numbers @{ 1 2 3 4 5 }
def even? {|x^number| [mod $x 2] == 0 }
$numbers |> [filter even?] |> map { $it * 2 } |> collect
# => @{ 4 8 }

# Persistent data: lists, maps, sets, tagged maps
def user %User{ name "Alice" roles ^{:admin :user} }

# Pattern matching
match $user~roles {
    %{ :admin } => "is admin"
    _           => "is not admin"
}

# Protocols and types
deftype Point %{ :x %{} :y %{} }

defimpl Point Drawable {
    draw {|ctx bounds|
        @doc "Draw a point at (x, y)"
        [draw/cell $ctx $self~x $self~y "*"]
    }
}

## Highlights - **TCL command syntax** — `[echo "hello"]`, or top level `echo "hello"` - **Infix expressions in parens** — `($a + $b)`, `($n == 0)` - **Postfix sugar on values** — `$str(trim)`, `$items(first)`, `$m~field` - **Range slicing** — `"string"(0..1)`, `$list(2..5)`, `$xs(1..)` — postfix slices of strings and collections - **Immutable persistent collections** — lists `@{}`, maps `%{}`, sets `^{}` - **Lazy sequences & transducers** — Clojure-style `map`/`filter`/`take`/`comp`/`into`/`transduce` - **Pattern matching** — `match`, type patterns, guards, or-patterns, ranges, regex - **User types & protocols** — `deftype`, `defprotocol`, `defimpl`, `defmethod` - **Coroutines & async tasks** — `defcoro` + `spawn`/`vwait`, `deftask` + `await`, `defworker` + `worker/send` - **Macros** — Elixir-style `defmacro` with `quote`/`unquote` - **Native FFI** — load shared libraries, call C functions (build with `-Dffi=true`) - **Batteries included** — HTTP client/server, SQLite, JSON/YAML, TCP/UDP, regex, crypto ## Performance The bytecode VM is competitive with Python on most workloads and faster than TCL on tight numeric loops. Tail calls are compiled to in-place loops so recursive idioms are safe at any depth. Locals are indexed slots — no hashmap lookup per variable access. ## Hosts The same binary drives three runtime modes: - **`deft`** — the scripting binary and REPL. Runs `.dft` files, exposes the full standard library, and serves as the entry point for tests, formatting, and the package manager. - **`retro`** — a panelised development environment (editor, git, file manager, terminal, AI chat, system monitor). Inspired by Emacs and Blender. Uses a native rendering backend. - **`retra`** — functionally identical to `retro` but pure ANSI, so it works over bare SSH. All TUI apps are written in Deft itself, and the same script API is available in every host. Platform-layer stdlib functions (`pub/*`, `config/*`, `runtime/*`, `sqlite/*`, `dialog/*`) work identically across all three. ## App Platform Each Deft app is loaded from its own directory, runs in its own OS thread, and owns an isolated runtime with its own VM and heap. Apps communicate through: - **`pub/*`** — broadcast topic-based events to any subscriber, in any runtime. - **`@rpc`** + **`rpc`** — type-safe direct calls to functions exposed by another runtime, addressed by runtime name. Available in every host. - **`config/*`** — a shared, persistent, reactive key/value store. - **`runtime/*`** — spawn and interact with child runtimes. The app launcher is itself a Deft app, so you can replace or extend it to load your own tools. ## Platforms Currently supported: - Linux (x86_64, aarch64) - Raspberry Pi The Zig codebase means macOS and Windows ports should follow with modest effort; they are on the roadmap but not yet shipped. ## Where To Go Next | If you want to... | Read | |---|---| | Get the feel of the language | [Syntax and Style](00-syntax-and-style.md) | | Run your first script | [Shell Scripting](shell-scripting) | | Understand the type system | [Types and Protocols](types-and-protocols) | | See the full stdlib function catalogue | [Stdlib](stdlib) | | Build a TUI app | [TUI Overview](tui-overview) | | Make apps talk to each other | [Pubsub](pubsub), [RPC](rpc) | | Embed SQLite | [SQLite](sqlite) | | Call C libraries | [FFI](ffi) | | Embed Deft in a host app | [Embedding](embedding) | | Understand the VM's memory model | [Memory Management](memory-management) | | Understand how text/fonts render in the TUI | [Font Rendering](font-rendering) | | Understand string indexing, widths, and bytes | [String Representation](string-representation) |

Documentation