Skip to content

19. Host declarations and Go bindings

A host declaration gives a signature whose implementation is outside Nomi:

/// An integer of any size.
host type Int

/// Returns the absolute value of n.
host fn abs(n: Int) -> Int
  • host type Name declares a type with no visible fields or body. Its operations are host fn declarations or functions in impl blocks, and its derives and impls are sibling derive and impl declarations.
  • host fn name(params) -> R declares a function with no body. It may also be an item of an impl block, where its host key is module.Type.function.
  • Host declarations take doc comments like any declaration.

host for the standard library, go for user bindings. Every std declaration whose implementation is Go is a host fn or host type, whichever Go package implements it, so importing any std module, std::regex included, needs no Go toolchain. A user binds Go code with gopkg and go (Binding Go packages below); there is no Go-side registration function. Why std does not use go is in the std package doc.

A Go program that embeds Nomi implements the host fns its Nomi program declares from a host table it passes in (the vmhost package doc covers the Go API).

  • A plain host type in such a program is an opaque handle. The table’s functions create and read its values; Nomi code passes them around and stores them. The type needs no registration.
  • A table implements each function by its declaration’s key: its name in the entry file, module.name in another file.
  • A program’s own host functions never implement a std call, nor the reverse, even when a file of the program has a Go-backed std module’s name: a project’s regex.nomi may bind a Go function named compile and use it beside std::regex’s.

Some code runs where nothing may act on the world: a subtype’s or validated type’s rule (§4 Subtypes, §4 Validated types), a typed literal’s handler run at compile time and a checked literal’s check (§18 Typed literals), and an expression a debugger evaluates. Such code may not reach an effect. An effect is one of:

  • a call into Go whose declaration does not mark it pure: output, files, the network, the clock, randomness, tasks, channels and the Context;
  • a read or write of the running app’s fields, its Context or its scope.

A std host fn is marked pure where the standard library binds it to Go, when it computes its answer from its operands alone and acts on nothing outside the program. String.uppercase, Map.get and Date.to_string are pure. A function whose one call costs more as an operand’s value grows, rather than its size, is not marked, so a bounded evaluation never makes it: String.repeat and Decimal.divide are effects here. A user’s go binding (Binding Go packages below), and a function an embedder’s host table implements, is always an effect. Code reaches an effect when its body, or any function it may call, has one; a call through an interface counts every implementation of the method.

Taught in Calling Go.

gopkg "path" as alias declares a handle for a Go package, resolved by Go’s module rules. A Go function binding gives an exported Go function a Nomi name and signature, fn name(params) -> R go alias.Symbol, and is called like any function of its file. After gopkg "strings" as strs, fn upper(s: String) -> String go strs.ToUpper binds Go’s strings.ToUpper as upper. A Go type binding gives a Go type a Nomi name: opaque type Name go alias.Type.

  • The path is a valid Go import path: gopkg "callback:= f(s": not a valid Go import path: invalid char ':'.
  • A Go standard library package needs no go.mod and no Go code of the project’s own; its source is the Go toolchain’s. A package internal to the standard library is an error: gopkg "internal/abi": internal to the Go standard library, which no other module may import.
  • Any other path is provided by the nearest go.mod above the declaring file: a package of the project’s own module, or of a module that go.mod requires or replaces. A path outside those is an error at the path.
  • A file held in memory rather than on disk (one an embedder passes with the source it loads) has no go.mod. Its bindings are implemented by the host table its program is loaded with, and one the table does not implement is a load error naming it.
  • A gopkg is a top-level declaration: a `gopkg` declaration belongs at the top level of a file, beside the `go` bindings that use it; it cannot appear inside a body.
  • The alias in go alias.Symbol is one a gopkg of the same file declares: `go t.ToUpper`: no `gopkg` in this file declares the alias t.
  • A Go type binding is opaque: type B go s.Builder is Go type binding B must be declared with `opaque type` . It may be private, a raw handle behind a Nomi facade (opaque type RawConn go ffi.Conn), or public (pub opaque type Regex go ffi.Regex); either way it can be named and passed but not constructed, unwrapped or inspected.

