File LFS Lua module initial commit (#3332)

* File LFS module initial commit * LFS file module update #1 * LFS file module update #2 - doc update and file.stat() returning read only attribute * Implementing file.list() * Fine-tuning `file_lfs` module * Adding `file_lfs` to mkdocs.yml * Implementing file.list() update #1 * Fine-tuning * Fine-tuning #2
nodemcu · Dec 30, 2021 · 1a1a4da · 1a1a4da
1 parent 3ed76a2
commit 1a1a4da
Show file tree

Hide file tree

Showing 6 changed files with 526 additions and 1 deletion.
diff --git a/docs/lua-modules/file_lfs.md b/docs/lua-modules/file_lfs.md
@@ -0,0 +1,197 @@
+# File LFS module
+| Since  | Origin / Contributor  | Maintainer  | Source  |
+| :----- | :-------------------- | :---------- | :------ |
+| 2020-11-30 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [file_lfs.lua](../../lua_modules/file_lfs/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](../../docs/modules/file.md) module documentation).
+
+## `resource.lua` file
+
+Files 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`](../../lua_modules/file_lfs/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.
+```Lua
+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` script
+
+Lua script to be run on PC to generate `resource.lua` file.
+
+### Syntax
+```bash
+ ./make_resource.lua [-o outputfile] file1 [file2]
+ ```
+
+### Example
+Create `resource.lua` file with all files in the `resource` directory
+```bash
+./make_resource resource/*
+```
+
+## Basic usage
+```Lua
+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.
+
+## file_lfs.list()
+
+Lists all files in the file system. It works almost in the same way as [`file.list()`](../../docs/modules/file.md#filelist)
+
+#### Syntax
+`file.list([pattern], [SPIFFs_only])`
+
+#### Parameters
+- `pattern` only files matching the Lua pattern will be returned
+- `SPIFFs_only` if not `nil` LFS files won't be included in the result (LFS files are returned only if the parameter is `nil`)
+
+#### Returns
+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](https://www.lua.org/pil/20.2.html),
+not, say, a UNIX shell glob) will be included in the resulting table.
+`file.list` will throw any errors encountered during pattern matching.
+
+
+## file.rename()
+
+Renames a file. If a file is currently open, it will be closed first. It works almost in the same way as [`file.rename()`](../../docs/modules/file.md#filerename)
+
+#### Syntax
+`file.rename(oldname, newname)`
+
+#### Parameters
+- `oldname` old file name
+- `newname` new file name
+
+#### Returns
+`true` on success, `false` when the file is stored in LFS (so read-only) or on error
+
+## file_lfs.open()
+
+Opens a LFS file included in LFS in the `resource.lua` file. If it cannot be found in LFS not standard [`file.open()`](../../docs/modules/file.md#fileopen) function is called.
+LFS file is opened only when "r" access is requested.
+
+#### Syntax
+`file.open(filename, mode)`
+
+#### Parameters
+- `filename` file to be opened
+- `mode`:
+    - "r": read mode (the default). If file of the same name is present in SPIFFS then SPIFFS file is opened instead of LFS file.
+    - "w": write mode - as LFS file is read-only a SPIFFS file of the same name is created and opened for writing.
+    - "r+", "w+", "a", "a+": as LFS file is read-only and all these modes allow file updates the LFS file is copied to SPIFFS and then it is opened with correspondig open mode.
+
+#### Returns
+LFS file object (Lua table) or SPIFFS file object if file opened ok. `nil` if file not opened, or not exists (read modes).
+
+## file.read(), file.obj:read()
+
+Read content from the open file. It has the same parameters and returns values as [`file.read()` / `file.obj:read()`](../../docs/modules/file.md#fileread-fileobjread)
+
+#### Syntax
+`file.read([n_or_char])`
+
+`fd:read([n_or_char])`
+
+#### 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.
+
+#### Returns
+File content as a string, or `nil` when EOF
+
+
+## file.readline(), file.obj:readline()
+
+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()`](../../docs/modules/file.md#filereadline-fileobjreadline)
+
+
+#### Syntax
+`file.readline()`
+
+`fd:readline()`
+
+#### Parameters
+none
+
+#### Returns
+File content in string, line by line, including EOL('\n'). Return `nil` when EOF.
+
+
+## file.seek(), file.obj: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.
+It has the same parameters and return values as [`file.seek()` / `file.obj:seek()`](../../docs/modules/file.md#fileseek-fileobjseek)
+
+#### Syntax
+`file.seek([whence [, offset]])`
+
+`fd: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
+
+## file.stat()
+
+Get attribtues of a file or directory in a table. Elements of the table are:
+
+- `size` file size in bytes
+- `name` file name
+- `time` 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()`**
+
+#### Syntax
+`file.stat(filename)`
+
+#### Parameters
+`filename` file name
+
+#### Returns
+table containing file attributes
+
diff --git a/docs/modules/file.md b/docs/modules/file.md
@@ -168,7 +168,7 @@ Lists all files in the file system.
 `file.list([pattern])`
 
 #### Parameters
-none
+- `pattern` only files matching the Lua pattern will be returned
 
 #### Returns
 a Lua table which contains all {file name: file size} pairs, if no pattern

diff --git a/lua_modules/file_lfs/file_lfs.lua b/lua_modules/file_lfs/file_lfs.lua
@@ -0,0 +1,158 @@
+local FILE_READ_CHUNK = 1024
+
+local _file = file
+local file_exists, file_open, file_getcontents, file_rename, file_stat, file_putcontents, file_close, file_list =
+  _file.exists, _file.open, _file.getcontents, _file.rename, _file.stat, _file.putcontents, _file.close, _file.list
+local node_LFS_resource = node.LFS.resource or function(filename) if filename then return else return {} end end -- luacheck: ignore
+
+local file_lfs = {}
+local current_file_lfs
+
+local function file_lfs_create (filename)
+  local content = node_LFS_resource(filename)
+  local pos = 1
+
+  local read = function (_, n_or_char)
+    local p1, p2
+    n_or_char = n_or_char or FILE_READ_CHUNK
+    if type(n_or_char) == "number" then
+      p1, p2 = pos, pos + n_or_char - 1
+    elseif type(n_or_char) == "string" and #n_or_char == 1 then
+      p1 = pos
+      local _
+      _, p2 = content:find(n_or_char, p1, true)
+      if not p2 then p2 = p1 + FILE_READ_CHUNK - 1 end
+    else
+      error("invalid parameter")
+    end
+    if p2 - p1 > FILE_READ_CHUNK then p2 = pos + FILE_READ_CHUNK - 1 end
+    if p1>#content then return end
+    pos = p2+1
+    return content:sub(p1, p2)
+  end
+
+  local seek = function (_, whence, offset)
+    offset = offset or 0
+    local len = #content + 1 -- position starts at 1
+    if whence == "set" then
+      pos = offset + 1 -- 0 offset means position 1
+    elseif whence == "cur" then
+      pos = pos + offset
+    elseif whence == "end" then
+      pos = len + offset
+    elseif whence then -- not nil not one of above
+      return -- on error return nil
+    end
+    local pos_ok = true
+    if pos < 1 then pos = 1; pos_ok = false end
+    if pos > len then pos = len; pos_ok = false end
+    return pos_ok and pos - 1 or nil
+  end
+
+  local obj = {}
+  obj.read = read
+  obj.readline = function(self) return read(self, "\n") end
+  obj.seek = seek
+  obj.close = function() current_file_lfs = nil end
+
+  setmetatable(obj, {
+    __index = function (_, k)
+      return function () --...)
+        error (("LFS file unsupported function '%s'") % tostring(k))
+        --return _file[k](...)
+      end
+    end
+  })
+
+  return obj
+end
+
+file_lfs.exists = function (filename)
+  return (node_LFS_resource(filename) ~= nil) or file_exists(filename)
+end
+
+file_lfs.open = function (filename, mode)
+  mode = mode or "r"
+  if file_exists(filename) then
+    return file_open(filename, mode)
+  elseif node_LFS_resource(filename) then
+    if mode ~=  "r" and mode:find("^[rwa]%+?$") then
+      -- file does not exist in SPIFFS but exists in LFS -> copy to SPIFFS
+      file_putcontents(filename, node_LFS_resource(filename))
+      return file_open(filename, mode)
+    else -- "r" or anything else
+      current_file_lfs = file_lfs_create (filename)
+      return current_file_lfs
+    end
+  else
+    return file_open(filename, mode)
+  end
+end
+
+file_lfs.close = function (...)
+  current_file_lfs = nil
+  return file_close(...)
+end
+
+file_lfs.getcontents = function(filename)
+  if file_exists(filename) then
+    return file_getcontents(filename)
+  else
+    return node_LFS_resource(filename) or file_getcontents(filename)
+  end
+end
+
+file_lfs.rename = function(oldname, newname)
+  if node_LFS_resource(oldname) ~= nil and not file_exists(oldname) then
+    -- error "LFS file cannot be renamed"
+    return false
+  else
+    return file_rename(oldname, newname)
+  end
+end
+
+file_lfs.stat = function(filename)
+  if node_LFS_resource(filename) ~= nil and not file_exists(filename) then
+    return {
+      name = filename,
+      size = #node_LFS_resource(filename),
+      time = {day = 1, hour = 0, min = 0, year = 1970, sec = 0, mon = 1},
+      is_hidden = false, is_rdonly = true, is_dir = false, is_arch = false, is_sys = false, is_LFS = true
+    }
+  else
+    return file_stat(filename)
+  end
+end
+
+file_lfs.list = function (pattern, SPIFFs_only)
+  local filelist = file_list(pattern)
+  if not SPIFFs_only then
+    local fl = node_LFS_resource()
+    if fl then
+      for _, f in ipairs(fl) do
+        if not(filelist[f]) and (not pattern or f:match(pattern)) then
+          filelist[f] = #node_LFS_resource(f)
+        end
+      end
+    end
+  end
+  return filelist
+end
+
+setmetatable(file_lfs, {
+  __index = function (_, k)
+    return function (...)
+        local t = ...
+        if type(t) == "table" then
+          return t[k](...)
+        elseif not t and current_file_lfs then
+          return current_file_lfs[k](...)
+        else
+          return _file[k](...)
+        end
+      end
+  end
+})
+
+print ("[file_lfs] LFS file routines loaded")
+return file_lfs