lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index] 

It was thus said that the Great Sean Conner once stated:
> It was thus said that the Great Lorenzo Donati once stated:
> > 
> > For that some kind of "mandated/blessed" API specifications would be needed.
> 
>   Okay, let's see if the community can just come together to define the
> minimum viable module for directory functions. 

  Okay, second take.  I've looked at LuaFileSystem, LuaPosix, PenLight and
my own org.conman.fsys modules and I've come up with a set of minimal
directory functions.  I've gone ahead and decided to use the method of error
reporting that the existing Lua functions (like io.open()) use---namely,
return a falsey value, a string with the error message, and an integer
representing the error as a value.  I don't like it, but I'm going with the
majority view point here.

  Anyway, before the functions are some data fields:

	_implementation string, informational "POSIX", "Windows", etc.
	tmp             string, temporary directory name
	null            string, NULL device name
	current         string representing current directory
	parent          string representing parent directory
	pathsep         string, $PATH separator character

  For a POSIX implementation, these would be:

	_implementation = "POSIX"
	tmp             = "/tmp" -- unles $TMPDIR defined
	null            = "/dev/null"
	current      	= "."
	parent          = ".."
	pathsep         = ":"

  and for Windows:

	_implementation = "Windows"
	tmp             = os.getenv("TMP") -- or $TEMP or $USERPROFILE
	null            = "NULL"
        current         = "."
	parent          = ".."
	pathsep         = ";"

  There are (some older, possibly no longer relevant) operating systems that
use different conventions for "current" and "parent" directories, thus the
decision to add those two fields.  The temp directory also changes location
from operating system to operating system, thus the addition of that field;
the same for the null device.  I decided to throw in the path separator for
$PATH as well.  The default directory separator is available as
package.config:sub(1,1) thus it is not included here.  The _implementation
field is informational only.

  And now the functions.  Items in [] are optional, and on the left side of
the '=', represents data returned in the error path.  On the right side of
the '=' it represents optional parameters.

Usage:        okay[,errs,erri] = mkdir(name)
Desc:         Make a directory
Input:        name (string) name of directory
Return:       okay (boolean) true if success, false if error
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

	---

Usage:        okay[,errs,erri] = rmdir(name)
Desc:         Remove a directory
Input:        name (string) name of directory
Return:       okay (boolean) true if success, false if error
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

	---

Usage:        path[,errs,erri] = getwd()
Desc:         Return the current directory
Return:       path (string) path of current working diirectory
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

	---

Usage:        okay[,errs,erri] = setwd(name)
Desc:         Set the working directory
Input:        name (string) name of directory
Return:       okay (boolean) true if success, false if error
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

	---

Usage:        list[,errs,erri] = list([name])
Desc:         Return a list of entries in a directory.  If no directory
              is given, return the entries in the current directory.
Input:        name (string/optional) name of directory, defaults to current diretory
Return:       list (array of string) list of filename in directory, nil on error.
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

Note:         The order of filenames is unspecified.

              The current and parent entries (if defined for a system)
              will NOT appear in the list.

	---

Usage:        for entry in glist([name]) do ... end
Desc:         Return an iterator for traversing a directory; if not given,
              traverse the current directory.
Input:        name (string/optional) name of directory, defaults to current directory
Return:       (iterator function)
              (iterator state)
              (iterator var) (string) filename

Note:         The ordering of filenames is unspecified.

              The current and parent entries (if defined for a system)
              will NOT appear in the list.

	---

Usage:        list[,errs,erri] = expand(pattern)
Desc:         Expand a list of filenames from a file globbing pattern
Input:        pattern (string) an operating system dependent globbing pattern
Return:       list (array) list of filename matching pattern, nil on error
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

Note:         The ordering of filenames is unspecified.

	---

Usage:        for entry in gexpand(pattern) do ... end
Desc:         Return an iterator for traversing a file glob
Input:        pattern (string) an operating system dependent globbing pattern
Return:       (iterator function)
              (iterator state)
              (iterator var) (string) filename

Note:         The ordering of filenames is unspecified.

	---

Usage:        file = filename(name)
Desc:         Return the file portion of a path specifier
Input:        name (string) path specifier
Return:       file (string) file portion---if none, return ""

Note:         The following sequence will produce an equivalent path:

                      dirname(path) .. DIRSEP .. filename(path)

	---

Usage:        dir = dirname(name)
Desc:         Return the directory portion of a path specifier
Input:        name (string) path specifier
Return:       dir (string) directory portion---if none, return "" (if root) or "." (if none exists in name).

Note:         The following sequence will produce an equivilent path:

                      dirname(path) .. DIRSEP .. filename(path)

	---

Usage:        info[,errs,erri] = status(name)
Desc:         Return information about a file or directory
Input:        name (string) name of file
Return:       info (table) info of file, nil on error
                      * name (string) filename
                      * size (integer) size of file
                      * timestamp (number) timestamp of file
                      * type (enum)
                              + 'file'
                              + 'directory'
                              + other system dependent type
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

Note:         The size field may not have meaning for directories
              the time field can be passed to os.date().

	---

Usage:        okay[,errs,erri] = timestamp(name[,time])
Desc:         Set the timestamp on a file.
Input:        name (string) name of file
              time (number) timestamp, if not given, use current time
Return:       okay (boolean) true if okay, false if error
              errs (string/optional) error message on failure
              erri (integer/optional) error number on failure

	---

  I've included both a 'return array' and 'iterator' version for listing the
contents of a directory and listing files per a file pattern more for
completeness than anything else---if I had to pick one version, it would be
the iterator one (think huge directories) as being more useful.

  -spc