19. Host declarations and Go bindings
Host and foreign declarations
Section titled “Host and foreign declarations”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 Namedeclares a type with no visible fields or body. Its operations arehost fndeclarations or functions inimplblocks, and its derives and impls are siblingderiveandimpldeclarations.host fn name(params) -> Rdeclares a function with no body. It may also be an item of animplblock, where its host key ismodule.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.
host declarations and embedders
Section titled “host declarations and embedders”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 typein 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.namein 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.nomimay bind a Go function namedcompileand use it besidestd::regex’s.
Effects
Section titled “Effects”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
Contextor 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.
Binding Go packages: gopkg and go
Section titled “Binding Go packages: gopkg and go”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.modand 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.modabove the declaring file: a package of the project’s own module, or of a module thatgo.modrequires 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
gopkgis 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.Symbolis one agopkgof 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.BuilderisGo 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.
How Nomi types project to Go
Section titled “How Nomi types project to Go”Taught in Calling Go.
A binding’s Nomi types project to Go types:
| Nomi | Go |
|---|---|
String | string |
Bool | bool |
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 range | int64, int, the sized signed widths and the unsigned widths other than uint8 |
Byte | uint8 |
Float | float64; also float32 |
Bytes | []byte |
std::io’s Reader | io.Reader or io.ReadCloser |
std::io’s Writer | io.Writer or io.WriteCloser |
Duration | time.Duration |
Instant | time.Time |
List<T> | []T |
Map<K, V> | map[K]V |
Maybe<T> | *T (except *big.Int, which is Int) |
| a declared Nomi struct | a Go struct with the matching exported fields |
Dynamic | a Go empty interface (any, interface{}, or a named type over one), or rt.Dynamic |
| a bound opaque Go type | its Go pointer type |
a callback (A, ...) -> R | func(A, ...) R |
| a distinct type | what its inner type projects to |
- Int. An
Intis 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’sInt64forint64andint, an intersection such asNonNegativeInt and Int64foruint64, or a subtype whosewhenrule 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 byand, 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 largerIntmeans takes*big.Int, which holds anyInt. A Go integer result is anIntwhatever its width, auint64past 2^63 - 1 included. - Byte.
Byteis its own type: anIntdoes not fill auint8parameter, and aBytedoes not fill anint64one. - Float. A
float32slot is range-checked.NaNand±Infcross unchanged, andNaNstays equal to itself under Nomi’s equality. - Streams. A Go stream a function returns becomes a
ReaderorWriterover it, closed through the Go value’sClosewhen it has one; aWriterhands 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.Readeris bound through one that returnsio.Reader, and a type that is both a reader and a writer, such asio.ReadWriterornet.Conn, has no projection. - Duration. A
Durationis anIntof nanoseconds of any size, and atime.Duration64 bits of them, about 292 years either way. A longerDurationcrosses as the longesttime.Duration, which a Go wait takes as never ending, and a more negative one as the most negative, already passed. - Instant. An
Instantis anIntof nanoseconds since the Unix epoch of any size. One crosses to atime.Timeexactly, clamped only past about 146 billion years from 1970. Atime.Timeof any year crosses back as its exactInstant, read from its Unix seconds rather thanUnixNano, which wraps outside the years 1677 to 2262; Go’s zero time is the year 1. AnInstantreturns to Go in UTC, with no zone and no monotonic reading, so two round-tripped times areEqualbut 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,
falsebeforetrue, 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 Gofunc(Row) boolbinds a Nomi(RawRow) -> Bool. The Go struct may be the bound package’s, or one of another package it imports that the project’sgo.modprovides, 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
Dynamicwraps. ADynamicfromJson.to_dynamicholds whatencoding/jsondecodes to:map[string]any,[]any,string,float64orint64,bool,nil.rt.Dynamicfromgithub.com/nomi-language/nomi/rtis theDynamicitself. Nothing else takes aDynamic; declare the type the Go value has. - Aliases. A Go type alias (
type ID = core.ID) projects as its target. - Enums. A declared Nomi
enumhas no projection. The only enums that cross areResult,MaybeandBool, as a trailing Goerror,*Tandbool, matched by the std type’s identity: a same-named type of another module is rejected. - Results. The Go signature decides the result. With
Nresults that are noterror,N == 0projects toUnit,N == 1to that value, andN >= 2to the tuple(A, B, ...). A trailingerrorwraps that inResult<_, String>:erroralone isResult<Unit, String>,(T, error)isResult<T, String>, and(A, B, error)isResult<(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 Int64asint64,type Ids List<Int64>as[]int64, a distinct over a struct as a Go struct with that struct’s fields, andtype Outer Innerovertype Inner Int64asint64. The value Go returns is wrapped in the declared type again. std’sInstantandDurationare opaque types overInt, an integer of any size, so one fills atime.Timeslot and the other atime.Durationslot, and neither fills anint64one. 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.