토파즈문서

토파즈 소개

토파즈는 애플리케이션 의도를 간결하고 일관된 문법으로 표현하는 프로그래밍 언어입니다.

토파즈는 애플리케이션 의도를 간결하게 표현하는 프로그래밍 언어입니다. Python이나 TypeScript처럼 가독성이 높지만, 동일한 동기를 여러 구문으로 분산하기보다 일관된 단일 문법 구조를 채택합니다. 사람이 직접 작성한 코드와 도구가 생성한 코드 모두 동일한 규칙을 적용받습니다.

하드웨어를 정밀하게 제어해야 하는 작업에는 Rust가 더 적합합니다. 토파즈는 그보다 상위 추상화 계층을 다룹니다. 명령줄 도구, 데이터 변환, 서비스 로직, 설정 처리, 그리고 SQL·셸·경로를 다루는 프로그램 개발에 집중합니다. 동일한 소스코드를 직접 실행할 수도 있고, 네이티브 프로그램이나 Python 아티팩트, 웹 아티팩트 형태로 빌드할 수도 있습니다.

이 문서는 토파즈가 적합한 작업 영역과 소스코드의 기본적인 구조를 소개합니다. 입문용 튜토리얼은 아닙니다. 토파즈를 처음 접한다면 학습 경로를 확인하거나 플레이그라운드에서 첫 프로그램을 실행해 보세요. 언어 전반을 빠르게 살펴보고 싶다면 문법 한눈에 보기를 보세요. 설계 철학이 궁금하다면 언어 철학을 읽어 보세요.

아래 예제는 실제 토파즈 도구로 검증하고 실행한 코드입니다.

토파즈 코드의 모습

유니코드를 기본으로

식별자는 렉서 단계부터 유니코드를 직접 수용합니다. 도메인 용어를 로마자로 변환하지 않고 소스코드에 그대로 작성합니다.

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

let 사용자 = "김토파즈"
print(인사(사용자, "한국어"))
print(인사("Topaz", "Русский"))
출력
안녕하세요, 김토파즈님!
Привет, Topaz!

사용자는 일반적인 변수입니다. 유니코드 식별자는 예외적인 기능이 아닌 언어의 기본 사양입니다. 토파즈는 작성된 식별자 이름을 임의로 변경하지 않습니다. 모호하거나 충돌 위험이 있는 모듈 이름은 오류로 처리합니다.

작고 닫힌 표면

자주 마주치는 구현 패턴에는 권장 형식이 정의되어 있습니다. 복구 가능한 실패는 Result, 예상되는 값의 부재는 Option, 자원 정리는 defer로 표현합니다. match 구문은 모든 조건을 다루었는지 검사합니다. 언어 차원에서 이 같은 기준을 제시하므로 파일마다 독자적인 방언을 정의할 필요가 없습니다.

TOPAZ
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 원문과 보간된 매개변수를 독립되게 보존합니다. 두 요소를 단일 문자열로 병합하지 않습니다.

TOPAZ
let 표 = "users"
let 질의 = sql"select * from {표} where active = {true}"
print("{질의}")
출력
<sql template, 3 part(s), 2 interpolation(s)>

출력 결과는 구체적인 구조를 요약해 보여줍니다. 템플릿 내부에는 원문 영역과 보간된 값이 각각 명확히 구분되어 유지됩니다.

한 번 검사하고, 필요한 출력 선택하기

토파즈는 정적 타입 언어입니다. 프로그램을 실행하기 전에 소스 파일 전체의 타입을 검사합니다.

TOPAZ
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 산출물은 동일한 언어 규칙을 준수하도록 함께 검증합니다. 현재 지원 범위와 제약 사항은 툴체인 상태에서 확인할 수 있습니다.

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

토파즈가 맞지 않는 경우

소유권과 수명을 직접 제어해야 하거나, 안전하지 않은 메모리 경계와 임베디드 환경을 다루어야 할 때, 혹은 성능 병목을 세밀하게 최적화해야 한다면 Rust, C, Zig가 더 적합합니다. 토파즈는 이러한 저수준 제어를 목표로 하지 않습니다.

토파즈는 그 반대편 영역의 작업을 수행하는 언어입니다. 시스템 레벨 소스를 직접 다루지 않고 애플리케이션 로직을 배포하고 싶을 때, 도메인 용어를 코드에 그대로 남기고 싶을 때, 개발자와 에이전트가 일관되게 다룰 수 있는 간결한 구문 체계가 필요할 때 적합합니다. 이러한 작업을 시작하려면 학습 경로로 이어가세요.

말하는 방법은 하나.