A tour of the language
Learn the language through small programs that you can run in one scratch project.
This tour introduces i to programmers who already know another language, such as TypeScript, Go, Rust, or OCaml. Each page starts with a complete program, then explains the forms it uses. By the end, you can read an i module, write functions over your own data, and follow the later pages on services, tasks, and libraries.
(
i/stdio
)
main = () { stdio.print("Hello from the tour!") } Hello from the tour! The opening group imports i/stdio; main is the program entry, and stdio.print writes a line. You do not need to understand the printing service yet. Keep that import and call while you experiment with the values between them. The services and errors page explains what printing needs from its caller.
Run the examples
The tour assumes that i is installed and available in your shell. See installation if it is not. It assumes familiarity with calling functions, basic types, and source files, but no previous knowledge of i or WebAssembly.
Make one scratch project:
i new tour
cd tour Replace src/main.i with the complete example above, then run it from the project directory:
i run The output is the text shown immediately below the example. Keep this project for the rest of the tour: replace src/main.i with each complete program in turn. Most examples on the first four pages use only the language-library modules under i/…. The evaluator examples also import std/int. For those examples, move the existing std entry in i.toml from [dev-dependencies] to [dependencies], and set its path to the std directory in your checkout of the i repository. The first-program guide explains the generated manifest.
A fence marked i run is a complete program. A fence marked i error is a complete program that the checker rejects on purpose; use i check for it and compare the diagnostic with the explanation. Do not combine the programs into one file: each defines its own names and usually its own main.
Format your current program with:
i fmt Formatting makes the line breaks and spaces consistent, which helps when comparing your code with the examples. To check it without running it, use i check. The types page also shows how to ask the checker for inferred types.
Read in this order
- Values and data introduces names, numbers, strings, records, lists, and labelled data.
- Functions and branches explains calls, patterns, choices, recursion, and pipelines.
- Types and inference shows type definitions, annotations, generic functions, and the types inferred from code.
- Services and errors explains how functions state their needs and how callers provide them.
- Resources covers acquiring and releasing resources.
- Concurrency introduces structured tasks and communication between them.
- Macros shows how i code works with code.
- Packages explains modules, dependencies, and the package file.
The complete tour program is examples/tour in the repository; the functions and types pages reuse its evaluator and pipeline.
The pages build on one another, so follow the order on a first reading. Afterward, use the standard links at the end of each page for exact grammar and rules. The tour teaches a small working program at a time; the standard defines the language in full.
Ideas behind the language
- No keywords: names, brackets, and symbols express definitions, calls, and branches.
- Immutable values: every value stays the same, so an update constructs a new value.
- Explicit needs: services are passed as needs and provided with
<-. - Structured concurrency only: concurrent work belongs to the structure that starts it.
- No library is special to the compiler: library APIs use the general language forms.
These ideas appear where the examples first need them. The language and its implementation are also under development; contributing explains how to report a problem or take part in the work.