Rename the file module to fs, and make some documentation changes

Makefile

@@ -2,8 +2,16 @@ PREFIX = /usr/local
 
 include config.mk
 
-OBJS = csto.o callisto.o lcl.o lenviron.o lextra.o lfile.o \
+OBJS = csto.o     \
-	   ljson.o lprocess.o lsocket.o util.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

lfs.c

@@ -1,7 +1,6 @@
 /***
- * Files, path manipulation,
+ * Files and file system manipulation.
- * and permissions.
+ * @module fs
- * @module file
  */
 
 #include <stdlib.h>
@@ -22,8 +21,8 @@
 
 /***
  * Returns the last component of the given pathname,
- * removing any trailing '/' characters. If *path*
+ * removing any trailing '/' characters. If the given
- * consists entirely of '/' characters, the string
+ * 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
+ * If the given path is an empty string or contains
- * '/' characters, the string `"."` is returned,
+ * 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*
+ * Moves the file at the path *src* to the path *dest*,
- * to the path *to*, moving it between directories
+ * moving it between directories if required. If *dest*
- * if required. If *to* exists, it is first removed.
+ * exists, it is first removed. Both *src* and *dest*
- * Both *from* and *to* must be of the same type
+ * must be of the same type (that is, both directories or
- * (that is, both directories or both non-directories)
+ * both non-directories) and must reside on the same file system.
- * and must reside on the same file system.
  *
- * This function will return nil and an error
+ * This function will return nil plus an error message
- * message if one of the following conditions are met:
+ * 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
+ *  - The directory containing *dest* resides on a read-only file system
- *
- * This function will throw an error if:
- *
- *  - An I/O error occurred
- *
- *  - An internal memory error occurred
  *
  * @function move
- * @usage file.move("file1", "file2")
+ * @usage fs.move("file1", "file2")
- * @tparam string from The pathname of the file to move.
+ * @tparam string src  The pathname of the file to move.
- * @tparam string   to The pathname to move *from* to.
+ * @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 *src;  /* parameter 1 (string) */
-	const char *to;   /* parameter 2 (string) */
+	const char *dest; /* parameter 2 (string) */
 
-	from = luaL_checkstring(L, 1);
+	src  = luaL_checkstring(L, 1);
-	to   = luaL_checkstring(L, 2);
+	dest = luaL_checkstring(L, 2);
-	ret  = rename(from, to); /* move file */
+	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()
+local wd = fs.workdir()
--- Set the current working directory to $HOME:
+-- Set the current working directory to the value of
-file.workdir(environment.get("HOME"))
+-- 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[] = {
+static const luaL_Reg fslib[] = {
-	{"basename", file_basename},
+	{"basename", fs_basename},
-	{"dirname",  file_dirname},
+	{"dirname",  fs_dirname},
-	{"exists",   file_exists},
+	{"exists",   fs_exists},
-	{"move",     file_move},
+	{"move",     fs_move},
-	{"workdir",  file_workdir},
+	{"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;
 }