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

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

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

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

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

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

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

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

TOPAZ

function greet(name: string, language: string) -> string {
    return match language {
        case "한국어" => "안녕하세요, {name}님!"
        case "Русский" => "Привет, {name}!"
        case _ => "Hello, {name}!"
    }
}

let 사용자 = "김토파즈"
print(greet(사용자, "한국어"))
print(greet("Topaz", "Русский"))

Вывод

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

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

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

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

TOPAZ

function parsePort(raw: string) -> Result<int, string> {
    let n = toInt(raw) ?? -1
    if n < 1 {
        return Err("not a port: {raw}")
    }
    return Ok(n)
}

function startup(raw: string) -> Result<string, string> {
    defer print("config closed")
    let port = parsePort(raw)?
    return Ok("listening on {port}")
}

print("{startup("8080")}")
print("{startup("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 отдельно от интерполированных параметров, не сливая всё в одну строку:

TOPAZ

let table = "users"
let q = sql"select * from {table} where active = {true}"
print("{q}")

Вывод

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

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

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

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

TOPAZ

type TrafficLight = "red" | "yellow" | "green"

function next(light: TrafficLight) -> TrafficLight {
    return match light {
        case "red" => "green"
        case "green" => "yellow"
        case _ => "red"
    }
}

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

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

BASH

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

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

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

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

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