fs/file

The fs.file package is the fullest set of tools for working with one file: read it whole or as lines, write, append, replace it safely, copy, move and delete it, look up its size, times and permissions, hash it and guess its MIME type. Its copy, move, delete and atomic write functions record failures in os.error; reads and plain writes do not, so check what they return. For folders use fs.dir, for paths fs.path, and for streaming a large file the handle functions of io.

Writes return the number of bytes written, or -1. Reads return empty text when the file cannot be opened, the same as for an empty file; ask Exists when the difference matters.

What people get wrong:

• Treating it as binary-safe. Every read and write goes through a str, which ends at the first zero byte, so ReadAll, ReadBytes, WriteBytes and the digest functions cut a binary file short. For images, archives and other binary data use ReadBinaryFile and WriteBinaryFile from archive, which carry a pointer and a length, and the pointer forms in crypto such as Sha256Bytes.
• Expecting Move to cross disks. It is a rename and fails between file systems; fs.dir.Move falls back to copying, or copy and delete yourself.
• Assuming AtomicWrite keeps the old file's permissions. It writes a new file, which gets the default permissions; a file you had narrowed to 0o600 becomes readable again unless you Chmod it after each save.
• Using Exists to mean "is a file". It is true for directories too; combine it with fs.dir.IsDir.

Read a settings file line by line

ReadLines splits a file at its line breaks and drops a trailing \r, so a file saved on Windows reads the same as one saved on Linux. That makes simple key = value files easy: trim each line, skip blank lines and comments, and split at the first =.

import fs.file
import str

func main:
    file.WriteText("app.conf", "# shop settings\nname = Corner Shop\n\nport = 8080\ncurrency = IRR\n")
    settings := HashMap {} as HashMap<str, str>
    each line in file.ReadLines("app.conf"):
        t := line.trim()
        if t.len() == 0 or str.StartsWith(t, "#"): continue end
        eq_at := str.IndexOf(t, "=")
        if eq_at < 0: continue end
        settings.put(t.substr(0, eq_at).trim(), t.substr(eq_at + 1, t.len() - eq_at - 1).trim())
    end
    println settings.size(), "settings"
    println "name:", settings.get("name")
    println "port:", settings.get("port")
    file.Delete("app.conf")
end

For a format with sections, quoting or nesting, use a real parser such as encoding.toml, encoding.json or encoding.envfile.

Append to a log

Append opens the file, adds the text at the end and closes it again, and creates the file on the first call. Each call is a separate open and close, which is fine for a line now and then. For a busy log, open the file once with Open(p, "ab"), write through io.Write and Close it at the end.

import fs.file

func log(line: str):
    file.Append("app.log", line.concat("\n"))
end

func main:
    log("started")
    log("loaded 3 orders")
    log("sent invoice 1042")
    log("stopped")
    lines := file.ReadLines("app.log")
    println "log has", lines.len(), "lines,", file.Size("app.log"), "bytes"
    println "last two:"
    mut i := lines.len() - 2
    until i < lines.len():
        println " ", lines.get(i)
        i += 1
    end
    file.Delete("app.log")
end

Check that a file arrived intact

Download pages often publish a SHA-256 digest next to each file. Compute the digest of your copy with Sha256Hex and compare the two: a change of even one byte gives a completely different digest. Md5Hex and Sha1Hex are fine for noticing accidental changes, such as a cache key, but anyone can build two different files with the same MD5 or SHA-1 on purpose, so do not trust them against an attacker.

import fs.file

func verify(p: str): bool:
    want := file.ReadText(p.concat(".sha256")).trim()
    ret file.Sha256Hex(p) == want
end

func main:
    file.WriteBytes("release.tar", "pretend this is a release archive")
    file.WriteText("release.tar.sha256", file.Sha256Hex("release.tar").concat("\n"))
    println "intact:", verify("release.tar")
    file.Append("release.tar", "!")
    println "after a change:", verify("release.tar")
    file.Delete("release.tar")
    file.Delete("release.tar.sha256")
end

The digest functions read the file into a string first, and a Salam string ends at the first zero byte. For text files that does not matter. A binary file that contains a zero byte, which most archives and images do, is hashed only up to that byte, so check such files with the system sha256sum or with the buffer functions in crypto, such as Sha256Bytes. The same limit applies to ReadAll, ReadText, ReadBytes and WriteBytes.

Save without losing the old version

AtomicWrite writes the new content to name.tmp next to the target and then renames it over the target in one step. A program that crashes in the middle leaves either the old file or the new one, never half of each. It does not flush the data to the disk first, so after a power cut a file saved a moment earlier can still be lost on some file systems, and two programs saving the same file at once share the same .tmp name. Copying the old file to .bak first also keeps one previous version. When the folder does not exist, AtomicWrite returns -1 and leaves its message in os.error.

