Support listing files in a directory Path

[jeffdgr8]

Listing files within a directory is one of the few file APIs my library tests require that kotlinx-io doesn't currently support.

Similar API references:

• JVM File.listFiles
• Apple Foundation NSFileManager.contentsOfDirectoryAtPath:error:
• Okio FileSystem.list

[fzhinkin]

I see a few design options here:

• return a list or a sequence (but Sequence is not closable);
• support filtration by filename or by additional metadata that could be collected during the directory listing (file type, file size);
• instead of returning some particular iterable type, pass a lambda accepting paths to a routine so that users can build whatever they want themselves (might lead to some problems with concurrent fs modification and infinite recursion via symlinks).

[jeffdgr8]

My current use case in tests is fairly simple. I'm using the API to either check the number of files in a directory using the size of the file list, or to recursively delete all the contents of a directory.

The file/path list API works well for both of these requirements. An iterable sequence could also work, although it requires iterating and terminating the sequence to get the size. I would think if the underlying platform file API being used is already returning a list or array, there's probably not much value in mapping that existing collection to a sequence.

The other API options could also be useful. It might make sense to offer these filter/iterable APIs in addition to a simple file/path list API. A recursive iteration API would be especially useful for the recursive delete operation.

[StefanOltmann]

I think just returning a list of strings with the file names in the directory like java.io.File.list() does is the easiest way to get this started.

[lppedd]

I think just returning a list of strings with the file names in the directory like java.io.File.list() does is the easiest way to get this started.

I'd say lets not force rushed solutions. Once something is in it's difficult to take out and will just clutter the API.
kotlinx-io can take Okio as a reference implementation but might try a design closer to Java NIO.
Personally the NIO API is the cleanest I've seen.

[fzhinkin]

TL;DR: there were (and are) no signs that a proper stable FS API will be released soon (I mean in the next couple of months), so I decided to provide some API (FileSystem.list(Path): Collection) to make the library more usable.

[StefanOltmann]

I agree with this decision!

And it's unlikely that this API will change. Maybe the implementation, but FileSystem.list(Path) just makes sense.