The option-map entry point: a key nothing reads is refused, and so is an opts that is not
a map.
Nearly every public entry point that takes trailing options wants exactly this, and
wants it for one reason: an option nothing reads takes the default in silence.
That is the quietest failure the API has — {:max-derivation 5} for :max-derivations
reads as no bound at all and the chain runs unbounded, {:strengh :monotonic} stores a
default where known-true was meant, {:varient :index} writes a dump other than the one
asked for. Each returns a handle, a count, a summary that looks exactly right.
So every such entry point runs one shape, identically bar the noun and one sentence, and this
is that shape once. What a caller supplies is the key set, the subject the
message names, and the consequence — the clause saying what taking the default
silently would have cost here, which is the sentence worth writing per entry point and the
only part of the refusal that ever carried information the others did not.
An entry point with further checks on the values of known keys keeps them; this is the key check, and it runs first because a misspelt key is not a bad value — it is a key that is not there.
The option-map entry point: a key nothing reads is refused, and so is an `opts` that is not
a map.
Nearly every public entry point that takes trailing options wants exactly this, and
wants it for one reason: **an option nothing reads takes the default in silence.**
That is the quietest failure the API has — `{:max-derivation 5}` for `:max-derivations`
reads as no bound at all and the chain runs unbounded, `{:strengh :monotonic}` stores a
default where known-true was meant, `{:varient :index}` writes a dump other than the one
asked for. Each returns a handle, a count, a summary that looks exactly right.
So every such entry point runs one shape, identically bar the noun and one sentence, and this
is that shape once. What a caller supplies is the key set, the `subject` the
message names, and the `consequence` — the clause saying what taking the default
silently would have cost *here*, which is the sentence worth writing per entry point and the
only part of the refusal that ever carried information the others did not.
An entry point with further checks on the *values* of known keys keeps them; this is the key
check, and it runs first because a misspelt key is not a bad value — it is a key that
is not there.What each numeric, callback or boolean bound a public entry point takes has to be —
[key, what it is in words, the predicate]. One table, read by every bounded entry
point: vaelii.core's search / chain / assert / extent checks and
vaelii.impl.budget/check-budget! all run their known keys through check-values!
below.
A value outside a bound's domain is refused for the roster check's reason at one remove.
A key nothing reads is one silent default (check! above); a key that is read holding
a value it cannot mean is the other, and quieter still where the value is not a cast
error but a near-miss: a string :max-ms reaches arithmetic and throws bare, but a
string :believed? reads as truthy and answers the stored extent where the believed one
was asked for. Either way the run happens at a setting nobody chose.
Every numeric bound admits 0, each a real question a caller may ask by name — no time
at all (:max-ms), no rule expansion (:max-depth), realize nothing and hand back a
resumable continuation (:max-results), report at every opportunity
(:progress-every-ms) — so the domain is non-negative rather than positive, matching the
anytime contract these bounds already keep and vaelii.impl.spec's nat-int?. What is
refused is the value that is not a number of the right kind at all: a string, a float, a
negative, a keyword where a function belongs, a string where a boolean belongs.
What each numeric, callback or boolean bound a public entry point takes has to *be* — `[key, what it is in words, the predicate]`. One table, read by every bounded entry point: `vaelii.core`'s search / chain / assert / extent checks and `vaelii.impl.budget/check-budget!` all run their known keys through `check-values!` below. A value outside a bound's domain is refused for the roster check's reason at one remove. A key nothing reads is one silent default (`check!` above); a key that *is* read holding a value it cannot mean is the other, and quieter still where the value is not a cast error but a near-miss: a string `:max-ms` reaches arithmetic and throws bare, but a string `:believed?` reads as truthy and answers the stored extent where the believed one was asked for. Either way the run happens at a setting nobody chose. Every numeric bound admits **0**, each a real question a caller may ask by name — no time at all (`:max-ms`), no rule expansion (`:max-depth`), realize nothing and hand back a resumable continuation (`:max-results`), report at every opportunity (`:progress-every-ms`) — so the domain is non-negative rather than positive, matching the anytime contract these bounds already keep and `vaelii.impl.spec`'s `nat-int?`. What is refused is the value that is not a number of the right kind at all: a string, a float, a negative, a keyword where a function belongs, a string where a boolean belongs.
(check! opts opt-keys subject)(check! opts opt-keys subject consequence)Refuse a non-nil non-map opts, and any key outside opt-keys — :unknown-option
both, carrying :options (the roster) and, for the second, :unknown (what was
passed). subject names the entry point in the message; consequence is the clause on what
the silent default would have done, and may be nil where the roster speaks for itself.
opt-keys is a set, used as the membership predicate and sorted for the message.
The second map? is redundant to a reader and required to clj-kondo, which does
not narrow a type through a when whose body throws: a bare (keys opts) below tells
it opts is seqable, and it propagates that up through every caller to
vaelii.core/assert's own signature — where the suite's deliberate :nope becomes a
type error. The guard is the narrowing, so keep it.
Refuse a non-nil non-map `opts`, and any key outside `opt-keys` — `:unknown-option` both, carrying `:options` (the roster) and, for the second, `:unknown` (what was passed). `subject` names the entry point in the message; `consequence` is the clause on what the silent default would have done, and may be nil where the roster speaks for itself. `opt-keys` is a set, used as the membership predicate and sorted for the message. The second `map?` is redundant to a reader and required to clj-kondo, which does not narrow a type through a `when` whose body throws: a bare `(keys opts)` below tells it `opts` is seqable, and it propagates that up through every caller to `vaelii.core/assert`'s own signature — where the suite's deliberate `:nope` becomes a type error. The guard is the narrowing, so keep it.
(check-values! opts subject)Refuse a bound in opts whose value is outside its domain (bound-domains), subject
naming the entry point in the message as check! does.
The value refusal beside the key one, and it runs after it: a misspelt key is not
a bad value, so the key roster (check!) is settled before any value is read, and by
then every key present is one the entry point admits. Reads the caller's opts against
bound-domain-map, so a key with no row here (a :strength, a :strategy) is not this
check's business, and a key the entry point does not read was already refused.
An absent key, and an explicit nil, are no bound rather than a bad one — a
legitimate request the domain does not judge, which every optional bound relies on. When
more than one bound is bad, the one whose key sorts first is reported, so the refusal does
not turn on opts's map order. :unknown-option with :mismatch :bad-value, the shape
every value refusal carries.
Refuse a bound in `opts` whose value is outside its domain (`bound-domains`), `subject` naming the entry point in the message as `check!` does. The **value** refusal beside the key one, and it runs *after* it: a misspelt key is not a bad value, so the key roster (`check!`) is settled before any value is read, and by then every key present is one the entry point admits. Reads the caller's `opts` against `bound-domain-map`, so a key with no row here (a `:strength`, a `:strategy`) is not this check's business, and a key the entry point does not read was already refused. An **absent** key, and an explicit `nil`, are no bound rather than a bad one — a legitimate request the domain does not judge, which every optional bound relies on. When more than one bound is bad, the one whose key sorts first is reported, so the refusal does not turn on `opts`'s map order. `:unknown-option` with `:mismatch :bad-value`, the shape every value refusal carries.
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 |