Re: Standard Libraries: (was: and Lua marches on)

[Sean Conner <sean@...>]

It was thus said that the Great GrayFace once stated:
> 
> --[[ Path functions ]]
> 
> -- if 'isdir' is false, files are iterated, otherwise directories are.
> -- Usage: for fileName, fileSize in path.find("c:\*.*") do
> path.find(filter, isdir = false)
> 
> -- Extracts file name from full path
> path.name(filePath)
> 
> -- Extracts file extension
> path.ext(filePath)
> 
> -- Changes extension to 'ext'
> path.setext(filePath, ext)
> 
> -- Adds trailing slash to the path
> path.addslash(filePath)
> 
> path.GetCurrentDirectory()
> path.SetCurrentDirectory(dir)

  The major problem with path/file functions is that you get similar, but
not quite the same, functionality between operating systems.  While I don't
have any Windows documentation, it can't be much different from MS-DOS,
which I have plenty of documentation.  I also have documentation for AmigaOS
(yes, I know, not widely used any more, but still, it provides a nice
counterpoint to Unix/Windows).  And to keep this short(ish), I'll just
concentrate on iterating over a directory.

  Under Unix, you have the following calls:

	opendir()	- open a directory to read
	rewinddir()	- set reading point back to start
	readdir()	- read the next entry
	closedir()	- close a directory

  readdir() basically returns the next name in the directory (and nothing
else).  No regex pattern matching either.  If you want that, you have to
check each result from readdir().  It's a simple API for scanning a
directory.

  Under MS-DOS (and I assume, Windows), you have the following:

	FindFirstFile()	 - return first file in current working directory
	FindNextFile()	 - return the next matching file

  FindFirstFile() only works for the current working directory (unlike
Unix), it takes a simple file regex (a file glob) and some flags (include
archive files, read-only files, system files, etc) and fills in a structure
(the address of which is passed in first via another function) with the
following information (for Unix, another all is needed to obtain this
information):

	name
	extention	(note: Unix does not use extentions---applications
			might, but not the OS itself)
	timestamp
	filesize
	attribute	(hidden, system, read-only, etc)

  Now, AmigaOS:

	Lock()		- obtain lock on passed in directory
	Currentdir()	- obtain lock on current directory
	Examine()	- return first entry (no pattern matching) as structure
	ExNext()	- return next entry as structure (no pattern matching)
	MatchFirst()	- return first file that matches pattern
	MatchNext()	- return next file that matches pattern
	MatchEnd()	- required to clean up after MatchFirst()/MatchNext()

  The documentation I have is a bit sparse in what exactly is returned by
these, but I suspect (the Amiga being packed away somewhere) that Examine*()
returns a similar structure to MS-DOS (some system specific attributes,
size, name, etc) and that the Match*() functions return just filenames that
can be examined using other calls.

  And the file globbing between the three systems I've listed are all
different (enough so that it's probably best to ignore, or attempt to
translate a Lua-like regex to the native file globbing, but I think that can
induce madness in someone [1]).

  There's also the difference between the various system attributes and
permissions to consider.  

  -spc (Ain't portability fun?)

[1]	Under Windows, "*.*" return return all files, including those
	without an extention; under Unix, that will fail to return any files
	without a '.' in the name somewhere, as the equivilent under Unix is
	just "*".  I'm not even going to to into the differences with
	AmigaOS.