/** * Rendering types as text, with the spans that name a declaration. * * A declaration's own annotation is rendered back to source form: it is * what the author wrote, and for documentation that beats the checker's * normalized spelling of the same type. When there is no annotation — * an inferred `let`, a method with no written return type — the * checker's type is printed with `typeToString` instead, and carries no * links, because there is no annotation node to resolve. * * Rendering happens once, here, and consumers get text plus offsets * rather than a type tree they would each have to render. See * docs/design/zenadoc.md. */ import { TypeAnnotation, NamedTypeAnnotation, UnionTypeAnnotation, NullableTypeAnnotation, FunctionTypeAnnotation, LiteralTypeAnnotation, RecordTypeAnnotation, TupleTypeAnnotation, InlineTypeAnnotation, ThisTypeAnnotation, StringLiteral, NumberLiteral, BooleanLiteral, NullLiteral, Node, } from 'compiler/ast'; import { Type, typeToString } from 'compiler/types'; import { TypeLink, TypeRef } from './model.zena'; import { StringBuilder } from 'zena:core'; /** * Resolves a type-reference node to the id of the declaration it names. * * Implemented over the semantic model; null when the name resolves to * nothing documented — a type parameter, a builtin, a type from a * package this run is not documenting. */ export interface TypeLinker { idFor(annotation: Node): String | null; } /** Accumulates the rendered text and the link spans within it. */ final class Render { sb = new StringBuilder(48); links = new Array(0); linker: TypeLinker | null; new(this.linker); write(s: String): void { this.sb.append(s); } /** * Writes a name and records the span it occupies, when the linker * knows what the name refers to. */ writeName(name: String, node: Node): void { let start = this.sb.length; this.sb.append(name); let linker = this.linker; if (linker != null) { let id = linker.idFor(node); if (id != null) { this.links.push(new TypeLink(start, this.sb.length, id)); } } } finish(): TypeRef { return new TypeRef(this.sb.toString(), this.links); } } /** A type annotation as source text, with links to what it names. */ export function annotationRef( annotation: TypeAnnotation, linker: TypeLinker | null = null ): TypeRef { let out = new Render(linker); renderAnnotation(out, annotation); return out.finish(); } /** A type annotation as source text alone. */ export function annotationText(annotation: TypeAnnotation): String { return annotationRef(annotation, null).text; } function renderAnnotation(out: Render, annotation: TypeAnnotation): void { match (annotation) { case NamedTypeAnnotation as named: renderNamed(out, named) case UnionTypeAnnotation {types}: renderJoined(out, types, ' | ') case NullableTypeAnnotation {typeAnnotation}: renderNullable(out, typeAnnotation) case FunctionTypeAnnotation as fn: renderFunction(out, fn) case LiteralTypeAnnotation {value}: out.write(literalText(value)) case RecordTypeAnnotation as record: renderRecord(out, record) case TupleTypeAnnotation {elementTypes, spreadIndices}: { out.write('('); var i = 0; for (let element in elementTypes) { if (i > 0) { out.write(', '); } if (spreadIndices != null && spreadIndices.contains(i)) { out.write('...'); } renderAnnotation(out, element); i += 1; } out.write(')'); } case InlineTypeAnnotation {typeAnnotation, ifPossible}: { out.write(if (ifPossible) 'inline? ' else 'inline '); renderAnnotation(out, typeAnnotation); } case ThisTypeAnnotation {}: out.write('this') } } function renderNamed(out: Render, named: NamedTypeAnnotation): void { // The name is what a link points at; the type arguments carry their // own, so `Map` links `Map` and `String` separately. out.writeName(named.name, named); let args = named.typeArguments; if (args == null || args.length == 0) { return; } out.write('<'); renderJoined(out, args, ', '); out.write('>'); } /** * `T?`, parenthesized when the inner type would otherwise bind wrong: * `A | B` under a `?` has to read as `(A | B)?`. */ function renderNullable(out: Render, inner: TypeAnnotation): void { let needsParens = match (inner) { case UnionTypeAnnotation {}: true case FunctionTypeAnnotation {}: true case InlineTypeAnnotation {}: true case _: false }; if (needsParens) { out.write('('); } renderAnnotation(out, inner); if (needsParens) { out.write(')'); } out.write('?'); } function renderFunction(out: Render, fn: FunctionTypeAnnotation): void { out.write('('); var i = 0; while (i < fn.params.length) { if (i > 0) { out.write(', '); } if (i < fn.paramNames.length && fn.paramNames[i].length > 0) { out.write(fn.paramNames[i]); out.write(': '); } renderAnnotation(out, fn.params[i]); i += 1; } out.write(') => '); renderAnnotation(out, fn.returnType); } function renderRecord(out: Render, record: RecordTypeAnnotation): void { out.write('{'); let spreads = record.spreads; var written = 0; var si = 0; for (let prop in record.properties) { // Spreads render where they were written, by source position. if (spreads != null) { while (si < spreads.length && startsBefore(spreads[si], prop)) { if (written > 0) { out.write(', '); } out.write('...'); renderAnnotation(out, spreads[si]); written += 1; si += 1; } } if (written > 0) { out.write(', '); } out.write(prop.name.name); if (prop.optional) { out.write('?'); } out.write(': '); renderAnnotation(out, prop.typeAnnotation); written += 1; } if (spreads != null) { while (si < spreads.length) { if (written > 0) { out.write(', '); } out.write('...'); renderAnnotation(out, spreads[si]); written += 1; si += 1; } } if (record.isExistential) { if (written > 0) { out.write(', '); } out.write('...'); } out.write('}'); } /** Whether `a` starts before `b` in the source; false when either has no location. */ function startsBefore(a: Node, b: Node): boolean { let la = a.loc; let lb = b.loc; return la != null && lb != null && la.start < lb.start; } function renderJoined( out: Render, annotations: Array, separator: String ): void { var i = 0; while (i < annotations.length) { if (i > 0) { out.write(separator); } renderAnnotation(out, annotations[i]); i += 1; } } function literalText(value: Node): String { return match (value) { case StringLiteral as s: `'${s.value}'` case NumberLiteral as n: n.raw case BooleanLiteral as b: if (b.value) { 'true' } else { 'false' } case NullLiteral {}: 'null' case _: '?' }; } /** A `TypeRef` for an annotation, or null when there is none. */ export function refFor( annotation: TypeAnnotation | null, linker: TypeLinker | null = null ): TypeRef | null { if (annotation == null) { return null; } return annotationRef(annotation, linker); } /** * A `TypeRef` for an annotation, falling back to a checked type. * * The annotation wins when there is one: `let x: Iterable = …` * documents as `Iterable` even where the checker's type for the * initializer is narrower. A type with no annotation has no node to * resolve, so it carries no links. */ export function refForOrType( annotation: TypeAnnotation | null, type: Type | null, linker: TypeLinker | null = null ): TypeRef | null { if (annotation != null) { return annotationRef(annotation, linker); } if (type != null) { return new TypeRef(typeToString(type), new Array(0)); } return null; }