diff options
Diffstat (limited to 'libs')
| -rw-r--r-- | libs/core/luasrc/fs.lua | 112 | ||||
| -rw-r--r-- | libs/core/luasrc/util.lua | 30 |
2 files changed, 113 insertions, 29 deletions
diff --git a/libs/core/luasrc/fs.lua b/libs/core/luasrc/fs.lua index 7086088ab2..0fc7193890 100644 --- a/libs/core/luasrc/fs.lua +++ b/libs/core/luasrc/fs.lua @@ -24,22 +24,41 @@ limitations under the License. ]]-- +--- LuCI filesystem library. module("luci.fs", package.seeall) require("posix") --- Access +--- Test for file access permission on given path. +-- @class function +-- @name access +-- @param str String value containing the path +-- @return Number containing the return code, 0 on sucess or nil on error +-- @return String containing the error description (if any) +-- @return Number containing the os specific errno (if any) access = posix.access --- Glob +--- Evaluate given shell glob pattern and return a table containing all matching +-- file and directory entries. +-- @class function +-- @name glob +-- @param filename String containing the path of the file to read +-- @return Table containing file and directory entries or nil if no matches +-- @return String containing the error description (if no matches) +-- @return Number containing the os specific errno (if no matches) glob = posix.glob --- Checks whether a file exists +--- Checks wheather the given path exists and points to a regular file. +-- @param filename String containing the path of the file to read +-- @return Boolean indicating wheather given path points to regular file function isfile(filename) return posix.stat(filename, "type") == "regular" end --- Returns the content of file +--- Read the whole content of the given file into memory. +-- @param filename String containing the path of the file to read +-- @return String containing the file contents or nil on error +-- @return String containing the error message on error function readfile(filename) local fp, err = io.open(filename) @@ -52,7 +71,11 @@ function readfile(filename) return data end --- Writes given data to a file +--- Write the contents of given string to given file. +-- @param filename String containing the path of the file to read +-- @param data String containing the data to write +-- @return Boolean containing true on success or nil on error +-- @return String containing the error message on error function writefile(filename, data) local fp, err = io.open(filename, "w") @@ -66,21 +89,48 @@ function writefile(filename, data) return true end --- Returns the file modification date/time of "path" +--- Get the last modification time of given file path in Unix epoch format. +-- @param path String containing the path of the file or directory to read +-- @return Number containing the epoch time or nil on error +-- @return String containing the error description (if any) +-- @return Number containing the os specific errno (if any) function mtime(path) return posix.stat(path, "mtime") end --- basename wrapper +--- Return the last element - usually the filename - from the given path with +-- the directory component stripped. +-- @class function +-- @name basename +-- @param path String containing the path to strip +-- @return String containing the base name of given path +-- @see dirname basename = posix.basename --- dirname wrapper +--- Return the directory component of the given path with the last element +-- stripped of. +-- @class function +-- @name dirname +-- @param path String containing the path to strip +-- @return String containing the directory component of given path +-- @see basename dirname = posix.dirname --- dir wrapper +--- Return a table containing all entries of the specified directory. +-- @class function +-- @name dir +-- @param path String containing the path of the directory to scan +-- @return Table containing file and directory entries or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error dir = posix.dir --- wrapper for posix.mkdir +--- Create a new directory, recursively on demand. +-- @param path String with the name or path of the directory to create +-- @param recursive Create multiple directory levels (optional, default is true) +-- @return Number with the return code, 0 on sucess or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error function mkdir(path, recursive) if recursive then local base = "." @@ -114,17 +164,49 @@ function mkdir(path, recursive) end end --- Alias for posix.rmdir +--- Remove the given empty directory. +-- @class function +-- @name rmdir +-- @param path String containing the path of the directory to remove +-- @return Number with the return code, 0 on sucess or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error rmdir = posix.rmdir --- Alias for posix.stat +--- Get information about given file or directory. +-- @class function +-- @name stat +-- @param path String containing the path of the directory to query +-- @return Table containing file or directory properties or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error stat = posix.stat --- Alias for posix.chmod +--- Set permissions on given file or directory. +-- @class function +-- @name chmod +-- @param path String containing the path of the directory +-- @param perm String containing the permissions to set ([ugoa][+-][rwx]) +-- @return Number with the return code, 0 on sucess or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error chmod = posix.chmod --- Alias for posix.link +--- Create a hardlink from given file to specified target file path. +-- @class function +-- @name link +-- @param path1 String containing the source path of a file to hardlink +-- @param path2 String containing the destination path for the link +-- @return Number with the return code, 0 on sucess or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error link = posix.link --- Alias for posix.unlink +--- Remove the given file. +-- @class function +-- @name unlink +-- @param path String containing the path of the file to remove +-- @return Number with the return code, 0 on sucess or nil on error +-- @return String containing the error description on error +-- @return Number containing the os specific errno on error unlink = posix.unlink diff --git a/libs/core/luasrc/util.lua b/libs/core/luasrc/util.lua index b2a683772e..e4e99b9c12 100644 --- a/libs/core/luasrc/util.lua +++ b/libs/core/luasrc/util.lua @@ -94,7 +94,7 @@ end -- Scope manipulation routines -- ---- Replace a function scope with a shallow copy of itself +--- Replace a function scope with a shallow copy of itself. -- This is useful if you want to get rid of several unwanted side effects -- while changing the scope of a certain Lua function. -- @param f Lua function @@ -102,13 +102,13 @@ function resfenv(f) setfenv(f, clone(getfenv(f))) end ---- Store given object associated with given key in the scope of a function +--- Store given object associated with given key in the scope of a function. -- @param f Lua function -- @param key String value containg the key of the object to store -- @param obj Object to store in the scope +-- @return Always nil -- @see updfenv -- @see resfenv --- @return Always nil function extfenv(f, key, obj) local scope = getfenv(f) scope[key] = obj @@ -118,9 +118,9 @@ end -- @param f Lua function -- @param key String value containg the key of the object to store -- @param obj Object to store in the scope +-- @return Always nil -- @see extfenv -- @see resfenv --- @return Always nil function updfenv(f, extscope) update(getfenv(f), extscope) end @@ -519,16 +519,17 @@ local oldpcall, oldxpcall = pcall, xpcall coxpt = {} setmetatable(coxpt, {__mode = "kv"}) --- Identity function for copcall +--- Identity function for copcall local function copcall_id(trace, ...) return ... end --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function --- @param f Lua function to be called protected --- @param err Custom error handler --- @param ... parameters passed to the function --- @return a boolean whether the function call succeeded and the return values of either the function or the error handler +-- @param f Lua function to be called protected +-- @param err Custom error handler +-- @param ... Parameters passed to the function +-- @return A boolean whether the function call succeeded and the return +-- values of either the function or the error handler function coxpcall(f, err, ...) local res, co = oldpcall(coroutine.create, f) if not res then @@ -543,14 +544,15 @@ function coxpcall(f, err, ...) end --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function --- @param f Lua function to be called protected --- @param ... parameters passed to the function --- @return a boolean whether the function call succeeded and the returns values of the function or the error object +-- @param f Lua function to be called protected +-- @param ... Parameters passed to the function +-- @return A boolean whether the function call succeeded and the returns +-- values of the function or the error object function copcall(f, ...) return coxpcall(f, copcall_id, ...) end --- Handle return value of protected call +--- Handle return value of protected call function handleReturnValue(err, co, status, ...) if not status then return false, err(debug.traceback(co, (...)), ...) @@ -562,7 +564,7 @@ function handleReturnValue(err, co, status, ...) end end --- Resume execution of protected function call +--- Resume execution of protected function call function performResume(err, co, ...) return handleReturnValue(err, co, coroutine.resume(co, ...)) end |