-
Notifications
You must be signed in to change notification settings - Fork 188
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.
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.
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 worldOverwrites 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
Works the same way as filesystem.write(), but appends passed data to end of file without overwriting.
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"
}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"
}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"}
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:
Tries to get list of files and directories from given path. Returns table with list on success, false and reason message otherwise.
Tries to get file size by given path in bytes. Returns size on success, false and reason message otherwise.
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.
Checks if file or directory exists on given path.
Checks if given path is a directory or a file.
Tries to create directory with all sub-paths by given path. Returns true on success, false and reason message otherwise.
Tries to remove file or directory by given path. Returns true on success, false and reason message otherwise.
Tries to rename file or directory from first path to second one. Returns true on success, false and reason message otherwise.
Tries to copy file from first path to second one. Returns true on success, false and reason message otherwise.
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/
Returns parent path from given path:
filesystem.path("/MineOS/Pictures/Dick.pic")> /MineOS/Pictures/
Returns extension from given path. Skips end slash if any:
filesystem.extension("/MineOS/Pictures/Dick.pic")
filesystem.extension("/MineOS/Pictures/Vagina.app/")> .pic
> .app
Returns given path without it's extension:
filesystem.hideExtension("/MineOS/Pictures/Dick.pic")> /MineOS/Pictures/Dick
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
Removes extra repeating slashes of path:
filesystem.removeSlashes("/MineOS///Pictures//Dick.pic")> /MineOS/Pictures/Dick.pic
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:
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:
Closes file stream, flushes internal buffer and releases the handle.
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.
If file was open in r or rb mode, it will have following methods:
Reads string with length of given count of bytes. Returns string value or nil if EOF has reached.
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.
Reads next bytes (up to 6 from current position) as char in UTF-8 encoding. Returns string value or nil if EOF has reached.
Reads next line from file without \n character. Returns string line or nil if EOF has reached.
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 > 29556When 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.
If file was open in w , wb, a or ab mode, it will have following methods:
Writes passed arguments to file. Returns true on success, false and reason message otherwise. Arguments may have string, int or boolean type.
Writes passed numbers in [0; 255] range as bytes to file. Returns true on success, false and reason message otherwise.
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.
Returns an iterator function for listing of mounted filesystems:
for proxy, path in filesystem.mounts() do
-- Do something
endMounts passed filesystem component proxy table to specified path.
Unmounts passed filesystem component proxy table or it's string address from mounted path.
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"