파일시스템

fs 모듈은 구성된 파일시스템 볼륨 내에서 파일을 읽고, 쓰고, 관리합니다.

이 페이지는 API 레퍼런스입니다. 예제는 구성된 볼륨과 그 볼륨을 획득할 권한을 전제로 합니다. 각 블록은 독립적인 작업 또는 부분 레시피입니다. config, message, process, report_cleanup_error와 같은 애플리케이션 값과 콜백은 이미 존재해야 합니다. report_cleanup_error(err)는 이미 발생한 작업 오류를 대체하지 않고 close 실패를 기록합니다.

파일시스템 설정은 파일시스템을 참조하세요.

로딩

local fs = require("fs")

볼륨 획득

레지스트리 ID로 파일시스템 볼륨을 획득합니다:

local vol, err = fs.get("app:storage")
if err then
    return nil, err
end

local content, read_err = vol:readfile("/config.json")
if read_err then return nil, read_err end
return content

반환: FS, error

파일 읽기

전체 파일을 읽습니다:

local json = require("json")

local vol, get_err = fs.get("app:config")
if get_err then return nil, get_err end

local data, err = vol:readfile("/settings.json")
if err then
    return nil, err
end

local config, decode_err = json.decode(data)
if decode_err then return nil, decode_err end
return config

open()으로 대용량 파일을 스트리밍합니다:

local errors = require("errors")

local file, err = vol:open("/data/large.csv", "r")
if err then
    return nil, err
end

while true do
    local chunk, err = file:read(65536)
    if err then
        if err:kind() == errors.NOT_FOUND then
            break -- EOF
        end
        local _, close_err = file:close()
        if close_err then report_cleanup_error(close_err) end
        return nil, err
    end
    process(chunk)
end

local _, close_err = file:close()
if close_err then return nil, close_err end

파일 쓰기

문자열 또는 리더 기반 스트림을 파일에 씁니다:

local json = require("json")

local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Overwrite (default)
local encoded, encode_err = json.encode(config)
if encode_err then return nil, encode_err end
local _, write_err = vol:writefile("/config.json", encoded)
if write_err then return nil, write_err end

-- Append
local _, append_err = vol:writefile("/logs/app.log", message .. "\n", "a")
if append_err then return nil, append_err end

-- Exclusive write (fails if exists)
local ok, err = vol:writefile("/lock.pid", tostring(pid), "wx")
if err then return nil, err end

-- Copy from an open file or another reader-backed value
local source, err = vol:open("/incoming/report.csv", "r")
if err then
    return nil, err
end
local copied, err = vol:writefile("/archive/report.csv", source)
local _, close_err = source:close()
if err then
    if close_err then report_cleanup_error(close_err) end
    return nil, err
end
if close_err then return nil, close_err end
return copied

스트리밍 쓰기에는 파일 핸들을 사용합니다:

local file, open_err = vol:open("/output/report.txt", "w")
if open_err then return nil, open_err end
local _, header_err = file:write("Header\n")
if header_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, header_err
end
local _, data_err = file:write("Data: " .. value .. "\n")
if data_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, data_err
end
local _, sync_err = file:sync()
if sync_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, sync_err
end
local _, close_err = file:close()
if close_err then return nil, close_err end

경로 확인

local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Check existence
local exists, exists_err = vol:exists("/cache/results.json")
if exists_err then return nil, exists_err end
if exists then
    return vol:readfile("/cache/results.json")
end

-- Check if directory
local is_dir, isdir_err = vol:isdir(path)
if isdir_err then return nil, isdir_err end
if is_dir then
    process_directory(path)
end

-- Get file info
local info, stat_err = vol:stat("/documents/report.pdf")
if stat_err then return nil, stat_err end
print(info.size, info.modified, info.type)

Stat 필드: name, size, mode, modified, is_dir, type

디렉터리 작업

local vol, get_err = fs.get("app:data")
if get_err then return nil, get_err end

-- Create directory
local _, mkdir_err = vol:mkdir("/uploads/" .. user_id)
if mkdir_err then return nil, mkdir_err end

-- List directory contents
local iter, state = vol:readdir("/documents")
if not iter then return nil, state end
for entry in iter, state do
    print(entry.name, entry.type)
end

-- Remove file or empty directory
local removed, remove_err = vol:remove("/temp/file.txt")
if remove_err then return nil, remove_err end
return removed

항목 필드: name, type ("file" 또는 "directory")

mkdir는 하나의 디렉터리만 만들며 누락된 상위 디렉터리는 만들지 않습니다. remove는 파일과 빈 디렉터리만 처리합니다.

파일 핸들 메서드

스트리밍용 vol:open() 사용 시:

파일 핸들 사용이 끝나면 close()를 호출하세요.

스캐너

줄 단위 처리에는 스캐너를 사용합니다:

local file, err = vol:open("/data/users.csv", "r")
if err then
    return nil, err
end
local scanner, err = file:scanner("lines")
if err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, err
end

scanner:scan()  -- skip header

while scanner:scan() do
    local line = scanner:text()
    process(line)
end

local scan_err = scanner:err()
if scan_err then
    local _, close_err = file:close()
    if close_err then report_cleanup_error(close_err) end
    return nil, scan_err
end

local _, close_err = file:close()
if close_err then return nil, close_err end

분할 모드: "lines" (기본값), "words", "bytes", "runes"

scanner:scan()은 불리언만 반환합니다. false를 반환하면 scanner:err()를 호출해 정상 EOF와 토큰화 또는 하위 읽기 실패를 구분하세요. scanner:err()는 구조화된 INTERNAL 오류 또는 nil을 반환합니다. 스트림 스캐너와 달리 파일 스캐너에는 별도의 스캔 디스패치 오류 반환이 없습니다.

상수

fs.type.FILE      -- "file"
fs.type.DIR       -- "directory"

fs.seek.SET       -- from start
fs.seek.CUR       -- from current
fs.seek.END       -- from end

FS 메서드

권한

볼륨을 획득할 때 보안 정책 평가가 적용됩니다.

에러

unspecified는 err:retryable()이 nil을 반환한다는 뜻이며, false와 같지 않습니다.

오류 처리는 오류 처리를 참조하세요.