Calling Go
A Nomi module can call functions from ordinary Go packages. The usual steps:
- Work in a project: a directory with a
nomi.tomland ago.mod, whose module path names your Go code.nomi new <module path>starts one in a new directory, andnomi 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
.gofile. - 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 checkandnomi testas 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
}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
}example.com/search tags=[go, nomi]
a+b%2Bc
Err(invalid URL escape "%zz")
Go and Nomi types
Section titled “Go and Nomi types”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 type | Nomi type | Notes |
|---|---|---|
string, bool, float64, uint8 | String, Bool, Float, Byte | |
int64, int | Int64 from std::int | A 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 integers | a subtype within the Go type’s range | uint64 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.Int | Int | Takes and returns any Int. |
[]byte | Bytes | A byte buffer, not the same type as List<Byte>. |
[]T, map[K]V | List<T>, Map<K, V> | The element, key and value types must be in this table too. |
time.Duration, time.Time | Duration, Instant | |
io.Reader, io.ReadCloser, io.Writer, io.WriteCloser | Reader, Writer from std::io | A Go stream becomes a Nomi stream over it. A Nomi stream passed to Go is read or written through its own buffer. |
*T | Maybe<T> | A pointer to a Go type you bound with opaque type crosses as that opaque type instead. |
| two or more return values | a Nomi tuple | func(string, string) (string, string) binds to (String, String). |
a trailing error | Result<_, 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 structs | Nomi struct | Exported 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 alias | the alias’s target | type ID = core.ID crosses as whatever core.ID is. |
a func(A) R parameter | a Nomi function (A) -> R | Pass 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.Context | left out of the Nomi signature | Go 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 holds | opaque type | Nomi stores it and passes it back, but can’t look inside. |
| a value of unknown shape | Dynamic | Nomi decodes it or matches on it. |
| channels, non-empty interfaces, named function types | Go adapter or opaque handle | Convert 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 Int64keeps a size positive and withinint64. A computed value goes throughInt64.try_from(n)before the call. ByteandIntdon’t stand in for each other: anIntdoesn’t fill auint8parameter.- A
float32slot is range-checked. NaN and the infinities cross unchanged. - A
time.Timeof any year crosses as its exactInstant. AnInstantgoes 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,MaybeandBooldo, as a trailingerror,*Tandbool. 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.
Binding the Go standard library
Section titled “Binding the Go standard library”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"))
endHI
ababab
Ok(42)
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.
Shipping a binding
Section titled “Shipping a binding”A project with Go bindings keeps its Nomi files, its Go files, nomi.toml and
a go.mod together in one directory:
- 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 itsgopkg. - A
gopkgstands at the top level of a file, beside the bindings that use it, and eachgo alias.Symbolnames an alias agopkgin 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.