CatCore

File System

How to work with files, directories and symlinks.

CatCore has it's own file system structure:

...
...
bootloader.bin
kernel
kernel.conf
...
...
...
...
...

/ 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"]
end

What 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")

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".

On this page