First Program

Outcome: Create one .tpz file, check it before execution, run it, and repair an error identified by the checker's source span.

Prerequisite: Choose a starting point on the Learning path. Run the commands below in a local terminal.

Install the command

On macOS or Linux:

BASH

curl -fsSL https://topaz.ooo/install.sh | sh

On Windows PowerShell:

POWERSHELL

irm https://topaz.ooo/install.ps1 | iex

If Node is already installed:

BASH

npm install -g topaz-lang

Confirm the installed product:

BASH

topaz version

Output

Topaz 5.19.0

This first program does not require a repository clone, package manifest, Rust, or Python.

If you use VS Code or an Open VSX-compatible editor, install the official Topaz extension from the Visual Studio Marketplace or the Open VSX Registry. It recognizes .tpz files, displays the Topaz file icon, and provides syntax highlighting. It also launches the installed topaz lsp to display editor diagnostics. The extension does not bundle a compiler, so ensure the installed Topaz executable is available on PATH or set topaz.executablePath. You can also run topaz check directly from the terminal.

Write the smallest study plan

Create first-program.tpz with the following contents:

TOPAZ

let topic = "Topaz basics"
let minutes: int = 25
print("{topic}: {minutes} minutes")

Check the source file, then run it:

BASH

topaz check first-program.tpz
topaz run first-program.tpz

check validates the file without executing it:

Output

first-program.tpz: types-ok (1 module)
first-program.tpz: resolve-ok (1 module)

run passes the same static gate and then prints:

Output

Topaz basics: 25 minutes

Read the program in execution order. The first let binding assigns a string and lets the checker infer its type. The second binding explicitly specifies int, requiring the checker to verify that 25 is an integer. print evaluates the interpolated expressions inside {...} and outputs a single line.

Read and repair a diagnostic

Create a separate file named first-program-error.tpz. This source code is intentionally invalid and is presented as plain text rather than a runnable Topaz example:

let topic = "Topaz basics"
let minutes: int = "25"
print("{topic}: {minutes} minutes")

Run the checker:

BASH

topaz check first-program-error.tpz

The checker does not execute the file. It identifies the declared type, the type it found, and the exact source span:

Output

error[TPZ5001]: expected `int`, found `string`
 --> first-program-error.tpz:2:20
  |
2 | let minutes: int = "25"
  |                    ^^^^

first-program-error.tpz: 1 type diagnostic

Repair the highlighted value by changing "25" to 25. Running topaz check first-program-error.tpz now succeeds, and running topaz run first-program-error.tpz produces the same output as the working program above.

Decision: check or run?

Use topaz check while editing to verify source validity without starting the program. topaz run performs the same static check before executing the code to demonstrate behavior. Running check separately provides a fast, execution-free validation step rather than an additional check that run omits.

Try this

Change topic to "Functions" and minutes to 30. What should the program output?

Answer

It outputs Functions: 30 minutes. Both edits preserve the inferred string and declared int types, allowing topaz check first-program.tpz to succeed before execution.

Ready to continue when

You can create a .tpz file, execute topaz check and topaz run, and use the expected and found types alongside the highlighted source span to repair invalid values.

Continue to Values and Functions. Refer to Syntax at a Glance whenever you need a quick syntax reference.