# dirent - Iterative directory listing library

Copyright (c) 2020 Telnyx LLC.

__Version:__ 1.0.0

# dirent

**dirent** is an iterative directory listing for Erlang.

Erlang functions such as `filelib:fold_files/5`, `file:list_dir/1`, `c:ls/0,1`,
etc return files from directories _after_ reading them from the filesystem.
When you have an humongous number of files on a single folder, all these
functions will block for a certain time.

In these cases you may not be interested in returning the full list of files,
but instead you may want to list them _iteratively_, returning each entry after
the another to your process, at the moment they are taken from

## Installation

Download the sources from our [Github repository](

To build the application simply run `rebar3 compile`.

Or add it to your rebar config add:


{deps, [
    {dirent, ".*", {git, "git://", {branch, "master"}}}

## Basic usage

The most basic usage of `dirent` is:

> {ok, Dir} = dirent:opendir(".").
> dirent:readdir(Dir).
> dirent:readdir(Dir).
> dirent:readdir(Dir).
> dirent:readdir(Dir).

But you can also use the functions `dirent:foreach/2` and `dirent:fold/3`.

For example, to print all files in the folder, one per line, do:

dirent:foreach(".", fun(F) -> io:fwrite("~s~n", [F]), cont end).

and if you need to collect all files from a folder in a list, do:

dirent:fold(".", fun(F, Tail) -> {cont, [F | Tail]} end, []).

The `dirent:foreach/2` function `Fun` can return `cont` or `halt`. In the
former case, the loop will continue reading files, while in the latter case the
loop will halt and the function will return `ok`.

The `dirent:fold/3` function `Fun` can return `{cont, AccOut}` or `{halt,
AccOut}`, likewise the above, but also returning the accumulator, which is
passed to the `{ok, AccOut}` return value.