A Batteries API specification (was Re: LuaDEAL - Lua DEad Alive Libraries)

[Sean Conner <sean@...>]

It was thus said that the Great Lorenzo Donati once stated:
> 
> Sadly this won't solve the basic problem: an unified, cross-platform 
> (Windows included) set of libraries whose behavior is the same on all 
> systems (bar system-specific subsets).
> 
> 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.  I'm looking at three
different modules that implement such functionality, LuaFileSystem, luaposix
and my own org.conman.fsys module.

  LuaFileSystem and luaposix are largely compatible---for instance, both
have rmdir(), and they both return the same information:

	happy path:	0
	sad path:	nil,"error string",err_integer

  This mimics the Lua file API.  I'm not happy with that, so when I wrote my
own, I did:

	happy path:	true,0
	sad path:	false,err_integer

  My thoughts for returning an error number instead of a string is that the
number is easier for error handling and if I want to print out a string, I
can use a wrapper for strerror() at that point.  But aside from error
reporting, all three APIs are similar enough to get a feel for what might
make the minimum library.  Here's what I have so far (excluding the error
reporting):

	okay = mkdir(name)

		Make Directory, name is a string, okay is non nil on
		success, nil on error, with additional error reporting TBD.

		NOTE:	luaposix is missing this function

	okay = rmdir(name)
		
		Remove Directory, name is a string, okay is non nil on
		success, nil on error, with additional error reporting TBD.

	okay = getcwd()

		Get Current Working Directory, returns the current working
		directory, nil on error, other error reporting TBD.

	okay = setcwd(name)

		Set Current Working Directory, takes a directory name, and
		tries to set it as the current directory.  Returns non-nil
		on success, nil on error, other error reporting TBD.

	cat = list([name])

		Obtain a list of files in the given directory; if not given,
		use the current working directory.  Return an array of
		names, or nil on error (error reporting TBD).

		NOTE: 	The ordering of entries is unspecified.
			None of modules I've listed have this specific
			functionality.

	cat = expand(glob)

		Obtain a list of files per the passed in file glob
		(for example, "*.c").  Return an array of names, or nil
		on error (error reporting TBD).

		NOTE:	The ordering of entries is unspecified.
			LuaFilesystem is missing this function.

	fun,state,var = glist([name])

		Returns an interator (function, state, var) for use in a for
		statement.  Each time the function is called, a new filename
		is returned.

		NOTE:	The ordering of entries is unspecified.
			All three modules have this function, although
			it's called files() under luaposix.

	fun,state,var = gexpand(glob)

		Returns an interator (function, state, var) for use in a for
		statement.  Each time the function is called, a new filename
		matching the file glob is returned.

		NOTE:	The ordering of entries is unspecified.
			Only org.conman.org has this functionaltiy.

	file = filename(name)

		Return a base filename.  name is a string of a filename, and
		upon return, all directory information is removed.

		Example:	foo/bar/baz.x
		return		baz.x

		NOTE:	Only org.conman.fsys has this function.

	dir = dirname(name)

		Return the directory part of a filename.  name is a string
		of a filename, and upon return, the filename portion is
		removed.

		Example:	foo/bar/baz.x
		return		foo/bar

		Note:	Only org.conman.fsys has this function.

			The semantics of filename() and dirname() here
			differ from the POSIX functions basename() and
			dirname().

			dirname() and filename() can work in
			conjuction with each other:

			path        = "c:\sample\path\to\file"
			dir         = dirname(path)
			file        = filename(path)
			constructed = dir .. "/" .. file
			assert(constructed == path)

  And that's it.  Additional information about files (like timestamps, size,
type) is not in the scope for this module---this is just about directory
manipulation.  Now imaging having to go through all this for other possible
batteries, like additional file operations, network API, events, etc.

  -spc