KB naming invariants, as predicates over symbols — and the walk that applies them to every literal of a sentence rather than to its outermost functor alone.
predicate camelCase, lowercase-initial, no underscore parentOf, genl, argIsa
individual CapitalCamelCase Fido, Tom
type snake_case, lowercase, unary predicate dog, physical_object
sense a type, plus which sense of it is meant abrasive-grit
context CapitalCamelCase ending in Context UniverseContext, CoreContext
lexeme the lex namespace; the name is parse input lex/fool's_gold
Single lowercase words (dog, genl, parentOf) satisfy both predicate? and
type-symbol?; role is disambiguated by position and arity, not the symbol alone.
A sense is a type too, so it is unary for the same reason, and a lexeme is the one
role a namespace decides — its text is a surface form and not ours to spell.
A functor carrying an underscore is a type name and nothing else, and types are
used as unary predicates — (dog Fido), not (isa Fido Dog) — so it is legal at
arity 1 and nowhere else. (lives_in penguin cold_place) is a type name doing a
relation's job; admitting it fragments the vocabulary into one-off predicates
(lives_in_antarctica, capable_of_swimming) that can never join a rule or match
another sentence.
How hard these are enforced is the KB's to say, not this namespace's: open-kb's
:naming selects :strict / :warn / :off (policies, below) and assert reads
it. The predicates themselves do not move — :off stores a name nothing can classify,
not one classified differently.
problems checks the functor of every literal a sentence contains — a rule's
antecedents, its consequent, an exceptWhen query's conjuncts, a not body, an
ist-directed sentence, a negation-as-failure query — not only the outermost one.
A rule consequent is exactly where generated content lands, and the outermost
functor there is implies.
KB naming invariants, as predicates over symbols — and the walk that applies them to every **literal** of a sentence rather than to its outermost functor alone. predicate camelCase, lowercase-initial, no underscore parentOf, genl, argIsa individual CapitalCamelCase Fido, Tom type snake_case, lowercase, unary predicate dog, physical_object sense a type, plus which sense of it is meant abrasive-grit context CapitalCamelCase ending in Context UniverseContext, CoreContext lexeme the `lex` namespace; the name is parse input lex/fool's_gold Single lowercase words (dog, genl, parentOf) satisfy both `predicate?` and `type-symbol?`; role is disambiguated by position and arity, not the symbol alone. A sense is a type too, so it is unary for the same reason, and a lexeme is the one role a *namespace* decides — its text is a surface form and not ours to spell. A functor carrying an **underscore** is a type name and nothing else, and types are used as *unary* predicates — `(dog Fido)`, not `(isa Fido Dog)` — so it is legal at arity 1 and nowhere else. `(lives_in penguin cold_place)` is a type name doing a relation's job; admitting it fragments the vocabulary into one-off predicates (`lives_in_antarctica`, `capable_of_swimming`) that can never join a rule or match another sentence. How hard these are enforced is the **KB's** to say, not this namespace's: `open-kb`'s `:naming` selects `:strict` / `:warn` / `:off` (`policies`, below) and `assert` reads it. The predicates themselves do not move — `:off` stores a name nothing can classify, not one classified differently. `problems` checks the functor of every literal a sentence contains — a rule's antecedents, its consequent, an `exceptWhen` query's conjuncts, a `not` body, an `ist`-directed sentence, a negation-as-failure query — not only the outermost one. A rule consequent is exactly where generated content lands, and the outermost functor there is `implies`.
(advice sentence)A well-formed sentence that is nonetheless almost certainly not what was meant — or
nil. Where problems reads the invariants, this reads intent, so everything here
passes every check and stores cleanly.
One entry so far. (isa Fido Dog) is the membership spelling every other KR system
taught the reader, and here it stores a two-place predicate named isa relating two
individuals — legal, indexed, believed, and matched by nothing anyone will ask. The
reader then asks (isa? kb 'Fido 'Dog) and gets false, with no error to search for,
because the type they meant was never asserted. CoreContext.txt says never to write
it and docs/naming.md calls it out by name; neither is in front of someone who is
typing.
The bar for a new entry is that the shape has no legitimate reading: isa is a
predicate no shipped KB declares and the one the ontology names as the mistake. A
shape somebody might mean stays out — a nudge that fires on correct input is one that
gets tuned out, and takes the real ones with it.
A well-formed sentence that is nonetheless almost certainly not what was meant — or nil. Where `problems` reads the invariants, this reads *intent*, so everything here passes every check and stores cleanly. One entry so far. `(isa Fido Dog)` is the membership spelling every other KR system taught the reader, and here it stores a two-place predicate named `isa` relating two individuals — legal, indexed, believed, and matched by nothing anyone will ask. The reader then asks `(isa? kb 'Fido 'Dog)` and gets false, with no error to search for, because the type they meant was never asserted. `CoreContext.txt` says never to write it and `docs/naming.md` calls it out by name; neither is in front of someone who is typing. The bar for a new entry is that the shape has no legitimate reading: `isa` is a predicate no shipped KB declares and the one the ontology names as the mistake. A shape somebody might mean stays out — a nudge that fires on correct input is one that gets tuned out, and takes the real ones with it.
(advise! policy sentence context)Log advice about sentence, once per process per kind of advice.
Silent under :naming :off, which asks for names not to be policed at all. Never a
refusal at any policy: the sentence is well-formed, and refusing a legal shape on a
guess about intent would make the front door unpredictable.
Log `advice` about `sentence`, once per process per kind of advice. Silent under `:naming :off`, which asks for names not to be policed at all. Never a refusal at any policy: the sentence is well-formed, and refusing a legal shape on a guess about intent would make the front door unpredictable.
(applied-literals sentence)(applied-literals role form)The [role literal] pairs of sentence as written — every position at which it
applies something to arguments, tagged with the frame that position sits in
(:sentence / :antecedent / :consequent / :exception).
Frames are descended through, arguments are not, so this is exactly the set of
positions an author wrote a predicate application in — a variable functor
((?p ?x ?y), the dotted rest (?pred . ?args)) among them, which is what
literals filters back out and rules/variable-functor-literals keeps.
The `[role literal]` pairs of `sentence` as written — every position at which it applies *something* to arguments, tagged with the frame that position sits in (`:sentence` / `:antecedent` / `:consequent` / `:exception`). Frames are descended through, arguments are not, so this is exactly the set of positions an author wrote a predicate application in — a variable functor (`(?p ?x ?y)`, the dotted rest `(?pred . ?args)`) among them, which is what `literals` filters back out and `rules/variable-functor-literals` keeps.
(blocking-problems policy sentence context)The naming violations that stop something under policy — the messages, or nil.
Empty under :warn and :off by construction, so a caller that has to yield a value
rather than throw (special/definitional-violation, the assert dry run) asks this
and needs no policy branch of its own.
The naming violations that **stop** something under `policy` — the messages, or nil. Empty under `:warn` and `:off` by construction, so a caller that has to yield a value rather than throw (`special/definitional-violation`, the `assert` dry run) asks this and needs no policy branch of its own.
(check! policy sentence context)Enforce policy on sentence in context: throw :naming under :strict, log
under :warn, do nothing under :off. The one place the three differ, so no caller
spells the throw out and none can drift from another.
Past the invariants it also gives advice — for a sentence that breaks none of them
and is still a mistake, which a refusal cannot reach.
Enforce `policy` on `sentence` in `context`: throw `:naming` under `:strict`, log under `:warn`, do nothing under `:off`. The one place the three differ, so no caller spells the throw out and none can drift from another. Past the invariants it also gives `advice` — for a sentence that breaks none of them and is still a mistake, which a refusal cannot reach.
A fresh tally accumulator: records seen, records with at least one violation, and
the per-class breakdown. Counts records rather than violations — one sentence can
break three conventions, and what an operator is deciding is what fraction of the
corpus is re-assertable.
A fresh `tally` accumulator: records seen, records with at least one violation, and the per-class breakdown. Counts records rather than violations — one sentence can break three conventions, and what an operator is deciding is what fraction of the corpus is re-assertable.
The namespace marking a lexeme — a surface form exactly as a model or a person
wrote it, before anything decided what it means. A namespace rather than a spelling
because a lexeme's own text is unconstrained: it carries apostrophes (fool's_gold),
dashes, dots and digits, so any marker written into the name would collide with the
word it marks. (namespace x) is a field read and cannot.
The namespace marking a **lexeme** — a surface form exactly as a model or a person wrote it, before anything decided what it means. A namespace rather than a spelling because a lexeme's own text is unconstrained: it carries apostrophes (`fool's_gold`), dashes, dots and digits, so any marker written *into* the name would collide with the word it marks. `(namespace x)` is a field read and cannot.
(lexeme? x)A lexeme: lex/fool's_gold. Parse input, and the only role whose text this makes no
claim about — what a person typed is not ours to spell.
Every other namespace stays invisible to the role checks, exactly as before: nm reads
the name half, so agg/count and set/forwardRule are the predicates they always
were. lex is the one namespace that decides a role.
A lexeme: `lex/fool's_gold`. Parse input, and the only role whose text this makes no claim about — what a person typed is not ours to spell. Every other namespace stays invisible to the role checks, exactly as before: `nm` reads the name half, so `agg/count` and `set/forwardRule` are the predicates they always were. `lex` is the one namespace that decides a role.
(literals sentence)(literals role form)The [role literal] pairs whose functor names a predicate — applied-literals
without the variable-functor positions, which are patterns and name nothing these
invariants can judge. This is the set of functors an author named, and what every
check below reads.
The `[role literal]` pairs whose functor **names a predicate** — `applied-literals` without the variable-functor positions, which are patterns and name nothing these invariants can judge. This is the set of functors an author named, and what every check below reads.
(message {:keys [class role symbol literal]})One problems* map rendered as the line a rejection carries. Every message names
the offending symbol, the frame it sits in and the spelling to write instead: whoever
reads it is mid-repair, and a violation reported without its fix is a second lookup.
One `problems*` map rendered as the line a rejection carries. Every message names the offending symbol, the frame it sits in and the spelling to write instead: whoever reads it is mid-repair, and a violation reported without its fix is a second lookup.
What a KB does with a naming violation, and the one line each is for.
A bulk path is not on this list because it does not consult it: a corpus import builds
records directly and never asks (docs/naming.md, "The two doors"). What it does
instead is report — an operator learns the refused fraction at load time, from a
count rather than from a failed experiment a year later.
What a KB does with a naming violation, and the one line each is for. A bulk path is not on this list because it does not consult it: a corpus import builds records directly and never asks (`docs/naming.md`, "The two doors"). What it does instead is *report* — an operator learns the refused fraction at load time, from a count rather than from a failed experiment a year later.
What a naming violation is, as a keyword, with the human line under it. A rejection reads as prose, but a caller that counts them needs to group without parsing English — an operator auditing a corpus wants five numbers, not eleven million sentences — so the class is the datum and the message is rendered from it.
What a naming violation *is*, as a keyword, with the human line under it. A rejection reads as prose, but a caller that counts them needs to group without parsing English — an operator auditing a corpus wants five numbers, not eleven million sentences — so the class is the datum and the message is rendered from it.
(problems sentence context)Checkable naming violations for a sentence in a context (seq of strings): the
context's own name, then every literal's functor (outermost frame first), then every
literal's atomic symbol arguments, then any ist context slot, then the dotted rest
marker where it cannot appear.
This is a check on the shape of a name, not on whether the name is worth having.
A unary snake_case functor is a well-formed type name, so
(implies (penguin ?x) (has_black_and_white_feathers ?x)) passes here, and so would
capable_of_swimming or thermoregulates_via_blubber_and_feathers — each is exactly
what the invariants say a type looks like. Nothing about a symbol distinguishes a
type the ontology wants from a one-off coined for a single sentence, so nothing here
can refuse the second: judging that needs the KB's existing vocabulary, which is a
separate question asked elsewhere. Read this as a guard against misnamed content,
never as a guard against vocabulary fragmentation.
Checkable naming violations for a sentence in a context (seq of strings): the context's own name, then every literal's functor (outermost frame first), then every literal's atomic symbol arguments, then any `ist` context slot, then the dotted rest marker where it cannot appear. **This is a check on the shape of a name, not on whether the name is worth having.** A *unary* snake_case functor is a well-formed type name, so `(implies (penguin ?x) (has_black_and_white_feathers ?x))` passes here, and so would `capable_of_swimming` or `thermoregulates_via_blubber_and_feathers` — each is exactly what the invariants say a type looks like. Nothing about a symbol distinguishes a type the ontology wants from a one-off coined for a single sentence, so nothing here can refuse the second: judging that needs the KB's existing vocabulary, which is a separate question asked elsewhere. Read this as a guard against *misnamed* content, never as a guard against vocabulary fragmentation.
(problems* sentence context)Checkable naming violations for a sentence in a context, as data: a vector of
{:class :role :symbol :literal} maps in the order problems reports them. :class
is one of problem-classes, :role the frame the offending literal sits in, :symbol
the name that broke the convention, and message renders the line.
Data rather than prose because the two callers want different halves of it. assert
wants the sentence it refused spelled out; an audit over a whole corpus wants to
group — how many violations, of which class, over how many distinct spellings — and
a message that embeds the literal is unique per record, so counting them counts
records. Rendering is therefore separate and paid only where a message is read.
Checkable naming violations for a sentence in a context, as **data**: a vector of
`{:class :role :symbol :literal}` maps in the order `problems` reports them. `:class`
is one of `problem-classes`, `:role` the frame the offending literal sits in, `:symbol`
the name that broke the convention, and `message` renders the line.
Data rather than prose because the two callers want different halves of it. `assert`
wants the sentence it refused spelled out; an audit over a whole corpus wants to
*group* — how many violations, of which class, over how many distinct spellings — and
a message that embeds the literal is unique per record, so counting them counts
records. Rendering is therefore separate and paid only where a message is read.(tally t sentence context)Fold one sentence's violations into t. Counts and classes only, never spellings: a
corpus large enough to need a bulk path has a vocabulary large enough that holding its
distinct offending names would cost more than the load
(vaelii.bench.survey's naming audit is where that question is asked).
Fold one sentence's violations into `t`. Counts and classes only, never spellings: a corpus large enough to need a bulk path has a vocabulary large enough that holding its distinct offending names would cost more than the load (`vaelii.bench.survey`'s `naming` audit is where that question is asked).
(tally-line t)The one line a load prints about t, or nil when the front door agrees with the
corpus — which is the common case and deserves no output at all.
The one line a load prints about `t`, or nil when the front door agrees with the corpus — which is the common case and deserves no output at all.
(type-symbol? x)A type: bare snake_case (dog, physical_object) or a sense (abrasive-grit).
Both are unary predicates — a sense is a type that says which sense it is.
A type: bare snake_case (`dog`, `physical_object`) or a sense (`abrasive-grit`). Both are unary predicates — a sense is a type that says which sense it is.
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 |