-
Notifications
You must be signed in to change notification settings - Fork 4
Nomenclature
This document identifies the nomenclature used through this documentation, as well as in the source code of the Truth code base. Great care has been (and must continue to be) taken when contributing to this document, as the comprehensibility of the entire project is hinged on it's clarity and specificity.
These terms relate to the parsing of individual lines of Truth code.
Statement - Refers to one single line of code in a file, initiated and terminated by newline characters or file bookends. A statement is separated by a Joint, which creates a left-hand Declaration side and a right-hand Annotation side.
Joint - Refers to the character that separates the Declaration side of a Statement from it's Annotation side. By default, the splitter character is the colon (:). A statement may or may not have a joint.
Vacuous Statement - Refers to a Statement that has no non-erroneous Subjects on either side of it's Joint. Vacuous Statements provide no practical function other than grouping, and are usually not created intentionally by the user directly, but rather are the result of errors being found on each of a statement's subjects.
Subject - An identifiable unit that resides on either the has-a side or is-a side of a Statement. A subject can be pluralized, singularized, or can take the form of a regular expression, or a URI.
Declaration - A Subject located on left of a Statement's Joint. If a statement has no joint, all of it's subjects are considered to be declarations.
Annotation - A Subject located on the right of a Statement's Joint.
Group - Refers to the set of Subjects contained on either the Declaration side or Annotation side of a Statement. The subjects in a group are separated by the Combinator character.
Combinator - Refers to the character the separates the Subjects on one side of a Statement. The default combinator character is the comma (,).
Indent - Refers to the number of whitespace characters that pad the left side of a Statement. The Indent of a statement is only loosely related to it's Depth.
Type URI - A Type URI (or in some places just referred to as a "URI"), refers to a special kind of URI that identifies a Truth document somewhere on some storage location (such as the file system, on an HTTP path), as well as the path to a Type defined within it. Type URIs use the following format:
protocol://path/to/the/file//type/path/goes/here
These terms relate to the operations that are carried out after the entire content of the document has been parsed and organized into a tree, but before any semantic typing has been applied.
Fragment - Refers to a unique instance of a has-a side Subject within a document, along with any of it's associated is-a side annotations. Fragments that share the same name, and are defined within the same scope (but not necessarily the same Locality) are combined to produce a Type.
Locality - Refers to a series of Fragment definitions that all share a common container within the file. The container is a Document in the case when the locality is root-level, and a Pointer when the locality is nested.
Pointer - Refers to a single instance of a Subject within a document, wrapped in an object with supporting properties that allow the precise location of the subject to be discovered within it's containing document. Pointers differ from Type URIs in that a pointer always points to a location in a document where information exists, whereas a Type URIs point to a theoretical location in a document where information may exist.
Thin Pointer - A kind of Pointer that has no underlying Subject. Instead, it refers to a single character position in a document. Thin Pointers are used to mark the has-a side of an anonymous type. Internally, Thin Pointers are assigned Invisible Subjects which are not exposed.
Global Pointer - A Pointer with extended information that allows the targeted location to be uniquely identified globally, across any set of documents.
Invisible Subject - A unique name generated and assigned to Thin Pointers, used for internal identification.
Depth - Refers to the number indicating level of nesting at which a Statement lies within it's parent statements. The Depth of a statement is always either less than or equal to it's Indent.
These terms relate to the operations that are carried out after the syntax tree has been constructed.
Type - The basic unit of the system. A Type is a singular instance of a term present within the member list of either a document, or another type. Types are composed from one or more Fragments, which exist across one or more Localities.
Scope - A grouping mechanism that refers to a series of member types that all share a common parent type. Underneath, scopes are composed from one or more Localities. A scope is owned by a type, which is in turn a member of another scope, and so on and so fourth.
Super - Refers to a scope S that is drawn in to another scope C, via a base defined on the containing type of scope C. This is different from Base. Whereas 'base' refers to the types from which another type extends, Super refers to a scope whose types are implicitly present within another. A type can have many supers. Below is an example:have multiple bases, each which can have their own bases, and so on and so fourth. These bases can be oriented in a diamond pattern, which results in a scope structure that is structured like a graph. This graph of scopes is called the Supergraph.
Specified Declaration - Specified refers to the circumstances when a Type is present within a Scope via an explicit declaration. Unspecified refers to the circumstance where a type is present within a scope not by explicit declaration, but rather through the declaration of a base on the containing type.
Base / Based / Unbased Type - The Base of a Type refers to the type from which another type derives. If a type is Based, it is annotated with another type (in the form of Foo : Bar). In this example Foo is said to be based by Bar. If no basings exist across all constituent fragments of a particular type (within a Scope), the type is said to be Unbased. Types can also be self-based, which is a way of forcing a type to be Fresh. All types which are said to be based are also specified. If a type is based, it cannot be matched.
Matched Annotation - Indicates that an Annotation applied to a Type is matched by a regular expression. If a type is matched, it cannot be based.
Dangling Annotation - Indicates that an Annotation applied to a type could not be resolved to a base, nor could it be matched by a regular expression. Dangling types result in errors, unless an agent indicates otherwise.
Annotated Type - An Annotated Type is one that has non-empty content on the right side of at least one of it's constituent fragments, regardless of whether that type is an Introduction or a Declaration. An annotated type must either Based, Matched, or Dangling (and cannot be more than one of these).
Fresh Type - A kind of Type that draws no information from any other parts of the document. In order for a type to be fresh, it must be specified, unannotated, and both Supergraph Inference and Introduction Inference must have failed.
Override - Opposite of Introduction. If a type is an Override (or is being overridden), it means that one or more equivalently named types exist in the type's Supergraph. Naturally, this means that if the containing scope has no supers, it can therefore have no types that are overrides.
Introduction - Opposite of Override. If a type is an Introduction, (or is being introduced), it means that no equivalently named types exist in the type's Supergraph. Naturally, this means that if the containing scope has no supers, all of it's types are introductions.
Ancestor / Ancestry - The Ancestry of a scope refers to the chain of scopes that contain it.
Inference - Refers to both Supergraph Inference and Introduction Inference collectively.
Supergraph Inference - Refers to the act of inferring the base of an Unannotated Type by checking for an equivalently named type defined in the Supergraph. Note that even if Supergraph Inference passes, the unannotated type is still considered unbased.
Ancestor Inference - Refers to the act of inferring the base of an unannotated type by checking for an equivalently named type defined somewhere in the containing scope's Ancestry. Note that even if Ancestor Inference succeeds in finding such a type, the unannotated type is still considered unbased.
Resolution - Refers to the act of searching upward through successive scope levels for a type with a specific name. Resolution is the process used to identify whether a type is based, matched, or dangling. Resolution follows a unique pattern which is said to be polymorphic, hence other documentation refers to this as Polymorphic Type Resolution.
Dependents - If type Bar is dependent on type Foo, it indicates that type Bar is defined within a scope that is nested within type Foo. A type's dependents therefore refers to the series of types that exist in scopes more deeply nested within it.
Reusables - The Reusables of type T refers to the types that are defined in scopes that are ancestors of the scope in which type T is defined.
Plural - A special kind of Type P that imposes the restriction on it's immediate child types that they must be compatible with P itself. Conceptually, a plural loosely maps to the idea of an Array or Set from traditional programming languages. The differentiating factor from Arrays or Sets is that plurals are designed with the ability to add type-safe information directly on the Plural itself. For example, it may be necessary to attach data directly to a list of items that isn't an item itself, such as sorting information, events, or display options.
Frame - Represents one single state of a document. A Frame is the concept that gives a time dimension to the editing of the document. Every edit to a document (down to the level of single-character changes) causes a new frame to be created for the document. Frames are important because their creation causes a signal to be sent to various caching mechanisms within the system, indicating that their internal structures should be updated or cleared.
Agent - A body of TypeScript code that is plugged into the compiler
Hook - A body of code that executes in response to events that occur within the compiler core. Hooks can potentially produce a return value, which are all collected (and). The compiler core defines a fixed set of events, which are broadcasted
Containment Hierarchy -
Inheritance Hierarchy -