Filesystem API

This library allows developer to interact with filesystem components, to mount them on virtual directories, to perform buffered I/O operations and to process string paths for extraction of their parts.

Contents
Easy methods
Working with paths
Opening file handles
Reading from handles
Writing to handles
Mounted filesystems

Easy methods

Want to read whole file contents with one line of code? Or, for example, to save table as serialized string on external HDD? No problem: library has some really convenient stuff for file manipulations.

filesystem.read(string path): string or nil data, boolean reason

Reads whole file as string. Returns string data if reading operation was successful, nil and reason message otherwise:

Test.txt:
--------------------------------------------
Hello world

filesystem.read("/Test.txt")

Hello world

filesystem.write(string path, ...): boolean success, boolean reason

Overwrites file with passed data. Data can be a string, number or boolean type. Returns true if writing operation was successful, false and reason message otherwise.

filesystem.write("/Test.txt", "Meow, ", "I love", "you")

Test.txt:
--------------------------------------------
Meow, I love you

filesystem.append(string path, ...): boolean success, boolean reason

Works the same way as filesystem.write(), but appends passed data to end of file without overwriting.

filesystem.readLines(string path): table or nil data, boolean reason

Reads string lines from file and packs them to table. Returns table of strings if reading operation was successful, nil and reason message otherwise.

Test.txt:
--------------------------------------------
Help
They're
Everywhere

filesystem.readLines("/Test.txt")

> {
    "Help",
    "They're"
    "Everywhere"
  }

filesystem.readTable(string path): table or nil data, boolean reason

Reads whole file and deserializes it as table. Returns table if reading operation was successful, nil and reason message otherwise.

Test.txt:
--------------------------------------------
{"Ur mom gay", "No u"}

filesystem.readTable("/Test.txt")

> {
    "Ur mom gay",
    "No u"
  }

filesystem.writeTable(string path, table t, ...): boolean success, boolean reason

Serializes given table as string and writes it to file. Multiple arguments are passed to text.serialize method. Returns true if serializing and writing operation was successful, false and reason message otherwise.

filesystem.writeTable("/Test.txt", {
  "Primitive creature",
  "Wonderful being"
})

Test.txt:
--------------------------------------------
{"Primitive creature", "Wonderful being"}

---

Working with paths

Need to extract file name or extension from path? Or to remove extra slashes? Or maybe to create some directories and get file list? These methods are for you:

filesystem.list(string path): table or nil list, string reason

Tries to get list of files and directories from given path. Returns table with list on success, false and reason message otherwise.

filesystem.size(string path): int or nil size, string reason

Tries to get file size by given path in bytes. Returns size on success, false and reason message otherwise.

filesystem.lastModified(string path): int or nil timestamp, string reason

Tries to get real world timestamp when file or directory by given path was modified. For directories this is usually the time of their creation. Returns timestamp on success, false and reason message otherwise.

filesystem.exists(string path): boolean exists

Checks if file or directory exists on given path.

filesystem.isDirectory(string path): boolean isDirectory

Checks if given path is a directory or a file.

filesystem.makeDirectory(string path): boolean success, string reason

Tries to create directory with all sub-paths by given path. Returns true on success, false and reason message otherwise.

filesystem.remove(string path): boolean success, string reason

Tries to remove file or directory by given path. Returns true on success, false and reason message otherwise.

filesystem.rename(string fromPath, string toPath): boolean success, string reason

Tries to rename file or directory from first path to second one. Returns true on success, false and reason message otherwise.

filesystem.copy(string fromPath, string toPath): boolean success, string reason

Tries to copy file from first path to second one. Returns true on success, false and reason message otherwise.

filesystem.name(string path): string name

Returns file name from given path:

filesystem.name("/MineOS/Pictures/Dick.pic")

> Dick.pic

filesystem.path(string path): string parentPath

Returns parent path from given path:

filesystem.path("/MineOS/Pictures/Dick.pic")

> /MineOS/Pictures/

filesystem.extension(string path): string extension

Returns extension from given path:

filesystem.extension("/MineOS/Pictures/Dick.pic")

> .pic

filesystem.hideExtension(string path): string path

Returns given path without it's extension:

filesystem.hideExtension("/MineOS/Pictures/Dick.pic")

> /MineOS/Pictures/Dick

filesystem.isHidden(string path): boolean isHidden

Hidden files are files which names starts of dot symbol. This method returns true if file is hidden or false otherwise:

filesystem.isHidden("/MineOS/Pictures/Dick.pic")
filesystem.isHidden("/MineOS/Pictures/.Very big.pic")

> false
> true

filesystem.removeSlashes(string path): string path

Removes extra repeating slashes of path:

filesystem.removeSlashes("/MineOS///Pictures//Dick.pic")

> /MineOS/Pictures/Dick.pic

Opening file handles

If you need to open file to write single byte, to read line or to read N bytes in big/little-endian format, then methods below is what you're looking for:

filesystem.open(string path[, string mode]): table handle

Opens a file at the specified path for reading or writing with specified string mode. By default, mode is r. Possible modes are: r, rb, w, wb, a and ab. If file has been opened, returns file handle table or nil and string error otherwise.

Independent of mode, every handle will have a close and seek methods:

handle:close()

Closes file stream, flushes internal buffer and releases the handle.

handle:seek(string whence, int offset): int or nil position, string reason

Sets or gets the handle position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence, as follows:

• set: base is position 0 (beginning of the file)
• cur: base is current position
• end: base is end of file

The default value for whence is "cur", and for offset is 0. If seek was successful, returns the final file position, measured in bytes from the beginning of the file. Otherwise it returns nil and string reason.

Reading from handles

If file was open in r or rb mode, it will have following methods:

handle:readString(int count): string or nil value

Reads string with length of given count of bytes. Returns string value or nil if EOF has reached.

handle:readBytes(int count[, boolean littleEndian]): int or nil value

Reads number represented by count of bytes in big endian format by default or little endian if desired. Returns int value or nil if EOF has reached.

handle:readUnicodeChar(): string or nil value

Reads next bytes (up to 6 from current position) as char in UTF-8 encoding. Returns string value or nil if EOF has reached.

handle:readLine(): string or nil line

Reads next line from file without \n character. Returns string line or nil if EOF has reached.

handle:readAll(): string or nil data, string reason

Reads whole file as string. Returns string data if reading operation was successful, nil and reason message otherwise.

---

Writing to handles

If file was open in w , wb, a or ab mode, it will have following methods:

handle:write(...): boolean success, string reason

Writes passed arguments to file. Returns true on success, false and reason message otherwise.

handle:writeBytes(...): boolean success, string reason

Writes passed numbers in [0; 255] range to file. Returns true on success, false and reason message otherwise.

---

Mounted filesystems

Want to copy file from one filesystem component to another? Mounts system was designed for that: when you add any filesystem component to computer, it's being "mounted" to virtual path.

filesystem.mounts(): function iterator -> proxy, path

Returns an iterator function for listing of mounted filesystems:

for proxy, path in filesystem.mounts() do
	-- Do something
end

filesystem.mount(table proxy, string path)

Mounts passed filesystem component proxy table to specified path.

filesystem.unmount(table proxy or string address)

Unmounts passed filesystem component proxy table or it's string address from mounted path.

filesystem.get(string path): table proxy, string proxyPath

Determines correct filesystem component proxy from given path and returns it with rest path part:

filesystem.get("/MineOS/Mounts/478ABF/Test.pic")

> table, "Test.pic"