Filesystem API - ProfessorCrown/WIKI-RUSSIA GitHub Wiki
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.
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. Keeps end slash if any:
filesystem.name("/MineOS/Pictures/Dick.pic")
filesystem.name("/MineOS/Pictures/Vagina/")
> Dick.pic
> Vagina/
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. Skips end slash if any:
filesystem.extension("/MineOS/Pictures/Dick.pic")
filesystem.extension("/MineOS/Pictures/Vagina.app/")
> .pic
> .app
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 positionend: 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.
Here is example for reading text file:
Test.txt:
--------------------------------------------
Mid or feed
Reading all file contents:
local handle = filesystem.open("/Test.txt", "r")
local data = handle:readAll()
handle:close()
data > "Mid or feed"
Reading file as strings or bytes:
local handle = filesystem.open("/Test.txt", "rb")
local char = handle:readString(1)
local byte = handle:readBytes(1)
local bytes = handle:readBytes(2)
handle:close()
char > "T"
byte > 101
bytes > 29556
When reading single bytes, this library automatically performs char -> int conversion.
Multiple bytes are being combined via pretty simple way: in this example we're reading part of file with st symbols as bytes. In ASCII encoding "s" symbol has value 155 and "t" has value 116. After reading these two bytes are being combined by 115 << 8 | 116 = 29556 rule. If optional littleEndian parameter is set to true, bytes will be combined in reverse direction: 116 << 8 | 115 = 29811.
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. Arguments may have string, int or boolean type.
handle:writeBytes(...): boolean success, string reason
Writes passed numbers in [0; 255] range as bytes 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"