API reference

The exact public surface for embedders. Only the index.ts re-exports listed here are public; everything else is package-private. Pipeline for an embed: parse → loadExternalData → resolve → expand → renderHtml.

witlang/parser

Package @witlang/parser.

parse(source: string, file?: string): Document
parseInlineFromText(...): Inline[]        // inline sub-parser
tryParseRecordFromText(...): Record | null
tryParseCollectionFromText(...): Collection | null
format(source: string, opts?: FormatOptions): string
FormatOptions { indent: string }          // default &#39;  &#39;
class WitError { code; loc; message }

parseInlineFromText

re-parses captured raw values at substitution time; the two tryParse… scanners parse late-bound record and collection text.

Types re-exported:

Document · Block · Inline · AstNode · Paragraph · Comment · NodeUse · NodeDef · DataDef · Record · Collection · IfStatement · EachStatement · ScriptBlock · ScriptCall · ReferenceDirective · Text · Italic · Bold · Interpolation · BodySlot · DataValue · StringValue · NumberValue · BooleanValue · NullValue · Condition · ExistenceCondition · ComparisonCondition · Param · AccessPath · Loc · HasLoc.

witlang/runtime

Package @witlang/runtime.

resolve(doc: Document, options?: ResolveOptions): ResolvedDocument
ResolveOptions { rootPath?; fileReader?; onMissingReference? }
expand(resolved: ResolvedDocument): ExpandedDocument
loadExternalData(doc: Document, source: DataSource): Document
DataSource = DataLoader | Record<string, unknown>
toDataValue(value: unknown, loc: Loc): DataValue
class RuntimeError / ResolverError / ExpanderError
RuntimeErrorCode                          // the code constants
CORE_VOCAB_NAMES / RESERVED_OPAQUE
isCoreVocabName(name) / isReservedNodeName(name)

loadExternalData

is the load pass; a plain { alias: value } dictionary is the simplest embedded DataSource. resolve throws ResolverError; expand throws ExpanderError.

Types re-exported:

DataLoader · DataLoadRequest · DataSource · ResolvedDocument · ExpandedDocument · ResolveOptions · FileReader · RuntimeErrorCodeName.

witlang/render-html

Package @witlang/render-html.

renderHtml(doc: ExpandedDocument, options?: RenderHtmlOptions): string
RenderHtmlOptions {
  mode?: &#39;fragment&#39; | &#39;document&#39;   // default &#39;fragment&#39;
  title?: string                   // default &#39;Wit document&#39;
  lang?: string                    // default &#39;en&#39;
  css?: string                     // default defaultThemeCss; &#39;&#39; = unstyled
}
escapeHtml(s: string): string
defaultThemeCss / rawThemeCss      // string constants

renderHtml

defaults to fragment mode — the CLI's --raw / --fragment pathways select mode and CSS on top of this.

witlang/render-markdown

Package @witlang/render-markdown. One export:

renderMarkdown(doc: ExpandedDocument): string

End-to-end embed

import { parse } from &#39;@witlang/parser&#39;;
import { loadExternalData, resolve, expand } from &#39;@witlang/runtime&#39;;
import { renderHtml } from &#39;@witlang/render-html&#39;;

const doc = parse(source, &#39;doc.wit&#39;);
const loaded = loadExternalData(doc, { sales: [{ region: &#39;West&#39;, total: 100 }] });
const html = renderHtml(expand(resolve(loaded)), { mode: &#39;document&#39; });