Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

cargo teksilo-fmt — formatter for teksu! blocks

rustfmt treats macro bodies as opaque token streams and won't descend into a teksu!(...) invocation, so the DSL inside is hand-formatted by default. cargo teksilo-fmt fills the gap: it walks Rust source files, finds every teksu! invocation, reformats the body, and writes the file back in place. Source outside teksu! blocks is byte-for-byte unchanged — cargo fmt still owns Rust formatting.

For the surface language the formatter normalizes, see teksu-macro-reference.md.

Installation

The crate ships in this workspace under crates/cargo-teksilo-fmt. Install it with:

cargo install --path crates/cargo-teksilo-fmt

cargo install puts the binary in ~/.cargo/bin/cargo-teksilo-fmt, which Cargo picks up as the cargo teksilo-fmt subcommand from any directory. Verify with:

cargo teksilo-fmt --version

To uninstall: cargo uninstall cargo-teksilo-fmt.

Usage

cargo teksilo-fmt [OPTIONS] [paths...]

OPTIONS:
    --check                 Read-only; exit 1 if any file would change
    --quiet, -q             Suppress per-file output
    --help, -h              Print help
    --version, -V           Print version

POSITIONAL:
    paths                   Files or directories to format. Directories
                            are walked recursively for *.rs, skipping
                            target/ and hidden directories. Defaults to
                            the current directory.

Examples:

cargo teksilo-fmt                              # format from CWD
cargo teksilo-fmt --check                      # CI mode: exit 1 if dirty
cargo teksilo-fmt examples/widget_catalog      # format one example
cargo teksilo-fmt src/main.rs src/build.rs     # format specific files

Files containing no teksu! token are skipped before parsing — there's no measurable cost on a workspace where most modules don't use the DSL.

Writes are atomic: the formatted output goes into a sibling NamedTempFile and is renamed into place. An interrupted run never leaves a truncated source file on disk.

What gets normalized

The formatter rewrites the shape of teksu! bodies. Rust expressions inside (property values, positional args, closure bodies, escape exprs, rust { … } blocks) are spliced verbatim from source — the formatter does not reformat Rust.

Layout rules (v1):

  • 4-space indent per nesting level.
  • Elements with a non-empty body span multiple lines: Type(args) {\n <items>\n}.
  • Elements with no body or with an empty {} body emit on one line without braces: Divider { } → Divider.
  • One body item per line. Properties keep name: value shape.
  • Property order is preserved verbatim. The macro lowering reorders handler properties (on_tap, cursor, …) to the end of the chain at compile time; that's a lowering concern, not the formatter's, so what you wrote is what you get back.
  • The ctx => <element> preamble joins to the root element on the same line: teksu!(ctx =>\n VStack { … }) becomes teksu!(ctx => VStack { … }).
  • Continuation lines are aligned to where the user already had the body's outermost } in source — the closing brace of the reformatted output lands at the same column.

Trivia preservation

Comments and blank lines between body items survive a reformat.

#![allow(unused)]
fn main() {
// before
teksu!(ctx =>
    VStack {
        spacing: 12.0
        // user-added section header
        Button(lit!("Save"))

        Button(lit!("Cancel"))
    }
)

// after — unchanged
teksu!(ctx =>
    VStack {
        spacing: 12.0
        // user-added section header
        Button(lit!("Save"))

        Button(lit!("Cancel"))
    }
)
}

How it works: syn::ParseStream discards comments before they reach the IR, so the formatter runs a separate pass over the original TokenStream using proc_macro2::Span::byte_range() to record the inter-token gaps in source. The pretty-printer then drains that table by byte offset, emitting each comment / blank-line marker at the right indent level before the next body item.

Multiple consecutive blank lines collapse to a single blank line.

Comments inside Rust expressions (e.g. Button(/* note */ lit!("ok"))) are preserved automatically because expression values are sliced verbatim from source — they ride along with the rest of the slice.

CI integration

Use --check to fail the build when any file would be reformatted:

# .github/workflows/lint.yml (or equivalent)
- name: teksilo-fmt
  run: cargo teksilo-fmt --check

--check is read-only, prints Would reformat: <path> for each dirty file, and exits 1 if any.

For a pre-commit hook, run without --check:

# .git/hooks/pre-commit
cargo teksilo-fmt --quiet
git add -u

