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
Path processing
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(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(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(path, ...): boolean success, boolean reason

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

filesystem.readLines(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(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(path, 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"}

---

Path processing

Need to extract file name or extension from path? Or to remove extra slashes? These methods are for you:

filesystem.name(path): string name

Returns file name from given path:

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

> Dick.pic

filesystem.path(path): string parentPath

Returns parent path from given path:

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

> /MineOS/Pictures/

filesystem.extension(path): string extension

Returns extension from given path:

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

> .pic

filesystem.hideExtension(path): string path

Returns given path without it's extension:

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

> /MineOS/Pictures/Dick

filesystem.isHidden(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(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 write single byte to file, to read single line or to read N bytes from file in big/little-endian format, then methods below is what you're looking for.

filesystem.open(path[, 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(whence, 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(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(count[, 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(proxy, path)

Mounts passed filesystem component proxy table to specified path.

filesystem.unmount(proxy or address)

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

filesystem.get(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"