343 lines
6.3 KiB
Markdown
343 lines
6.3 KiB
Markdown
|
# 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)<br />
|
||
|
|
- "w": write mode<br />
|
||
|
|
- "a": append mode<br />
|
||
|
|
- "r+": update mode, all previous data is preserved<br />
|
||
|
|
- "w+": update mode, all previous data is erased<br />
|
||
|
|
- "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()`
|
||
|
|
___
|