vaelii.foreign.term — com.vaelii/vaelii-foreign 0.1.0

Spell a foreign name as a vaelii term.

Every ontology this repo reads names its terms in its own alphabet — Cyc writes #$Agent-PartiallyTangible, RDF an IRI, OBO GO:0008150, WordNet a lemma and a byte offset, ATOMIC an English sentence — and vaelii names a term with a symbol whose shape encodes its role (vaelii.impl.naming):

type         snake_case                 dog, physical_object
predicate    camelCase                  parentOf, argIsa
individual   CapitalCamelCase           Rover, Einstein
function     CapitalCamelCase           GroupFn
context      CapitalCamelCase + Context UniverseContext

So a translation cannot rename term-by-term as it goes: it has to know a term's role first, and every reader here earns that the same way — a classifying pass over the source, then a naming pass with the classification in hand. What differs between them is only what counts as evidence, which is each reader's business; the spelling and the collision handling are this namespace's, so five readers cannot disagree about what a legal predicate name looks like.

Two properties matter more than they look:

• Renaming is not injective, so collisions are the normal case. GO:0008150 and GO:0008151 may both be named biological_process, owl:Class and rdfs:Class both class. name-table resolves them with the smallest numeric suffix that is free, in a sorted pass, so the same source always produces the same names whatever order it was read in — a corpus you can diff between runs.

• A name becomes a file name. A context file is <Context>.txt, and a filesystem bounds a name at 255 bytes, while a computed Cyc microtheory or an ATOMIC event runs far longer. abbreviate truncates and appends a hash of the whole, in letters rather than digits so spell cannot break the hash into a word of its own.

abbreviate clj

(abbreviate s)

s if it is short enough, else its head plus a hash of the whole, so a long name stays readable at a glance and still cannot collide by truncation alone. The hash is spelled in letters: the name goes through spell, which would break a digit run into a word of its own.

disambiguate clj

(disambiguate taken role base)

base if free in taken, else base with the smallest numeric suffix that is.

name-limit clj

How long a minted name may run before it is abbreviated. A context becomes a file name, which a filesystem bounds at 255 bytes, and a minted name — a nested Cyc microtheory, an ATOMIC event sentence — has no bound of its own.

name-table clj

(name-table entries)

The foreign term -> vaelii term map, built from entries — [key role base] triples, where base is the foreign name to spell and key is whatever the reader looks a term up by (a symbol, an IRI string, a whole form).

Entries are consumed in the order given, and the order is what decides which of two colliding names keeps the unsuffixed spelling. So a caller sorts first: a translation whose names depend on the order the source happened to stream in is one whose output cannot be diffed against the previous run.

Returns {key {:term symbol :role role}}.

resolve-role clj

(resolve-role precedence evidence)

The single role each key is given, resolving evidence — a map of evidence-key -> #{key …} — by precedence, a seq of [role evidence-key] in decreasing authority. The first rule that names a key decides it.

Every reader classifies this way because the evidence is always partial and always contradictory: a source states a term's role in some places, implies it by position in others, and leaves the rest to be whatever is left over. Precedence is where a reader says which of those it trusts, and it is the one place to look to find out.

spell clj

(spell role nm)

The vaelii spelling of foreign name nm in role, before collision resolution. Each role's shape is the naming invariant it must satisfy. A name that would come out empty or leading-digit is prefixed rather than mangled further, because a mangled name is one nobody can look up in the source and a prefixed one still reads.

words clj

(words s)

The word parts of a foreign name. Splits on case boundaries as well as on the punctuation a source may allow and vaelii's symbols may not (Agent-PartiallyTangible, owl:Class, has_part, mitochondrion inheritance).