The task’s context. A Go function whose first parameter is context.Context receives the calling task’s context there, and the binding leaves that parameter out: func Fetch(ctx context.Context, url string) (string, error) binds as fn fetch(url: String) -> Result<String, String> go web.Fetch. The context carries the deadline of the Context in force (with App.context = Context.with_timeout(...)) and ends when the task is cancelled, so a Go call that honours it stops then. A context.Context at any other position is an error at the binding: Go function "Late" in package "example.com/web" takes a context.Context as parameter 2; only a first parameter may be a context.Context, where Go receives the calling task's context. Nomi’s Context value itself does not cross.

Building and running a program with Go bindings is in the tooling reference.

Taught in Calling Go.

A binding’s Nomi types project to Go types:

NomiGo
Stringstring
Boolbool
Int*big.Int; a result also int64, int, the sized signed widths and the unsigned widths other than uint8
Int64, or a subtype of Int within the Go type’s rangeint64, int, the sized signed widths and the unsigned widths other than uint8
Byteuint8
Floatfloat64; also float32
Bytes[]byte
std::io’s Readerio.Reader or io.ReadCloser
std::io’s Writerio.Writer or io.WriteCloser
Durationtime.Duration
Instanttime.Time
List<T>[]T
Map<K, V>map[K]V
Maybe<T>*T (except *big.Int, which is Int)
a declared Nomi structa Go struct with the matching exported fields
Dynamica Go empty interface (any, interface{}, or a named type over one), or rt.Dynamic
a bound opaque Go typeits Go pointer type
a callback (A, ...) -> Rfunc(A, ...) R
a distinct typewhat its inner type projects to
  • Int. An Int is exact at any size, so a fixed-width Go integer that receives one (a parameter, a struct field or element it reaches, a callback’s result) takes a type whose every value it holds: std::int’s Int64 for int64 and int, an intersection such as NonNegativeInt and Int64 for uint64, or a subtype whose when rule bounds it (subtype Int32 Int when fn n -> n >= -2147483648 and n <= 2147483647). The bounds are read from rules that compare the value with Int literals joined by and, through a subtype’s parents and an intersection’s members; a conjunct of another form narrows the values further and is not read. A type that admits a value past the width is an error at the binding, naming the type to declare: Go function "Repeat" in package "strings": parameter count (Int) to Go int: Go int holds an Int in -9223372036854775808..9223372036854775807, and Int admits Ints past that: declare it `Int64` (std::int), or a subtype whose `when` bounds it within that range; a Go function that takes an Int of any size takes *big.Int. A Go function that defines what a larger Int means takes *big.Int, which holds any Int. A Go integer result is an Int whatever its width, a uint64 past 2^63 - 1 included.
  • Byte. Byte is its own type: an Int does not fill a uint8 parameter, and a Byte does not fill an int64 one.
  • Float. A float32 slot is range-checked. NaN and ±Inf cross unchanged, and NaN stays equal to itself under Nomi’s equality.
  • Streams. A Go stream a function returns becomes a Reader or Writer over it, closed through the Go value’s Close when it has one; a Writer hands Go each write as it is made. A stream passed to Go is read or written through the handle’s own buffer and lock, so Go reads what the program would read next, and writes in order with it. The Go type must be the interface itself: a function that returns *gzip.Reader is bound through one that returns io.Reader, and a type that is both a reader and a writer, such as io.ReadWriter or net.Conn, has no projection.
  • Duration. A Duration is an Int of nanoseconds of any size, and a time.Duration 64 bits of them, about 292 years either way. A longer Duration crosses as the longest time.Duration, which a Go wait takes as never ending, and a more negative one as the most negative, already passed.
  • Instant. An Instant is an Int of nanoseconds since the Unix epoch of any size. One crosses to a time.Time exactly, clamped only past about 146 billion years from 1970. A time.Time of any year crosses back as its exact Instant, read from its Unix seconds rather than UnixNano, which wraps outside the years 1677 to 2262; Go’s zero time is the year 1. An Instant returns to Go in UTC, with no zone and no monotonic reading, so two round-tripped times are Equal but not ==.
  • Map. The projected key is a valid Go map key. A Go map projects with its keys in ascending order: strings and numbers in their natural order, false before true, a struct by its exported fields in declaration order. A Go key type with no such order, such as a pointer or an interface, is refused at the binding. Two keys that would become one on either side fail the conversion rather than drop an entry.
  • Structs. Field names are snake_case unless a nomi:"..." tag says otherwise. The Nomi type of a struct value always comes from the declaration at that position (the declared result of the binding, or the declared parameter type of the Nomi function being called), never from the Go type; only the fields are compared, at every depth. So a Go func(Row) bool binds a Nomi (RawRow) -> Bool. The Go struct may be the bound package’s, or one of another package it imports that the project’s go.mod provides, named directly (model.User) or through an alias the bound package declares (type Cell = core.Cell). A struct of a Go standard library package crosses only from a bound standard library package.
  • Dynamic. A Go empty interface holds the value the Dynamic wraps. A Dynamic from Json.to_dynamic holds what encoding/json decodes to: map[string]any, []any, string, float64 or int64, bool, nil. rt.Dynamic from github.com/nomi-language/nomi/rt is the Dynamic itself. Nothing else takes a Dynamic; declare the type the Go value has.
  • Aliases. A Go type alias (type ID = core.ID) projects as its target.
  • Enums. A declared Nomi enum has no projection. The only enums that cross are Result, Maybe and Bool, as a trailing Go error, *T and bool, matched by the std type’s identity: a same-named type of another module is rejected.
  • Results. The Go signature decides the result. With N results that are not error, N == 0 projects to Unit, N == 1 to that value, and N >= 2 to the tuple (A, B, ...). A trailing error wraps that in Result<_, String>: error alone is Result<Unit, String>, (T, error) is Result<T, String>, and (A, B, error) is Result<(A, B), String>.
  • Tuples project in result position only, since Go has no tuple type to take as a parameter. A Go struct against a Nomi struct of the same shape carries several values both ways.
  • Distinct types. A distinct type, opaque or not, crosses as its inner type, at every depth: type Id Int64 as int64, type Ids List<Int64> as []int64, a distinct over a struct as a Go struct with that struct’s fields, and type Outer Inner over type Inner Int64 as int64. The value Go returns is wrapped in the declared type again. std’s Instant and Duration are opaque types over Int, an integer of any size, so one fills a time.Time slot and the other a time.Duration slot, and neither fills an int64 one. A marker type (type Expired) holds no value and has no projection.

