Modules¶
Each .kod file is a module. Imports name either a file relative to the importing module or a stdlib module.
Importing¶
Two forms:
import "./utils" // relative — utils.kod next to the importing file
import "./math/vec" // relative — math/vec.kod below the importing file's directory
import "kod/ast" // stdlib — stdlib/kod/ast.kod
import "io" // stdlib — stdlib/io.kod
Paths beginning with ./ resolve against the directory of the importing file, not the project root or the current directory. Anything else resolves under stdlib/.
The imported module's public names are accessible via the import alias, which is the last path component:
Qualified constructors have the imported type, so let v = vec.Vec2(x: 1, y: 2)
needs no annotation before v.x. Calling a function the module doesn't
declare, such as vec.lenght(v), is an error with a did-you-mean hint.
No local can be named like an import alias: a let, mut, parameter,
for variable or pattern binding named vec is an error,
`vec` is the name of an import; give the local another name, so
vec. always means the module.
A function named like an import alias doesn't hide it: with func vec()
declared too, vec() calls the function and vec.make(1) the module's.
To use some names unqualified instead, list them after the path:
An import that lists names binds only those names, not its alias, so
vec.dot is an error there (unknown name `vec`; an import that lists
names binds no `vec`, so add a plain import of it to write `vec.`) and a
local may be named vec. That keeps the
usual way of naming a value after its module working:
To have both, import the module twice: import "./math/vec" binds vec
and import "./math/vec" { Vec2 } adds Vec2, and then no local can be
named vec.
Each listed name must be a function, extern, constant, variable or type the module declares; otherwise it's an error with a did-you-mean hint: module `vec` has no function, constant or type `dto`; did you mean `dot`?.
Where names resolve¶
Parameter defaults, struct field defaults and the method bodies of a generic type resolve function names, type names and import aliases in the module that wrote them, even though they run as part of the caller's code. A default in util.kod that calls helper() calls util's own helper, a function util imports with { helper }, or the builtin of that name, never one that belongs to the caller. Likewise rng.seed() in that default means util's own import "./rng", whether or not the caller imports a module named rng:
// util.kod
func helper() -> int64 {
return 1
}
func f(x: int64 = helper()) -> int64 {
return x
}
// main.kod
import "./util"
func helper() -> int64 {
return 2
}
func main() -> int64 {
let helper = 3 // not visible to util's default either
print(f"{util.f()}") // 1
return 0
}
The same holds for a function literal or a function value used as a default (cb: func() -> int64 = helper). A name the defining module doesn't have is an error, reported at the default when a call leaves the parameter out, even when the caller happens to declare it.
A bare type name T means, in this order: a type parameter of the generic declaration around it, a primitive (int64, bool, str, bytes, none), a type the module declares (its own aliases included), a type it lists in an import (import "./pa" { Pt }), then a builtin type. A type of a module imported without listing it, or loaded only because another module imports it, is written through the module: pa.Pt. Otherwise it's an error with a hint naming the file that declares it: unknown type `Pt`; lib/pa.kod declares `Pt`: write `pa.Pt` or list it in the import (`{ Pt }`), or unknown type `Pt`; lib/pa.kod declares `Pt`: import it to use it here when the module doesn't import that file. kod finds the file anywhere in the program being built, so the hint also names a module that imports this one or that only another module imports. sh_kodc run on one file knows only that file's imports.
m.T means a type that the module imported as m declares, its own aliases included. This holds in a type, a constructor m.T(...), a type argument, m.E.V and a pattern b: m.T. Types that m only imports aren't reachable through it. Otherwise it's an error: module `m` has no type `T`, with a did-you-mean over m's types (module `m` has no function or type `T` for a call m.T(...)). When m isn't a module this one imports, the error spells what was written: unknown type `m.T`. A generic type takes its arguments the same way, as in m.Box[m.Pt](v: p), also where it is itself a type argument: Stack[m.Box[str]].
A module exports only what it declares, never what it imports. When m lists T in one of its own imports, m.T, m.f(), m.f and import "./m" { T } say where T comes from: `T` is imported by `m`, not declared there; import it from lib/b.kod. A value of such a type can still be used without naming it, as in let t = m.make(). To pass a type on deliberately, m declares an alias of it, type T = b.T (which needs a plain import "./b"), and for a function a wrapper.
A module declares each of its names once. A function, extern, struct, enum, interface or type alias with the name of an earlier one in the same module is an error at the second declaration (`f` is already declared on line 1), and so is a method, field or variant with the name of an earlier one of the same struct, interface or enum (`Kind.A` is already declared on line 2). A method can't take the name of a field of its struct either; the error is at the method (`Bag.len` is already declared on line 3).
A name an import lists counts the same way. A module can't both declare a name and list it in an import, and two imports can't list the same name, whether it names a type or a function. The later one is the error: `Pt` is already imported on line 1, or `Pt` is already declared on line 3 when the declaration comes first. Two imports can't share a name either, unless they load the same file: after import "./a/util", import "./b/util" is `util` is already imported on line 1, while a second import "./a/util" { Vec2 } only adds to the first import's list.
Each module's structs, enums, interfaces and type aliases are its own. Two modules may declare a type of the same name, and they are different types: pa.Pt and pb.Pt don't convert to each other, is pa.Pt doesn't hold for a pb.Pt, and Box[pa.Pt] and Box[pb.Pt] are different instances. Aliases of different types may share a name across modules, and an alias may take its target's name (type Pt = pb.Pt), so a module that imports only this one reaches the type as its Pt. Only the builtins may declare Map, Option, Result, Error, Stringable or ExitCode; anywhere else it's an error: `Option` is the name of a builtin type; give this type another name. A module is one module however its path is spelled: import "./lib/../lib/pa" and import "./lib/pa" load the same file once.
A message writes a type by its bare name, unless another module of the program declares a struct, enum or interface of that name too (an alias doesn't count, as a message writes the type it stands for). Then it's written the way the module being compiled would write it (pa.Pt, or Pt when the module has it under that name: declared, aliased or listed in an import), or with its file when that module can't name it (Pt (lib/pb.kod)).
Standard library¶
The stdlib lives under stdlib/ in the repository.
| Module | Contents |
|---|---|
builtins |
Always imported. print, print_int, len, fail, Map[K, V], the Error / Stringable / ExitCode interfaces. |
primitives/int64, primitives/float64, primitives/str, primitives/bool (and int64_float, str_float, which hold to_float64 and parse_float, and float_text, which both float methods use) |
Methods on the primitive types (to_str, hash, parse_float). Auto-loaded; not imported directly. |
io |
read_file, write_file, and stdin/stdout/stderr helpers. |
fs |
FileSystem interface with DiskFs (real disk) and MemFs (in-memory, for tests). |
process |
process.run(argv) — spawn a subprocess and capture stdout/stderr/exit code. process.exec(argv) — replace the calling process (compiled programs only). |
env |
get, set and unset for environment variables. See Built-ins. |
time |
monotonic_ns(), unix_ns(), Duration, sleep(d), and Time with now(), parse(s) and parse_date(s). See Time. |
sets |
Set[T], a hash set built on Map: Set[str](), with add, contains, remove(x) -> bool, values() and len; for x in s goes over the elements in the order they were first added. |
sort |
sorted(xs) and sorted_by(xs, less:), stable, returning a new array. See Arrays. |
arrays |
contains(xs, x) and equal(a, b). See Arrays. |
json |
Strict JSON parse/emit, with builders. See JSON. |
strbuilder, stream, posix |
StrBuilder; Reader / Writer and IoError; file descriptors. See Strings and Streams. |
net/tcp, net/tls, net/http |
TCP, TLS, and HTTP/1.1 messages with a client. See Streams and HTTP client. |
jsonrpc |
Content-Length framed messages on stdin/stdout, as used by LSP. |
encoding/base64 |
Base64, standard and URL-safe, strict decoding. See Encodings. |
hash/crc32 |
CRC-32 (gzip polynomial), streaming or one-shot. |
compress/deflate, compress/inflate |
Compress to and decompress from gzip, zlib and raw deflate. See Encodings. |
kod/ast |
AST node types (for the self-hosted compiler). |
kod/lexing |
Tokenizer (self-hosted). |
kod/parsing |
Parser (self-hosted). |
kod/codegen |
ARM64 code generator. |
Circular imports¶
Circular imports work: a struct, enum or interface
declared in a module of the cycle is the same type on either side, so a
value of it can be passed both ways, also inside an array, an optional, a
Map or another generic type's instance such as Box[Pt], and is
recovers a struct from an interface value whichever side boxed it.
Visibility¶
Top-level functions, externs, constants and types are visible to importing modules, except those whose name starts with _. Those are private to the module that declares them, which uses them like any other name:
// lib.kod
let _LIMIT: int64 = 3
type _Slot = struct {
n: int64
}
func _clamp(anon n: int64) -> int64 {
if n > _LIMIT {
return _LIMIT
}
return n
}
func slots(anon n: int64) -> int64 {
return _Slot(n: _clamp(n)).n
}
// main.kod
import "./lib"
func main() -> int64 {
print_int(lib.slots(5)) // 3
lib._clamp(5) // error: `_clamp` is private to module `lib`
return 0
}
The same error is reported for lib._LIMIT, lib._Slot(...), lib._Slot in a type, and _clamp in an import list (import "./lib" { _clamp }). Did-you-mean hints never suggest another module's private names.
A private name keeps a helper out of the module's interface, so the module can change or remove it without breaking its importers. A public function may still take or return a private type: callers can use such a value, its fields and its methods, but can't write the type's name. Fields and methods whose names start with _ are private to their struct; see Structs.
A module's top level holds declarations (func, type, interface, import, extern and test) constants (let NAME: T = value, see Module-level constants) and variables (mut NAME: T = value, see Module-level variables). Any statement there is an error. Constants and variables are visible to importing modules like functions, and only the declaring module assigns a variable.
Symbol and object names¶
A module is identified by its normalized path: ./x and ./a/../x are one module, while x (the file under stdlib/) and ./x (the project's own) are two. Everything a module emits (functions, types, tests) is labelled $<prefix>$<name>. The prefix is computed from the path and from whether stdlib/<path>.kod exists (step 5):
- Drop the
.kodextension, and the leading/of an absolute path. - A path under
stdlib/drops that directory:stdlib/io.kodisio,stdlib/kod/ast.kodiskod$ast. - Each remaining byte becomes symbol characters.
/becomes$. Letters, digits and_stay..stays, except as the first byte. Every other byte (space,-,+,@,$, each byte of a non-ASCII character) becomes$$followed by its two lowercase hex digits:my-appismy$$2dapp. - The label is
$<prefix>$<name>, and the assembler reads$followed by a digit as a number, and takes no$$nameat all, so a prefix is never empty and never starts with$or a digit. If it would, a.is put in front:-xis.$$2dx,01_hellois.01_hello,2024/reportis.2024$report, and a file named.kodis.. (A digit after an inner$is fine:tests/3distests$3d.) The assembler also reads.and digits followed byeorEas a number (.1e5), so then that letter is written$$65or$$45as well:1e5is.1$$655,2East/libis.2$$45ast$lib. - A module outside
stdlib/whose path also exists understdlib/is in the namespace.user$: a project'sio.kodis.user$ioand does not clash with the stdlibio. The check is a file test, so on a case-insensitive volume a project'sIo.kodalso gets the marker; that is harmless, because every project module is recompiled for each program.
Two different normalized paths never get the same prefix: a prefix's own leading . is always escaped by step 3, so a raw leading . comes only from step 4, the marker .user$ starts .u, which step 4 never produces, and $$65 and $$45 are escapes that step 3 never writes (it keeps letters). (An absolute path and the relative path with the same components still collide, as before.)
A vtable and a type's identity word are shared between objects by label, so their labels have to differ for different types as well: the parts of those labels are joined with $$for$, $$of$ and the like, which step 3 never writes (a $$ it writes has two hex digits after it). is and interface calls therefore can't mix up two types, whatever their paths are called. A method's label joins its type and name the same way, $<prefix>$<Type>$$m$<name>, so T.m in x.kod and a function m in x/T.kod are two symbols, not one defined twice.
kod build writes a program's objects under build/apps/<stem>/<stem>.obj/, mirroring the source tree: stdlib/json.kod becomes <stem>.obj/stdlib/json.kod.o, a project's lib/json.kod becomes <stem>.obj/lib/json.kod.o. The compiler writes the object itself; its assembly, .s, sits beside the .o only when asked for (KOD_ASM_TEXT, see self-hosting). A .. directory is written %2e%2e (a . one %2e), the root of an absolute path %2f, and a literal % in a name %25. The _main shim is <stem>.obj/<entry>.main.{s,o} (<stem>.obj/<first entry>.testmain.{s,o} for tests). The executable is build/apps/<stem>/<stem>, or <stem>_test for kod test; <stem>.obj can equal neither. <stem> is the entry's file name without .kod; for kod test <dir> it is the directory with every byte outside letters, digits, _ and - replaced by _ (its last 200 bytes, when it is longer), then _tests. A file whose name without .kod is empty, . or .. (.kod, ..kod, ...kod) has no program name and is refused. An entry named kod or lsp (other than tools/kod.kod and tools/lsp.kod, however they are spelled) is refused, because its executable would replace the tool. So is one whose directory the volume takes for the tool's, such as KOD on a case-insensitive volume.
The object path has to fit the file system as well: a file name of more than about 240 bytes (the shim adds .kod.main.s), or an absolute entry path of more than about 950 bytes (build/apps/<stem>/<stem>.obj/%2f/ goes in front of it), is too long, and the build stops with a message that a file could not be opened or a directory made.
kod test <dir> builds every *_test.kod below <dir> into one program, except a file with a path component below <dir> that starts with . (worktrees under .claude/, editor files, the scratch .kod_compile_test.kod) and a build directory directly below <dir>. kod test <file> takes the file named, whatever its path.
Link inputs¶
A module that needs C code or a system library says so in the comment lines at the top of its file, before its first declaration:
// kod:require ${OPENSSL}/include/openssl/ssl.h brew install openssl@3
// kod:cc tls.c -I${OPENSSL}/include
// kod:link -L${OPENSSL}/lib -lssl -lcrypto
import "io"
kod:cc <file.c> [flags...]: a C file beside the module.kod buildcompiles it withCCandCFLAGSoflink.cfgfollowed by the flags given, and links the object. Flags are passed as written; a relative-Iis relative to the repository root, wherekodruns. The file is compiled on every build, like the modules, so an edit to it, to a header it includes or toCCandCFLAGSis picked up by the next one. A C file that several modules of a program name (or several test files of onekod test <dir>) is compiled and linked once; naming it with different flags is an error.kod:link <args...>: arguments for the final link, after all objects:-lz,-L...,-framework Security, a path to a.a. They are passed in the order the modules appear in the program, and a-lnamethat comes up again is passed once.kod:require <file> [hint...]: the file (a path from the repository root, or an absolute one) must exist before anything is compiled; otherwise the build stops withpath:line:1: error: needs <file> (<hint>)(needs <file>when there is no hint), for each such file, naming the line of the directive. Use it for a file outside the repository that the other lines rely on, so that a machine without it gets the hint instead of'openssl/err.h' file not found.
${NAME} in a word is replaced by the value of NAME in link.cfg, or in link.local.cfg when that overrides it (the example assumes link.cfg has an OPENSSL line). A name that neither file sets, or one whose value is not exactly one word, is an error, and so is a $ that does not start ${NAME}. Words are separated by spaces; there is no quoting, and a tab or another control character in a directive line is an error.
Only the leading block counts: the lines from the top of the file that are blank or start with //, up to the first other line. In it a line that starts with // kod: (after any indent) is a directive, and any other comment line is just a comment; a // kod: line further down is a comment too and does nothing. A line in the block that is spelled like a directive but not so (//kod:cc x.c, // kod:cc x.c, // Kod:cc x.c, // kod :cc x.c) is an error, so that a slip is not taken for a comment. A UTF-8 byte order mark at the start of the file is skipped, as the compiler skips it. Put a blank line after the block, or the first declaration takes it as its doc comment (shown on hover).
These are errors, path:line:1: error: ..., from kod build, kod run, kod test and kod check: an unknown directive (unknown directive kod:linkk), a directive spelled almost right, a tab in a directive line, a directive without its argument, a kod:cc that does not name a .c file beside the module (a bare file name ending in .c, which has to exist), and a ${NAME} that cannot be replaced. kod check validates the lines, and that the C file is there, but it does not test kod:require and compiles no C.
Only a program that imports the module compiles its C file or passes its arguments, and that includes a module that only a test file imports: kod test reads the lines of every module of its program, and kod test <dir> builds all its files into one program, so one test file's missing kod:require file stops them all. A program that imports no such module compiles no C file. A C file's object is <stem>.obj/<path>.c.o in the tree of Symbol and object names, next to the module's own <path>.kod.o. If the C compiler fails, kod shows its output and kod: compiling <file> failed, exits 1 and links nothing.
A module that declares link inputs cannot be one that the Makefile builds: it does not read their lines. That is a module listed in STAGE0_KOD of link.cfg, one of the compiler's own modules (COMPILER_KOD in the Makefile) and kodc.kod and tools/kod.kod. For a STAGE0_KOD module the driver says so (path:line:1: error: ...) and stops, rather than leave the lines unread; for the others a test of the repository checks that there are none.
C files export bare symbols into one namespace shared with libc and runtime.c: name them kod_<module>_.... #include "kod_rt.h" (CFLAGS has -I stdlib) declares what they need of the runtime:
KodStr: what a Kodstris when it crosses into C.bufpoints atlenbytes followed by a NUL byte, and astrparameter or result is aKodStr *.KodArray: a Kod[T]:ptrpoints atlenelements of 8 bytes each (one byte each for a[bool]), with room forcap.arena_alloc(size): memory that is never freed.rc_alloc(size, mask): a counted object, zeroed, with a count of 1 that the caller owns.masksays which of its 8-byte slots hold references, bit 0 for the first; it must not use bits past 20.rc_alloc_rawis the same but leaves filling it to the caller.rc_retain_c(p)andrc_release_c(p)count a reference up and down, and do nothing for memory outside the counted heap.kod_str_new(len): a newstroflenbytes for the caller to fill in.kod_str_from_bytes(p, n): astrthat is a copy ofnbytes atp, which may contain NUL bytes.panic(msg): printpanic:and the message with a backtrace, and exit 1.
A function value isn't a C function pointer, so an extern can't take or return one: an `extern` can't take or return a function value. To give C a function to call back, pass the address unsafe.c_function(f) gives as an int64.
Kod values are reference counted, and C code follows the same rules as generated code. A parameter is borrowed: it stays alive during the call, and C code that keeps it after returning calls rc_retain_c. A result is owned by the caller, which releases it, so returning anything other than a new object, such as a parameter or something kept in a static, takes an rc_retain_c first. The same goes for references written into an object: each one needs its own count.