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

[Sean Conner <sean@...>]

It was thus said that the Great Sean Conner once stated:
> It was thus said that the Great Thorkil Naur once stated:
> > Hello Sean,
> > 
> > On Wed, Jan 22, 2020 at 06:46:32PM -0500, Sean Conner wrote:
> > > ...
> > > 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
> > 
> > What happens when glist(name) is called with a name that would cause
> > list(name) to fail?
> 
>   There's no iteration (or rather, the loop is immediately exited).  Are you
> expecting perhaps error() be called?  

  I tested LuaFileSystem to see what it does, and it throws an error.  I've
been thinking about this, and for iterating over a directory, I think
throwing an error is probably a good idea as otherwise, there is no
indication the directory doesn't exist (or there's some other error).

  So for this function, I think throwing an error is appropriate.

> > And similarly, what happens when gexpand(pattern) is called with a
> > pattern that would cause expand(pattern) to fail?
> 
>   Same here.  No iteration.

  I'm rethinking on the expand() and gexpand() functions.  I had:

> 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

  In looking at the return errors for the function I'm wrapping, one error
it returns is NOMATCH, which I'm torn about returning that or an empty
array.  There are some other errors as well which means I might as well
throw an error for gexpand().  I'm just trying to think what would be better
for no matches, an error, or an empty array/iterator?

  -spc