libtmux.workspace
- Anonymous module
-
Owned Common Lisp workspace descriptions and explicit tmux application. MAKE-WORKSPACE validates inert native data without evaluation. PLAN-WORKSPACE is local and pure; APPLY-WORKSPACE is the explicit external-operation boundary. Workspace objects, plans, steps, results, and their readers return defensive data. Conflicts fail before mutation, and partial application retains evidence.
Members26#
Common operations14#
- apply-workspace function Create or reuse WORKSPACE through explicit CLIENT and return WORKSPACE-RESULT. The function first calls FETCH-SNAPSHOT and PLAN-WORKSPACE. A proven match returns immediately with no command outcomes. A missing session executes each planned core mutation once, in order, then captures and proves the final topology. TIMEOUT and OUTPUT-LIMIT, when supplied, apply separately to each core operation; CANCEL-TOKEN is shared. Conflicts dispatch no mutation.
- make-workspace function Validate closed native DATA and return an owned WORKSPACE without I/O. DATA is a keyword plist in schema libtmux.lisp.workspace/1. Lists and vectors must be finite. MAX-WINDOWS, MAX-PANES, and MAX-ARGV bound retained topology and commands. MAX-ENVIRONMENT bounds session (name . value) string pairs; tmux stores them in the session environment inherited by later panes. Pane :COMMAND is argv; :SHELL-COMMAND is explicit shell source, mutually exclusive with argv. Window :LAYOUT is a named keyword or (:CUSTOM string) validated by tmux on apply. Names reject characters tmux would rewrite. Unknown/duplicate keys, invalid types or limits signal INVALID-WORKSPACE. Mutable inputs are copied.
- parse-workspace function Parse one bounded libtmux.lisp.workspace/1 JSON string into a WORKSPACE. The complete document uses a closed grammar, rejects duplicate members, and never interns or evaluates external names. Limits bound UTF-8 bytes, nesting, nodes, strings, windows, total panes, argv length, session environment pairs (MAX-ENVIRONMENT, default 256), and integer token digits. Pane shell_command is explicit shell source; window layout accepts a named string or a custom object. Input and retained values are copied. Signals INVALID-WORKSPACE-DOCUMENT or WORKSPACE-LIMIT-EXCEEDED with WORKSPACE-PATH and WORKSPACE-LIMIT diagnostics.
- plan-steps function Return PLAN's ordered steps as a fresh simple vector. No I/O.
- plan-workspace function Return a finite local WORKSPACE-PLAN, optionally against captured SNAPSHOT. Without SNAPSHOT, return the deterministic creation plan. With SNAPSHOT, return that plan when the named session is absent, an empty proven no-op when topology matches, or signal WORKSPACE-CONFLICT before dispatch. Planning compares window names, declared indexes, and pane counts; creation-only cwd, argv, and layout are not inferred from mutable live state. Explicit indexes are reserved before automatic windows. Pane creation and final order follow the declaration. No tmux I/O occurs.
- read-workspace function Read one bounded regular UTF-8 JSON file and return an owned WORKSPACE. PATH is opened for input and never modified. MAX-INPUT-BYTES is enforced on bytes read even if the file changes after opening. The descriptor is opened nonblocking, then directories and special files are rejected before reading. Other OPTIONS are forwarded to PARSE-WORKSPACE. Signals INVALID-WORKSPACE-DOCUMENT or WORKSPACE-LIMIT-EXCEEDED and closes the stream.
- result-created-p function Return true when APPLY-WORKSPACE created the declared session.
- result-outcomes function Return retained COMMAND-OUTCOME objects in a fresh simple vector.
- result-snapshot function Return the final captured SNAPSHOT retained by RESULT. No I/O.
- step-action function Return STEP's action keyword, without I/O.
- step-data function Return a fresh plist of STEP operands, without I/O.
- workspace-apply-failed exception Workspace application stopped with retained partial outcomes.
- workspace-conflict exception Captured topology conflicts with the declared workspace.
- workspace-deadline-exceeded exception The application budget expired at a workspace boundary. WORKSPACE-LIMIT returns :TOTAL-TIMEOUT. No new command outcome is implied; previous completed outcomes remain on a wrapping WORKSPACE-APPLY-FAILED. An already admitted core call retains its own timeout and cleanup contract.
Other members12#
- failed-step function Return the failed or refused next WORKSPACE-STEP, or NIL for final verification. NIL does not imply that no mutations completed; inspect RESULT-OUTCOMES.
- invalid-workspace exception Native workspace data violates the closed workspace grammar.
- invalid-workspace-document exception A workspace JSON document is malformed, unknown, or invalid.
- workspace class An immutable-by-contract, owned workspace description.
- workspace-data function Return fresh closed native data for WORKSPACE, without I/O.
- workspace-error exception A workspace validation, planning, or application failure.
- workspace-limit function Return the exhausted workspace limit name, or NIL, without I/O.
- workspace-limit-exceeded exception A workspace JSON or file input exceeds a configured bound.
- workspace-path function Return a fresh vector locating the workspace error, without I/O.
- workspace-plan class A finite local plan; an empty step vector is a proven no-op.
- workspace-result class Retained workspace application evidence and final captured topology.
- workspace-step class One inspectable, inert workspace operation in execution order.