Skip to content

Calling Go

A Nomi module can call functions from ordinary Go packages. The usual steps:

  • Work in a project: a directory with a nomi.toml and a go.mod, whose module path names your Go code. nomi new <module path> starts one in a new directory, and nomi init <module path> makes the current directory one. A binding to the Go standard library needs no project.
  • Write Go adapter code in a normal .go file.
  • Name the Go package in your Nomi file with gopkg.
  • Bind each Nomi function to a Go function with go package.Function. Each Go type maps to a Nomi type: see Go and Nomi types.
  • Give the rest of your Nomi code functions and types that fit your program, rather than the Go package’s own shapes.
  • Work with nomi run, nomi check and nomi test as usual.

The adapter can live next to your Nomi code: a small .go file that talks to a service your app already has, a vendor SDK, or a platform API. Common integrations such as SQL, SQLite and HTTP can be shared Nomi modules backed by Go adapter code in the same way.

gopkg is not a Nomi import. It names a Go package, and only go bindings use that name. Here urls.nomi binds the functions of the Go package in urltools.go, which is regular Go, and main.nomi calls them like any other Nomi functions:

// FILE: main.nomi
import
    std::io
    urls
end

fn main() -> Result<Unit, String>
    url = urls.parse("https://example.com/search?tag=go&tag=nomi&q=hello+world")?

    tags =
        url.query
        |> Map.get("tag")
        |> Maybe.with_default([])

    io.print("${url.host}${url.path} tags=${tags}")
    io.print(urls.escape_query("a b+c"))
    io.print(urls.unescape_query("%zz"))
    Ok(Unit)
end

// FILE: urls.nomi
gopkg "urltools"

pub struct ParsedURL
    scheme:    String
    host:      String
    path:      String
    raw_query: String
    query:     Map<String, List<String>>
end

pub fn escape_query(value: String) -> String go urltools.EscapeQuery

pub fn unescape_query(value: String) -> Result<String, String> go urltools.UnescapeQuery

pub fn parse_query(raw: String) -> Result<Map<String, List<String>>, String> go urltools.ParseQuery

pub fn parse(raw: String) -> Result<ParsedURL, String> go urltools.Parse

// FILE: urltools.go
package urltools

import "net/url"

type ParsedURL struct {
	Scheme   string
	Host     string
	Path     string
	RawQuery string
	Query    map[string][]string
}

func EscapeQuery(value string) string {
	return url.QueryEscape(value)
}

func UnescapeQuery(value string) (string, error) {
	return url.QueryUnescape(value)
}

func ParseQuery(raw string) (map[string][]string, error) {
	return url.ParseQuery(raw)
}

func Parse(raw string) (ParsedURL, error) {
	parsed, err := url.Parse(raw)
	if err != nil {
		return ParsedURL{}, err
	}
	return ParsedURL{
		Scheme:   parsed.Scheme,
		Host:     parsed.Host,
		Path:     parsed.Path,
		RawQuery: parsed.RawQuery,
		Query:    map[string][]string(parsed.Query()),
	}, nil
}

The Nomi signature decides what the function looks like to Nomi code. The Go function’s job is to match it. Nomi writes the code that calls the Go function and converts values in both directions. The table below lists the Go types it converts.

For any other Go type, convert it in your Go adapter. If Nomi only needs to hold a Go value and hand it back, declare an opaque type for it, such as opaque type Conn go dbtools.Conn. If Nomi needs to look inside a value whose shape you can’t write in the signature, pass it as Dynamic and decode it on the Nomi side (JSON & Dynamic).

Go typeNomi typeNotes
string, bool, float64, uint8String, Bool, Float, Byte
int64, intInt64 from std::intA parameter declared Int is an error at the binding, since an Int may be larger. A result may be declared Int.
int32, uint64 and the other sized Go integersa subtype within the Go type’s rangeuint64 takes NonNegativeInt and Int64; int32 takes a subtype of your own, such as subtype Int32 Int when fn n -> n >= -2147483648 and n <= 2147483647.
*big.IntIntTakes and returns any Int.
[]byteBytesA byte buffer, not the same type as List<Byte>.
[]T, map[K]VList<T>, Map<K, V>The element, key and value types must be in this table too.
time.Duration, time.TimeDuration, Instant
io.Reader, io.ReadCloser, io.Writer, io.WriteCloserReader, Writer from std::ioA Go stream becomes a Nomi stream over it. A Nomi stream passed to Go is read or written through its own buffer.
*TMaybe<T>A pointer to a Go type you bound with opaque type crosses as that opaque type instead.
two or more return valuesa Nomi tuplefunc(string, string) (string, string) binds to (String, String).
a trailing errorResult<_, String>(T, error) becomes Result<T, String>, and a lone error becomes Result<Unit, String>. The Err holds the Go error’s message.
exported Go structsNomi structExported Go fields match Nomi fields by name: RawQuery matches raw_query. The struct may come from another package your adapter imports, such as model.User, used directly or through an alias like type User = model.User.
a Go type aliasthe alias’s targettype ID = core.ID crosses as whatever core.ID is.
a func(A) R parametera Nomi function (A) -> RPass a lambda or a named function, and Go calls it. The Go function may return nothing ((A) -> Unit), one value, or a value and an error ((A) -> Result<R, String>).
a first parameter ctx context.Contextleft out of the Nomi signatureGo receives the calling task’s context: it carries the with App.context deadline and ends when the task is cancelled.
a Go value Nomi only holdsopaque typeNomi stores it and passes it back, but can’t look inside.
a value of unknown shapeDynamicNomi decodes it or matches on it.
channels, non-empty interfaces, named function typesGo adapter or opaque handleConvert to a type in this table, or keep the value opaque.

