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

[Albert Krewinkel <albert+lua@...>]

Sean Conner writes:

> 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.

I'd like to add another dimension to that. We are using Lua in pandoc,
a document converter written in Haskell, and the experience made me
really appreciate Lua's beauty and elegance. I

A lot of interesting functionality, like file system access, is already
included in pandoc via some Haskell library. So we expose those library
functions to Lua instead of adding additional libraries. Filesystem
example: <https://github.com/hslua/hslua-module-system>. A standardized
API, as proposed above, would be a great. It would leave us with the
freedom to implement APIs in our own, Haskell-focused way, while
allowing users to swap-out compatible libraries.

>   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.

I agree, that's awfully hard. Taking inspiration from other language
communitites: The Haskell community has a [Core Library Committee] which
decides about changes to the "base" package. The process may not be
perfect, but seems to work remarkably well.

Maybe something similar could be done for Lua?

Cheers,
 Albert

[Core Library Committee]: https://wiki.haskell.org/Core_Libraries_Committee


>   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


--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124