Знакомство с Топазом

Эта страница описывает Топаз v5.17. Прежде чем считать её актуальной, сверьте поле version в /version.json со значением 5.17.

Топаз — компактный язык для прикладных программ. Его код читается примерно так же легко, как Python или TypeScript, но для каждой распространённой идеи язык предпочитает один последовательный способ записи. Одинаковые правила действуют и для человека, и для генератора кода.

Rust остаётся правильным инструментом там, где нужен прямой контроль машины. Топаз работает уровнем выше: командные инструменты, преобразование данных, серверная логика, конфигурация, SQL, shell и пути. Один исходник можно выполнить напрямую либо собрать в нативную программу, продукт для Python или веб-артефакт.

Эта страница объясняет назначение языка и показывает характер его кода. Это не первый урок. Если вы только знакомитесь с Топазом, откройте учебный маршрут или запустите первую программу в Playground. Краткий обзор синтаксиса служит картой языка, а философия языка объясняет принятые проектные решения.

Примеры ниже проверяются и выполняются настоящими инструментами Топаза.

Как выглядит код Топаза

Unicode по умолчанию

Идентификаторы — Unicode начиная с лексера. Слова предметной области остаются на вашем языке, а не превращаются в латинизированные приближения:

function приветствовать(имя: string, язык: string) -> string {
    return match язык {
        case "한국어" => "안녕하세요, {имя}님!"
        case "Русский" => "Привет, {имя}!"
        case _ => "Hello, {имя}!"
    }
}

let пользователь = "김토파즈"
print(приветствовать(пользователь, "한국어"))
print(приветствовать("Topaz", "Русский"))

안녕하세요, 김토파즈님!
Привет, Topaz!

사용자 — обычная переменная. Unicode-идентификаторы являются частью языка, а не исключением. Топаз не заменяет написанное имя другой формой и отклоняет имена модулей, которые легко перепутать.

Малая замкнутая поверхность

Для типичных решений есть предпочтительные формы. Восстановимая ошибка представлена Result, ожидаемое отсутствие — Option, очистка — defer, а match проверяет полноту вариантов. Эти решения закреплены в языке, поэтому каждый файл не превращается в отдельный диалект.

function разобратьПорт(исходное: string) -> Result<int, string> {
    let число = toInt(исходное) ?? -1
    if число < 1 {
        return Err("not a port: {исходное}")
    }
    return Ok(число)
}

function запустить(исходное: string) -> Result<string, string> {
    defer print("config closed")
    let порт = разобратьПорт(исходное)?
    return Ok("listening on {порт}")
}

print("{запустить("8080")}")
print("{запустить("http")}")

config closed
Ok(listening on 8080)
config closed
Err(not a port: http)

Оператор ? возвращает Err вызывающей стороне, а defer выполняется при любом выходе. Поэтому строка config closed появляется перед обоими результатами.

Шаблоны сохраняют намерение

В текущем реестре есть теги p, r, sh и sql. Например, p"..." создаёт шаблон пути, а sql"..." хранит текст SQL отдельно от интерполированных параметров, не сливая всё в одну строку:

let таблица = "users"
let запрос = sql"select * from {таблица} where active = {true}"
print("{запрос}")

<sql template, 3 part(s), 2 interpolation(s)>

Вывод показывает краткое описание структуры: шаблон по-прежнему различает буквальный текст и подставленные значения.

Одна проверка, несколько форматов

Топаз — статически типизированный язык. Проверка охватывает всю программу до запуска:

type Светофор = "red" | "yellow" | "green"

function следующий(сигнал: Светофор) -> Светофор {
    return match сигнал {
        case "red" => "green"
        case "green" => "yellow"
        case _ => "red"
    }
}

topaz run разбирает, связывает, проверяет и выполняет программу. Из того же исходника topaz emit и topaz build создают другие форматы. Цель Rust создаёт автономную нативную программу, а цель Python записывает program.py и файл поддержки topaz_py_rt.py.

Результаты Rust и Python проверяются на одних и тех же сценариях поведения языка. Текущая поддержка и ограничения отдельных целей перечислены на странице состояния.

topaz build app.tpz --target python --out-dir py-out

Когда Топаз не подходит

Используйте Rust, C или Zig, если вам нужен прямой контроль владения памятью и времени жизни данных, небезопасные границы, встроенные системы, ручная оптимизация горячих мест или полный доступ к системной экосистеме. Узкая дорога Топаза в таких задачах становится настоящей ценой.

Топаз предназначен для другой формы работы: развёртываемая прикладная логика без необходимости работать с исходным кодом системного уровня, слова предметной области прямо в программе и малая грамматика, которой одинаково предсказуемо пользуются люди и агенты. Если это похоже на вашу задачу, продолжайте по учебному маршруту.

Один способ сказать.