File-System Module

FicsIt-Networks implements it’s own virtual filesystem for UNIX like experience using the FileSystem. The file system consists of nodes. Such a node can be a File, a Folder or something else. Each nodes is able to have child nodes and might be able to get opened with a file stream. A folder also delivers an abstract interface for adding and removing nodes. A Device implements lookup functions for searching for nodes in the filesystem structure. Such a device can be a temporary filesystem (tmpfs) which exists only in memory and which will get purged on a system reboot, or f.e. a disk filesystem (drives) which store the nodes on the real virtual filesystem in a folder. You can then mount such a device to a location in the root filesystem tree so when you now access a path, the filesystem looks first for the device and uses then the remaining path to get the node data from the device. There is also a DriveNode which simply holds a reference to a drive so you can access a drive via the filesystem. You can use then the mount function to mount the Drive of a DriveNode to the given location in the filesystem tree. Because you need at least one drive mounted to even be able to access any node, we provide the initFileSystem function which you can call only once in a system session. This functions will then mount the DevDevice to the given location. The DevDevice is a sepcial Device which holds all the DeviceNodes representing Device attached to the computer session, like hard drives, tempfs and the serial I/O.

Globals

filesystem

The filesystem api provides structures, functions and variables for interacting with the virtual file systems. You can’t access files outside the virtual filesystem. If you try to do so, the Lua runtime crashes.

filesystem.analyzePath (…​: string) → …​

Each provided string will be viewed as one filesystem-path and will be checked for lexical features.
Each of those string will then have a integer return value which is a bit-flag-register describing those lexical features.

Bit-Flags

1

Is filesystem root

2

Is Empty (includes if it is root-path)

3

Is absolute path

4

Is only a file/folder name

5

Filename has extension

6

Ends with a / → refers a directory
Details
Parameters
Name Type Description

Paths …​

string

Paths that will be analyzed
Return Values
Name Type Description

Results …​

integer

Analysis results

filesystem.children (path: string) → string[]

Lists all children names of the node with the given path. (i.e. items in a folder)

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to list
Return Values
Name Type Description

Children children

string[]

file names of children

filesystem.createDir (path: string, recursive: bool) → boolean

Creates the folder path.

Details
Parameters
Name Type Description

Path path

string

folder path the function should create

Recursive recursive

boolean

If false creates only the last folder of the path. If true creates all folders in the path.
Return Values
Name Type Description

Success success

boolean

Returns true if it was able to create the directory.

filesystem.doFile (path: string) → …​

Executes Lua code in the file referd by the given path.

Function fails if path doesn￢ﾀﾙt exist or path doesn￢ﾀﾙt refer to a file.

Returns the result of the execute function or what ever it yielded.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to execute
Return Values
Name Type Description

Results …​

any

the result of the execute function or what ever it yielded

filesystem.exists (path: string) → boolean

Returns true if the given path exists.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to check
Return Values
Name Type Description

Exists exists

boolean

returns true if the given file exists

filesystem.isDir (path: string) → boolean

Returns true if the given path refers to directory.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to check
Return Values
Name Type Description

Is dir isDir

boolean

returns true if the given path refers to a directory

filesystem.isFile (path: string) → boolean

Returns true if the given path refers to a file.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to check
Return Values
Name Type Description

Is file isFile

boolean

returns true if the given path refers to a file

filesystem.isNode (…​: string) → …​

For each given string, returns a bool to tell if string is a valid node (file/folder) name.

Details
Parameters
Name Type Description

Paths …​

string

Paths that will be checked
Return Values
Name Type Description

Results …​

boolean

True if path is a valid node (file/folder) name

filesystem.loadFile (path: string) → fun(): …​

Loads the file refered by the given path as a Lua function and returns it. Functions fails if path doesn￢ﾀﾙt exist or path doesn￢ﾀﾙt reger to a file.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to load
Return Values
Name Type Description

Code code

fun(): …​

a function that runs the loaded code

filesystem.meta (…​: string) → …​

Returns for each given string path, a table that defines contains some meta information about node the string references.

Possible type-Field strings

| === | File | A normal File | Directory | A directory or folder that can hold multiple nodes. | Device | A special type of Node that represents a filesystem and can be mounted. | Unknown | The node type is not known to this utility function. | ===

Details
Parameters
Name Type Description

Paths …​

string

Paths that will be checked
Return Values
Name Type Description

Results …​

{type:string}

