@@ -7,8 +7,6 @@ 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 subdirectories/folders.
Only one file can be open at any given time.
Besides the SPIFFS file system on internal flash, this module can also access FAT partitions on an external SD card is [FatFS is enabled](../sdcard.md).
```lua
...
...
@@ -43,30 +41,6 @@ Current directory defaults to the root of internal SPIFFS (`/FLASH`) after syste
#### Returns
`true` on success, `false` otherwise
## file.close()
Closes the open file, if any.
#### Syntax
`file.close()`
#### Parameters
none
#### Returns
`nil`
#### Example
```lua
-- open 'init.lua', print the first line.
iffile.open("init.lua","r")then
print(file.readline())
file.close()
end
```
#### See also
[`file.open()`](#fileopen)
## file.exists()
Determines whether the specified file exists.
...
...
@@ -95,34 +69,6 @@ end
#### See also
[`file.list()`](#filelist)
## 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()`](#fileclose) performs an implicit flush as well.
#### Syntax
`file.flush()`
#### Parameters
none
#### Returns
`nil`
#### Example
```lua
-- open 'init.lua' in 'a+' mode
iffile.open("init.lua","a+")then
-- write 'foo bar' to the end of the file
file.write('foo bar')
file.flush()
-- write 'baz' too
file.write('baz')
file.close()
end
```
#### See also
[`file.close()`](#fileclose)
## 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.
...
...
@@ -280,9 +226,9 @@ When done with the file, it must be closed using `file.close()`.
- "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.
file object if file opened ok. `nil` if file not opened, or not exists (read modes).
#### Example
#### Example (basic model)
```lua
-- open 'init.lua', print the first line.
iffile.open("init.lua","r")then
...
...
@@ -290,124 +236,245 @@ if file.open("init.lua", "r") then
file.close()
end
```
#### Example (object model)
```lua
-- open 'init.lua', print the first line.
fd=file.open("init.lua","r")
iffdthen
print(fd:readline())
fd:close();fd=nil
end
```
#### See also
-[`file.close()`](#fileclose)
-[`file.readline()`](#filereadline)
## file.read()
## file.remove()
Read content from the open file.
Remove a file from the file system. The file must not be currently open.
!!! note
###Syntax
`file.remove(filename)`
The function temporarily allocates 2 * (number of requested bytes) on the heap for buffering and processing the read data. Default chunk size (`FILE_READ_CHUNK`) is 1024 bytes and is regarded to be safe. Pushing this by 4x or more can cause heap overflows depending on the application. Consider this when selecting a value for parameter `n_or_char`.
#### Parameters
`filename` file to remove
#### Returns
`nil`
#### Example
```lua
-- remove "foo.lua" from file system.
file.remove("foo.lua")
```
#### See also
[`file.open()`](#fileopen)
## file.rename()
Renames a file. If a file is currently open, it will be closed first.
#### Syntax
`file.read([n_or_char])`
`file.rename(oldname, newname)`
#### Parameters
-`n_or_char`:
- if nothing passed in, then read up to `FILE_READ_CHUNK` bytes or the entire file (whichever is smaller).
- if passed a number `n`, then read up to `n` bytes or the entire file (whichever is smaller).
- if passed a string containing the single character `char`, then read until `char` appears next in the file, `FILE_READ_CHUNK` bytes have been read, or EOF is reached.
-`oldname` old file name
-`newname` new file name
#### Returns
File content as a string, or nil when EOF
`true` on success, `false` on error.
#### Example
```lua
-- print the first line of 'init.lua'
-- rename file 'temp.lua' to 'init.lua'.
file.rename("temp.lua","init.lua")
```
# File access functions
The `file` module provides several functions to access the content of a file after it has been opened with [`file.open()`](#fileopen). They can be used as part of a basic model or an object model:
## Basic model
In the basic model there is max one file opened at a time. The file access functions operate on this file per default. If another file is opened, the previous default file needs to be closed beforehand.
```lua
-- open 'init.lua', print the first line.
iffile.open("init.lua","r")then
print(file.read('\n'))
print(file.readline())
file.close()
end
```
-- print the first 5 bytes of 'init.lua'
iffile.open("init.lua","r")then
print(file.read(5))
file.close()
## Object model
Files are represented by file objects which are created by `file.open()`. File access functions are available as methods of this object, and multiple file objects can coexist.
```lua
src=file.open("init.lua","r")
ifsrcthen
dest=file.open("copy.lua","w")
ifdestthen
localline
repeat
line=src:read()
iflinethen
dest:write(line)
end
untilline==nil
dest:close();dest=nil
end
src:close();dest=nil
end
```
!!! Attention
It is recommended to use only one single model within the application. Concurrent use of both models can yield unpredictable behavior: Closing the default file from basic model will also close the correspoding file object. Closing a file from object model will also close the default file if they are the same file.
!!! Note
The maximum number of open files on SPIFFS is determined at compile time by `SPIFFS_MAX_OPEN_FILES` in `user_config.h`.
## file.close()
## file.obj:close()
Closes the open file, if any.
#### Syntax
`file.close()`
`fd:close()`
#### Parameters
none
#### Returns
`nil`
#### See also
-[`file.open()`](#fileopen)
-[`file.readline()`](#filereadline)
[`file.open()`](#fileopen)
## file.readline()
## file.flush()
## file.obj:flush()
Read the next line from the open file. Lines are defined as zero or more bytes ending with a EOL ('\n') byte. If the next line is longer than 1024, this function only returns the first 1024 bytes.
Flushes any pending writes to the file system, ensuring no data is lost on a restart. Closing the open file using [`file.close()` / `fd:close()`](#fileclose) performs an implicit flush as well.
#### Syntax
`file.readline()`
`file.flush()`
`fd:flush()`
#### Parameters
none
#### Returns
File content in string, line by line, including EOL('\n'). Return `nil` when EOF.
`nil`
#### Example
#### Example (basic model)
```lua
-- print the first line of 'init.lua'
iffile.open("init.lua","r")then
print(file.readline())
-- open 'init.lua' in 'a+' mode
iffile.open("init.lua","a+")then
-- write 'foo bar' to the end of the file
file.write('foo bar')
file.flush()
-- write 'baz' too
file.write('baz')
file.close()
end
```
#### See also
-[`file.open()`](#fileopen)
-[`file.close()`](#fileclose)
-[`file.read()`](#filereade)
[`file.close()` / `file.obj:close()`](#fileclose)
## file.remove()
## file.read()
## file.obj:read()
Remove a file from the file system. The file must not be currently open.
Read content from the open file.
###Syntax
`file.remove(filename)`
!!! note
The function temporarily allocates 2 * (number of requested bytes) on the heap for buffering and processing the read data. Default chunk size (`FILE_READ_CHUNK`) is 1024 bytes and is regarded to be safe. Pushing this by 4x or more can cause heap overflows depending on the application. Consider this when selecting a value for parameter `n_or_char`.
#### Syntax
`file.read([n_or_char])`
`fd:read([n_or_char])`
#### Parameters
`filename` file to remove
-`n_or_char`:
- if nothing passed in, then read up to `FILE_READ_CHUNK` bytes or the entire file (whichever is smaller).
- if passed a number `n`, then read up to `n` bytes or the entire file (whichever is smaller).
- if passed a string containing the single character `char`, then read until `char` appears next in the file, `FILE_READ_CHUNK` bytes have been read, or EOF is reached.
Renames a file. If a file is currently open, it will be closed first.
Read the next line from the open file. Lines are defined as zero or more bytes ending with a EOL ('\n') byte. If the next line is longer than 1024, this function only returns the first 1024 bytes.
#### Syntax
`file.rename(oldname, newname)`
`file.readline()`
`fd:readline()`
#### Parameters
-`oldname` old file name
-`newname` new file name
none
#### Returns
`true` on success, `false` on error.
#### Example
File content in string, line by line, including EOL('\n'). Return `nil` when EOF.