Library API

The CLI is a thin wrapper around the teksilo-fmt library crate. Editor integrations can call into it directly:

#![allow(unused)]
fn main() {
use teksilo_fmt::{format_block, format_file, FmtConfig, FmtError};

// Format a single teksu! body string (the contents inside the macro parens):
let cfg = FmtConfig::default();
let formatted = format_block("ctx => VStack { spacing: 8.0 }", &cfg)?;

// Format every teksu! invocation in a Rust file's source:
let new_source = format_file(&source_text, &cfg)?;
}

Both functions are pure: they take a &str and return a String. There's no I/O at the library level. format_file detects the host file's line ending convention (LF or CRLF) and applies it to every newline the formatter emits, so a CRLF file round-trips as CRLF.

FmtConfig is empty in v1 — every invocation produces canonical output. Style knobs may be added later; defaults will not change for existing invocations.

Editor integration (LSP)

The teksilo-fmt-lsp crate ships a minimal Language Server Protocol server that wraps the formatter. Install:

cargo install --path crates/teksilo-fmt-lsp

The server speaks JSON-RPC over stdio and advertises a single capability: documentFormattingProvider. Wire it into your editor as a secondary formatter for Rust files (rust-analyzer stays your primary).

Helix

# ~/.config/helix/languages.toml
[language-server.teksilo-fmt-lsp]
command = "teksilo-fmt-lsp"

[[language]]
name = "rust"
language-servers = [{ name = "rust-analyzer" }, { name = "teksilo-fmt-lsp" }]

VS Code

VS Code needs an extension to register an LSP server. See the dedicated walkthrough in teksilo-fmt-vscode.md — it covers two paths: a five-minute Run on Save hook (no LSP) and a small custom extension that registers teksilo-fmt-lsp for Rust documents.

Neovim (nvim-lspconfig)

local configs = require('lspconfig.configs')
configs.teksilo_fmt_lsp = {
  default_config = {
    cmd = { 'teksilo-fmt-lsp' },
    filetypes = { 'rust' },
    root_dir = require('lspconfig.util').root_pattern('Cargo.toml'),
    settings = {},
  },
}
require('lspconfig').teksilo_fmt_lsp.setup{}

Behavior

  • On every textDocument/formatting request, the server runs teksilo_fmt::format_file on the buffer contents and returns either an empty edit list (already canonical) or a single full-document TextEdit (entire buffer replaced with formatted output).
  • A parse error in the host file or in any teksu! body is treated as "leave it alone" — the server returns empty edits, mirroring how rustfmt behaves on save when Rust source is mid-edit.
  • Document sync is full (mode 1): every change resends the whole text. Cheaper than maintaining incremental-diff state for a format-only server.

Architecture

Four crates, layered:

  • teksilo-parse — parser and IR for the teksu! DSL. Extracted from teksilo-macros so non-proc-macro consumers (the formatter, future linters, editor tooling) can build on the same grammar without depending on a proc-macro = true crate. The proc-macro crate now depends on it.
  • teksilo-fmt — pure formatter library. Pretty-printer, byte-range trivia scanner, host-file teksu!-macro visitor, LF/CRLF detection.
  • cargo-teksilo-fmt — CLI binary. File walker, in-place rewriter with atomic writes, --check mode.
  • teksilo-fmt-lsp — LSP server binary. Hand-rolled JSON-RPC over stdio (no tokio); thin wrapper around format_file.

The CLI and LSP have no teksu! grammar knowledge — all parsing and printing happens in the library crates.

Limitations (v1)

  • Closure / multi-line expression bodies inside property values use uniform dedent + reindent. The output is round-trip stable (format(format(x)) == format(x)) but brace alignment inside a closure body may drift one level from what hand-formatting would produce. Hand-fix as needed; the alignment doesn't affect parsing.
  • Empty bodies normalize to bodyless form: Divider { } becomes Divider. The two are semantically identical to the macro; the formatter picks one.
  • ctx => line-break collapse: a ctx => preamble joins to the root element on the same line, even if the user wrote them across lines. Multi-line preambles aren't a documented form anywhere; the formatter standardizes on the joined shape.
  • No configurable rules. Indent width, brace style, and reflow thresholds are fixed. Configurability may come in a later version through FmtConfig.