DSM & Definitions¶
This bucket holds the two ways to obtain runtime definitions: build them in code
with Definitions, or parse them from .dsm source with
DSMBuilder. Both yield the same kind of registry — concepts, clubs,
enumerations, structures and attachments — that the rest of the runtime resolves
types against. The DSM* classes additionally model the parsed declarations
themselves (a DSMStructure, its DSMStructureFields, and so
on) for introspection.
When to use: reach for Definitions to assemble a schema
programmatically (registering types one call at a time); reach for
DSMBuilder to load and introspect an existing model file. Wrap either
result in a DefinitionsInspector (or DSMDefinitionsInspector)
to query types by name.
Note
The static (code-generation) path that turns a parsed model into a typed module ships in a later release. This page covers the runtime introspection surface only.
Quick Start¶
Build a Definitions registry in code:
const {
Definitions, NameSpace, ValueUUId, Type,
TypeEnumerationDescriptor, TypeStructureDescriptor,
DefinitionsInspector,
} = require('@digitalsubstrate/dsviper');
const defs = new Definitions();
const ns = new NameSpace(ValueUUId.create(), 'Game');
// Concepts and clubs
const player = defs.createConcept(ns, 'Player', 'a participant');
const team = defs.createClub(ns, 'Team');
defs.createMembership(team, player);
// An enumeration, described then registered
const levelDesc = new TypeEnumerationDescriptor('Level');
levelDesc.addCase('beginner');
levelDesc.addCase('expert');
const level = defs.createEnumeration(ns, levelDesc);
// A structure, described field by field
const propsDesc = new TypeStructureDescriptor('Props', 'player properties');
propsDesc.addField('name', Type.STRING);
propsDesc.addField('score', Type.INT64);
const props = defs.createStructure(ns, propsDesc);
// An attachment keys a document type onto a concept
defs.createAttachment(ns, 'props', player, props);
// Inspect the assembled registry
const insp = new DefinitionsInspector(defs.const());
insp.structureTypeNames(); // [ TypeName('Props') ]
insp.checkStructure(props.typeName()); // -> TypeStructure (throws if absent)
Or parse a .dsm model and introspect the result:
const { DSMBuilder } = require('@digitalsubstrate/dsviper');
// assemble(path) loads a file or a directory of .dsm files; or append() in code
const builder = DSMBuilder.assemble('model.dsm');
const [report, dsm, defs] = builder.parse();
// Always check the report before using the definitions
if (report.hasError()) {
for (const err of report.errors()) console.error(err.message());
throw new Error('DSM parse failed');
}
// Walk the parsed declarations
for (const struct of dsm.structures()) {
console.log(`struct ${struct.typeName().name()}`);
for (const field of struct.fields()) {
console.log(` ${field.name()}: ${field.type().typeName().name()}`);
}
}
A parse error is reported through the DSMParseReport, not thrown; a
runtime failure (an unknown type, a duplicate case) surfaces as a JS Error whose
.name is 'ViperError'.
Choosing an entry point¶
Goal |
Start with |
Then |
|---|---|---|
Assemble a schema in code |
|
|
Load a schema from |
|
|
Query types by name |
|
|
Introspect a parsed model |
|
The mirror of this page for the Python binding is DSM & Definitions; for a narrative walkthrough see the DSM guide. The type classes referenced by fields live on Type System.
Generated from the @digitalsubstrate/dsviper TypeScript declarations (index.d.ts) by TypeDoc.
Source map¶
Pass a DSMSourceMap to DSMBuilder.parse(sourceMap) and the parser records, as a
by-product, the exact source span of every declaration, field, case, namespace, type
sub-expression and resolved type-reference. That is what makes a span-precise codemod
possible: patch a hand-authored .dsm in place under a transformation — file split,
comments and ordering preserved — instead of regenerating it. Opt-in: a parse without a
source map is unchanged.
const { DSMBuilder, DSMSourceMap } = require('@digitalsubstrate/dsviper');
const sourceMap = new DSMSourceMap();
const [report, dsmDefs, defs] = DSMBuilder.assemble('model.dsm').parse(sourceMap);
Parsing¶
Class |
Description |
|---|---|
Assembles a DSM model from several sources |
|
One content appended to a DSMBuilder, and where it landed in the assembled text |
|
A model in DSM form, whole: parsed from text by DSMBuilder.parse(), or read back from definitions with fromDefinitions() |
|
Retrieves DSM declarations by TypeName, and attachments by identifier |
|
Collects the errors found while parsing the assembled sources |
|
One parse failure |
Model Elements¶
Class |
Description |
|---|---|
A concept as declared: its qualified name and the concept it specialises, if any |
|
A club as declared: its qualified name and the concepts it gathers |
|
A struct as declared: its qualified name and its fields, in order |
|
One field of a struct, as declared: its name, its type, and the value it defaults to |
|
An enum as declared: its qualified name and its cases, in order |
|
One case of an enum, as declared: its name |
|
An attachment as declared: its qualified name, the key type it files under, and the type of the document it holds |
DSM Types¶
Class |
Description |
|---|---|
A type as a DSM model declares it: the base of the declared type family |
|
The key |
|
The vector |
|
The set |
|
The map<keyType, elementType> as a DSM model declares it |
|
The xarray |
|
The optional |
|
The tuple<T0, …> as a DSM model declares it |
|
The vec<numericType, size> as a DSM model declares it |
|
The mat<numericType, columns, rows> as a DSM model declares it |
|
The variant<T0, …> as a DSM model declares it |
|
A type a DSM model names rather than spells out |
Functions¶
Class |
Description |
|---|---|
A function as declared: its prototype |
|
A function pool as declared: the uuid it is declared under, its name, and its functions |
|
A function signature as declared: its name, its parameters and their types, and what it returns |
|
An attachment function as declared: its prototype, and whether it mutates the document or only reads it |
|
An attachment function pool as declared: the uuid it is declared under, its name, and its functions |
Literals¶
Class |
Description |
|---|---|
What a declaration writes as a literal: the base of DSMLiteralValue and DSMLiteralList |
|
A single literal written in a declaration: which kind it is, and its text |
|
A list literal written in a declaration: the literals it holds |
Definitions¶
Class |
Description |
|---|---|
Registers concepts, clubs, enums, structs and attachments |
|
Retrieves registered types and attachments by runtime id |
|
Gathers the types a subset of definitions references, to hand to DefinitionsConst.extract |
|
Retrieves registered types by TypeName, and attachments by identifier |
|
The runtime ids an extension added: what Definitions.extend or a database’s extendDefinitions gained from the definitions it was given, and what a synchronization added (CommitSynchronizerInfoTransmit.extendInfo) |
|
Rewrites a Type, a Value or an Attachment of sourceDefinitions into the matching declaration of targetDefinitions, matched by name |
Source Map¶
Class |
Description |
|---|---|
A source-map collected while parsing DSM: the exact source spans of every namespace, type declaration (concept, struct, enum, club, attachment), field, case, resolved type-reference and type sub-expression |
|
A source span: a 1-based line in the assembled content, and the [start, stop] offsets into the content the builder assembled |
|
A declaration - struct, enum, concept, club or attachment - with its identifier and its source spans (name, block, documentation) |
|
A struct field and its source spans (name, type, whole declaration, doc) |
|
An enumeration case and its source spans (name, doc) |
|
A namespace declaration and its source spans (name, uuid) |
|
A resolved type-reference site: its source span and its referent TypeName |
|
A type sub-expression occurrence: its source span and its fully-qualified DSM spelling, such as |
Reference¶
- class DSMBuilder()¶
Assembles a DSM model from several sources.
DSM is the human form of what Definitions, Type and Attachment build through the API: a namespace holds concepts, structures, enumerations and clubs, plus the attachments that file a document under a key, and a function pool declares the functions that act on them.
Every type and attachment declared there can be built through the API and read back with DSMDefinitions.fromDefinitions(); the reverse is DSMDefinitions.toDsm(), which renders definitions you already hold back as DSM text. DSMDefinitions.fromFunctionPool has no Node form, the runtime’s function pool class not being bound here; the function pools a model declares parse and read back as usual (functionPools()).
exported from
index.d- DSMBuilder.append(source, content)¶
Append one part of the model, under the name it is known by.
source is that name - a file name, or anything the parse report can point back to. content is the DSM text.
A namespace carries a name and a uuid in braces, and holds the declarations:
- namespace App {6f9619ff-8b86-d011-b42d-00cf4fc964ff} {
concept User; struct Profile { string name; optional<uint32> age; }; attachment<User, Profile> profile;
};
That is the shape, not the whole language: a concept specialises another with ‘is a’, and clubs, memberships, enumerations, field defaults and doc comments sit in the namespace beside these.
A function pool does not: it is declared beside the namespace, at the level of the part, and carries a uuid of its own.
- function_pool Tools {dc9740c9-9d1d-4c1e-9caa-4c8843b91e82} {
int64 add(int64 a, int64 b);
};
- Arguments:
source (string)
content (string)
- DSMBuilder.content()¶
Return every appended part concatenated, which is what parse() reads.
- Returns:
string
- DSMBuilder.lineOffset()¶
Return the line the next appended part will start at, counting from 1.
- Returns:
number
- DSMBuilder.parse(sourceMap)¶
Parse and return (DSMParseReport, DSMDefinitions, DefinitionsConst).
The last two are undefined when parsing failed; the report says why. The DefinitionsConst reads definitions the parse built, which nothing else holds. Pass a DSMSourceMap as sourceMap to have the source spans filled in as it parses. Only a parse that succeeds fills it, and it adds to what the map already holds: pass an empty map to each parse.
What the text declared is reached by name through a DefinitionsInspector over the DefinitionsConst: checkAttachment(‘App::User.profile’) answers the Attachment to write with, checkStructure(new TypeName(ns, ‘Profile’)) the type.
- Arguments:
sourceMap (DSMSourceMap | null)
- Returns:
[DSMParseReport, DSMDefinitions | undefined, DefinitionsConst | undefined]
- DSMBuilder.part(line)¶
- Return the part that holds the 1-based line of the assembled content, or undefined
if no part covers it.
- Arguments:
line (number)
- Returns:
DSMBuilderPart | undefined
- DSMBuilder.parts()¶
Return the list of parts.
- Returns:
DSMBuilderPart[]
- static DSMBuilder.assemble(path)¶
Return a DSMBuilder holding the DSM content found at path.
A file is appended under its file name. A folder appends its .dsm files, sorted by path, each under its path; subfolders are not read. A path that does not exist throws Error.
- Arguments:
path (string)
- Returns:
DSMBuilder
- class DSMBuilderPart()¶
One content appended to a DSMBuilder, and where it landed in the assembled text.
Note: Not directly instantiable.
exported from
index.d- DSMBuilderPart.lineEnd()¶
Return the line the part ends at in the assembled content.
- Returns:
number
- DSMBuilderPart.lineStart()¶
Return the line the part starts at in the assembled content.
- Returns:
number
- DSMBuilderPart.source()¶
Return the name this content was appended under.
- Returns:
string
- class DSMDefinitions()¶
- A model in DSM form, whole: parsed from text by DSMBuilder.parse(), or read back
from definitions with fromDefinitions().
The definitions it declares plus the function pools attached to them. Serialises to and from a blob.
Note: Not directly instantiable.
exported from
index.d- DSMDefinitions.attachmentFunctionPools()¶
Return the list of attachment function pools.
- Returns:
DSMAttachmentFunctionPool[]
- DSMDefinitions.attachments()¶
Return the list of attachments.
- Returns:
DSMAttachment[]
- DSMDefinitions.clubs()¶
Return the list of clubs.
- Returns:
DSMClub[]
- DSMDefinitions.concepts()¶
Return the list of concepts.
- Returns:
DSMConcept[]
- DSMDefinitions.encode(streamCodecInstancing)¶
- Return the blob that encodes the definitions with
Codec.STREAM_TOKEN_BINARY if not specified.
- Arguments:
streamCodecInstancing (StreamCodecInstancing | null)
- Returns:
ValueBlob
- DSMDefinitions.enumerations()¶
Return the list of enumerations.
- Returns:
DSMEnumeration[]
- DSMDefinitions.functionPools()¶
Return the list of function pools.
- Returns:
DSMFunctionPool[]
- DSMDefinitions.structures()¶
Return the list of structures.
- Returns:
DSMStructure[]
- DSMDefinitions.toBsonBlob()¶
Return the definitions in bson.
- Returns:
ValueBlob
- DSMDefinitions.toDefinitions()¶
Return a Definitions by converting all DSM definitions.
- Returns:
Definitions
- DSMDefinitions.toDsm(showDocumentation, showRuntimeId, html, attachments)¶
Return the DSM text of these declarations.
The output is grouped by attachment, two blocks each: the types it depends on, sorted so that every type comes after what it needs, then the attachment itself, the mapping that persists a document under a key. A namespace therefore opens once per block. A comment on each says which it is. With attachments empty or unset, every attachment is rendered, then the function pools, the attachment function pools and every type no block declared yet. attachments restricts the output to those attachments and what they depend on, without function pools. showDocumentation keeps the doc comments, showRuntimeId annotates each declaration with its runtime id, and html wraps every token in a <span> carrying a colour class.
- Arguments:
showDocumentation (boolean | null)
showRuntimeId (boolean | null)
html (boolean | null)
attachments (DSMAttachment[] | null)
- Returns:
string
- DSMDefinitions.toJsonString(indent)¶
- Encode and return the definitions in a JSON encoded string.
If indent is specified, the string is pretty printed.
- Arguments:
indent (number | null)
- Returns:
string
- DSMDefinitions.toXmlString(indent)¶
- Encode and return the definitions in an XML encoded string.
If indent is specified, the string is pretty printed.
- Arguments:
indent (number | null)
- Returns:
string
- DSMDefinitions.write(streamWriting)¶
Write the definitions with the StreamWriting interface.
- Arguments:
streamWriting (StreamWriting)
- static DSMDefinitions.decode(blob, streamCodecInstancing)¶
- Return the decoded DSMDefinitions with Codec.STREAM_TOKEN_BINARY
if not specified.
- Arguments:
blob (ValueBlob)
streamCodecInstancing (StreamCodecInstancing | null)
- Returns:
DSMDefinitions
- static DSMDefinitions.fromBsonBlob(blob)¶
Return a DSMDefinitions from a bson encoded blob.
- Arguments:
blob (ValueBlob)
- Returns:
DSMDefinitions
- static DSMDefinitions.fromDefinitions(definitions)¶
Return the DSM declarations of every type and attachment definitions holds.
- Arguments:
definitions (DefinitionsConst)
- Returns:
DSMDefinitions
- static DSMDefinitions.fromJsonString(jsonString)¶
Return a DSMDefinitions from a JSON encoded string.
- Arguments:
jsonString (string)
- Returns:
DSMDefinitions
- static DSMDefinitions.fromXmlString(xmlString)¶
Return a DSMDefinitions from an XML encoded string.
- Arguments:
xmlString (string)
- Returns:
DSMDefinitions
- static DSMDefinitions.read(streamReading)¶
Return a DSMDefinitions.
- Arguments:
streamReading (StreamReading)
- Returns:
DSMDefinitions
- class DSMDefinitionsInspector(definitions)¶
Retrieves DSM declarations by TypeName, and attachments by identifier.
exported from
index.d- Arguments:
definitions (DSMDefinitions)
- DSMDefinitionsInspector.attachmentFunctionPoolIds()¶
Return the distinct uuid for all attachment function pools.
- Returns:
ValueSet<ValueUUId>
- DSMDefinitionsInspector.attachmentIdentifiers()¶
Return the distinct identifiers for all attachments.
- Returns:
ValueSet<string>
- DSMDefinitionsInspector.checkAttachment(identifier)¶
Return the DSMAttachment whose identifier is identifier, or throw if none is.
- Arguments:
identifier (string)
- Returns:
DSMAttachment
- DSMDefinitionsInspector.checkAttachmentFunctionPool(uuid)¶
Return the DSMAttachmentFunctionPool declared under uuid, or throw if none is.
- Arguments:
uuid (ValueUUId)
- Returns:
DSMAttachmentFunctionPool
- DSMDefinitionsInspector.checkClub(typeName)¶
Return the DSMClub named typeName, or throw if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMClub
- DSMDefinitionsInspector.checkConcept(typeName)¶
Return the DSMConcept named typeName, or throw if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMConcept
- DSMDefinitionsInspector.checkEnumeration(typeName)¶
Return the DSMEnumeration named typeName, or throw if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMEnumeration
- DSMDefinitionsInspector.checkFunctionPool(uuid)¶
Return the DSMFunctionPool declared under uuid, or throw if none is.
- Arguments:
uuid (ValueUUId)
- Returns:
DSMFunctionPool
- DSMDefinitionsInspector.checkStructure(typeName)¶
Return the DSMStructure named typeName, or throw if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMStructure
- DSMDefinitionsInspector.clubTypeNames()¶
Return the distinct TypeName for all clubs.
- Returns:
TypeName[]
- DSMDefinitionsInspector.conceptTypeNames()¶
Return the distinct TypeName for all concepts.
- Returns:
TypeName[]
- DSMDefinitionsInspector.enumerationTypeNames()¶
Return the distinct TypeName for all enums.
- Returns:
TypeName[]
- DSMDefinitionsInspector.functionPoolIds()¶
Return the distinct uuid for all function pools.
- Returns:
ValueSet<ValueUUId>
- DSMDefinitionsInspector.nameSpaces()¶
Return the distinct NameSpace the inspected declarations sit in.
- Returns:
NameSpace[]
- DSMDefinitionsInspector.queryAttachment(identifier)¶
Return the DSMAttachment whose identifier is identifier, or undefined if none is.
- Arguments:
identifier (string)
- Returns:
DSMAttachment | undefined
- DSMDefinitionsInspector.queryAttachmentFunctionPool(uuid)¶
Return the DSMAttachmentFunctionPool declared under uuid, or undefined if none is.
- Arguments:
uuid (ValueUUId)
- Returns:
DSMAttachmentFunctionPool | undefined
- DSMDefinitionsInspector.queryClub(typeName)¶
Return the DSMClub named typeName, or undefined if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMClub | undefined
- DSMDefinitionsInspector.queryConcept(typeName)¶
Return the DSMConcept named typeName, or undefined if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMConcept | undefined
- DSMDefinitionsInspector.queryEnumeration(typeName)¶
Return the DSMEnumeration named typeName, or undefined if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMEnumeration | undefined
- DSMDefinitionsInspector.queryFunctionPool(uuid)¶
Return the DSMFunctionPool declared under uuid, or undefined if none is.
- Arguments:
uuid (ValueUUId)
- Returns:
DSMFunctionPool | undefined
- DSMDefinitionsInspector.queryStructure(typeName)¶
Return the DSMStructure named typeName, or undefined if none is.
- Arguments:
typeName (TypeName)
- Returns:
DSMStructure | undefined
- DSMDefinitionsInspector.representation(typeName)¶
Return the shortest unambiguous spelling of typeName.
The namespace is dropped as far as no other type answers to what is left. DSMSourceType.representation() qualifies instead, so the two answer differently for one type.
- Arguments:
typeName (TypeName)
- Returns:
string
- DSMDefinitionsInspector.structureTypeNames()¶
Return the distinct TypeName for all structs.
- Returns:
TypeName[]
- class DSMParseReport()¶
Collects the errors found while parsing the assembled sources.
Note: Not directly instantiable.
exported from
index.d- DSMParseReport.errors()¶
Return the list of errors.
- Returns:
DSMParseError[]
- DSMParseReport.hasError()¶
Return true if the parse reported at least one error.
- Returns:
boolean
- class DSMParseError()¶
One parse failure.
The source it came from, the line and position, and the message.
Note: Not directly instantiable.
exported from
index.d- DSMParseError.line()¶
Return the 1-based line number within the part source() names.
- Returns:
number
- DSMParseError.message()¶
Return what the parser could not accept, in one sentence.
- Returns:
string
- DSMParseError.pos()¶
Return the 1-based UTF-16 position in the line.
It counts UTF-16 units, as a JS string index and a DSMSourceSpan offset do - but a span counts from 0 over the whole assembled content, so the two do not compare directly. The message, shared with the Python binding, writes the position in code points.
- Returns:
number
- DSMParseError.source()¶
Return the name of the part the error was found in, as appended to the builder.
- Returns:
string
- class DSMConcept()¶
A concept as declared: its qualified name and the concept it specialises, if any.
Note: Not directly instantiable.
exported from
index.d- DSMConcept.documentation()¶
- Return the concept’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMConcept.parent()¶
Return the type reference of the parent concept or undefined.
- Returns:
DSMTypeReference | undefined
- DSMConcept.runtimeId()¶
Return the uuid identifying this type.
It is computed from what the type is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.
- Returns:
ValueUUId
- DSMConcept.typeName()¶
Return the TypeName.
- Returns:
TypeName
- DSMConcept.typeReference()¶
- Return the DSMTypeReference that names this concept where another declaration uses
it.
- Returns:
DSMTypeReference
- class DSMClub()¶
A club as declared: its qualified name and the concepts it gathers.
Note: Not directly instantiable.
exported from
index.d- DSMClub.documentation()¶
- Return the club’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMClub.members()¶
Return the list of member concepts, as type references.
- Returns:
DSMTypeReference[]
- DSMClub.runtimeId()¶
Return the uuid identifying this type.
It is computed from what the type is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.
- Returns:
ValueUUId
- DSMClub.typeName()¶
Return the TypeName.
- Returns:
TypeName
- DSMClub.typeReference()¶
Return the DSMTypeReference that names this club where another declaration uses it.
- Returns:
DSMTypeReference
- class DSMStructure()¶
A struct as declared: its qualified name and its fields, in order.
Note: Not directly instantiable.
exported from
index.d- DSMStructure.documentation()¶
- Return the struct’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMStructure.fields()¶
Return the list of fields.
- Returns:
DSMStructureField[]
- DSMStructure.runtimeId()¶
Return the uuid identifying this type.
It is computed from what the type is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.
- Returns:
ValueUUId
- DSMStructure.typeName()¶
Return the TypeName.
- Returns:
TypeName
- DSMStructure.typeReference()¶
- Return the DSMTypeReference that names this struct where another declaration uses
it.
- Returns:
DSMTypeReference
- class DSMStructureField()¶
One field of a struct, as declared: its name, its type, and the value it defaults to.
Note: Not directly instantiable.
exported from
index.d- DSMStructureField.defaultValue()¶
- Return the literal the field defaults to; a field that declares no default answers a
DSMLiteralValue whose domain() is ‘None’.
- Returns:
DSMLiteral
- DSMStructureField.documentation()¶
- Return the field’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMStructureField.name()¶
Return the field name as declared.
- Returns:
string
- DSMStructureField.type()¶
Return the DSMType the field is declared with.
- Returns:
DSMType
- class DSMEnumeration()¶
An enum as declared: its qualified name and its cases, in order.
Note: Not directly instantiable.
exported from
index.d- DSMEnumeration.documentation()¶
- Return the enum’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMEnumeration.members()¶
Return the list of cases, in declaration order.
- Returns:
DSMEnumerationCase[]
- DSMEnumeration.runtimeId()¶
Return the uuid identifying this type.
It is computed from what the type is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.
- Returns:
ValueUUId
- DSMEnumeration.typeName()¶
Return the TypeName.
- Returns:
TypeName
- DSMEnumeration.typeReference()¶
Return the DSMTypeReference that names this enum where another declaration uses it.
- Returns:
DSMTypeReference
- class DSMEnumerationCase()¶
One case of an enum, as declared: its name.
Note: Not directly instantiable.
exported from
index.d- DSMEnumerationCase.documentation()¶
- Return the case’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMEnumerationCase.name()¶
Return the case name as declared.
- Returns:
string
- class DSMAttachment()¶
- An attachment as declared: its qualified name, the key type it files under, and the
type of the document it holds.
Note: Not directly instantiable.
exported from
index.d- DSMAttachment.documentType()¶
- Return the type of the document as the model writes it - a DSMTypeReference when
it is named, a DSM type such as DSMTypeVector when it is spelled out.
- Returns:
DSMType
- DSMAttachment.documentation()¶
- Return the attachment’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMAttachment.identifier()¶
- Return the identifier, unique among the attachments: the attachment’s namespace, its
key type written relative to that namespace, and its name. App::User.profile for an attachment profile of namespace App on a concept User of App; App::Lib::User.profile when the concept is Lib’s; App::any_concept.tag for a key any_concept.
- Returns:
string
- DSMAttachment.keyType()¶
- Return the reference to the key type: a concept, a club or any_concept (its domain()
says which).
- Returns:
DSMTypeReference
- DSMAttachment.representation()¶
- Return the DSM text of the whole declaration: attachment<keyType, documentType>
followed by the qualified name. The other representation() methods of the DSM classes spell one type.
- Returns:
string
- DSMAttachment.runtimeId()¶
Return the uuid identifying this attachment.
It is computed from what the attachment is, so the same declaration yields the same id in any Definitions. Definitions says what each kind is computed from.
- Returns:
ValueUUId
- DSMAttachment.typeName()¶
Return the TypeName.
- Returns:
TypeName
- class DSMType()¶
A type as a DSM model declares it: the base of the declared type family.
Its subclasses are the parameterized declared types and DSMTypeReference, the leaf that carries a name. Reached from DSMStructureField.type(), DSMAttachment.documentType() and DSMFunctionPrototype.returnType().
Note: Not directly instantiable.
exported from
index.d
- class DSMTypeKey()¶
The key<elementType> as a DSM model declares it.
elementType() is another declared type, so the leaves are names. Definitions holds the registered TypeKey those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeKey.elementType()¶
Return the type of the element.
- Returns:
DSMType
- class DSMTypeVector()¶
The vector<elementType> as a DSM model declares it.
elementType() is another declared type, so the leaves are names. Definitions holds the registered TypeVector those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeVector.elementType()¶
Return type of element.
- Returns:
DSMType
- class DSMTypeSet()¶
The set<elementType> as a DSM model declares it.
elementType() is another declared type, so the leaves are names. Definitions holds the registered TypeSet those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeSet.elementType()¶
Return the type of element.
- Returns:
DSMType
- class DSMTypeMap()¶
The map<keyType, elementType> as a DSM model declares it.
Both are other declared types, so the leaves are names. Definitions holds the registered TypeMap those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeMap.elementType()¶
Return the type of the element.
- Returns:
DSMType
- DSMTypeMap.keyType()¶
Return the type of the key.
- Returns:
DSMType
- class DSMTypeXArray()¶
The xarray<elementType> as a DSM model declares it.
elementType() is another declared type, so the leaves are names. Definitions holds the registered TypeXArray those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeXArray.elementType()¶
Return type of element.
- Returns:
DSMType
- class DSMTypeOptional()¶
The optional<elementType> as a DSM model declares it.
elementType() is another declared type, so the leaves are names. Definitions holds the registered TypeOptional those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeOptional.elementType()¶
Return the type of the element.
- Returns:
DSMType
- class DSMTypeTuple()¶
The tuple<T0, …> as a DSM model declares it.
types() gives the component types, each another declared type, so the leaves are names. Definitions holds the registered TypeTuple those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeTuple.types()¶
Return the list of types.
- Returns:
DSMType[]
- class DSMTypeVec()¶
The vec<numericType, size> as a DSM model declares it.
elementType() is another declared type, so the leaves are names; size is the dimension written in the model. Definitions holds the registered TypeVec those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeVec.elementType()¶
Return the type of element.
- Returns:
DSMType
- DSMTypeVec.size()¶
Return how many components the vec packs.
- Returns:
number
- class DSMTypeMat()¶
The mat<numericType, columns, rows> as a DSM model declares it.
elementType() is another declared type, so the leaves are names; columns and rows are the dimensions written in the model. Definitions holds the registered TypeMat those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeMat.columns()¶
Return the number of columns.
- Returns:
number
- DSMTypeMat.elementType()¶
Return the type of element.
- Returns:
DSMType
- DSMTypeMat.rows()¶
Return the number of rows.
- Returns:
number
- class DSMTypeVariant()¶
The variant<T0, …> as a DSM model declares it.
types() gives the alternatives, each another declared type, so the leaves are names. Definitions holds the registered TypeVariant those names stand for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeVariant.types()¶
Return the list of types.
- Returns:
DSMType[]
- class DSMTypeReference()¶
A type a DSM model names rather than spells out.
Every leaf of a declared type is one of these, string and int32 included: typeName() is the name it resolves to, with its namespace, and domain() the kind it resolves to. Definitions holds the registered type that name stands for.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMType
- DSMTypeReference.domain()¶
- Return what the reference resolves to: ‘Primitive’, ‘Concept’, ‘Club’, ‘Enumeration’,
‘Structure’, ‘Any’ (any) or ‘AnyConcept’ (any_concept).
- Returns:
string
- DSMTypeReference.typeName()¶
Return the TypeName.
- Returns:
TypeName
- class DSMFunction()¶
A function as declared: its prototype.
Note: Not directly instantiable.
exported from
index.d- DSMFunction.documentation()¶
- Return the function’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMFunction.prototype()¶
- Return the DSMFunctionPrototype: the function name, its parameters and its return
type.
- Returns:
DSMFunctionPrototype
- class DSMFunctionPool()¶
- A function pool as declared: the uuid it is declared under, its name, and its
functions.
Note: Not directly instantiable.
exported from
index.d- DSMFunctionPool.documentation()¶
- Return the pool’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMFunctionPool.functions()¶
Return the list of functions.
- Returns:
DSMFunction[]
- DSMFunctionPool.name()¶
Return the pool name as declared.
- Returns:
string
- DSMFunctionPool.uuid()¶
Return the uuid the pool is declared under.
- Returns:
ValueUUId
- class DSMFunctionPrototype()¶
- A function signature as declared: its name, its parameters and their types, and what it
returns.
Note: Not directly instantiable.
exported from
index.d- DSMFunctionPrototype.name()¶
Return the function name as declared.
- Returns:
string
- DSMFunctionPrototype.parameters()¶
Return the list of parameters.
- Returns:
[string, DSMType][]
- DSMFunctionPrototype.returnType()¶
Return the type of the returned value.
- Returns:
DSMType
- class DSMAttachmentFunction()¶
- An attachment function as declared: its prototype, and whether it mutates the document
or only reads it.
Note: Not directly instantiable.
exported from
index.d- DSMAttachmentFunction.documentation()¶
- Return the function’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMAttachmentFunction.isMutable()¶
Return true if the function mutates the state it is given.
- Returns:
boolean
- DSMAttachmentFunction.prototype()¶
- Return the DSMFunctionPrototype: the function name, its parameters and its return
type.
- Returns:
DSMFunctionPrototype
- class DSMAttachmentFunctionPool()¶
- An attachment function pool as declared: the uuid it is declared under, its name, and
its functions.
Note: Not directly instantiable.
exported from
index.d- DSMAttachmentFunctionPool.documentation()¶
- Return the pool’s documentation - its doc comment in the DSM text, or the
documentation given to Definitions - empty when there is none.
- Returns:
string
- DSMAttachmentFunctionPool.functions()¶
Return the list of functions.
- Returns:
DSMAttachmentFunction[]
- DSMAttachmentFunctionPool.name()¶
Return the pool name as declared.
- Returns:
string
- DSMAttachmentFunctionPool.uuid()¶
Return the uuid the pool is declared under.
- Returns:
ValueUUId
- class DSMLiteral()¶
- What a declaration writes as a literal: the base of DSMLiteralValue and
DSMLiteralList.
Reached from DSMStructureField.defaultValue(); narrow it to the concrete class to read what it holds.
Note: Not directly instantiable.
exported from
index.d
- class DSMLiteralValue()¶
- A single literal written in a declaration: which kind it is, and its text. A field that
declares no default answers one too, of domain ‘None’ and value ‘’.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMLiteral
- DSMLiteralValue.domain()¶
- Return which kind of literal this is: ‘Boolean’, ‘Integer’, ‘Float’, ‘Double’,
‘String’, ‘UUId’, ‘EnumerationCase’, or ‘None’ for the literal of a field that declares no default.
- Returns:
string
- DSMLiteralValue.value()¶
Return the literal exactly as written in the source.
- Returns:
string
- class DSMLiteralList()¶
A list literal written in a declaration: the literals it holds.
Note: Not directly instantiable.
exported from
index.d- Extends:
DSMLiteral
- DSMLiteralList.members()¶
Return the list of literals it holds.
- Returns:
DSMLiteral[]
- class Definitions()¶
Registers concepts, clubs, enums, structs and attachments.
Each type gets a runtimeId computed from what it is, so the same declaration yields the same id in any Definitions, and a database keeps its documents under those ids. What goes into the computation differs by kind:
a primitive: its name.
a container, tuple, optional, map, variant or key: its kind and its element types. vector<string> is the same id in two models that share nothing, and a different one from set<string>. Nothing named enters it, so the shape alone identifies the type.
a concept, club, enumeration, structure or attachment: the namespace UUID and the name, together with what defines it - a concept’s parent, an enumeration’s cases or a structure’s fields, an attachment’s key and document types. A club’s members do not enter its id. Adding a field moves the id; renaming the namespace does not, the UUID being what is hashed. The kind does not enter it, and need not: among concepts, clubs, enumerations and structures one name names one type, and registering a second under a name already taken throws, whatever its kind. An attachment’s name is unique over one key concept of its namespace only: it may repeat over another concept, and may be a type’s name.
A name is an ASCII letter, then letters, digits and underscores, and not a word of the definitions’ text form (struct, concept, namespace…); a type’s name is not that of a built-in type (int64, uuid, any…). What a target language reserves is for the code generator to handle.
exported from
index.d- Definitions.const()¶
Return the read-only interface of these definitions.
It is a LIVE view, not a snapshot: a type created here afterwards shows through it. A DefinitionsConst read back from a store is a snapshot instead - same class, opposite liveness.
- Returns:
DefinitionsConst
- Definitions.createAttachment(namespace, name, keyType, documentType, documentation)¶
Create an attachment in namespace and return it.
It is named name, keyed by keyType and holds a document of documentType. documentation is kept on the attachment and read back with documentation().
- Arguments:
namespace (NameSpace)
name (string)
keyType (AbstractionType)
documentType (Type)
documentation (string | null)
- Returns:
Attachment
- Definitions.createClub(namespace, name, documentation)¶
Create a club named name in namespace, and return it.
documentation is kept on the club and read back with documentation().
- Arguments:
namespace (NameSpace)
name (string)
documentation (string | null)
- Returns:
TypeClub
- Definitions.createConcept(namespace, name, documentation, parent)¶
Create a concept named name in namespace, and return it.
parent makes it a specialisation of another concept; documentation is kept on the concept and read back with documentation().
- Arguments:
namespace (NameSpace)
name (string)
documentation (string | null)
parent (TypeConcept | null)
- Returns:
TypeConcept
- Definitions.createEnumeration(namespace, enumerationDescriptor)¶
Create the enum enumerationDescriptor describes, in namespace, and return it.
- Arguments:
namespace (NameSpace)
enumerationDescriptor (TypeEnumerationDescriptor)
- Returns:
TypeEnumeration
- Definitions.createMembership(typeClub, typeConcept)¶
Enrol typeConcept into typeClub.
- Arguments:
typeClub (TypeClub)
typeConcept (TypeConcept)
- Definitions.createStructure(namespace, structureDescriptor)¶
Create the struct structureDescriptor describes, in namespace, and return it.
- Arguments:
namespace (NameSpace)
structureDescriptor (TypeStructureDescriptor)
- Returns:
TypeStructure
- Definitions.extend(definitions)¶
Extend the registered types with those of definitions.
Return information about added definitions. A type registered under the same name, or an attachment under the same name and key, with another runtime id throws ViperError, and nothing is added: every check runs before the first insertion. A club already registered gains the members it lacked.
- Arguments:
definitions (DefinitionsConst)
- Returns:
DefinitionsExtendInfo
- Definitions.extendConcepts(definitions)¶
- Extend the registered concepts with the concepts of definitions, and return the set
of uuid added.
- Arguments:
definitions (DefinitionsConst)
- Returns:
ValueSet<ValueUUId>
- static Definitions.decode(blob, streamCodecInstancing)¶
- Return a Definitions by decoding the blob with Codec.STREAM_TOKEN_BINARY
if not specified.
- Arguments:
blob (ValueBlob)
streamCodecInstancing (StreamCodecInstancing | null)
- Returns:
Definitions
- static Definitions.read(streamReading)¶
Read and return a Definitions.
- Arguments:
streamReading (StreamReading)
- Returns:
Definitions
- class DefinitionsConst()¶
Retrieves registered types and attachments by runtime id.
Note: Not directly instantiable.
exported from
index.d- DefinitionsConst.attachmentRuntimeIds()¶
Return the distinct runtime ID for all attachments.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.attachments()¶
Return the list of attachments.
- Returns:
Attachment[]
- DefinitionsConst.checkAttachment(attachmentRuntimeId)¶
Return the attachment registered under attachmentRuntimeId, or throw if none is.
- Arguments:
attachmentRuntimeId (ValueUUId)
- Returns:
Attachment
- DefinitionsConst.checkClub(runtimeId)¶
Return the club registered under runtimeId, or throw if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeClub
- DefinitionsConst.checkConcept(runtimeId)¶
Return the concept registered under runtimeId, or throw if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeConcept
- DefinitionsConst.checkEnumeration(runtimeId)¶
Return the enum registered under runtimeId, or throw if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeEnumeration
- DefinitionsConst.checkStructure(runtimeId)¶
Return the struct registered under runtimeId, or throw if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeStructure
- DefinitionsConst.checkType(runtimeId)¶
Return the type registered under runtimeId, or throw if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
Type
- DefinitionsConst.clubRuntimeIds()¶
Return the distinct runtime ID for all clubs.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.clubs()¶
Return the list of clubs.
- Returns:
TypeClub[]
- DefinitionsConst.collector()¶
- Return an empty DefinitionsCollector bound to these definitions, to feed extract()
with.
- Returns:
DefinitionsCollector
- DefinitionsConst.conceptMembers(typeConcept)¶
- Return the concepts a key of typeConcept accepts: typeConcept and its descendants. A
club’s membership plays no part.
- Arguments:
typeConcept (TypeConcept)
- Returns:
TypeConcept[]
- DefinitionsConst.conceptRuntimeIds()¶
Return the distinct runtime ID for all concepts.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.concepts()¶
Return the list of concepts.
- Returns:
TypeConcept[]
- DefinitionsConst.contains(definitions)¶
Return true if every type and attachment of definitions is already registered here.
- Arguments:
definitions (DefinitionsConst)
- Returns:
boolean
- DefinitionsConst.copy()¶
- Return a mutable Definitions holding the same types and attachments - the way out of
the const view. Nothing done to it reaches this one.
- Returns:
Definitions
- DefinitionsConst.discard(namespace)¶
- Remove from a target object the objects inject bound for these definitions. A name
bound to anything else is left as it is. If the target is null or omitted, globalThis is used.
- Arguments:
namespace (Record<string, unknown> | null)
- DefinitionsConst.encode(streamCodecInstancing)¶
- Return the blob that encodes the definitions with
Codec.STREAM_TOKEN_BINARY if not specified.
- Arguments:
streamCodecInstancing (StreamCodecInstancing | null)
- Returns:
ValueBlob
- DefinitionsConst.enumerationRuntimeIds()¶
Return the distinct runtime ID for all enums.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.enumerations()¶
Return the list of enums.
- Returns:
TypeEnumeration[]
- DefinitionsConst.extract(definitionsCollector)¶
- Return a new Definitions holding only the types definitionsCollector gathered, and
the types those depend on.
- Arguments:
definitionsCollector (DefinitionsCollector)
- Returns:
Definitions
- DefinitionsConst.hexdigest()¶
Return the SHA1 of the definitions, as a hex string.
It hashes the sorted runtime ids of the concepts, clubs, enumerations, structures and attachments. A runtime id covers neither documentation nor a club’s members, so two Definitions differing only there share it.
- Returns:
string
- DefinitionsConst.inject(namespace)¶
- Bind, on a target object, one object per namespace of the definitions, named as they
name it. If the target is null or omitted, globalThis is used.
The object holds the namespace’s types under their names, and three views: keys, a concept’s or a club’s key type by its name; attachments, by key concept then name; paths, a structure’s field paths by structure then field. Tuto.User, Tuto.keys.User, Tuto.attachments.User.login, Tuto.paths.Login.nickname. A key concept of another namespace takes that namespace in front: App.attachments.Lib_User.profile. The objects are frozen.
A name the target already binds to something inject did not bind throws Error, as do a type named keys, attachments or paths and two key concepts meeting under one name; nothing is bound then. What a previous inject bound under the same name is replaced.
- Arguments:
namespace (Record<string, unknown> | null)
- DefinitionsConst.isEqual(definitions)¶
Return true if definitions holds the same types and attachments.
By runtime ids, so two registries built apart from the same model answer true; documentation and club memberships are not compared. Comparing hexdigest() answers the same question on a string, which is what travels between processes.
- Arguments:
definitions (DefinitionsConst)
- Returns:
boolean
- DefinitionsConst.queryAttachment(attachmentRuntimeId)¶
Return the attachment registered under attachmentRuntimeId, or undefined if none is.
- Arguments:
attachmentRuntimeId (ValueUUId)
- Returns:
Attachment | undefined
- DefinitionsConst.queryClub(runtimeId)¶
Return the club registered under runtimeId, or undefined if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeClub | undefined
- DefinitionsConst.queryConcept(runtimeId)¶
Return the concept registered under runtimeId, or undefined if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeConcept | undefined
- DefinitionsConst.queryEnumeration(runtimeId)¶
Return the enum registered under runtimeId, or undefined if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeEnumeration | undefined
- DefinitionsConst.queryStructure(runtimeId)¶
Return the struct registered under runtimeId, or undefined if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
TypeStructure | undefined
- DefinitionsConst.queryType(runtimeId)¶
Return the type registered under runtimeId, or undefined if none is.
- Arguments:
runtimeId (ValueUUId)
- Returns:
Type | undefined
- DefinitionsConst.queryTypes(name)¶
Return every type whose name is name, across all namespaces.
- Arguments:
name (string)
- Returns:
Type[]
- DefinitionsConst.runtimeIds()¶
Return the distinct runtime ID for all registered types.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.structureRuntimeIds()¶
Return the distinct runtime ID for all structs.
- Returns:
ValueSet<ValueUUId>
- DefinitionsConst.structures()¶
Return the list of structs.
- Returns:
TypeStructure[]
- DefinitionsConst.toDsmDefinitions()¶
Convert and return a DSMDefinitions.
- Returns:
DSMDefinitions
- DefinitionsConst.types()¶
Return the topologically sorted list of types.
- Returns:
Type[]
- DefinitionsConst.write(streamWriting)¶
Write to a stream.
- Arguments:
streamWriting (StreamWriting)
- class DefinitionsCollector()¶
- Gathers the types a subset of definitions references, to hand to
DefinitionsConst.extract.
The runtime ids of the named kinds read back; a container type or an attachment is carried and not listed.
Note: Not directly instantiable.
exported from
index.d- DefinitionsCollector.clubRuntimeIds()¶
Return the set of runtime IDs for collected clubs.
- Returns:
ValueSet<ValueUUId>
- DefinitionsCollector.collectAttachment(attachment)¶
Collect the types referenced by the attachment.
- Arguments:
attachment (Attachment)
- DefinitionsCollector.collectPrototype(prototype)¶
Collect the types referenced by the prototype.
- Arguments:
prototype (FunctionPrototype)
- DefinitionsCollector.collectPrototypes(prototypes)¶
Collect the types referenced by the list of prototypes.
- Arguments:
prototypes (FunctionPrototype[])
- DefinitionsCollector.collectStructureDescriptor(typeStructureDescriptor)¶
Collect the types typeStructureDescriptor references, transitively.
- Arguments:
typeStructureDescriptor (TypeStructureDescriptor)
- DefinitionsCollector.collectType(type)¶
Collect the types referenced by the type.
- Arguments:
type (Type)
- DefinitionsCollector.conceptRuntimeIds()¶
Return the set of runtime IDs for collected concepts.
- Returns:
ValueSet<ValueUUId>
- DefinitionsCollector.enumerationRuntimeIds()¶
Return the set of runtime IDs for collected enumerations.
- Returns:
ValueSet<ValueUUId>
- DefinitionsCollector.hasAny()¶
Return true if the type any was collected.
- Returns:
boolean
- DefinitionsCollector.hasAnyConcept()¶
Return true if the type any_concept was collected.
- Returns:
boolean
- DefinitionsCollector.structureRuntimeIds()¶
Return the set of runtime IDs for collected structures.
- Returns:
ValueSet<ValueUUId>
- class DefinitionsInspector(definitions)¶
Retrieves registered types by TypeName, and attachments by identifier.
An index taken at construction over definitions, which hold lists and no maps. A type registered afterwards is NOT in it: query* answers undefined and check* throws for a type that exists. Build a new inspector: even when the DefinitionsConst it reads is live, this index is not. It also knows which short names are ambiguous, which is what representation() answers with: the shortest spelling that still names one type.
Look a type up with new TypeName(nameSpace, name), or take one from conceptTypeNames(), structureTypeNames(), enumerationTypeNames() or clubTypeNames(). An attachment takes its identifier as a string.
exported from
index.d- Arguments:
definitions (DefinitionsConst)
- DefinitionsInspector.attachmentIdentifiers()¶
Return the distinct identifiers for all attachments.
- Returns:
ValueSet<string>
- DefinitionsInspector.checkAttachment(identifier)¶
Return the attachment whose identifier is identifier, or throw if the index holds none.
- Arguments:
identifier (string)
- Returns:
Attachment
- DefinitionsInspector.checkClub(typeName)¶
Return the club named typeName, or throw if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeClub
- DefinitionsInspector.checkConcept(typeName)¶
Return the concept named typeName, or throw if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeConcept
- DefinitionsInspector.checkEnumeration(typeName)¶
Return the enum named typeName, or throw if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeEnumeration
- DefinitionsInspector.checkStructure(typeName)¶
Return the struct named typeName, or throw if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeStructure
- DefinitionsInspector.clubTypeNames()¶
Return the distinct TypeName for all clubs.
- Returns:
TypeName[]
- DefinitionsInspector.conceptTypeNames()¶
Return the distinct TypeName for all concepts.
- Returns:
TypeName[]
- DefinitionsInspector.enumerationTypeNames()¶
Return the distinct TypeName for all enums.
- Returns:
TypeName[]
- DefinitionsInspector.isAmbiguous(attachment)¶
Return whether attachment needs its key concept qualified.
True when another attachment of the same namespace carries the same name over a key concept of the same SHORT name - two User concepts of different namespaces, each with a profile. A name built from the short form would then name both. The identifier names the attachment whatever this answers.
- Arguments:
attachment (Attachment)
- Returns:
boolean
- DefinitionsInspector.nameSpaces()¶
Return the distinct NameSpace the inspected types are declared in.
- Returns:
NameSpace[]
- DefinitionsInspector.queryAttachment(identifier)¶
Return the attachment whose identifier is identifier, or undefined if the index holds none.
- Arguments:
identifier (string)
- Returns:
Attachment | undefined
- DefinitionsInspector.queryClub(typeName)¶
Return the club named typeName, or undefined if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeClub | undefined
- DefinitionsInspector.queryConcept(typeName)¶
Return the concept named typeName, or undefined if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeConcept | undefined
- DefinitionsInspector.queryEnumeration(typeName)¶
Return the enum named typeName, or undefined if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeEnumeration | undefined
- DefinitionsInspector.queryStructure(typeName)¶
Return the struct named typeName, or undefined if the index holds none.
- Arguments:
typeName (TypeName)
- Returns:
TypeStructure | undefined
- DefinitionsInspector.representation(typeName)¶
- Return the shortest unambiguous spelling of typeName - the namespace is dropped as
far as no other type answers to what is left.
- Arguments:
typeName (TypeName)
- Returns:
string
- DefinitionsInspector.structureTypeNames()¶
Return the distinct TypeName for all structs.
- Returns:
TypeName[]
- class DefinitionsExtendInfo()¶
- The runtime ids an extension added: what Definitions.extend or a database’s
extendDefinitions gained from the definitions it was given, and what a synchronization added (CommitSynchronizerInfoTransmit.extendInfo).
Per kind, plus the memberships between them and a count of the whole. Resolve an id through the target’s DefinitionsConst - checkConcept, checkStructure and their siblings.
Note: Not directly instantiable.
exported from
index.d- DefinitionsExtendInfo.attachmentRuntimeIds()¶
Return the distinct runtime ID for all added attachments.
- Returns:
ValueSet<ValueUUId>
- DefinitionsExtendInfo.clubRuntimeIds()¶
Return the distinct runtime ID for all added clubs.
- Returns:
ValueSet<ValueUUId>
- DefinitionsExtendInfo.conceptRuntimeIds()¶
Return the distinct runtime ID for all added concepts.
- Returns:
ValueSet<ValueUUId>
- DefinitionsExtendInfo.count()¶
Return the count of added definitions.
- Returns:
number
- DefinitionsExtendInfo.enumerationRuntimeIds()¶
Return the distinct runtime ID for all added enumerations.
- Returns:
ValueSet<ValueUUId>
- DefinitionsExtendInfo.memberships()¶
- Return the concepts enrolled into a club the target already held, keyed by the
club’s runtime id as a uuid string, each value the set of the concepts’ runtime ids. A club that was added arrives with its own members, and clubRuntimeIds names it.
- Returns:
Record<string, ValueSet<ValueUUId>>
- DefinitionsExtendInfo.structureRuntimeIds()¶
Return the distinct runtime ID for all added structures.
- Returns:
ValueSet<ValueUUId>
- class DefinitionsMapper(sourceDefinitions, targetDefinitions)¶
- Rewrites a Type, a Value or an Attachment of sourceDefinitions into the matching
declaration of targetDefinitions, matched by name.
Every concept, club, enumeration, structure and attachment of the source must be declared in the target under the same qualified name, or the constructor throws ViperError. type(), value() and attachment() throw ViperError for what the source does not declare. Not part of the supported surface.
exported from
index.d- Arguments:
sourceDefinitions (DefinitionsConst)
targetDefinitions (DefinitionsConst)
- DefinitionsMapper.attachment(attachment)¶
Return the mapped attachment.
- Arguments:
attachment (Attachment)
- Returns:
Attachment
- DefinitionsMapper.source()¶
Return the source.
- Returns:
DefinitionsConst
- DefinitionsMapper.target()¶
Return the target.
- Returns:
DefinitionsConst
- DefinitionsMapper.type(type)¶
Return the mapped type.
- Arguments:
type (Type)
- Returns:
Type
- DefinitionsMapper.value(value)¶
Return the mapped value.
- Arguments:
value (Value)
- Returns:
Value
- class DSMSourceMap()¶
- A source-map collected while parsing DSM: the exact source spans of every namespace,
type declaration (concept, struct, enum, club, attachment), field, case, resolved type-reference and type sub-expression. Function pools are not mapped.
Create an empty one and pass it to DSMBuilder.parse(sourceMap) to fill it.
exported from
index.d- DSMSourceMap.cases()¶
Return the list of DSMSourceCase (enumeration cases).
- Returns:
DSMSourceCase[]
- DSMSourceMap.declarations()¶
Return the list of DSMSourceDeclaration (concept / struct / enum / club / attachment).
- Returns:
DSMSourceDeclaration[]
- DSMSourceMap.fields()¶
Return the list of DSMSourceField (struct fields).
- Returns:
DSMSourceField[]
- DSMSourceMap.nameSpaces()¶
Return the list of DSMSourceNameSpace (namespace headers).
- Returns:
DSMSourceNameSpace[]
- DSMSourceMap.references()¶
Return the list of DSMSourceReference (every resolved type-reference site).
A primitive type is a site too: its referent is in the empty namespace and names no declaration.
- Returns:
DSMSourceReference[]
- DSMSourceMap.types()¶
Return the list of DSMSourceType (every type sub-expression occurrence).
- Returns:
DSMSourceType[]
- class DSMSourceSpan()¶
- A source span: a 1-based line in the assembled content, and the [start, stop]
offsets into the content the builder assembled.
start counts from 0 and stop is inclusive - it is the offset of the last character, not the one past it. An offset counts UTF-16 units, as a JS string index does: content.slice(start, stop + 1) slices the span. (The Python binding counts code points, Python’s string index; past a character above U+FFFF the two differ.)
Note: Not directly instantiable.
exported from
index.d- DSMSourceSpan.line()¶
Return the 1-based line number of the span, in the assembled content.
- Returns:
number
- DSMSourceSpan.start()¶
Return the start UTF-16 offset (inclusive, 0-based) in the assembled content.
- Returns:
number
- DSMSourceSpan.stop()¶
Return the stop UTF-16 offset (inclusive) in the assembled content.
- Returns:
number
- class DSMSourceDeclaration()¶
- A declaration - struct, enum, concept, club or attachment - with its identifier and its
source spans (name, block, documentation).
Note: Not directly instantiable.
exported from
index.d- DSMSourceDeclaration.blockSpan()¶
Return the DSMSourceSpan of the whole declaration block, or null.
It starts at the docstring when there is one and ends with the closing ‘;’.
- Returns:
DSMSourceSpan | null
- DSMSourceDeclaration.documentationSpan()¶
Return the DSMSourceSpan of the docstring, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceDeclaration.identifier()¶
- Return the unique identifier of the declaration:
NameSpace::Namefor a concept, club, enumeration or structure, and for an attachment its namespace, its key type written relative to that namespace, and its name, as Attachment.identifier() writes it.
- Returns:
string
- Return the unique identifier of the declaration:
- DSMSourceDeclaration.nameSpan()¶
Return the DSMSourceSpan of the declaration name, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceDeclaration.typeName()¶
Return the TypeName of the declaration.
- Returns:
TypeName
- class DSMSourceField()¶
A struct field and its source spans (name, type, whole declaration, doc).
Note: Not directly instantiable.
exported from
index.d- DSMSourceField.declarationSpan()¶
Return the DSMSourceSpan of the whole field declaration, or null.
It starts at the docstring when there is one and stops before the ‘;’.
- Returns:
DSMSourceSpan | null
- DSMSourceField.defaultSpan()¶
- Return the DSMSourceSpan of the field’s default clause - the
=through the literal - or null when the field declares no default.
- Returns:
DSMSourceSpan | null
- Return the DSMSourceSpan of the field’s default clause - the
- DSMSourceField.documentationSpan()¶
Return the DSMSourceSpan of the field docstring, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceField.name()¶
Return the field name.
- Returns:
string
- DSMSourceField.nameSpan()¶
Return the DSMSourceSpan of the field name, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceField.structure()¶
Return the TypeName of the enclosing structure.
- Returns:
TypeName
- DSMSourceField.typeSpan()¶
Return the DSMSourceSpan of the field type expression, or null.
It runs from the first character of the type to the field name, the blanks between them included.
- Returns:
DSMSourceSpan | null
- class DSMSourceCase()¶
An enumeration case and its source spans (name, doc).
Note: Not directly instantiable.
exported from
index.d- DSMSourceCase.documentationSpan()¶
Return the DSMSourceSpan of the case docstring, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceCase.enumeration()¶
Return the TypeName of the enclosing enumeration.
- Returns:
TypeName
- DSMSourceCase.name()¶
Return the case name.
- Returns:
string
- DSMSourceCase.nameSpan()¶
Return the DSMSourceSpan of the case name, or null.
- Returns:
DSMSourceSpan | null
- class DSMSourceNameSpace()¶
A namespace declaration and its source spans (name, uuid).
Note: Not directly instantiable.
exported from
index.d- DSMSourceNameSpace.nameSpace()¶
Return the NameSpace.
- Returns:
NameSpace
- DSMSourceNameSpace.nameSpan()¶
Return the DSMSourceSpan of the namespace name, or null.
- Returns:
DSMSourceSpan | null
- DSMSourceNameSpace.uuidSpan()¶
Return the DSMSourceSpan of the namespace UUID, braces included, or null.
- Returns:
DSMSourceSpan | null
- class DSMSourceReference()¶
A resolved type-reference site: its source span and its referent TypeName.
Note: Not directly instantiable.
exported from
index.d- DSMSourceReference.referent()¶
Return the TypeName the reference resolves to.
null only when it did not resolve, which a model that checked never leaves: a source map is built from such a model.
- Returns:
TypeName | null
- DSMSourceReference.span()¶
Return the DSMSourceSpan of the reference site, or null.
- Returns:
DSMSourceSpan | null
- class DSMSourceType()¶
- A type sub-expression occurrence: its source span and its fully-qualified DSM spelling,
such as ‘vector<Shop::Order>’.
Note: Not directly instantiable.
exported from
index.d- DSMSourceType.representation()¶
Return the DSM representation of the type, fully qualified.
It renders what the source declared - ‘vector<Shop::Order>’ - so no namespace is dropped. DSMDefinitionsInspector.representation(typeName) is the one that shortens a name against what is in scope, and answers a shorter spelling for the same type.
- Returns:
string
- DSMSourceType.span()¶
Return the DSMSourceSpan of the whole type expression, or null.
- Returns:
DSMSourceSpan | null