Topazdocs
Обзор

Начало работы с Топазом

Установка Топаза и первая программа на тулчейне v5.2: hello, тур в десять строк, настоящий fault и модульный юнит из двух файлов.

Примечание: Каждая программа на этой странице была выполнена тулчейном v5.2 ровно в таком виде, а напечатанный вывод зафиксирован байт в байт верификатором сайта. Что работает сегодня и чем это доказано, на странице Состояние тулчейна.

Установка Топаза

Установите тулчейн topaz без клонирования репозитория и без сборки.

Shell (macOS / Linux):

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

Windows (PowerShell):

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

Через npm, если у вас уже есть Node:

npm install -g topaz-lang

Проверьте установку:

topaz version
OUTPUT
Topaz 5.2

Можно также попробовать Topaz в браузере, ничего не устанавливая.

Одно замечание о нативной сборке. topaz run, topaz check и topaz emit работают из самостоятельного бинарника без чего-либо ещё. Компиляция прямо в нативный бинарник через topaz build вызывает cargo через rustup, поэтому именно этой команде нужен установленный тулчейн Rust.

Первая программа

Создайте файл hello.tpz:

TOPAZ
let greeting = "Hello, Topaz!"
print(greeting)

Запустите его:

topaz run hello.tpz
OUTPUT
Hello, Topaz!

Это весь цикл: один файл, topaz run, вывод. Никакого скелета проекта, манифеста или шага сборки.

Тур в десять строк

tour.tpz затрагивает ядро языка: match с условиями и диапазонами, изменяемый Map, функцию высшего порядка и значение по умолчанию для опционала:

TOPAZ
function classify(n: int) -> string {
    return match n {
        case 0 => "zero"
        case x if x < 0 => "negative"
        case 1..99 => "small"
        case _ => "large"
    }
}

let mut report: Map<string, string> = Map.new()
for n in [-5, 0, 42, 1000] {
    report.insert("{n}", classify(n))
}

print("{report.keys}")
print("{map([1, 2, 3], (x: int) => x * x)}")
print("{toInt("42") ?? 0}")
topaz run tour.tpz
OUTPUT
[-5, 0, 42, 1000]
[1, 4, 9]
42

Три вещи, на которые стоит обратить внимание:

  • match — это выражение: classify возвращает его результат напрямую. В ветвях допустимы литералы, диапазоны, привязки и условия if.
  • Интерполяция "{…}" — единственный способ форматировать строки; она работает для любого значения, включая report.keys.
  • toInt("42") возвращает опционал, а ?? подставляет значение по умолчанию. Ничто не преобразуется молча.

Когда программа останавливается

Выход за границы массива в Топазе — не ошибка, которую можно перехватить, а fault: программа останавливается, и тулчейн печатает диагностику. fault.tpz:

TOPAZ
let xs = [10, 20, 30]
let i = 7
print("{xs[i]}")
topaz run fault.tpz
OUTPUT
error[TPZ4001]: index 7 is out of bounds for an array of length 3
 --> fault.tpz:3:9
  |
3 | print("{xs[i]}")
  |         ^^^^^

Процесс завершается с ненулевым кодом. Фолт означает нарушение контракта; отсутствие значения, с которым вы собираетесь работать, моделируется опционалами — см. Обработку ошибок.

Модули в двух файлах

Каталог файлов .tpz — это юнит. Файлы импортируют друг друга по имени; единственный механизм видимости — export. util.tpz:

TOPAZ
export function shout(s: string) -> string {
    return s + "!"
}

export let greeting: string = "hello"

main.tpz в том же каталоге:

TOPAZ
import util

print(util.shout(util.greeting))
topaz run main.tpz
OUTPUT
hello!

Резолвер находит util.tpz рядом с входным файлом — без манифеста и настройки путей. Полные правила (пути, коллизии, циклы, порядок инициализации) описаны в разделе Модули.

Сборка нативного бинарника

topaz run выполняет программу через интерпретатор. Чтобы вместо этого скомпилировать её в самостоятельный нативный исполняемый файл, используйте topaz build:

topaz build hello.tpz --out-dir out --run

Команда понижает hello.tpz до Rust, собирает его офлайн в out/target/debug/program и (--run) запускает — печатая тот же Hello, Topaz!. Именно этому пути нужен установленный тулчейн Rust; страница состояния отслеживает гейты тулчейна.

Дальнейшие шаги