.TH filelib 3erl "stdlib 2.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
filelib \- File utilities, such as wildcard matching of filenames
.SH DESCRIPTION
.LP
This module contains utilities on a higher level than the \fIfile\fR\& module\&.
.LP
This module does not support "raw" file names (i\&.e\&. files whose names do not comply with the expected encoding)\&. Such files will be ignored by the functions in this module\&.
.LP
For more information about raw file names, see the \fBfile\fR\& module\&.
.SH DATA TYPES
.nf

\fBfilename()\fR\& = \fBfile:name()\fR\&
.br
.fi
.nf

\fBdirname()\fR\& = \fBfilename()\fR\&
.br
.fi
.nf

\fBdirname_all()\fR\& = \fBfilename_all()\fR\&
.br
.fi
.nf

\fBfilename_all()\fR\& = \fBfile:name_all()\fR\&
.br
.fi
.SH EXPORTS
.LP
.nf

.B
ensure_dir(Name) -> ok | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfilename_all()\fR\& | \fBdirname_all()\fR\&
.br
Reason = \fBfile:posix()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIensure_dir/1\fR\& function ensures that all parent directories for the given file or directory name \fIName\fR\& exist, trying to create them if necessary\&.
.LP
Returns \fIok\fR\& if all parent directories already exist or could be created, or \fI{error, Reason}\fR\& if some parent directory does not exist and could not be created for some reason\&.
.RE

.LP
.nf

.B
file_size(Filename) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = \fBfilename_all()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIfile_size\fR\& function returns the size of the given file\&.
.RE

.LP
.nf

.B
fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Dir = \fBdirname()\fR\&
.br
RegExp = string()
.br
Recursive = boolean()
.br
Fun = fun((F :: \fBfile:filename()\fR\&, AccIn) -> AccOut)
.br
AccIn = AccOut = term()
.br
.RE
.RE
.RS
.LP
The \fIfold_files/5\fR\& function folds the function \fIFun\fR\& over all (regular) files \fIF\fR\& in the directory \fIDir\fR\& that match the regular expression \fIRegExp\fR\& (see the \fBre\fR\& module for a description of the allowed regular expressions)\&. If \fIRecursive\fR\& is true all sub-directories to \fIDir\fR\& are processed\&. The regular expression matching is done on just the filename without the directory part\&.
.LP
If Unicode file name translation is in effect and the file system is completely transparent, file names that cannot be interpreted as Unicode may be encountered, in which case the \fIfun()\fR\& must be prepared to handle raw file names (i\&.e\&. binaries)\&. If the regular expression contains codepoints beyond 255, it will not match file names that do not conform to the expected character encoding (i\&.e\&. are not encoded in valid UTF-8)\&.
.LP
For more information about raw file names, see the \fBfile\fR\& module\&.
.RE

.LP
.nf

.B
is_dir(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfilename_all()\fR\& | \fBdirname_all()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIis_dir/1\fR\& function returns \fItrue\fR\& if \fIName\fR\& refers to a directory, and \fIfalse\fR\& otherwise\&.
.RE

.LP
.nf

.B
is_file(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfilename_all()\fR\& | \fBdirname_all()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIis_file/1\fR\& function returns \fItrue\fR\& if \fIName\fR\& refers to a file or a directory, and \fIfalse\fR\& otherwise\&.
.RE

.LP
.nf

.B
is_regular(Name) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfilename_all()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIis_regular/1\fR\& function returns \fItrue\fR\& if \fIName\fR\& refers to a file (regular file), and \fIfalse\fR\& otherwise\&.
.RE

.LP
.nf

.B
last_modified(Name) -> file:date_time() | 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfilename_all()\fR\& | \fBdirname_all()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIlast_modified/1\fR\& function returns the date and time the given file or directory was last modified, or 0 if the file does not exist\&.
.RE

.LP
.nf

.B
wildcard(Wildcard) -> [file:filename()]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Wildcard = \fBfilename()\fR\& | \fBdirname()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIwildcard/1\fR\& function returns a list of all files that match Unix-style wildcard-string \fIWildcard\fR\&\&.
.LP
The wildcard string looks like an ordinary filename, except that certain "wildcard characters" are interpreted in a special way\&. The following characters are special:
.RS 2
.TP 2
.B
?:
Matches one character\&.
.TP 2
.B
*:
Matches any number of characters up to the end of the filename, the next dot, or the next slash\&.
.TP 2
.B
**:
Two adjacent \fI*\fR\&\&'s used as a single pattern will match all files and zero or more directories and subdirectories\&.
.TP 2
.B
[Character1,Character2,\&.\&.\&.]:
Matches any of the characters listed\&. Two characters separated by a hyphen will match a range of characters\&. Example: \fI[A-Z]\fR\& will match any uppercase letter\&.
.TP 2
.B
{Item,\&.\&.\&.}:
Alternation\&. Matches one of the alternatives\&.
.RE
.LP
Other characters represent themselves\&. Only filenames that have exactly the same character in the same position will match\&. (Matching is case-sensitive; i\&.e\&. "a" will not match "A")\&.
.LP
Note that multiple "*" characters are allowed (as in Unix wildcards, but opposed to Windows/DOS wildcards)\&.
.LP
Examples:
.LP
The following examples assume that the current directory is the top of an Erlang/OTP installation\&.
.LP
To find all \fI\&.beam\fR\& files in all applications, the following line can be used:
.LP
.nf

    filelib:wildcard("lib/*/ebin/*.beam").        
.fi
.LP
To find either \fI\&.erl\fR\& or \fI\&.hrl\fR\& in all applications \fIsrc\fR\& directories, the following
.LP
.nf

    filelib:wildcard("lib/*/src/*.?rl")        
.fi
.LP
or the following line
.LP
.nf

    filelib:wildcard("lib/*/src/*.{erl,hrl}")        
.fi
.LP
can be used\&.
.LP
To find all \fI\&.hrl\fR\& files in either \fIsrc\fR\& or \fIinclude\fR\& directories, use:
.LP
.nf

    filelib:wildcard("lib/*/{src,include}/*.hrl").        
.fi
.LP
To find all \fI\&.erl\fR\& or \fI\&.hrl\fR\& files in either \fIsrc\fR\& or \fIinclude\fR\& directories, use:
.LP
.nf

    filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")        
.fi
.LP
To find all \fI\&.erl\fR\& or \fI\&.hrl\fR\& files in any subdirectory, use:
.LP
.nf

    filelib:wildcard("lib/**/*.{erl,hrl}")        
.fi
.RE

.LP
.nf

.B
wildcard(Wildcard, Cwd) -> [file:filename()]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Wildcard = \fBfilename()\fR\& | \fBdirname()\fR\&
.br
Cwd = \fBdirname()\fR\&
.br
.RE
.RE
.RS
.LP
The \fIwildcard/2\fR\& function works like \fIwildcard/1\fR\&, except that instead of the actual working directory, \fICwd\fR\& will be used\&.
.RE