fs
Reading, writing, copying and moving files, file information, times and permissions, and MD5 and SHA digests.
import fs
The fs package is everything you need to work 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, change the permissions, hash it and guess its MIME type. One import is enough: import fs, then fs.ReadText(path). For folders use fs.dir, for paths fs.path, and for streaming a large file the handle functions of io. The simpler os package covers whole-file reads, folder listings and existence checks.
The old fs.file package still works but is deprecated: it forwards every call to fs. In new code write import fs and fs.ReadText instead of import fs.file and file.ReadText.
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, soReadAll,ReadBytes,WriteBytesand the digest functions cut a binary file short. For images, archives and other binary data useReadBinaryFileandWriteBinaryFilefrom archive, which carry a pointer and a length, and the pointer forms in crypto such asSha256Bytes. - Expecting
Moveto cross disks. It is a rename and fails between file systems;fs.dir.Movefalls back to copying, or copy and delete yourself. - Assuming
AtomicWritekeeps the old file's permissions. It writes a new file, which gets the default permissions; a file you had narrowed to0o600becomes readable again unless youChmodit after each save. - Using
Existsto mean "is a file". It is true for directories too; combine it withfs.dir.IsDir.
Times are whole seconds since the start of 1970 (Unix time), as an i64. Every function returns -1 when the path does not exist or the system cannot answer.
Write permissions in octal, such as 0o644, meaning the owner reads and writes and everyone else reads. Permissions returns the same digits as an ordinary number, such as 644, so that it reads easily. The two are not the same number (0o644 is 420), so never pass the result of Permissions back to Chmod unchanged.
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
import str
func main:
fs.WriteText("app.conf", "# shop settings\nname = Corner Shop\n\nport = 8080\ncurrency = IRR\n")
settings := HashMap {} as HashMap<str, str>
each line in fs.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")
fs.Delete("app.conf")
endFor 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
func log(line: str):
fs.Append("app.log", line.Concat("\n"))
end
func main:
log("started")
log("loaded 3 orders")
log("sent invoice 1042")
log("stopped")
lines := fs.ReadLines("app.log")
println "log has", lines.Len(), "lines,", fs.Size("app.log"), "bytes"
println "last two:"
mut i := lines.Len() - 2
until i < lines.Len():
println " ", lines.Get(i)
i++
end
fs.Delete("app.log")
endCheck 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
func verify(p: str): bool:
want := fs.ReadText(p.Concat(".sha256")).Trim()
ret fs.Sha256Hex(p) == want
end
func main:
fs.WriteBytes("release.tar", "pretend this is a release archive")
fs.WriteText("release.tar.sha256", fs.Sha256Hex("release.tar").Concat("\n"))
println "intact:", verify("release.tar")
fs.Append("release.tar", "!")
println "after a change:", verify("release.tar")
fs.Delete("release.tar")
fs.Delete("release.tar.sha256")
endThe 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
import os.error
func save(p: str, data: str): bool:
if fs.Exists(p): fs.Copy(p, p.Concat(".bak")) end
if fs.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:", fs.ReadText("profile.json")
println "backup: ", fs.ReadText("profile.json.bak")
println "temp file left:", fs.Exists("profile.json.tmp")
save("no-such-dir/profile.json", "{}")
fs.Delete("profile.json")
fs.Delete("profile.json.bak")
endServe 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
func main:
each name in ["index.html", "app.js", "logo.SVG", "photo.jpeg", "data.json", "notes", "backup.7z"]:
ext := fs.Extension(name)
if ext == "": println name, "(no extension)", fs.MimeType(name)
else: println name, ext, fs.MimeType(name)
end
end
endAn 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.
Keep a secret file private
A new file gets the system default permissions, usually 644, which lets every account on the machine read it. For tokens, keys and passwords, write the file and then narrow it to 0o600. Keep the two notations apart: Chmod takes octal (0o600), while Permissions gives the same digits back as an ordinary number (600). That is why p % 100 == 0 below means that the group and everyone else have no rights at all.
import fs
func main:
fs.WriteText("token.txt", "s3cr3t")
fs.Chmod("token.txt", 0o644)
println "before:", fs.Permissions("token.txt")
fs.Chmod("token.txt", 0o600)
p := fs.Permissions("token.txt")
println "after: ", p
if p % 100 == 0:
println "only the owner can read it"
end
fs.Delete("token.txt")
endReading the permission digits
The three digits are for the owner, the group and everyone else, in that order. Inside one digit, 4 means read, 2 means write and 1 means execute, and the digit is their sum:
| Digit | Letters | Meaning |
|---|---|---|
7 | rwx | read, write and run |
6 | rw- | read and write |
5 | r-x | read and run |
4 | r-- | read only |
0 | --- | nothing |
This example turns the number into the letters that ls -l prints. A script needs the execute bit for its owner (0o755 or 0o700) before the shell runs it, and a directory needs it before anyone can open it.
import fs
func letters(digit: int): str:
mut out := ""
if digit >= 4: out += "r" else: out += "-" end
if digit % 4 >= 2: out += "w" else: out += "-" end
if digit % 2 == 1: out += "x" else: out += "-" end
ret out
end
func show(p: int): str:
ret letters(p / 100) + letters(p / 10 % 10) + letters(p % 10)
end
func main:
fs.WriteText("deploy.sh", "echo deploying\n")
each mode in [0o755, 0o750, 0o644, 0o600]:
fs.Chmod("deploy.sh", mode)
p := fs.Permissions("deploy.sh")
println p, show(p)
end
fs.Delete("deploy.sh")
endRebuild only what changed
ModTime is how build tools such as make decide what to do: an output is out of date when its source changed after the output was written. For a path that does not exist ModTime returns -1, which the example reads as "build it". Times are in whole seconds, so a source and an output written in the same second count as up to date. That is the right answer here, because the output was written after the source.
import fs
func needs_build(src: str, out: str): bool:
built := fs.ModTime(out)
if built < 0: ret true end
ret fs.ModTime(src) > built
end
func main:
fs.WriteText("page.md", "# Hello\n")
println "first run, build:", needs_build("page.md", "page.html")
fs.WriteText("page.html", "<h1>Hello</h1>\n")
println "after building, build:", needs_build("page.md", "page.html")
fs.Delete("page.html")
println "output deleted, build:", needs_build("page.md", "page.html")
fs.Delete("page.md")
endPlatform notes
CreatedTimeis0where the file system does not record a creation time, which is common on Linux. UseModTimewhen you need a value that is always there.- On Linux, macOS and BSD the time functions and
Permissionsrun the systemstatcommand through the shell, with the path quoted. That is quick for a handful of files, but over thousands of files in a loop the process starts add up.Chmodcalls the system directly. - Windows has no Unix permission bits, only a read only flag, so
Chmodcan only switch that flag, andPermissionsreturns 292 (0o444) for a read only file and 438 (0o666) otherwise: the octal value, not the digits it gives on Unix. Write permission logic for Unix and test it there.
Which function for which job
| Job | Function |
|---|---|
| Read a small text file whole | ReadText, or ReadLines for a vector of lines |
| Read only the start of a file | ReadBytes |
| Replace a file's content | WriteText, or AtomicWrite when the file matters |
| Add to the end of a file | Append |
| Work through a big file piece by piece | Open, then the io functions, then Close |
| Size, times and permissions in one call | Stat |
| Duplicate, move or delete | Copy, Move (or Rename), Delete |
| Check a download | Sha256Hex |
| Content type for a web response | MimeType |
Types
FileInfo
struct FileInfo| Name | Type | Description |
|---|---|---|
size | i64 = 0 | The size in bytes. |
mod_time | i64 = 0 | When it was last changed. |
accessed_time | i64 = 0 | When it was last read. |
created_time | i64 = 0 | When it was created. |
permissions | int = 0 | The permissions, as octal digits such as 644. |
exists | bool = false | True when the path exists (a directory counts); the other fields are 0 when it does not. |
import fs
func main:
fs.WriteText("picture.png", "PNG")
info := fs.Stat("picture.png")
println info.exists, info.size, info.mod_time > 0, info.permissions > 0
println fs.Size("picture.png"), fs.Exists("picture.png")
println fs.ModTime("picture.png") > 0, fs.AccessedTime("picture.png") > 0, fs.CreatedTime("picture.png") >= 0
fs.Chmod("picture.png", 0o600)
println fs.Permissions("picture.png")
println fs.Extension("picture.png"), fs.MimeType("picture.png"), fs.MimeType("letter.pdf")
println fs.Stat("missing.txt").exists
endFileMeta
struct FileMeta| Name | Type | Description |
|---|---|---|
path | str = "" | |
exists | bool = false | |
is_file | bool = false | |
is_dir | bool = false | |
is_link | bool = false | |
size | i64 = 0 | |
mod_time | i64 = 0 | |
mode | u32 = 0 | |
readable | bool = false | |
writable | bool = false | |
executable | bool = false |
EventKind
enum EventKind| Name | Type | Description |
|---|---|---|
Created | | |
Modified | | |
Deleted | |
Event
struct Event| Name | Type | Description |
|---|---|---|
kind | EventKind | |
path | str = "" |
Watcher
struct Watcher| Name | Type | Description |
|---|---|---|
root | str = "" | |
recursive | bool = true | |
fingerprints | collections.OrderedMap | |
initialized | bool = false |
Functions
Open
func Open(path: str, mode: str): File*import fs
func main:
fs.WriteText("poem.txt", "The children of Adam are limbs of one body\n")
fs.Append("poem.txt", "having been created of one essence\n")
print fs.ReadText("poem.txt")
println fs.ReadAll("poem.txt") == fs.ReadText("poem.txt")
lines := fs.ReadLines("poem.txt")
println lines.Len(), lines.Get(1)
fs.WriteBytes("data.bin", "ABCDEF")
println fs.ReadBytes("data.bin", 3)
fs.AtomicWrite("settings.txt", "language=english")
println fs.ReadText("settings.txt")
f := fs.Open("poem.txt", "rb")
println f.Readline()
fs.Close(f)
endClose
func Close(f: File*)The example for this item is shown with the ones above: fs-ReadText.salam
ReadText
func ReadText(path: str): strThe example for this item is shown with the ones above: fs-ReadText.salam
ReadAll
func ReadAll(path: str): strReadText. The result is a str, so a binary file is cut at its first zero byte.The example for this item is shown with the ones above: fs-ReadText.salam
ReadBytes
func ReadBytes(path: str, n: int): strn bytes of the file, such as a header to recognise its format; cut short at a zero byte.The example for this item is shown with the ones above: fs-ReadText.salam
ReadLines
func ReadLines(path: str): Vector<str>\r removed.The example for this item is shown with the ones above: fs-ReadText.salam
WriteText
func WriteText(path: str, data: str): intThe example for this item is shown with the ones above: fs-ReadText.salam
WriteBytes
func WriteBytes(path: str, data: str): intWriteText. The data is a str, so it stops at the first zero byte and is not safe for binary content.The example for this item is shown with the ones above: fs-ReadText.salam
Append
func Append(path: str, data: str): intThe example for this item is shown with the ones above: fs-ReadText.salam
AtomicWrite
func AtomicWrite(path: str, data: str): intpath.tmp and renames it over the file, so an interrupted program leaves either the complete new version or the old one, never a half written file. Returns 0 or -1 (with an os.error record). The new file gets default permissions, and the data is not flushed to disk first.The example for this item is shown with the ones above: fs-ReadText.salam
Size
func Size(p: str): i64The example for this item is shown with the ones above: fs-Stat.salam
Extension
func Extension(p: str): str.JPG; empty when there is none.The example for this item is shown with the ones above: fs-Stat.salam
MimeType
func MimeType(p: str): strapplication/octet-stream for an unknown extension. The file is not opened.The example for this item is shown with the ones above: fs-Stat.salam
Stat
func Stat(p: str): FileInfostat command four times, so it is not faster than the single calls.The example for this item is shown with the ones above: fs-Stat.salam
Copy
func Copy(src: str, dst: str): intimport fs
func main:
fs.WriteText("original.txt", "hello")
fs.Copy("original.txt", "copy.txt")
fs.Move("copy.txt", "moved.txt")
fs.Rename("moved.txt", "final.txt")
println fs.Exists("copy.txt"), fs.Exists("final.txt"), fs.ReadText("final.txt")
fs.Delete("final.txt")
println fs.Exists("final.txt")
endMove
func Move(src: str, dst: str): intfs.dir.Move can copy instead.The example for this item is shown with the ones above: fs-Copy.salam
Rename
func Rename(src: str, dst: str): intMove.The example for this item is shown with the ones above: fs-Copy.salam
Delete
func Delete(p: str): intos.error as FileNotFound, a missing permission included.The example for this item is shown with the ones above: fs-Copy.salam
Exists
func Exists(p: str): boolThe example for this item is shown with the ones above: fs-Stat.salam
Md5Hex
func Md5Hex(p: str): strimport fs
func main:
fs.WriteText("message.txt", "abc")
println fs.Md5Hex("message.txt")
println fs.Sha1Hex("message.txt")
println fs.Sha256Hex("message.txt")
println fs.Sha512Hex("message.txt").Len()
endSha1Hex
func Sha1Hex(p: str): strThe example for this item is shown with the ones above: fs-Sha256Hex.salam
Sha256Hex
func Sha256Hex(p: str): strThe example for this item is shown with the ones above: fs-Sha256Hex.salam
Sha512Hex
func Sha512Hex(p: str): strThe example for this item is shown with the ones above: fs-Sha256Hex.salam
Exists
func Exists(path: str): boolThe example for this item is shown with the ones above: fs-Stat.salam
IsFile
func IsFile(path: str): boolIsDir
func IsDir(path: str): boolIsLink
func IsLink(path: str): boolIsSymlink
func IsSymlink(path: str): boolSize
func Size(path: str): i64The example for this item is shown with the ones above: fs-Stat.salam
CanRead
func CanRead(path: str): boolCanWrite
func CanWrite(path: str): boolCanExecute
func CanExecute(path: str): boolMode
func Mode(path: str): u32SetMode
func SetMode(path: str, mode: u32): boolMakeReadable
func MakeReadable(path: str): boolMakeWritable
func MakeWritable(path: str): boolMakeExecutable
func MakeExecutable(path: str): boolModTime
func ModTime(path: str): i64The example for this item is shown with the ones above: fs-Stat.salam
SetExecutable
func SetExecutable(path: str, executable: bool = true): boolGet
func Get(path: str): FileMetaFormatMode
func FormatMode(mode: u32): strIsReadable
func IsReadable(path: str): boolIsWritable
func IsWritable(path: str): boolIsExecutable
func IsExecutable(path: str): boolTypeName
func TypeName(path: str): strIsHidden
func IsHidden(path: str): boolModTime
func ModTime(path: str): i64The example for this item is shown with the ones above: fs-Stat.salam
AccessedTime
func AccessedTime(path: str): i64noatime), so do not rely on it.import fs
func main:
fs.WriteText("report.txt", "hello")
t := fs.ModTime("report.txt")
println t > 0, fs.AccessedTime("report.txt") > 0, fs.CreatedTime("report.txt") >= 0
fs.Chmod("report.txt", 0o644)
println fs.Permissions("report.txt")
endCreatedTime
func CreatedTime(path: str): i64The example for this item is shown with the ones above: fs-ModTime.salam
Chmod
func Chmod(path: str, mode: int): int0o644. Returns 0 on success and -1 on failure. On Windows only the read only flag can change.The example for this item is shown with the ones above: fs-ModTime.salam
Permissions
func Permissions(path: str): int644; -1 when the path does not exist. On Windows it returns 292 or 438 instead.The example for this item is shown with the ones above: fs-ModTime.salam
New
func New(root: str, recursive: bool = true): WatcherSnapshot
func Snapshot(w &: Watcher)Poll
func Poll(w &: Watcher): Vector<Event>PollSleepMs
func PollSleepMs(w &: Watcher, ms: int): Vector<Event>Reset
func Reset(w &: Watcher)FreeEvents
func FreeEvents(events &: Vector<Event>)IsInitialized
func IsInitialized(w &: Watcher): boolRoot
func Root(w &: Watcher): strFree
func Free(w &: Watcher)