Fine print

  • A parameter whose type admits an Int the Go integer can’t hold is an error at the binding, naming the type to declare. An intersection such as PositiveInt and Int64 keeps a size positive and within int64. A computed value goes through Int64.try_from(n) before the call.
  • Byte and Int don’t stand in for each other: an Int doesn’t fill a uint8 parameter.
  • A float32 slot is range-checked. NaN and the infinities cross unchanged.
  • A time.Time of any year crosses as its exact Instant. An Instant goes back to Go in UTC, with no zone.
  • A Go map comes back with its keys in ascending order. A Go key type with no order, such as a pointer, is refused at the binding.
  • Your own enums don’t cross. Only Result, Maybe and Bool do, as a trailing error, *T and bool. A distinct type crosses as the type it wraps.
  • A generic Go function can’t be bound: write a non-generic Go function that calls it, and bind that.

Spec: How Nomi types project to Go.

A Go standard library package needs no adapter file and no go.mod. Bind its functions directly:

import
    std::int.Int64
    std::io
end

gopkg "strings"

gopkg "strconv"

fn upper(s: String) -> String go strings.ToUpper

fn repeat(s: String, count: NonNegativeInt and Int64) -> String go strings.Repeat

fn parse_int(s: String) -> Result<Int, String> go strconv.Atoi

fn main()
    io.print(upper("hi"))
    io.print(repeat("ab", 3))
    io.print(parse_int("42"))
end

This runs from any directory, as a .nomi file or as a #! script. The Go function must still use the types in Go and Nomi types. A function that returns a concrete type such as *gzip.Reader, or a generic one such as slices.Max, needs a small adapter of your own, like urltools above.

A project with Go bindings keeps its Nomi files, its Go files, nomi.toml and a go.mod together in one directory:

go-bindings/
  • nomi.toml
  • go.mod
  • main.nomi
  • urls.nomi
  • urls.go

nomi new writes nomi.toml and go.mod for a new project, and nomi init writes them in a directory that already holds your files, as in the steps at the top of this page. The go.mod is an ordinary Go module file. It names your module and your own Go dependencies. It says nothing about Nomi:

module gobindings

go 1.27.0

The module path is also the gopkg path of the Go code in the project directory, so urls.nomi binds urls.go with gopkg "gobindings". Go code in a subdirectory adds the subdirectory to the path: gopkg "gobindings/adapters".

To use a third-party Go package, add its module with nomi add in the project directory: nomi add github.com/user/gopkg takes a package’s path as well as its module’s. If you have Go, go get works on the same file. Then import the package in your .go file. A gopkg can also name a package from a module you added, with no adapter file, as long as its functions use the types in Go and Nomi types.

Go has a feature called cgo that lets Go code call C code. Nomi builds the Go side without it. A gopkg naming a package that needs cgo, itself or through a package it imports, is a compile error at the gopkg.

Fine print

  • The cgo check follows the package’s imports, so a package that is pure Go itself but imports one that needs cgo is refused too.
  • A package internal to the Go standard library, such as internal/abi, is refused at its gopkg.
  • A gopkg stands at the top level of a file, beside the bindings that use it, and each go alias.Symbol names an alias a gopkg in the same file declares.
  • A Go type binding is always opaque type: Nomi can hold and pass it, never build or look inside it.

Spec: Binding Go packages. Building a project with Go bindings is in the tooling reference’s Go bindings.

Go bindings are compiled with Go, and programs without them need no Go at all. nomi uses the go that NOMI_GO names, else the one on your PATH, else it downloads the Go release it was built with. nomi run, nomi test and nomi check compile the Go side for you and reuse it until the Go code, go.mod or Nomi itself changes, and nomi build compiles it into the executable. The tooling reference’s Go bindings has the details.

The examples on this page run in your browser, which can’t compile Go. So the site compiles the Go they bind ahead of time, and an example’s Go file is read-only. You can edit its Nomi files and call the bound functions however you like, but binding a Go function the site did not compile is an error.

Generating Code is next. It shows how a tool writes Nomi code from data, as sqlkit does in Databases.