Cross-platform path helpers. A LEAF namespace (no project deps) so any layer — core, extensions, tests — can normalize without a require cycle.
Cross-platform path helpers. A LEAF namespace (no project deps) so any layer — core, extensions, tests — can normalize without a require cycle.
(abbreviate-home path)(abbreviate-home path home)Shorten an absolute path for DISPLAY by replacing the user's home dir with
~, matching the footer/navigator/dialogs. Only rewrites when path is at
or under home (so /etc/x and relative paths stay unchanged). Rendered
descendants always use / separators; nil-safe.
Shorten an absolute path for DISPLAY by replacing the user's home dir with `~`, matching the footer/navigator/dialogs. Only rewrites when `path` is at or under home (so `/etc/x` and relative paths stay unchanged). Rendered descendants always use `/` separators; nil-safe.
(claim-dir! dir)Claim dir as in use by this process for as long as it runs, so cleanup in
another process can tell a directory that is still served from one a dead
process left behind. Idempotent per directory and never throws: a directory
that cannot be claimed is simply left to be judged by age. Answers dir.
Claim `dir` as in use by this process for as long as it runs, so cleanup in another process can tell a directory that is still served from one a dead process left behind. Idempotent per directory and never throws: a directory that cannot be claimed is simply left to be judged by age. Answers `dir`.
(claim-state dir)How dir's in-use claim stands right now: :held while some process still
serves it, :free once every claimant is gone, and :none for a directory
that carries no claim at all — one written before claims existed, or one
nobody ever used. Never throws; a claim that cannot be tested reads as
:held, because being wrong about a live directory deletes work in use.
How `dir`'s in-use claim stands right now: `:held` while some process still serves it, `:free` once every claimant is gone, and `:none` for a directory that carries no claim at all — one written before claims existed, or one nobody ever used. Never throws; a claim that cannot be tested reads as `:held`, because being wrong about a live directory deletes work in use.
(compact-path-text root text)(compact-path-text root text home)Shorten absolute path prefixes inside DISPLAY text: root (and its ~/ spelling)
becomes relative and the user's home dir becomes ~, the spelling the footer,
navigator and dialogs use. Embedded URL paths and sibling names that merely START
with a prefix stay unchanged. A nil root shortens home alone; non-string text
passes through.
Shorten absolute path prefixes inside DISPLAY text: `root` (and its `~/` spelling) becomes relative and the user's home dir becomes `~`, the spelling the footer, navigator and dialogs use. Embedded URL paths and sibling names that merely START with a prefix stay unchanged. A nil `root` shortens home alone; non-string `text` passes through.
(ensure-log-date-dir!)(ensure-log-date-dir! instant)Create the UTC date directory and return its path. Filesystem errors propagate.
Create the UTC date directory and return its path. Filesystem errors propagate.
(ensure-logs-dir!)Create ~/.vis/logs (and parents) when absent; return its path string.
Never throws.
Create `~/.vis/logs` (and parents) when absent; return its path string. Never throws.
(expand-home path)(expand-home path home)Expand a leading ~ path segment to the user's home directory for filesystem
I/O. Bare ~ becomes home; ~/… and ~\… use native separators; ~user,
mid-path tildes, and ordinary paths pass through unchanged. Nil-safe and a
no-op when home is unavailable.
Expand a leading `~` path segment to the user's home directory for filesystem I/O. Bare `~` becomes home; `~/…` and `~\…` use native separators; `~user`, mid-path tildes, and ordinary paths pass through unchanged. Nil-safe and a no-op when home is unavailable.
(held-file? f)True when f names a file this process holds OS locks on, such as a live SQLite
database with its -wal and -shm companions. POSIX record locks belong to the
PROCESS, not to a descriptor: closing ANY descriptor of the file drops every
lock the process holds on it. One read of a live vis.db-shm by a file tool
therefore releases SQLite's wal-index locks; the next process to open the
database then truncates the -shm this process still has mapped, and its next
write dies with SIGBUS. Code that opens user-chosen files must refuse or skip
held ones.
True when `f` names a file this process holds OS locks on, such as a live SQLite database with its `-wal` and `-shm` companions. POSIX record locks belong to the PROCESS, not to a descriptor: closing ANY descriptor of the file drops every lock the process holds on it. One read of a live `vis.db-shm` by a file tool therefore releases SQLite's wal-index locks; the next process to open the database then truncates the `-shm` this process still has mapped, and its next write dies with SIGBUS. Code that opens user-chosen files must refuse or skip held ones.
(held-files)Canonical path strings of every file this process holds OS locks on.
Canonical path strings of every file this process holds OS locks on.
(hold-files! owner files)Record that owner holds OS locks on files (they need not exist yet), so the
rest of this process leaves them alone (see held-file?). Replaces what
owner held before. Answers nil.
Record that `owner` holds OS locks on `files` (they need not exist yet), so the rest of this process leaves them alone (see `held-file?`). Replaces what `owner` held before. Answers nil.
(log-date-dir)(log-date-dir instant)Diagnostic directory for an instant's UTC date: ~/.vis/logs/YYYY-MM-DD.
Defaults to now; does not create directories. Long-lived writers retain the
path chosen at startup rather than switching files at midnight.
Diagnostic directory for an instant's UTC date: `~/.vis/logs/YYYY-MM-DD`. Defaults to now; does not create directories. Long-lived writers retain the path chosen at startup rather than switching files at midnight.
(log-date-dirs)Existing UTC date directories, newest first. Ignores files, invalid dates and symlinks; retention and session log lookup share this directory boundary.
Existing UTC date directories, newest first. Ignores files, invalid dates and symlinks; retention and session log lookup share this directory boundary.
(log-file)(log-file role)Diagnostic log file for this process. The name carries its role, UTC start
time, and pid: ~/.vis/logs/YYYY-MM-DD/<role>-<yyyyMMddTHHmmssZ>-pid<pid>.log.
TUI and gateway are separate writers because Telemere rotates by renaming its
file; sharing a path lets the non-rotating process keep writing to an orphaned
descriptor. Embedded Python belongs to the gateway stream rather than a third
file. The active .log remains tail-able and Telemere gzip-compresses rotated
parts; housekeeping removes stale generations by age.
Diagnostic log file for this process. The name carries its role, UTC start time, and pid: `~/.vis/logs/YYYY-MM-DD/<role>-<yyyyMMddTHHmmssZ>-pid<pid>.log`. TUI and gateway are separate writers because Telemere rotates by renaming its file; sharing a path lets the non-rotating process keep writing to an orphaned descriptor. Embedded Python belongs to the gateway stream rather than a third file. The active `.log` remains tail-able and Telemere gzip-compresses rotated parts; housekeeping removes stale generations by age.
(logs-dir)Root for diagnostic logs and reports: ~/.vis/logs. Writers use UTC date
directories below it. This dedicated root is accessible to the file tools and
sandbox without exposing configuration, session databases or gateway tokens.
Root for diagnostic logs and reports: `~/.vis/logs`. Writers use UTC date directories below it. This dedicated root is accessible to the file tools and sandbox without exposing configuration, session databases or gateway tokens.
(process-id)This JVM's OS process id. Read fresh so native-image never bakes the builder's pid into the installed binary.
This JVM's OS process id. Read fresh so native-image never bakes the builder's pid into the installed binary.
(release-held-files! owner)Forget owner's files once it holds no more locks on them. Answers nil.
Forget `owner`'s files once it holds no more locks on them. Answers nil.
(sandbox-defs-dir)Directory for persisted Python sandbox helper definitions — ~/.vis/sandbox.
Its own subdir (not ~/.vis) for the same reason as logs-dir: nothing here
needs to sit beside the session DB or the gateway token.
Directory for persisted Python sandbox helper definitions — `~/.vis/sandbox`. Its own subdir (not `~/.vis`) for the same reason as `logs-dir`: nothing here needs to sit beside the session DB or the gateway token.
(sandbox-defs-file session-id)File holding ONE session's persisted sandbox helper definitions —
~/.vis/sandbox/<session-id>.py. The sandbox dies with the process, so this
is what re-creates a session's own defs in a fresh one. The id is reduced
to a safe file name; every other character becomes _.
File holding ONE session's persisted sandbox helper definitions — `~/.vis/sandbox/<session-id>.py`. The sandbox dies with the process, so this is what re-creates a session's own `def`s in a fresh one. The id is reduced to a safe file name; every other character becomes `_`.
(set-log-role! role)Set this process's diagnostic role before its first log path is opened.
Accepted roles are tui, gateway, and vis (short-lived CLI work).
Set this process's diagnostic role before its first log path is opened. Accepted roles are `tui`, `gateway`, and `vis` (short-lived CLI work).
(shell-path path)(shell-path path home)Render path for DISPLAY as one copyable POSIX shell word. A path at or under
home reads ~/… with ~/ left unquoted, so the shell still expands it; a
remainder holding anything beyond [A-Za-z0-9_@%+=:,./-] is single-quoted.
Nil-safe.
Render `path` for DISPLAY as one copyable POSIX shell word. A path at or under home reads `~/…` with `~/` left unquoted, so the shell still expands it; a remainder holding anything beyond `[A-Za-z0-9_@%+=:,./-]` is single-quoted. Nil-safe.
(unixify s)Normalize a path string to / separators on every OS. Java's File/Path
APIs can hand back platform-native separators — so this is the single
canonical normalizer.
Use it ONLY where a path is DATA: compared, glob-matched, shown to the model,
or embedded in a URL / wire / DB. NEVER for real filesystem I/O — io/file,
.exists, JGit, nio all take native paths fine. Returns nil for nil input.
Normalize a path string to `/` separators on every OS. Java's `File`/`Path` APIs can hand back platform-native separators — so this is the single canonical normalizer. Use it ONLY where a path is DATA: compared, glob-matched, shown to the model, or embedded in a URL / wire / DB. NEVER for real filesystem I/O — `io/file`, `.exists`, JGit, nio all take native paths fine. Returns nil for nil input.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |