My use case is replacing shell scripts. ;)
Writing a walkDir(string): file iterator should be a nice exercise for me (beside from the fact that I don't like accessing primitive C API).
Ok, since the forum is as good a place as any, I guess I'll outline my plans for the stat() procedure (which, at the moment, I've named getFileInfo), as well as it's related object, the FileInfo object.
My general aim with the design of these things is to allow common use cases in an easy, cross-platform manner. The getFileInfo procedure, as I am drafting it, currently has the following overloads/argument options:
proc getFileInfo(path: string, followSymlink = true): FileInfo
## Retrieves file information for the file object pointed to by `path`.
##
## When `followSymlink` is true, symlinks are followed and the information
## retrieved is information related to the symlink's target. Otherwise,
## information on the symlink itself is retrieved.
##
## If the information cannot be retrieved, such as when the path doesn't
## exist, or when permission restrictions prevent the program from retrieving
## file information, an error will be thrown.
proc getFileInfo(handle: FileHandle): FileInfo
## Retrieves file information for the file object represented by the given
## handle.
##
## If the information cannot be retrieved, such as when the file handle
## is invalid, an error will be thrown.
As far as I'm aware, Windows and Linux both support retrieval of a file's information via either paths or filehandles (actually, on Windows, one must use a file handle to get extended information).
Here is a rough layout of the FileInfo object and it's related types:
type
FileInfo = object
## Contains information associated with a file object.
id: tuple[device: DeviceID, file: FileID] # Device and file id
kind: TPathComponent # Kind of file object - directory, symlink, etc.
size: FileSize # Size of file
linkCount: int64 # Number of hard links the file object has.
lastAccessTime: FileTime # Time file was last accessed.
lastModificationTime: FileTime # Time file was last modified.
I'm very open to suggestions on how to improve the FileInfo structure - if there's some information I've missed that can be easily retrieved on both Linux/Posix and Windows, please tell me. I am aware that the above draft has missing types - I'm still pondering what to do about some of them (see below)
Well, the Posix standard requires it, and the Windows API supports it. That's why I included it.
Should there be an optional data value in the FileInfo type for extended information specific to the OS? If so, what kind of information should be stored?
No, that defeats its purpose. I can always call 'stat' on my own for OS specific information.
What types should lastAccessTime and lastModificationTime be? Should we try to coerce them to types from the times module, or let them be os-module specific?
times.TTime.
Should FileSize be an int64, or a distinct type? This might seem silly, but newer file systems might be able to hold files greater than an int64 in length.
I think this should simply be system.BiggestInt. We'll support int128 when it becomes common.
Should file access and permissions be retrieved? While Posix provides this as part of stat(), in windows it can get a bit... complicated.
I think these should be included.