구형 문법 이전

이 문서는 구형 문법을 다루는 유일한 가이드입니다. 실제 v5 이전 버전의 토파즈 소스코드를 현재 문법으로 옮길 때만 참고하세요. 마이너 버전마다 순차적으로 수행하는 업그레이드 경로가 아닙니다. 하위 호환되는 제품 변경에는 별도의 이전 절차가 필요하지 않습니다. 기존 프로그램에서 관찰되는 동작 의도와 실행 결과를 미리 기록하고, 코드를 재작성하는 동안 해당 동작을 보존하세요. 이후 현재 검사기를 통해 남은 호환성 경계를 확인하세요.

1. 다시 쓰기 전에 결과 기록하기

진입점 파일, 모듈 루트, 입력값, 예상 출력값, 오류 상황, 파일·네트워크 부작용을 미리 기록해 두세요. 기존 코드베이스에 Rust나 JavaScript, 프레임워크 문법이 섞여 있다면 토파즈 소스코드와 외부 언어 예제를 분리하세요. 단순히 문법이 익숙해 보인다는 이유만으로 이전 문서에서 동작을 추측하지 마세요. 현재 매뉴얼과 정본 예제를 기준점으로 삼으세요.

2. 자주 나오는 표기 바꾸기

예전 표기	현재 표기	이유
`mut let x`	`let mut x`	가변성은 `let` 뒤에 표기합니다.
`[T]`	`Array<T>`	컬렉션 타입을 명시적으로 지정합니다.
`function(T) -> U`	`(T) -> U`	함수 타입을 선언 문법과 구분합니다.
`[head, ...tail]`	`[head, ..tail]`	패턴의 나머지는 `..`를 사용합니다.
`args: ...T`	`...args: T`	가변 매개변수 표기를 하나로 통일합니다.
익명 `function`	`(x: T) => expr`	익명 함수는 람다 표기로 작성합니다.
`s[i]`, `s.length`	`s.scalars()`, 명시적 문자열 API	문자열은 바이트 배열로 취급하지 않습니다.
백틱, `${expr}`	큰따옴표, `{expr}`	토파즈 문자열 보간 표기를 사용합니다.

실패와 값 없음을 구분하기

복구 가능한 실패는 Result로 표현합니다. 값이 없을 수 있는 상태는 Option이나 null을 포함한 타입으로 표현합니다. 계속 실행할 수 없는 상태는 런타임 오류로 표현합니다. 자원 정리 로직은 defer나 허용된 using 구문으로 이전하세요.

모듈 구조를 현재 규칙으로 맞추기

import/export 구문, 모듈 경로, 가시성, 초기화 순서를 모듈과 가시성을 기준으로 다시 정리하세요. 외부 언어 코드는 토파즈 모듈 내부에 직접 작성하지 마세요. 빌드 단계나 변환 경계에 배치하세요.

3. 예전 코드는 예전 코드로 표시하기

아래 표기는 구형 문법입니다. 정본 토파즈 코드 블록이 아니라 text 블록에만 작성하세요.

mut let 이름들: [string] = ["Ada"]
let 첫값 = 이름들[0]

현재 표준 문법은 가변성, 컬렉션 타입, 범위를 벗어난 인덱스 조회를 명시적으로 다룹니다.

TOPAZ

let mut 이름들: Array<string> = ["Ada"]
let 첫값: Option<string> = 이름들.get(0)
print("{첫값}")

출력

Some(Ada)

이름들.get(0)은 Option<string>을 반환합니다. 이에 따라 조회된 결과가 Some(Ada)로 드러납니다.

4. 문법뿐 아니라 동작도 확인하기

BASH

topaz check from-pre-v5.tpz
topaz run from-pre-v5.tpz

검사를 통과하면 실행 결과를 마이그레이션 전에 기록한 결과와 비교하세요. 모듈 초기화 순서, 컬렉션 순회 순서, 문자열 스칼라 위치, 수식 계산 오류, 자원 정리와 호스트 프로필 경계 동작도 다시 확인하세요.

배포할 네이티브·Python·Web 타깃 가운데 현재 소스코드를 지원하는 타깃만 빌드하세요. 빌드한 뒤에는 선언된 결과와 비교하세요. 지원하지 않는 형식은 의도와 다른 결과나 불완전한 산출물을 생성해서는 안 되며, 명확한 진단 메세지와 함께 거부되어야 합니다.

5. 자동화의 경계 알기

topaz migrate --from <version> --to <version>는 명시적으로 채택된 인접 v5 경계만 인식합니다. 이 명령은 해당 경계에서 호환되는 소스코드를 검사하거나 지원되는 패키지 메타데이터를 변경할 수 있습니다. 하지만 v5 이전 문법을 자동으로 변환하거나 기존 코드의 의미를 추론하지는 않습니다. 클래식은 역사적 맥락 참고용으로만 활용하세요. 코드는 현재 언어 문법으로 직접 옮기세요.

이전을 마치는 기준