Topazdocs
Начало

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

Topaz — компактный язык для прикладных программ с единообразным синтаксисом и поддержкой Unicode.

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

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

Примеры на этой странице проверяются и выполняются инструментами Topaz.

Интеграция с Lena Code. Topaz входит в семейство продуктов STUDIO HAZE вместе с Lena Code. В процессах преобразования Lena Code можно выбрать Topaz как исходный или целевой язык. Подробности находятся на странице Интеграция с Lena Code.

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", "Русский"))
OUTPUT
안녕하세요, 김토파즈님!
Привет, Topaz!

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

Четыре вещи, которые нужно знать

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

У каждого намерения один способ записи. Восстановимая ошибка — Result, отсутствие — опционал, очистка — 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")}")
OUTPUT
config closed
Ok(listening on 8080)
config closed
Err(not a port: http)

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

Удобство для генераторов кода

Topaz даёт коду человека и генератора один сосредоточенный синтаксис. Неверные формы приводят к понятной ошибке, а примеры на сайте проверяются настоящими инструментами. Поэтому код остаётся читаемым независимо от того, кто его создал.

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

Строки sql, sh и path — это шаблоны. Они остаются структурированными значениями, где части и интерполяции не схлопываются в одну строку:

TOPAZ
let table = "users"
let q = sql"select * from {table} where active = {true}"
print("{q}")
OUTPUT
<sql template, 3 part(s), 2 interpolation(s)>

Сейчас вывод показывает структуру шаблона. Отдельные способы формирования SQL, shell и других шаблонов появятся в будущих версиях.

Статическая проверка и несколько целей

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

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 тестируются на одном поведении языка. Текущая поддержка и ограничения отдельных целей перечислены на странице состояния.

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

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

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

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

С чего начать

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