File System
How to work with files, directories and symlinks.
CatCore has it's own file system structure:
/ is root, containing mounts inside.
/app, /bin, /boot, /config, /data, /dev, /lib, /system and /tmp are mounts, each one has it's own use:
Now that you know the structure, let's look at how you can interact with it inside your code. First you might want to check if some path exists, get it's info and directtory contents inside:
if (await CatCore.FS.exists("/", true)) {
// Path / exists
// Get info
var info = await CatCore.FS.info("/", true);
console.log(info.type == CatCore.FS.Type.ROOT); // true
var contents = await CatCore.FS.readdir("/");
console.log(contents); // ["bin", "boot", "config", "data", "dev", "system"]
}if (await $CatCore->FS->exists("/", true)) {
// Path / exists
// Get info
$info = await $CatCore->FS->info("/", true);
echo $info->type == $CatCore->FS->Type->ROOT; // true
$contents = await $CatCore->FS->readdir("/");
echo $contents; // ["bin", "boot", "config", "data", "dev", "system"]
}if await CatCore.FS.exists("/", true)
# Path / exists
# Get info
info = await CatCore.FS.info("/", true)
puts(info.type == CatCore.FS.Type.ROOT) # true
contents = await CatCore.FS.readdir("/")
puts(contents) # ["bin", "boot", "config", "data", "dev", "system"]
endWhat does true mean here?
You might have noticed that CatCore.FS.exists and CatCore.FS.info have true as a second argument.
That argument is named follow and controls if that function should follow symlinks.
Until you learn symlinks, you can keep it as true.
Making changes
Let's actually make some changes - like create and delete a directory, for example:
// Creating a folder
await CatCore.FS.mkdir("/data/test");
// Deleting a folder
await CatCore.FS.rmdir("/data/test", true);// Creating a folder
await $CatCore->FS->mkdir("/data/test");
// Deleting a folder
await $CatCore->FS->rmdir("/data/test", true);# Creating a folder
await CatCore.FS.mkdir("/data/test")
# Deleting a folder
await CatCore.FS.rmdir("/data/test", true)What does true mean here?
You might have noticed that CatCore.FS.rmdir has true as a second argument.
That argument is named recursive and controls if that function should delete directory recursively (even if it contains files and folders inside!).
Working with files
Files can be hard to work with:
// fd is a handle
var fd = await CatCore.FS.open("/data/test.txt", "rw+");
// Writing to a file
await fd.write("Test!");
// Reading a file as Buffer
var contents = await fd.read();
// Or as a string
var contents = await fd.readString();
// Or as JSON
var contents = await fd.readJSON();
// Close the handle once you finished working with it!
fd.close();// $fd is a handle
$fd = await $CatCore->FS->open("/data/test.txt", "rw+");
// Writing to a file
await $fd->write("Test!");
// Reading a file as Buffer
$contents = await $fd->read();
// Or as a string
$contents = await $fd->readString();
// Or as JSON
$contents = await $fd->readJSON();
// Close the handle once you finished working with it!
$fd->close();# fd is a handle
fd = await CatCore.FS.open("/data/test.txt", "rw+")
# Writing to a file
await fd.write("Test!")
# Reading a file as Buffer
contents = await fd.read()
# Or as a string
contents = await fd.readString()
# Or as JSON
contents = await fd.readJSON()
# Close the handle once you finished working with it!
fd.close()Files work using handles, as you can see you need to open them with a specific mode, then do operations and close it.
If you're wondering what mode means: r means allow Reading, w means allow Writing, x - eXclusive (will give an error instead of opening the file if it exists), + will create the file if it doesn't exist.
Why do I need the mode?
You might want to open every file as rw+, even if you're not planning to write to it, but that's not recommended. Why?
Different modes restrict the file differently for other processes. If you're not planning to write to the file, please open the file without w mode, which will allow other processes to write to it to freely.
Simplifying files
Handles can be hard to work with, especially if you only need to read file once - you have to open in a correct mode, read, close. There's actually some built-in functions to simplify this process:
var contents = await CatCore.FS.readFileString("/data/test.txt");$contents = await $CatCore->FS->readFileString("/data/test.txt");contents = await CatCore.FS.readFileString("/data/test.txt")As you can see in this example, there's functions like CatCore.FS.readFile, CatCore.FS.readFileString, CatCore.FS.readFileJSON, CatCore.FS.writeFile and they all are simplifying work with files. Note, that you still use handles - these functions are just wrappers and all they do is open, do the action and close.
Deleting files
Deleting files is easy:
await CatCore.FS.deleteFile("/data/test.txt");await $CatCore->FS->deleteFile("/data/test.txt");await CatCore.FS.deleteFile("/data/test.txt")Symlinks
Symbolic links (or symlinks) are just shortcuts. Let's make a symlink:
await CatCore.FS.link("/data/test.txt", "/data/test2.txt");await $CatCore->FS->link("/data/test.txt", "/data/test2.txt");await CatCore.FS.link("/data/test.txt", "/data/test2.txt")After this operation, there will be two paths /data/test.txt and /data/test2.txt, but they both point to a single file! If you change contents of one of them, other one will also change. Symlinks also work the same with directories.
Path normalization
If you're making a file explorer, a terminal or anything else, you might need this function:
var fixedPath = CatCore.FS.normalizePath("/data\\../data/./test.txt");$fixedPath = $CatCore->FS->normalizePath("/data\\../data/./test.txt");fixedPath = CatCore.FS.normalizePath("/data\\../data/./test.txt")This function "fixes" paths - "/data\\../data/./test.txt" will be transformed to "/data/test.txt".