Since | Origin / Contributor | Maintainer | Source |
---|---|---|---|
2020-11-30 | vsky279 | vsky279 | file_lfs.lua |
Provides access to arbitrary files stored in LFS.
An arbitrary file can be stored in LFS and still can be accessed using file
functions. This module is an overlay over file
base functions providing access to such LFS files.
The module tries to be transparent as much as possible so it makes no difference where LFS file or standard SPIFFS file is accessed. LFS file is read only. If the file is open for writing a standard SPIFFS file is opened instead. Both basic and object model can be used to access LFS file (see file module documentation).
resource.lua
fileFiles to be stored in LFS needs to be preprocessed, i.e. a Lua file with its contents needs to be generated. This file called resource.lua
is then included in the LFS image. A Lua script make_resource.lua
can be used to generate resource.lua
script.
A structure of the resource.lua
file is simple. It returns a string, i.e. file content, depending on filename parameter passed to it. It returns table with list of files stored when called without any parameter.
local arg = ...
if arg == "index.html" then return "<!DOCTYPE html><html><body>Hi, there!</body></html>" end
if arg == "favicon.ico" then return ""\000\000\000\000\000\000..." end
if arg == nil then return {"index.html", "favicon.ico"} end
make_resource.lua
scriptLua script to be run on PC to generate resource.lua
file.
./make_resource.lua [-o outputfile] file1 [file2]
Create resource.lua
file with all files in the resource
directory
./make_resource resource/*
file = require("file_lfs")
f = file.open("index.html") -- let's assume the above resource.lua file is embedded in LFS
print(f:readline())
-- prints: <!DOCTYPE html><html><body>Hi, there!</body></html>
f:close()
f = file.open("init.lua")
-- init.lua file is not stored in LFS (does not have entry in resource.lua stored in LFS) -> SPIFFS files is opened instead
print(f:readline())
f:close()
Methods implemented - basically all file
module functions are available though only some of them work with LFS files. The other functions are just passed through to the base file
functions.
Lists all files in the file system. It works almost in the same way as file.list()
file.list([pattern], [SPIFFs_only])
pattern
only files matching the Lua pattern will be returnedSPIFFs_only
if not nil
LFS files won’t be included in the result (LFS files are returned only if the parameter is nil
)a Lua table which contains all {file name: file size} pairs, if no pattern
given. If a pattern is given, only those file names matching the pattern
(interpreted as a traditional Lua pattern,
not, say, a UNIX shell glob) will be included in the resulting table.
file.list
will throw any errors encountered during pattern matching.
Renames a file. If a file is currently open, it will be closed first. It works almost in the same way as file.rename()
file.rename(oldname, newname)
oldname
old file namenewname
new file nametrue
on success, false
when the file is stored in LFS (so read-only) or on error
Opens a LFS file included in LFS in the resource.lua
file. If it cannot be found in LFS not standard file.open()
function is called.
LFS file is opened only when «r» access is requested.
file.open(filename, mode)
filename
file to be openedmode
:
LFS file object (Lua table) or SPIFFS file object if file opened ok. nil
if file not opened, or not exists (read modes).
Read content from the open file. It has the same parameters and returns values as file.read()
/ file.obj:read()
file.read([n_or_char])
fd:read([n_or_char])
n_or_char
:
FILE_READ_CHUNK
bytes or the entire file (whichever is smaller).n
, then read up to n
bytes or the entire file (whichever is smaller).char
, then read until char
appears next in the file, FILE_READ_CHUNK
bytes have been read, or EOF is reached.File content as a string, or nil
when EOF
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.
It has the same parameters and return values as file.readline()
/ file.obj:readline()
file.readline()
fd:readline()
none
File content in string, line by line, including EOL(’\n’). Return nil
when EOF.
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.
It has the same parameters and return values as file.seek()
/ file.obj:seek()
file.seek([whence [, offset]])
fd:seek([whence [, offset]])
whence
offset
default 0If no parameters are given, the function simply returns the current file offset.
the resulting file position, or nil
on error
Get attribtues of a file or directory in a table. Elements of the table are:
size
file size in bytesname
file nametime
table with time stamp information. Default is 1970-01-01 00:00:00 in case time stamps are not supported (on SPIFFS).
year
mon
day
hour
min
sec
is_dir
flag true
if item is a directory, otherwise false
is_rdonly
flag true
if item is read-only, otherwise false
is_hidden
flag true
if item is hidden, otherwise false
is_sys
flag true
if item is system, otherwise false
is_arch
flag true
if item is archive, otherwise false
is_LFS
flag true
if item is stored in LFS, otherwise it is not present in the file.stat()
result table - the only difference to file.stat()
file.stat(filename)
filename
file name
table containing file attributes