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: the vis.logs.dir system property, else
~/.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. The :test alias points it at target/.
Root for diagnostic logs and reports: the `vis.logs.dir` system property, else `~/.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. The `:test` alias points it at `target/`.
(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 `_`.
(sandbox-spill-dir session-id)Directory for ONE session's spilled sandbox values — ~/.vis/sandbox/<session-id>.spill.
It holds large text and bytes values that the snapshot budget left out, beside
sandbox-defs-file. The id is reduced to a safe file name like there.
Directory for ONE session's spilled sandbox values — `~/.vis/sandbox/<session-id>.spill`. It holds large text and bytes values that the snapshot budget left out, beside [[sandbox-defs-file]]. The id is reduced to a safe file name like there.
(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.
(with-claim-lock f)Call f while this process holds its claim lock, and answer what f answers.
A sweep holds the lock while it judges and deletes a directory. A publisher
holds it while it creates and claims a directory, before it fills it. So a
sweep of this process deletes a directory before the claim or not at all. A
sweep in another process can still judge a directory free before the claim.
Call `f` while this process holds its claim lock, and answer what `f` answers. A sweep holds the lock while it judges and deletes a directory. A publisher holds it while it creates and claims a directory, before it fills it. So a sweep of this process deletes a directory before the claim or not at all. A sweep in another process can still judge a directory free before the claim.
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 |