From 84f58824b93be326101f27701a155268787599d7 Mon Sep 17 00:00:00 2001 From: Jeremy Baxter Date: Mon, 31 Jul 2023 07:33:23 +1200 Subject: [PATCH] Rename the file module to fs, and make some documentation changes --- Makefile | 14 ++++-- lfile.c => lfs.c | 110 +++++++++++++++++++++-------------------------- 2 files changed, 59 insertions(+), 65 deletions(-) rename lfile.c => lfs.c (75%) diff --git a/Makefile b/Makefile index 037c339..fd4a5a5 100644 --- a/Makefile +++ b/Makefile @@ -2,8 +2,16 @@ PREFIX = /usr/local include config.mk -OBJS = csto.o callisto.o lcl.o lenviron.o lextra.o lfile.o \ - ljson.o lprocess.o lsocket.o util.o +OBJS = csto.o \ + callisto.o \ + lcl.o \ + lenviron.o \ + lextra.o \ + lfs.o \ + ljson.o \ + lprocess.o \ + lsocket.o \ + util.o LIBS = liblua.a cjson.a socket.a all: csto libcallisto.so @@ -23,7 +31,7 @@ callisto.o: callisto.c callisto.h lcl.o: lcl.c callisto.h lextra.o: lextra.c callisto.h lenviron.o: lenviron.c callisto.h -lfile.o: lfile.c callisto.h +lfs.o: lfs.c callisto.h ljson.o: ljson.c callisto.h lprocess.o: lprocess.c callisto.h lsocket.o: lsocket.c callisto.h diff --git a/lfile.c b/lfs.c similarity index 75% rename from lfile.c rename to lfs.c index 13b5d8b..8cf44a4 100644 --- a/lfile.c +++ b/lfs.c @@ -1,7 +1,6 @@ /*** - * Files, path manipulation, - * and permissions. - * @module file + * Files and file system manipulation. + * @module fs */ #include @@ -22,8 +21,8 @@ /*** * Returns the last component of the given pathname, - * removing any trailing '/' characters. If *path* - * consists entirely of '/' characters, the string + * removing any trailing '/' characters. If the given + * path consists entirely of '/' characters, the string * `"/"` is returned. If *path* is an empty string, * the string `"."` is returned. * @@ -32,11 +31,11 @@ * limit (On most Linux systems this will be 4096). * * @function basename - * @usage file.basename(arg[0]) + * @usage fs.basename(arg[0]) * @tparam string path The path to process. */ static int -file_basename(lua_State *L) +fs_basename(lua_State *L) { const char *ret; char *path; /* parameter 1 (string) */ @@ -55,8 +54,8 @@ file_basename(lua_State *L) * Returns the parent directory of the pathname * given. Any trailing '/' characters are not * counted as part of the directory name. - * If *path* is an empty string or contains no - * '/' characters, the string `"."` is returned, + * If the given path is an empty string or contains + * no '/' characters, the string `"."` is returned, * signifying the current directory. * * This function may return nil if the given @@ -64,11 +63,11 @@ file_basename(lua_State *L) * limit (On most Linux systems this will be 4096). * * @function dirname - * @usage file.dirname(arg[0]) + * @usage fs.dirname(arg[0]) * @tparam string path The path to process. */ static int -file_dirname(lua_State *L) +fs_dirname(lua_State *L) { const char *ret; char *path; /* parameter 1 (string) */ @@ -94,13 +93,13 @@ file_dirname(lua_State *L) * * @function exists * @usage -if file.exists("/etc/fstab") then +if fs.exists("/etc/fstab") then -- ... end * @tparam string path The path of the file to look for. */ static int -file_exists(lua_State *L) +fs_exists(lua_State *L) { const char *path; int ret; @@ -116,15 +115,14 @@ file_exists(lua_State *L) } /*** - * Moves the file at the path *from* - * to the path *to*, moving it between directories - * if required. If *to* exists, it is first removed. - * Both *from* and *to* must be of the same type - * (that is, both directories or both non-directories) - * and must reside on the same file system. + * Moves the file at the path *src* to the path *dest*, + * moving it between directories if required. If *dest* + * exists, it is first removed. Both *src* and *dest* + * must be of the same type (that is, both directories or + * both non-directories) and must reside on the same file system. * - * This function will return nil and an error - * message if one of the following conditions are met: + * This function will return nil plus an error message + * if one of the following conditions are met: * * - One of the given pathnames are longer than the system's path length limit * @@ -139,40 +137,34 @@ file_exists(lua_State *L) * * - A component of one of the given pathnames is not a directory * - * - *from* is a directory, but *to* is not + * - *src* is a directory, but *dest* is not * - * - *to* is a directory, but *from* is not + * - *dest* is a directory, but *src* is not * * - The given pathnames are on different file systems * * - There is no space left on the file system * * - The current user's quota of disk blocks on the file system - * containing the directory of *to* has been exhausted + * containing the directory of *dest* has been exhausted * - * - The directory containing *to* resides on a read-only file system - * - * This function will throw an error if: - * - * - An I/O error occurred - * - * - An internal memory error occurred + * - The directory containing *dest* resides on a read-only file system * * @function move - * @usage file.move("file1", "file2") - * @tparam string from The pathname of the file to move. - * @tparam string to The pathname to move *from* to. + * @usage fs.move("file1", "file2") + * @tparam string src The pathname of the file to move. + * @tparam string dest The destination pathname. */ static int -file_move(lua_State *L) +fs_move(lua_State *L) { int ret; - const char *from; /* parameter 1 (string) */ - const char *to; /* parameter 2 (string) */ + const char *src; /* parameter 1 (string) */ + const char *dest; /* parameter 2 (string) */ - from = luaL_checkstring(L, 1); - to = luaL_checkstring(L, 2); - ret = rename(from, to); /* move file */ + src = luaL_checkstring(L, 1); + dest = luaL_checkstring(L, 2); + ret = rename(src, dest); /* move file */ if (ret == 0) { /* check for success */ lua_pushboolean(L, 1); @@ -231,11 +223,11 @@ file_move(lua_State *L) } /*** - * Sets/returns the current working directory. + * Returns or sets the current working directory. * * If *dir* is nil, returns the current working * directory. Otherwise, sets the current working - * directory to *dir*. + * directory to *dir* and returns true on success. * * This function will return nil and an error * message if one of the following conditions are met: @@ -250,28 +242,22 @@ file_move(lua_State *L) * * - *dir* could not be translated as a result of too many symbolic links * - * This function will throw an error if: - * - * - Insufficient memory is available - * - * - An internal memory error occurred - * - * - An I/O error occurred - * * @function workdir * @usage -- Store the current working directory in a variable: -local wd = file.workdir() --- Set the current working directory to $HOME: -file.workdir(environment.get("HOME")) +local wd = fs.workdir() +-- Set the current working directory to the value of +-- the HOME environment variable: +fs.workdir(environ["HOME"]) * @tparam[opt] string dir The directory to set as the current working directory. */ static int -file_workdir(lua_State *L) +fs_workdir(lua_State *L) { const char *workdir; /* parameter 1 (string) */ char *buffer; /* buffer used by getcwd() */ char *ret; + if (lua_isnoneornil(L, 1)) { /* if first argument was not given... */ buffer = malloc(sizeof(char *) * 512); ret = getcwd(buffer, 512); @@ -340,18 +326,18 @@ file_workdir(lua_State *L) } } -static const luaL_Reg filelib[] = { - {"basename", file_basename}, - {"dirname", file_dirname}, - {"exists", file_exists}, - {"move", file_move}, - {"workdir", file_workdir}, +static const luaL_Reg fslib[] = { + {"basename", fs_basename}, + {"dirname", fs_dirname}, + {"exists", fs_exists}, + {"move", fs_move}, + {"workdir", fs_workdir}, {NULL, NULL} }; int -luaopen_file(lua_State *L) +luaopen_fs(lua_State *L) { - luaL_newlib(L, filelib); + luaL_newlib(L, fslib); return 1; }