Metadata for each path

filesystem.mount (device: string, mountPoint: string) → boolean

This function mounts the device referenced by the the path to a device node to the given mount point.

Details
Parameters
Name Type Description

Device device

string

the path to the device you want to mount

Mount Point mountPoint

string

the path to the point were the device should get mounted to
Return Values
Name Type Description

Success success

boolean

true if the mount was executed successfully

filesystem.move (from: string, to: string) → boolean

Moves the filesystem object from the given path to the other given path.

Function fails if it is not able to move the object.

Details
Parameters
Name Type Description

From from

string

path to the filesystem object you want to move

To to

string

path to the filesystem object the target should get moved to
Return Values
Name Type Description

Success success

boolean

returns true if it was able to move the node

filesystem.open (path: string, mode: string) → File

Opens a file-stream and returns it as File-table.

Possible Modes

r

read only

File-Stream can just read from file.
If file doesn￢ﾀﾙt exist, open will return nil

w

write

File-Stream can read and write.
Creates the file if it doesn￢ﾀﾙt exist

a

end of file

File-Stream can read and write.
Cursor is set to the end of file.

+r

truncate

File-Stream can read and write.
All previous data in file gets dropped

+a

append

File-Stream can read the full file,
but can only write to the end of the existing file.
Details
Parameters
Name Type Description

Path path

string

the path to the file you want to open a file-stream for

Mode mode

string

The mode for the file stream
Return Values
Name Type Description

File file

File

The File table of the file stream. Nil if not able to open file in read only.

filesystem.path ([conversion: integer,] …​: string) → string

Combines a variable amount of strings as paths together to one big path.

Additionally, applies given conversion. Defined by the optionally given integer.

Possible Conversions

0

Normalize the path.
/my/../weird/./path → /weird/path

1

Normalizes and converts the path to an absolute path.
my/abs/path → /my/abs/path

2

Normalizes and converts the path to an relative path.
/my/relative/path → my/relative/path

3

Returns the whole file/folder name.
/path/to/file.txt → file.txt

4

Returns the stem of the filename.
/path/to/file.txt → file
/path/to/.file → .file

5

Returns the file-extension of the filename.
/path/to/file.txt → .txt
/path/to/.file → empty-str
/path/to/file. → .
Details
Parameters
Name Type Description

Conversion conversion

integer|string

Conversion that will be applied to paths

Paths …​

string

Paths that will be joined
Return Values
Name Type Description

Result result

string

Joined and processed path

filesystem.remove (path: string, recursive: bool) → boolean

Removes the filesystem object at the given path.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object

Recursive recusive

boolean

If false only removes the given filesystem object. If true removes all childs of the filesystem object.
Return Values
Name Type Description

Success success

boolean

Returns true if it was able to remove the node

filesystem.rename (path: string, name: string) → boolean

Renames the filesystem object at the given path to the given name.

Details
Parameters
Name Type Description

Path path

string

path to the filesystem object you want to rename

Name name

string

the new name for your filesystem object
Return Values
Name Type Description

Success success

boolean

returns true if it was able to rename the node

filesystem.unmount (mountPoint: string) → boolean

This function unmounts if the device at the given mount point.

Details
Parameters
Name Type Description

Mount Point mountPoint

string

the path the device is mounted to
Return Values
Name Type Description

Success success

boolean

returns true if it was able to unmount the device located at the mount point

Types

File

File.close ()

Closes the File-Stream.

Details
Parameters
Name Type Description

self self

File

File.read (…​: integer) → …​

Reads up to the given amount of bytes from the file. Strings may be smaller than the given amount of bytes due to f.e. reaching the End-Of-File.

Details
Parameters
Name Type Description

self self

File

Sizes …​

integer

Maximum sizes of strings
Return Values
Name Type Description

Contents …​

string?

Contents of the file

File.seek (where: string, offset: integer) → integer

Moves the File-Streams pointer to a position defined by the offset and from what starting location.

Possble where values

  • cur Offset is relative to the current location

  • set Offset is relative to the beginning of the file

  • end Offset is relative to the end of the file

Details
Parameters
Name Type Description

self self

File

Where where

string

Starting location

Offset offset

integer

Offset
Return Values
Name Type Description

Position position

string?

Current position in the file

File.write (…​ string)

Writes the given strings to the File-Stream.

Details
Parameters
Name Type Description

self self

File

Strings …​

string

Strings that will be written to the stream