lower

Documentation

Overview

Package lower is bento's ahead-of-time type lowering: it turns the resolved, flow-narrowed types the frontend hands it (pkg/frontend) into the Go source the Go toolchain then compiles. It implements 05_type_lowering.md.

Lowering is a translation, not a type inference. The frontend already ran the real TypeScript checker, so every type that reaches here is settled, and the partitioner (pkg/partition, 06_compile_vs_interpret.md) already promised the unit is lowerable before handing it over. Lowering's contract in return is that it never emits unsound Go: when it meets a construct it does not render, it reports a NotYetLowerable error rather than guess, and the caller routes that unit to the engine (05_type_lowering.md section 30).

This file owns the type renderer: the mapping from one frontend.Type to the Go type expression that represents it, together with the generated named declarations (structs today, tagged unions and vtables in later slices) that the expression refers to. The mapping table is 05_type_lowering.md section 31; each row is a case here or an explicit NotYetLowerable until its slice lands.

Index

• type Decl
• type NotYetLowerable
  • func (e *NotYetLowerable) Error() string
• type Program
• type Renderer
  • func NewRenderer(prog *frontend.Program) *Renderer
  • func (r *Renderer) CheckBlockScopeEarlyErrors(roots ...frontend.Node) error
  • func (r *Renderer) DeclNodes() []ast.Decl
  • func (r *Renderer) Decls() []Decl
  • func (r *Renderer) GoImportPaths() []string
  • func (r *Renderer) Imports() []string
  • func (r *Renderer) RenderFunc(fn frontend.Node) (Decl, error)
  • func (r *Renderer) RenderProgram(entry frontend.Node) (Program, error)
  • func (r *Renderer) RenderProgramModules(entry frontend.Node, deps []frontend.Node) (Program, error)
  • func (r *Renderer) RenderType(t frontend.Type) (string, error)
  • func (r *Renderer) SetGoConstants(resolve func(importPath, name string) (goimport.ConstInfo, bool))
  • func (r *Renderer) SetGoErrorVars(resolve func(importPath, name string) bool)
  • func (r *Renderer) SetGoSignatures(resolve func(importPath, name string) (goimport.FuncSig, bool))

Types

type Decl

type Decl struct {
	Name   string
	Source string
}

Decl is one generated Go declaration: a name and its gofmt-clean source.

type NotYetLowerable

type NotYetLowerable struct {
	// Flags is the coarse classification of the type that could not be lowered,
	// enough for a diagnostic without holding the type across the boundary.
	Flags frontend.TypeFlags
	// Reason is a short human explanation of why this construct is not lowered
	// yet, phrased as the boundary it hit.
	Reason string
	// Where is the source position of the construct, empty when the handback was
	// raised somewhere with no node in hand. A reason names a shape, and a program
	// the size of a Node test has many of that shape, so the reason on its own says
	// what is missing and not where to look. Finding the one line behind a family of
	// a thousand tests meant bisecting the file by hand twice before this was here.
	Where string
}

NotYetLowerable is the reason lowering hands a unit back to the partitioner instead of emitting Go. It is not an internal failure: it is the honest edge of the compiled subset (05_type_lowering.md section 30), naming the construct that has no lowering yet so the partitioner can route the unit to the engine and a later slice can grow the covered set.

func (*NotYetLowerable) Error

func (e *NotYetLowerable) Error() string

type Program

type Program struct {
	Source string
}

Program is the assembled Go source for one compiled entry module. Source is a complete, gofmt-clean package main file the Go toolchain builds directly.

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer renders the types of one checked program to Go. It accumulates the named declarations its rendered expressions refer to, so a caller renders a set of types and then emits Decls once. A Renderer is scoped to a single program because it keys generated struct names on the program's structural type identity (05_type_lowering.md section 29), which is only stable within one program.

func NewRenderer

func NewRenderer(prog *frontend.Program) *Renderer

NewRenderer builds a renderer over a checked program.

func (*Renderer) CheckBlockScopeEarlyErrors

func (r *Renderer) CheckBlockScopeEarlyErrors(roots ...frontend.Node) error

CheckBlockScopeEarlyErrors walks the given source roots for the block-scoped function-declaration-versus-var collision and returns a plain error naming the clashing binding on the first one it finds, or nil when none is present. The error is intentionally not a *NotYetLowerable: it is a real early-error rejection the build surfaces the way it surfaces a checker diagnostic, so a parse-phase negative test scores a pass rather than a handback.

func (*Renderer) DeclNodes

func (r *Renderer) DeclNodes() []ast.Decl

