Introduction

Version: 1.0; Date: 2026-11-14

This document is the definition of the i programming language. A compiler or a program that does not keep to it is wrong. The present compiler does not yet do everything in this document.

This document is complete in itself, except that the principality argument (§4.7), the contract of resource.ensure’s final callback (§9.5), and the contracts of the library operations in §9.12 are still being completed; this qualification is to be removed when all three are complete. It defines:

the source language (§1 to §8);
effects, and the library modules i/fail, i/control, i/resource, i/assertion, i/io, i/key, i/task, i/random, i/request, i/clock, i/fs, i/process, i/net, i/tls, and i/stdio (§9);
the library module i/core, which has the operations that are not written in i (§13);
macros, the Lisp surface, and the library module i/syntax (§14);
the library module i/float_text, the text form of a Float written in i (§11.8);
packages, versions, and the files i.toml and i.lock (§2.1, §2.6 to §2.8);
what programs do when they run, and the text form of values (§11);
the binary interface between a compiled module and its host (§10 and Appendix B).

Every compiler must give the library modules above. The target modules i/target, i/js, and i/wasi have the contracts of §9.7, §10.1 and §B.7.1. A program may not define a module with any of these library paths. Other library modules, command-line behavior not specified in §2.6, and the way test results are shown are not part of the language.

i is small, and every part of it is what it looks like. A thing that looks like a function is a normal function, and a chain of branches is a function too (§6.12). A binding is a binding wherever it is written, and a parameter group is a pattern matched as a binding matches. Where two forms look the same, they have the same rules, with this exception, where the place of a form decides its rules:

x : T in a parameter item is a type annotation when its branch is the only branch of its shape group, has no guard, and the item has no alternatives, and a test when not (§7.1). So with v : { Int | String }, v |> (x : Int) { x } is a compile error, but v |> (x : Int) { x } | (_) { 0 } is correct.