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.
(ancestor-chain dir)dir and each parent up to the filesystem root, nearest first, as a lazy seq.
dir is a File or a Path, and each item has the same type. Nil gives an empty
seq. Make dir absolute or canonical first, because a relative path stops at its
first segment.
`dir` and each parent up to the filesystem root, nearest first, as a lazy seq. `dir` is a `File` or a `Path`, and each item has the same type. Nil gives an empty seq. Make `dir` absolute or canonical first, because a relative path stops at its first segment.
(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.
(create-private-dirs! dir)Create dir and its missing parents owner-only (700). An existing directory keeps its mode.
Create `dir` and its missing parents owner-only (700). An existing directory keeps its mode.
(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.
(install-temp-dir!)Point java.io.tmpdir at the private tmp directory in the task runtime
directory, and return it. Return nil and change nothing when the setting is
unset. Run it at startup: the one-argument createTempFile forms keep the
startup value, so their callers pass temp-dir. A second run keeps the same
directory.
Point `java.io.tmpdir` at the private `tmp` directory in the task runtime directory, and return it. Return nil and change nothing when the setting is unset. Run it at startup: the one-argument `createTempFile` forms keep the startup value, so their callers pass [[temp-dir]]. A second run keeps the same directory.
(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/`.
(nearest-ancestor pred dir)The first item of ancestor-chain of dir for which pred is true, or nil.
For example, (nearest-ancestor #(.exists (File. ^File % ".git")) dir).
The first item of [[ancestor-chain]] of `dir` for which `pred` is true, or nil. For example, `(nearest-ancestor #(.exists (File. ^File % ".git")) dir)`.
(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.
(process-role)This process's role: gateway, tui or vis (short-lived CLI work, the default).
This process's role: `gateway`, `tui` or `vis` (short-lived CLI work, the default).
(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.
(runtime-dir)The checked task runtime directory, or nil when it is unset. A set value fails
closed and never falls back to /tmp: it must be an existing absolute directory
without symbolic links that only its owner can write. A refusal is
:vis/runtime-dir and names its reason.
The checked task runtime directory, or nil when it is unset. A set value fails closed and never falls back to `/tmp`: it must be an existing absolute directory without symbolic links that only its owner can write. A refusal is `:vis/runtime-dir` and names its reason.
(runtime-dir-setting)The task runtime directory: JVM property vis.runtime.dir, then VIS_RUNTIME_DIR.
Empty is unset. A set value holds worker control endpoints and temporary files (#423).
The task runtime directory: JVM property `vis.runtime.dir`, then `VIS_RUNTIME_DIR`. Empty is unset. A set value holds worker control endpoints and temporary files (#423).
(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.
(spit-private! path content)Write content to path atomically as an owner-only (600) file. This is the one
writer for files that hold a secret. A failure keeps the previous file and leaves
no temporary file. A symbolic link path writes its target. Missing parent
directories are created owner-only. A filesystem without atomic moves gets a
plain replace, which is not atomic.
Write `content` to `path` atomically as an owner-only (600) file. This is the one writer for files that hold a secret. A failure keeps the previous file and leaves no temporary file. A symbolic link path writes its target. Missing parent directories are created owner-only. A filesystem without atomic moves gets a plain replace, which is not atomic.
(temp-dir)The directory for temporary files: java.io.tmpdir, which install-temp-dir!
moves into the task runtime directory. Give it to every createTempFile and
createTempDirectory call.
The directory for temporary files: `java.io.tmpdir`, which [[install-temp-dir!]] moves into the task runtime directory. Give it to every `createTempFile` and `createTempDirectory` call.
(temp-env)The TMPDIR of a child process when the task runtime directory is set, else an
empty map, so the child keeps its inherited value.
The `TMPDIR` of a child process when the task runtime directory is set, else an empty map, so the child keeps its inherited value.
(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 |