import fs.file
import os.error

func save(p: str, data: str): bool:
    if file.Exists(p): file.Copy(p, p.concat(".bak")) end
    if file.AtomicWrite(p, data) != 0:
        println "save failed:", error.LastMessage()
        ret false
    end
    ret true
end

func main:
    save("profile.json", "{\"name\": \"Sara\"}")
    save("profile.json", "{\"name\": \"Sara\", \"city\": \"Tabriz\"}")
    println "current:", file.ReadText("profile.json")
    println "backup: ", file.ReadText("profile.json.bak")
    println "temp file left:", file.Exists("profile.json.tmp")
    save("no-such-dir/profile.json", "{}")
    file.Delete("profile.json")
    file.Delete("profile.json.bak")
end

Serve files with the right type

A web server has to send a Content-Type with each file. MimeType picks it from the extension alone, without upper and lower case mattering, and knows the common web, image, audio, video and archive types; anything else is application/octet-stream, which browsers download instead of showing. Extension keeps the dot and the original case, and is empty when the name has no extension.

import fs.file

func main:
    each name in ["index.html", "app.js", "logo.SVG", "photo.jpeg", "data.json", "notes", "backup.7z"]:
        ext := file.Extension(name)
        if ext == "": println name, "(no extension)", file.MimeType(name)
        else: println name, ext, file.MimeType(name)
        end
    end
end

An HTTP server usually wants net.mime instead: its MimeType adds ; charset=utf-8 to text types and knows web fonts, and the package also parses Content-Type headers and multipart bodies.

Which function for which job

Types

struct FileInfo

import fs.file

func main:
    file.WriteText("picture.png", "PNG")
    info := file.Stat("picture.png")
    println info.exists, info.size, info.mod_time > 0, info.permissions > 0
    println file.Size("picture.png"), file.Exists("picture.png")
    println file.ModTime("picture.png") > 0, file.AccessedTime("picture.png") > 0, file.CreatedTime("picture.png") >= 0
    file.Chmod("picture.png", 0o600)
    println file.Permissions("picture.png")
    println file.Extension("picture.png"), file.MimeType("picture.png"), file.MimeType("letter.pdf")
    println file.Stat("missing.txt").exists
end

Functions

func Open(path: str, mode: str): File*

import fs.file

func main:
    file.WriteText("poem.txt", "The children of Adam are limbs of one body\n")
    file.Append("poem.txt", "having been created of one essence\n")
    print file.ReadText("poem.txt")
    println file.ReadAll("poem.txt") == file.ReadText("poem.txt")
    lines := file.ReadLines("poem.txt")
    println lines.len(), lines.get(1)
    file.WriteBytes("data.bin", "ABCDEF")
    println file.ReadBytes("data.bin", 3)
    file.AtomicWrite("settings.txt", "language=english")
    println file.ReadText("settings.txt")
    f := file.Open("poem.txt", "rb")
    println f.readline()
    file.Close(f)
end

func Close(f: File*)

func ReadText(path: str): str

func ReadAll(path: str): str

func ReadBytes(path: str, n: int): str

func ReadLines(path: str): Vector<str>

func WriteText(path: str, data: str): int

func WriteBytes(path: str, data: str): int

func Append(path: str, data: str): int

func AtomicWrite(path: str, data: str): int

func Size(p: str): i64

func ModTime(p: str): i64

func AccessedTime(p: str): i64

func CreatedTime(p: str): i64

func Permissions(p: str): int

func Chmod(p: str, mode: int): int

func Extension(p: str): str

func MimeType(p: str): str

func Stat(p: str): FileInfo

func Copy(src: str, dst: str): int

import fs.file

func main:
    file.WriteText("original.txt", "hello")
    file.Copy("original.txt", "copy.txt")
    file.Move("copy.txt", "moved.txt")
    file.Rename("moved.txt", "final.txt")
    println file.Exists("copy.txt"), file.Exists("final.txt"), file.ReadText("final.txt")
    file.Delete("final.txt")
    println file.Exists("final.txt")
end

func Move(src: str, dst: str): int

func Rename(src: str, dst: str): int

func Delete(p: str): int

func Exists(p: str): bool

func Md5Hex(p: str): str

import fs.file

func main:
    file.WriteText("message.txt", "abc")
    println file.Md5Hex("message.txt")
    println file.Sha1Hex("message.txt")
    println file.Sha256Hex("message.txt")
    println file.Sha512Hex("message.txt").len()
end

func Sha1Hex(p: str): str

func Sha256Hex(p: str): str

func Sha512Hex(p: str): str