파일과 리소스

파일 전체를 읽고 쓰려면 FS를, 파일을 연 채 여러 작업을 하려면 File을 쓰세요. 실패는 Result로 처리하고 파일을 닫을 시점은 using이나 defer로 정합니다.

첫 프로그램에서 토파즈를 설치하세요. 프로그램을 실행하는 환경이 파일 시스템 접근을 허용해야 합니다. 모듈을 가져와도 이 권한은 생기지 않습니다.

File 하나를 열어 읽기

작업 폴더에 ready가 담긴 UTF-8 파일 note.txt를 만드세요. 같은 폴더에 다음 프로그램을 files-resources.tpz로 저장하세요.

TOPAZ

function 메모읽기(경로: string) -> Result<string, string> {
    let mut 결과: Result<string, string> = Err("not read")
    using 파일 = open(경로)? {
        결과 = 파일.read()
    }
    return 결과
}

match 메모읽기("note.txt") {
    case Ok(텍스트) => print(텍스트.trim())
    case Err(오류) => print(오류)
}

그 폴더에서 topaz run files-resources.tpz를 실행하세요.

출력

ready

파일을 열면 open은 Ok(파일)을 반환합니다. 열기에 실패하면 ?가 블록에 들어가기 전에 메모읽기 함수에서 오류를 반환합니다.

파일을 연 뒤 using이 파일을 바인딩하고 close 호출을 등록합니다. 파일.read()는 읽은 Result를 바깥 변수에 저장합니다. 블록을 나가면 파일을 닫고, 함수는 저장한 결과를 반환합니다.

note.txt가 없으면 프로그램은 open의 오류를 출력합니다. 작업 폴더에 파일을 다시 만든 뒤 실행하세요. Err 분기가 오류 문자열을 출력하므로, 읽기에 실패해도 이 프로그램 자체는 성공 상태로 종료할 수 있습니다.

`FS`와 `File` 중 고르기

하려는 일	호출	반환 타입
텍스트 전체 읽기	`FS.readText(path)`	`Result<string, string>`
텍스트 전체 교체	`FS.writeText(path, text)`	`Result<(), string>`
바이트 전체 읽기	`FS.readBytes(path)`	`Result<Bytes, string>`
바이트 전체 교체	`FS.writeBytes(path, bytes)`	`Result<(), string>`
디렉터리 항목 나열	`FS.list(path)`	`Result<Array<{ kind: string, name: string, sizeBytes: Option<int> }>, string>`
파일을 열어 두기	`open(path)`	`Result<File, string>`

FS는 Path나 string을 받습니다. 쓰기 연산은 파일 내용을 교체합니다. 필요한 데이터를 덮어쓰기 전에 새 경로를 고르거나 복사본을 보관하세요.

열린 File에는 다음 호출을 사용합니다.

open(path: string) -> Result<File, string>
파일.read() -> Result<string, string>
파일.write(s: string) -> Result<(), string>
파일.close() -> ()

open으로 파일을 열고 read, write로 텍스트를 다루세요. 파일 전체의 바이너리 데이터에는 FS 바이트 연산을 씁니다. File.open, File.create, File.append, readLine, writeLine, flush는 없습니다.

`using`과 `defer` 중 고르기

파일이 필요한 곳	정리 방법
한 블록 안	`using 파일 = open(경로)? { ... }`가 블록을 나갈 때 닫음
함수 안의 여러 중첩 블록	`let 파일 = open(경로)?` 바로 다음에 `defer { 파일.close() }` 등록

using은 하위 스코프에 불변 바인딩을 만듭니다. 열린 파일은 그 스코프 안에서 사용하세요. using 안에서 직접 닫아도 등록한 닫기가 다시 실행되므로 수동으로 닫지 마세요. 반복해서 닫은 뒤의 동작은 런타임마다 다를 수 있습니다.

두 방식 모두 정상 종료와 return, 후위 ?, break, continue로 스코프를 나갈 때 정리합니다. 실행 오류(fault)가 나면 실행을 즉시 멈춥니다. 실행 오류 뒤의 정리 동작은 정해져 있지 않습니다.

파일 접근과 지원 연산

File, FS, std.fs, std.io에는 파일 시스템 접근을 허용하는 프로필이 필요합니다. 프로필은 프로그램이 사용할 수 있는 작업을 정합니다.
모듈을 가져와도 경로, 환경 변수, 프로세스, 네트워크, 데이터베이스 접근 권한은 생기지 않습니다.
열기·읽기·쓰기 실패는 Err 값으로 반환합니다. match로 처리하거나 ?로 전달하세요.
File은 내부 상태를 공개하지 않으며 비교할 수 없습니다. 닫은 뒤에는 사용하지 마세요.
File.write에는 런타임에 공통으로 적용되는 이어 쓰기 모드가 없습니다. File의 바이너리 오버로드, 버퍼링, 권한 제어, 줄 단위 메서드도 정해져 있지 않습니다.
using은 File 하나를 다룹니다. 사용자 정의 정리 프로토콜, 다중 리소스 using, 비동기·취소 정리, 모듈 종료 시 정리는 지원하지 않습니다.

정리 순서는 Defer와 리소스, 오류 전달은 Null·Option·결과·fault에서 확인하세요. 다른 작업은 표준 라이브러리 개요에서 찾으세요.

File 하나를 열어 읽기

FS와 File 중 고르기

using과 defer 중 고르기

파일 접근과 지원 연산

`FS`와 `File` 중 고르기

`using`과 `defer` 중 고르기