First Program

Create a .tpz file, check and run it, then fix a type error using the location shown in the error message.

Use a local terminal and a text editor. Open an empty working folder and save the files below there. If you want help choosing where to begin, see the Learning path.

Install Topaz

Choose one installation method for your system.

On macOS or Linux, run this command.

BASH

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

On Windows, use PowerShell.

POWERSHELL

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

If Node is already installed, you can install with npm.

BASH

npm install -g topaz-lang

Each method downloads the compressed program for your system. It checks the download and the decompressed program against the SHA-256 checksums published with the release. On Linux x86_64 the download is about 33 to 47 MB, and the installed topaz program is 122 MB.

After installation, open a new terminal and check that it can find Topaz.

BASH

topaz version

Output

Topaz 5.20.4

The output starts with Topaz, followed by the installed version. The current release prints the line above. If the command is not found, reopen the terminal and check that the installation folder is on PATH.

You can check and run this file with the installed Topaz command. Native builds also need Rust with Cargo for the target platform. You will use those tools in First Application.

Write and run a study plan

Save this code as first-program.tpz in your working folder.

TOPAZ

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

In that folder, check the file and run it.

BASH

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

check reports the type and name checks without running the file.

Output

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

run checks the file before printing this result.

Output

Topaz basics: 25 minutes

The first let names a string, so the checker infers its type. The second line declares minutes as an int, an integer. print inserts the values inside {...} into the output.

Read and fix an error

Save a second file named first-program-error.tpz with this deliberate type error.

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

Check the second file.

BASH

topaz check first-program-error.tpz

The checker exits with an error. It shows the expected type, the actual type, and the location to fix.

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

In first-program-error.tpz, change the highlighted "25" to 25. The quotes made it a string. Now topaz check first-program-error.tpz succeeds, and topaz run first-program-error.tpz prints Topaz basics: 25 minutes.

Choose check or run

Use topaz check for type and name errors while editing, without starting the program. Use topaz run to perform the same checks and then see what the program does. Test the output to check your program logic.

Try it

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

Answer

It prints Functions: 30 minutes. The values still have types string and int, so the checker accepts them.

Set up your editor

In VS Code or an Open VSX-compatible editor, install the official Topaz extension from the Visual Studio Marketplace or Open VSX Registry. It recognizes .tpz files, adds the Topaz icon, and highlights syntax.

The extension starts the installed topaz lsp to show error messages in the editor. The compiler is installed separately. Make sure the editor can find it on PATH, or set topaz.executablePath to its location. You can also use topaz check in the terminal.

Continue when the program works

You are ready when the corrected file passes topaz check and prints the expected line with topaz run.

Continue to Values and Functions. Keep Syntax at a Glance nearby to look up syntax.