Topazdocs
개요

토파즈 시작하기

토파즈를 설치하고 v5.2 툴체인으로 첫 프로그램 실행하기: hello, 10줄 투어, 실제 폴트, 두 파일짜리 모듈 유닛.

안내: 이 페이지의 모든 프로그램은 보이는 그대로 v5.2 툴체인에서 실행되었고, 출력은 사이트 검증기가 바이트 단위로 고정합니다. 오늘 무엇이 돌고 무엇이 그것을 증명하는지는 툴체인 상태에서 확인할 수 있습니다.

토파즈 설치

레포 클론도, 빌드도 없이 topaz 툴체인을 설치합니다.

셸 (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 run, topaz check, topaz emit은 단독 바이너리만으로 동작합니다. topaz build로 곧장 네이티브 바이너리를 만들면 rustup을 통해 cargo로 셸아웃하므로, 그 명령 하나만은 머신에 Rust 툴체인이 있어야 합니다.

첫 프로그램

hello.tpz 파일을 만듭니다:

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

실행합니다:

topaz run hello.tpz
OUTPUT
Hello, Topaz!

이것이 전부입니다: 파일 하나, topaz run, 출력. 프로젝트 스캐폴딩도, 매니페스트도, 빌드 단계도 없습니다.

10줄 투어

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는 그 결과를 그대로 반환합니다. arm에는 리터럴, 범위, 바인딩, 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]}")
  |         ^^^^^

프로세스는 0이 아닌 코드로 종료합니다. 폴트는 계약 위반의 표지이고, 처리할 것을 예상하는 부재는 옵셔널로 모델링합니다. 에러 처리를 참고하세요.

두 파일로 보는 모듈

.tpz 파일들이 모인 디렉터리가 유닛(unit)입니다. 파일은 이름으로 서로를 임포트하고, 가시성 제어는 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 툴체인이 필요한 부분이며, 상태 페이지가 툴체인 게이트를 추적합니다.

다음 단계