// The standard library declarations the compiler has built-in knowledge of, // and where each one lives. // // The compiler cannot recognize these by name alone. A program may declare // its own `Array`, `Error` or `Iterator`, and treating one of those as the // standard library's applies stdlib lowering to a layout that does not // match it. Every check goes through `isWellKnown`, which compares two // things exactly: the declaration's name, and the library that owns the // module declaring it. // // Keying on the library rather than the file means a library may move its // declarations between its own files without touching this table. Moving a // declaration to a different library does change its entry, and because the // checked-in bootstrap carries the old one, such a move takes two steps: // add the new library here, reseed, then move the declaration. // // To give the compiler knowledge of another declaration, add a variant and // a row to `buildLocations`. Those are the only two places a well-known // declaration is written down. import { stdlibLibraryOf } from './stdlib-manifest.zena'; import { HashMap } from 'zena:collections'; /** A standard library declaration the compiler treats specially. */ export enum WellKnown { /** `String`, which backs string literals and concatenation. */ StringClass, /** `TemplateStringsArray`, the first argument of a tagged template. */ TemplateStringsArrayClass, /** `Box`, which a tagged template's primitive interpolation is * wrapped in when the tag's value type accepts the box. */ BoxClass, /** `Error`, the type `throw` and `catch` trade in. */ ErrorClass, /** `Iterator` and `Iterable`, the `for`-in protocol. */ IteratorInterface, IterableInterface, /** `AsyncIterator` and `AsyncIterable`, what a `for await` adds * to it (docs/design/async-iteration.md). */ AsyncIteratorInterface, AsyncIterableInterface, /** The array types, which back array literals and indexed `for`-in. */ ArrayInterface, MutableArrayInterface, FixedArrayClass, ImmutableArrayClass, GrowableArrayClass, /** The ranges a range literal builds: `Range` is their base, and * `BoundedRange` and `FromRange` are the two a `for`-in compiles to a * counting loop. */ RangeClass, BoundedRangeClass, FromRangeClass, ToRangeClass, FullRangeClass, /** `StringIndex`, the other type a range literal's bounds may have. */ StringIndexAlias, /** `HashMap`, which a map literal builds. */ HashMapClass, /** `Future` and `CancelScope`, which `async`/`await` lower onto. */ FutureClass, CancelScopeClass, /** `TaskGroup`, whose `cancel` is the whole-program cancellation * gate's evidence: the one call that marks a scope cancelled. */ TaskGroupClass, /** `Awaited`, the type operator an `await`'s result is read through. */ AwaitedAlias, /** `Hashable`, which a generic's `Hashable` bound is satisfied against * — including by primitives, which implement it structurally. */ HashableInterface, /** `Equatable`, satisfied the same way as `Hashable`: by primitives * structurally, and by case classes that derive their equality. */ EquatableInterface, /** `Stringable`, which opts a class into custom string conversion * via `[Stringable.toString]()`. */ StringableInterface, /** `Resource`, the bound `resource class` and the ownership handles * are checked against. */ ResourceClass, /** The three ownership handles, which are distinct type aliases. */ OwnAlias, BorrowAlias, UnmanagedAlias, /** `Scoped`, the no-duplicate no-escape corner (not a handle). */ ScopedAlias, /** `Option`, what a Pending iteration step's future settles with. */ OptionAlias, /** `BigInt`, which backs `n`-suffixed and contextually typed integer literals. */ BigIntClass, } /** * Where a well-known declaration lives: its local name, the library that * owns it, and — only while it is being moved between libraries — the * library it is moving to. * * Both libraries are exact names compared with `==`; `movingTo` is not a * relaxation of the match, it is a second exact answer that is true for * the length of a migration. It exists because the checked-in bootstrap * carries this table: a declaration cannot move to a library the * bootstrap has never heard of, so the new location has to be accepted * for one reseed before the file moves, and dropped after the next one. * See docs/design/stdlib-organization.md, Phase 1. */ final class Location { library: String; name: String; movingTo: String | null; new(this.library, this.name, this.movingTo = null); } var locations: HashMap | null = null; var ordered: GrowableArray | null = null; function buildLocations() { let t = new Map(); let order = new Array(); let add = (w: WellKnown, library: String, name: String) => { t[w as i32] = new Location(library, name); order.push(w); }; /** Registers a declaration that is mid-move to another library. */ let moving = (w: WellKnown, library: String, name: String, movingTo: String) => { t[w as i32] = new Location(library, name, movingTo); order.push(w); }; add(WellKnown.StringClass, 'core', 'String'); add(WellKnown.TemplateStringsArrayClass, 'core', 'TemplateStringsArray'); add(WellKnown.BoxClass, 'core', 'Box'); add(WellKnown.ErrorClass, 'core', 'Error'); add(WellKnown.IteratorInterface, 'core', 'Iterator'); add(WellKnown.IterableInterface, 'core', 'Iterable'); add(WellKnown.ArrayInterface, 'core', 'Array'); add(WellKnown.MutableArrayInterface, 'core', 'MutableArray'); add(WellKnown.FixedArrayClass, 'core', 'FixedArray'); add(WellKnown.ImmutableArrayClass, 'core', 'ImmutableArray'); add(WellKnown.GrowableArrayClass, 'core', 'GrowableArray'); add(WellKnown.RangeClass, 'core', 'Range'); add(WellKnown.BoundedRangeClass, 'core', 'BoundedRange'); add(WellKnown.FromRangeClass, 'core', 'FromRange'); add(WellKnown.ToRangeClass, 'core', 'ToRange'); add(WellKnown.FullRangeClass, 'core', 'FullRange'); add(WellKnown.StringIndexAlias, 'core', 'StringIndex'); add(WellKnown.HashMapClass, 'collections', 'HashMap'); // Declared in async/future.zena, a private file of zena:async. Keying on // the library is what lets that be true without a prefix match. add(WellKnown.FutureClass, 'async', 'Future'); add(WellKnown.CancelScopeClass, 'async', 'CancelScope'); add(WellKnown.TaskGroupClass, 'async', 'TaskGroup'); add(WellKnown.AwaitedAlias, 'async', 'Awaited'); add(WellKnown.HashableInterface, 'core', 'Hashable'); add(WellKnown.EquatableInterface, 'core', 'Equatable'); add(WellKnown.StringableInterface, 'core', 'Stringable'); add(WellKnown.ResourceClass, 'core', 'Resource'); add(WellKnown.OwnAlias, 'core', 'Own'); add(WellKnown.BorrowAlias, 'core', 'Borrow'); add(WellKnown.UnmanagedAlias, 'core', 'Unmanaged'); add(WellKnown.ScopedAlias, 'core', 'Scoped'); add(WellKnown.OptionAlias, 'core', 'Option'); add(WellKnown.AsyncIteratorInterface, 'async', 'AsyncIterator'); add(WellKnown.AsyncIterableInterface, 'async', 'AsyncIterable'); add(WellKnown.BigIntClass, 'bigint', 'BigInt'); locations = t; ordered = order; return t; } /** * Every well-known declaration, in registration order. A caller that has to * visit them all — filling the checker's table as each library is checked — * iterates this instead of repeating the list. */ export function allWellKnown(): GrowableArray { if (ordered == null) { buildLocations(); } return ordered as GrowableArray; } function locationOf(w: WellKnown): Location { let t = if (locations != null) { locations as HashMap } else { buildLocations() }; if (let (true, loc) = t.get(w as i32)) { return loc; } // Unreachable unless a variant was added without a row. throw new Error('No location registered for well-known declaration ' + i32ToString(w as i32)); } /** The library `w` is declared in. */ export function wellKnownLibrary(w: WellKnown): String { return locationOf(w).library; } /** The name `w` is declared under, inside its library. */ export function wellKnownName(w: WellKnown): String { return locationOf(w).name; } /** * The standard library symbols the compiler names itself, and the fixed * member key each one keys. * * A member keyed by a symbol is normally keyed by that symbol's identity, * minted per compilation (`:act_87`), so two same-named symbols key two * members. Codegen cannot resolve anything, though, so the members it * calls on its own — the release action it runs when a resource is * dropped, the iterator a `for`-in asks for, the async runtime's hooks — * have to be nameable as constants. Each row is one such symbol: the * library that declares it, the type that declares it when it is a * `static symbol` (empty for a top-level `symbol`), and its name. * * Matching is exact on all three, so a program's own `symbol complete` or * `interface Disposable` keys by identity like any other symbol. */ final class ProtocolSymbol { library: String; owner: String; name: String; new(this.library, this.owner, this.name); } var protocolSymbols: GrowableArray | null = null; function buildProtocolSymbols() { let t = new Array(); let add = (library: String, owner: String, name: String) => { t.push(new ProtocolSymbol(library, owner, name)); }; // Dropping a resource runs its release action. add('core', 'Disposable', 'dispose'); // Custom string conversion for template literals and `toString()`. add('core', 'Stringable', 'toString'); // A `for`-in over anything but an array asks for an iterator; a // `for await` over an asynchronous iterable asks its own symbol. add('core', 'Iterable', 'iterator'); add('async', 'AsyncIterable', 'asyncIterator'); // The async runtime's hooks, which `async`/`await` lower onto. add('async', '', 'registerTask'); add('async', '', 'install'); add('async', '', 'checkpoint'); add('async', '', 'shieldScope'); add('async', '', 'childScope'); add('async', '', 'cancelScope'); add('async', '', 'subscribe'); add('async', '', 'valueOrThrow'); add('async', '', 'complete'); add('async', '', 'fail'); add('async', '', 'adoptFrom'); add('async', '', 'cancelComplete'); // An implicit drop of a future of an owner releases through it. add('async', '', 'release'); protocolSymbols = t; return t; } /** * The fixed member key of the symbol `name` declared in `modulePath` — * on the type `owner`, or at the top level when `owner` is empty — when * it is one the compiler names itself; null for every other symbol. */ export function protocolSymbolKey( owner: String, name: String, modulePath: String): String | null { let library = stdlibLibraryOf(modulePath); if (library == null) { return null; } let rows = if (protocolSymbols != null) { protocolSymbols as GrowableArray } else { buildProtocolSymbols() }; for (let row in rows) { if (row.name == name && row.owner == owner && row.library == (library as String)) { return ":" + name; } } return null; } /** * Whether a declaration named `name` in the module `modulePath` is the * well-known declaration `w`. * * `modulePath` is the canonical id of the declaring module — `sourcePath` * on a class, interface or mixin type, `declaringModule` on a type alias. * Both halves are compared exactly, and a module outside the standard * library belongs to no library and so matches nothing. * * The name is tested first because it rules out almost every call without * touching the manifest. */ export function isWellKnown(w: WellKnown, name: String, modulePath: String): boolean { let loc = locationOf(w); if (name != loc.name) { return false; } let library = stdlibLibraryOf(modulePath); if (library == null) { return false; } let owner = library as String; if (owner == loc.library) { return true; } let movingTo = loc.movingTo; return movingTo != null && owner == (movingTo as String); }