Binary identity: which names on PATH denote a program.
(bin :rg) => "rg" (names :fd) => ["fd" "fdfind"] (locate :fd) => (ok {:path "/usr/bin/fdfind" :bin "fdfind"})
A binary identity answers exactly one question: what is this program called
where it is installed. It says nothing about how to install it (that is
shell.tools, which owns provisioning) and nothing about how a pattern
enters its argv (that is shell.search, which owns grammar). Both of those
registries reference an id here rather than restating the names.
An id is registered under :binary/id AND under every :binary/aliases
member, all pointing at the same map, so a lookup is a plain get and the
value always names its own canonical id. shell.tools has keyed ripgrep as
:ripgrep since before shell.search keyed it :rg; both resolve, and
neither registry has to know what the other calls it.
Collect (registry reads) / Promote (pure derivation over a Binary VALUE) /
Boundary (locate, the only form here that touches PATH). The probe is a
port, so a caller — a test above all — supplies its own adapter instead of
redefining somebody's var.
Binary identity: which names on PATH denote a program.
(bin :rg) => "rg"
(names :fd) => ["fd" "fdfind"]
(locate :fd) => (ok {:path "/usr/bin/fdfind" :bin "fdfind"})
## What belongs here, and what does not
A binary identity answers exactly one question: what is this program called
where it is installed. It says nothing about how to install it (that is
`shell.tools`, which owns provisioning) and nothing about how a pattern
enters its argv (that is `shell.search`, which owns grammar). Both of those
registries reference an id here rather than restating the names.
## Aliases
An id is registered under `:binary/id` AND under every `:binary/aliases`
member, all pointing at the same map, so a lookup is a plain `get` and the
value always names its own canonical id. `shell.tools` has keyed ripgrep as
`:ripgrep` since before `shell.search` keyed it `:rg`; both resolve, and
neither registry has to know what the other calls it.
## Layout
Collect (registry reads) / Promote (pure derivation over a Binary VALUE) /
Boundary (`locate`, the only form here that touches PATH). The probe is a
port, so a caller — a test above all — supplies its own adapter instead of
redefining somebody's var.The probe locate uses when given none. Rebind to inject an adapter; the
var is read at CALL time, so a binding is honoured by everything downstream
— shell.tools and shell.search included — without either of them
growing a probe parameter they have no opinion about.
The probe `locate` uses when given none. Rebind to inject an adapter; the var is read at CALL time, so a binding is honoured by everything downstream — `shell.tools` and `shell.search` included — without either of them growing a probe parameter they have no opinion about.
(bin id)The upstream name ID denotes, or nil for an unregistered id.
The upstream name ID denotes, or nil for an unregistered id.
(bin-of binary)The upstream name BINARY goes by.
The upstream name BINARY goes by.
A program's names, as data.
:binary/bin the upstream name, and the one an argv is built from.
:binary/alts other names the SAME program is installed under. Debian
ships fd as fdfind and bat as batcat, the upstream
names having gone to fdclone and bacula-console-qt. A
packaging fact: probing :binary/bin alone reports the
program missing while it sits on PATH.
:binary/aliases other ids that denote this same program.
A program's names, as data.
:binary/bin the upstream name, and the one an argv is built from.
:binary/alts other names the SAME program is installed under. Debian
ships fd as `fdfind` and bat as `batcat`, the upstream
names having gone to fdclone and bacula-console-qt. A
packaging fact: probing `:binary/bin` alone reports the
program missing while it sits on PATH.
:binary/aliases other ids that denote this same program.Registry keys a Binary is reachable under. Non-empty: its own id is one.
Registry keys a Binary is reachable under. Non-empty: its own id is one.
Every program either registry names.
Every program either registry names.
(canonical)Snapshot of {canonical-id -> Binary}, alias keys excluded.
Snapshot of {canonical-id -> Binary}, alias keys excluded.
Does a program of this name exist on this host, and where.
Does a program of this name exist on this host, and where.
(-probe this program-name)Result<{:path .. :program ..}> for PROGRAM-NAME.
Result<{:path .. :program ..}> for PROGRAM-NAME.
(keys-of binary)Every registry key BINARY is reachable under: its id and every alias.
Every registry key BINARY is reachable under: its id and every alias.
(locate id)(locate id probe)Result<{:path .. :bin ..}>: the name ID is actually installed under HERE.
Probes names in order through PROBE (default *probe*), stopping at the
first that answers. Refuses naming every name it tried, rather than letting
the caller meet the absence as an ENOENT from the fork.
An unregistered id and an uninstalled program are DIFFERENT refusals:
:binary/unknown says nobody declared this identity, :binary/not-installed
says we looked and it is not here. Collapsing them would make "I never
looked" indistinguishable from "it is absent".
Result<{:path .. :bin ..}>: the name ID is actually installed under HERE.
Probes `names` in order through PROBE (default `*probe*`), stopping at the
first that answers. Refuses naming every name it tried, rather than letting
the caller meet the absence as an ENOENT from the fork.
An unregistered id and an uninstalled program are DIFFERENT refusals:
`:binary/unknown` says nobody declared this identity, `:binary/not-installed`
says we looked and it is not here. Collapsing them would make "I never
looked" indistinguishable from "it is absent".(located name res)The answer for NAME having answered with RES, or nil if it did not.
Reports the name that ANSWERED rather than the canonical one — that is the name a caller must spawn.
The answer for NAME having answered with RES, or nil if it did not. Reports the name that ANSWERED rather than the canonical one — that is the name a caller must spawn.
(lookup id)The Binary ID denotes, or nil. Resolves aliases.
The Binary ID denotes, or nil. Resolves aliases.
(names id)Every name ID may be installed under, upstream first, or nil for an unregistered id. This is the probe order.
Every name ID may be installed under, upstream first, or nil for an unregistered id. This is the probe order.
(names-of binary)Every name BINARY may be installed under, upstream first. The probe order.
Every name BINARY may be installed under, upstream first. The probe order.
Names to probe, upstream first. Non-empty: a Binary always has :binary/bin.
Names to probe, upstream first. Non-empty: a Binary always has `:binary/bin`.
(register! binary)Register BINARY under its id and every alias. Result<Binary>. A map that does not conform to the Binary schema is refused.
Register BINARY under its id and every alias. Result<Binary>. A map that does not conform to the Binary schema is refused.
(register-built-in!)Register every built-in identity. Returns the vector of Results.
Register every built-in identity. Returns the vector of Results.
(registered)Snapshot of {id -> Binary}, alias keys included.
Snapshot of {id -> Binary}, alias keys included.
(unregister! id)Drop the binary registered under ID, and every key that pointed at it. Returns it, or nil.
Drop the binary registered under ID, and every key that pointed at it. Returns it, or nil.
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 |