diff --git a/docs/en/modules/file.md b/docs/en/modules/file.md new file mode 100644 index 00000000..d73d75e5 --- /dev/null +++ b/docs/en/modules/file.md @@ -0,0 +1,342 @@ +# file Module +The file module provides access to the file system and its individual files. + +The file system is a flat file system, with no notion of directories/folders. + +Only one file can be open at any given time. + +## file.fsinfo() + +Return size information for the file system, in bytes. + +####Syntax +`file.fsinfo()` + +####Parameters +`nil` + +####Returns +- `remaining` (number) +- `used` (number) +- `total` (number) + +####Example + +```lua + -- get file system info + remaining, used, total=file.fsinfo() + print("\nFile system info:\nTotal : "..total.." Bytes\nUsed : "..used.." Bytes\nRemain: "..remaining.." Bytes\n") + ``` +``` +___ +## file.format() + +Format the file system. Completely erases any existing file system and writes a new one. Depending on the size of the flash chip in the ESP, this may take several seconds. + +####Syntax +`file.format()` + +####Parameters +`nil` + +####Returns +`nil` + +####Example +```lua + file.format() +``` + +####See also + - `file.remove()` +___ +## file.list() + +Lists all files in the file system. + +####Syntax +`file.list()` + +####Parameters +`nil` + +####Returns +a lua table which contains the {file name: file size} pairs + +####Example +```lua + l = file.list(); + for k,v in pairs(l) do + print("name:"..k..", size:"..v) + end +``` +___ +## file.remove() + +Remove a file from the file system. The file must not be currently open. + +###Syntax +`file.remove(filename)` + +####Parameters + - `filename`: file to remove + +####Returns +`nil` + +####Example + +```lua + -- remove "foo.lua" from file system. + file.remove("foo.lua") +``` +####See also + - `file.open()` +___ +## file.rename() + +Renames a file. If a file is currently open, it will be closed first. + +####Syntax +`file.rename(oldname, newname)` + +####Parameters + - `oldname`: old file name + - `newname`: new file name + +####Returns +`true` on success, `false` on error. + +####Example + +```lua + -- rename file 'temp.lua' to 'init.lua'. + file.rename("temp.lua","init.lua") +``` +___ +## file.open() + +Opens a file for access, potentially creating it (for write modes). + +When done with the file, it must be closed using `file.close()`. + +####Syntax +`file.open(filename, mode)` + +####Parameters + - `filename`: file to be opened, directories are not supported + - `mode`: + - "r": read mode (the default)
+ - "w": write mode
+ - "a": append mode
+ - "r+": update mode, all previous data is preserved
+ - "w+": update mode, all previous data is erased
+ - "a+": append update mode, previous data is preserved, writing is only allowed at the end of file + +####Returns + - `nil` if file not opened, or not exists (read modes). true` if file opened ok. + +####Example + +```lua + -- open 'init.lua', print the first line. + file.open("init.lua", "r") + print(file.readline()) + file.close() +``` +####See also + - `file.close()` + - `file.readline()` +___ +## file.close() + +Closes the open file, if any. + +####Syntax +`file.close()` + +####Parameters +`nil` + +####Returns +`nil` + +####Example + +```lua + -- open 'init.lua', print the first line. + file.open("init.lua", "r") + print(file.readline()) + file.close() +``` +####See also + - `file.open()` +___ +## file.readline() + +Read the next line from the open file. + +####Syntax +`file.readline()` + +####Parameters +`nil` + +####Returns +File content in string, line by line, include EOL('\n'). Return `nil` when EOF. + +####Example + +```lua + -- print the first line of 'init.lua' + file.open("init.lua", "r") + print(file.readline()) + file.close() +``` +####See also + - `file.open()` + - `file.close()` + - `file.read()` +___ +## file.writeline() + +Write a string to the open file and append '\n' at the end. + +####Syntax +`file.writeline(string)` + +####Parameters + - `string`: content to be write to file + +####Returns +`true` if write ok, `nil` on error. + +####Example + +```lua + -- open 'init.lua' in 'a+' mode + file.open("init.lua", "a+") + -- write 'foo bar' to the end of the file + file.writeline('foo bar') + file.close() +``` + +####See also + - `file.open()` + - `file.readline()` +___ +## file.read() + +Read content from the open file. +####Syntax +`file.read([n_or_str])` + +####Parameters + - `n_or_str`: + - if nothing passed in, read all byte in file. + - if pass a number n, then read n bytes from file, or EOF is reached. + - if pass a string "str", then read until 'str' or EOF is reached. + +####Returns +File content in string, or nil when EOF. + +####Example +```lua + -- print the first line of 'init.lua' + file.open("init.lua", "r") + print(file.read('\n')) + file.close() + + -- print the first 5 byte of 'init.lua' + file.open("init.lua", "r") + print(file.read(5)) + file.close() +``` + +####See also + - `file.open()` + - `file.readline()` +___ +## file.write() + +Write a string to the open file. + +####Syntax +`file.write(string)` + +####Parameters +`string`: content to be write to file. + +####Returns +`true` if the write is ok, `nil` on error. + +####Example + +```lua + -- open 'init.lua' in 'a+' mode + file.open("init.lua", "a+") + -- write 'foo bar' to the end of the file + file.write('foo bar') + file.close() +``` + +####See also + - `file.open()` + - `file.writeline()` +___ +## file.flush() + +Flushes any pending writes to the file system, ensuring no data is lost on a restart. Closing the open file using `file.close()` performs an implicit flush as well. + +####Syntax +`file.flush()` + +####Parameters +`nil` + +####Returns +`nil` + +####Example +```lua + -- open 'init.lua' in 'a+' mode + file.open("init.lua", "a+") + -- write 'foo bar' to the end of the file + file.write('foo bar') + file.flush() + -- write 'baz' too + file.write('baz') + file.close() +``` +####See also + - `file.close()` +___ +## file.seek() +Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence. + +####Syntax +`file.seek([whence [, offset]])` + +####Parameters + - `whence`: + - "set": base is position 0 (beginning of the file) + - "cur": base is current position (default value) + - "end": base is end of file + - offset: default 0 + +If no parameters are given, the function simply returns the current file offset. + +####Returns +The resulting file position, or `nil` on error. + +####Example +```lua + file.open("init.lua", "r") + -- skip the first 5 bytes of the file + file.seek("set", 5) + print(file.readline()) + file.close() +``` +####See also + - `file.open()` +___ diff --git a/mkdocs.yml b/mkdocs.yml index f49bfc27..167f0c11 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,5 +30,6 @@ pages: - Support: 'en/support.md' - Modules: - 'node': 'en/modules/node.md' + - 'file': 'en/modules/file.md' - Deutsch: - - Home: 'de/index.md' \ No newline at end of file + - Home: 'de/index.md'