DeclNodes returns the same generated declarations as their go/ast nodes, in the same first-seen order, so the program assembler can splice them into the one file it prints rather than reparse the text Decls returns.

func (*Renderer) Decls

func (r *Renderer) Decls() []Decl

Decls returns the generated declarations the rendered types referred to, in a stable first-seen order, each a gofmt-clean Go declaration. A caller emits them once alongside the lowered functions that use them.

func (*Renderer) GoImportPaths

func (r *Renderer) GoImportPaths() []string

GoImportPaths returns the Go import paths the rendered program reaches through a go: interop call, sorted, with no duplicates. It reads the alias map, which is populated only as a package is actually called into, so a go: import that is declared but never called is not listed. The build consults this to detect whether any reached package pulls in cgo before it runs the toolchain (document 16 section 9.5), the one caller that needs the interop paths apart from the import block importSpecs already assembles.

func (*Renderer) Imports

func (r *Renderer) Imports() []string

Imports returns the import paths the emitted Go refers to, sorted so the output is deterministic. A caller writes one import per path into the file it assembles around the rendered declarations.

func (*Renderer) RenderFunc

func (r *Renderer) RenderFunc(fn frontend.Node) (Decl, error)

RenderFunc lowers a function declaration to its Go declaration: the signature from the checker plus a lowered body. It returns a NotYetLowerable for any construct the statement and expression subset does not cover yet, so a caller emits Go only for what lowers soundly.

func (*Renderer) RenderProgram

func (r *Renderer) RenderProgram(entry frontend.Node) (Program, error)

RenderProgram lowers one entry source file to a runnable Go program. Top-level function declarations become package-level Go functions, and the remaining top-level statements become the body of main in source order, so the module's side effects run when the binary runs. Top-level classes become a struct, a NewX constructor, and pointer-receiver methods (classes.go). A construct the statement subset does not cover, or a top-level form that is neither a function, a class, nor a lowerable statement (an import, an export), hands back.

The module's own top-level bindings are locals of main, so a top-level function that reads one is not yet supported: the function is a separate Go declaration that cannot see main's locals, which would fail the Go build rather than emit wrong output. Hoisting shared module bindings to package-level vars is a later slice; today a program whose functions are self-contained (the common shape of the compute workloads, which are a single top-level body) compiles.

func (*Renderer) RenderProgramModules

func (r *Renderer) RenderProgramModules(entry frontend.Node, deps []frontend.Node) (Program, error)

RenderProgramModules lowers an entry source file together with the sibling modules it imports, which the build composed and staged alongside it, into one runnable Go program. The entry lowers exactly as it does alone: its top-level statements become main's body and its declarations become package-level Go. A sibling contributes its declarations to the same package, so an import of one of its exports resolves to a package-level Go name the entry references directly. This slice composes a sibling's declarations, not its top-level evaluation: a sibling that carries runtime, a variable statement or a side-effecting statement whose order the composed unit would have to preserve, hands back (see collectModules). With no siblings this is exactly the single-file path.

func (*Renderer) RenderType

func (r *Renderer) RenderType(t frontend.Type) (string, error)

RenderType returns the Go type expression that represents t, registering any named declarations it needs (a struct for an object shape) into the renderer. It returns a NotYetLowerable error for a construct whose slice has not landed, which is the section 30 handoff, never a silent wrong answer.

func (*Renderer) SetGoConstants

func (r *Renderer) SetGoConstants(resolve func(importPath, name string) (goimport.ConstInfo, bool))

SetGoConstants wires the resolver a go: constant reference marshals against, the companion to SetGoSignatures for a binding used as a value rather than called. It is set from the same Go package load; a renderer with no resolver hands a reference to a go: binding back rather than guess whether it is a constant.

func (*Renderer) SetGoErrorVars

func (r *Renderer) SetGoErrorVars(resolve func(importPath, name string) bool)

SetGoErrorVars wires the resolver a caught error's is() checks a go: sentinel against, so err.is(EOF) lowers to errors.Is against io.EOF. It is set from the same Go package load; a renderer with no resolver hands err.is back rather than guess whether a bound name is an error variable.

func (*Renderer) SetGoSignatures

func (r *Renderer) SetGoSignatures(resolve func(importPath, name string) (goimport.FuncSig, bool))

SetGoSignatures wires the resolver a go: call marshals numbers against, so a Go int, int64, and float64 (all one TypeScript number) each cross the boundary with the right conversion and range check. The build sets it from the Go package load the declaration generator already ran; a renderer with no resolver lowers only the string and boolean crossings a TypeScript type settles on its own.