filesystem
Reading and writing files through a small virtual filesystem.
A Filesystem knows two places. The save directory is writable and is where
write, append, createDirectory and remove act; you pick it once with
setIdentity, which uses the platform's per-user preferences path. The
source directory is read-only and is the directory the executable lives in.
You can add more read directories with mount. Reading searches the save
directory first, then the source directory, then the mounts.
Names are relative and stay inside the sandbox, so a name with a leading slash
or a .. part is rejected rather than reaching outside the chosen
directories. This builds on std/os and the platform path helpers rather than
SDL's asynchronous Storage API, which buys nothing extra on desktop.
type FileItemKind = enum
What a name points at. fikOther covers symlinks to non-files, devices
and anything that is neither a plain file nor a directory.
Values
-
fikFile -
fikDirectory -
fikOther
type FileInfo2d = object
Fields
-
kindFileItemKind -
sizeint64– size in bytes (0 for directories) -
modtimeint64– last modification time, Unix seconds
newFilesystem ¶
proc newFilesystem(): Filesystem
Create a filesystem with the source directory set to the program's base
path and no save identity yet.
Returns
Filesystem
setIdentity ¶
proc setIdentity(fs: Filesystem; org, app: string)
Set the org and app folder names used for the save directory, and create
it. Call once before reading or writing saves.
Parameters
-
fs(Filesystem) -
org(string) -
app(string)
setIdentity ¶
proc setIdentity(fs: Filesystem; app: string)
Set just the app folder name for the save directory, with an empty org.
Parameters
-
fs(Filesystem) -
app(string)
getSaveDirectory ¶
proc getSaveDirectory(fs: Filesystem): string
The absolute path of the writable save directory, or "" if no identity has
been set.
Parameters
-
fs(Filesystem)
Returns
string
getSourceDirectory ¶
proc getSourceDirectory(fs: Filesystem): string
The absolute path of the read-only source directory.
Parameters
-
fs(Filesystem)
Returns
string
mount ¶
proc mount(fs: Filesystem; path: string)
Add a read directory to search when reading. Mounts are searched after the
save and source directories, in the order they were added.
Parameters
-
fs(Filesystem) -
path(string)
unmount ¶
proc unmount(fs: Filesystem; path: string): bool
Remove a previously mounted read directory. Returns true if it was mounted.
Parameters
-
fs(Filesystem) -
path(string)
Returns
bool
read ¶
proc read(fs: Filesystem; name: string): string
Read a whole file as a string, searching the save directory, then the
source directory and mounts. Raises IOError if not found.
Parameters
-
fs(Filesystem) -
name(string)
Returns
string
lines ¶
iterator lines(fs: Filesystem; name: string): string
Yield the file's lines one at a time without the trailing newline.
Parameters
-
fs(Filesystem) -
name(string)
Returns
string
exists ¶
proc exists(fs: Filesystem; name: string): bool
True if a file or directory by that name exists in any search root.
Parameters
-
fs(Filesystem) -
name(string)
Returns
bool
getInfo ¶
proc getInfo(fs: Filesystem; name: string): Option[FileInfo2d]
Type, size and modification time for a name if it exists, or none.
Parameters
-
fs(Filesystem) -
name(string)
Returns
Option[FileInfo2d]
getDirectoryItems ¶
proc getDirectoryItems(fs: Filesystem; dir: string): seq[string]
The names (not full paths) of entries in a directory, merged across the
search roots with duplicates removed. An empty dir lists the top-level entries of each search root.
Parameters
-
fs(Filesystem) -
dir(string)
Returns
seq[string]
write ¶
proc write(fs: Filesystem; name: string; data: string)
Write data to a file in the save directory, replacing it if it exists and
creating parent directories as needed.
Parameters
-
fs(Filesystem) -
name(string) -
data(string)
write ¶
proc write(fs: Filesystem; name: string; data: openArray[byte])
Write raw bytes to a file in the save directory, replacing it if it exists.
Parameters
-
fs(Filesystem) -
name(string) -
data(openArray[byte])
append ¶
proc append(fs: Filesystem; name: string; data: string)
Append data to the end of a file in the save directory, creating it if it
does not exist.
Parameters
-
fs(Filesystem) -
name(string) -
data(string)
createDirectory ¶
proc createDirectory(fs: Filesystem; dir: string)
Create a directory and any missing parents inside the save directory.
Parameters
-
fs(Filesystem) -
dir(string)
remove ¶
proc remove(fs: Filesystem; name: string): bool
Delete a file or empty directory from the save directory. Returns true if
something was removed.
Parameters
-
fs(Filesystem) -
name(string)
Returns
bool