The check. Bindings are checked against Go source before the program loads: the project’s own packages, packages of required modules in the Go module cache or a local replace, the packages a bound package’s signatures and struct fields name, and bound standard library packages, read from the toolchain’s GOROOT with this platform’s build constraints. A missing name, a generic Go function and a signature mismatch are errors that point at the binding:

Go function "Index" in package "slices" is generic, and a binding needs one concrete signature; write a non-generic Go function that calls it and bind that
signature mismatch for Go function "ToUpper" in package "strings": parameter 1 "x" projects to String, but Nomi declares Int

The check runs forward only. For each declared Nomi type, it computes the Go type the Nomi type projects to and compares it with the Go type the bound declaration has: a scalar by its row above; Dynamic against a Go empty interface or rt.Dynamic; a List, Maybe, Map, Result, tuple or callback by its structure; an opaque binding by the Go type it binds; a struct of the binding’s file field by field; a distinct type of the binding’s file, and std’s Duration and Instant, through the inner type; and a subtype of a scalar, or an intersection of subtypes, as its base. A subtype is resolved where the binding’s file finds it: declared in that file, in a file it imports (import std::int.Int64, import units.{Pixels}), or in the prelude (NonNegativeInt). Another name declared in another file fills a Go struct slot on trust, its fields held to the Go struct’s when the binding is built, and fills no other slot, so a binding that passes a distinct type declares it in the binding’s file. Whether an Int subtype’s range fits its Go integer is checked when the binding is built, before the program runs (Int above). The inverse is not checked, because a Go type does not determine its Nomi type (int64 is Int64 and every distinct type over it), so an inverse check would reject bindings that work.