aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/filelib.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/filelib.xml')
-rw-r--r--lib/stdlib/doc/src/filelib.xml186
1 files changed, 96 insertions, 90 deletions
diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml
index 2cf9490f4b..7c6380ce28 100644
--- a/lib/stdlib/doc/src/filelib.xml
+++ b/lib/stdlib/doc/src/filelib.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -28,19 +28,23 @@
<docno>1</docno>
<approved>Kenneth Lundin</approved>
<checked></checked>
- <date>03-01-21</date>
+ <date>2003-01-21</date>
<rev>A</rev>
- <file>filelib.sgml</file>
+ <file>filelib.xml</file>
</header>
<module>filelib</module>
- <modulesummary>File utilities, such as wildcard matching of filenames</modulesummary>
+ <modulesummary>File utilities, such as wildcard matching of filenames.
+ </modulesummary>
<description>
- <p>This module contains utilities on a higher level than the <c>file</c>
- module.</p>
- <p>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.</p>
- <p>For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p>
+ <p>This module contains utilities on a higher level than the
+ <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
+
+ <p>This module does not support "raw" filenames (that is, files whose
+ names do not comply with the expected encoding). Such files are ignored
+ by the functions in this module.</p>
+
+ <p>For more information about raw filenames, see the
+ <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
</description>
<datatypes>
@@ -61,93 +65,99 @@
<funcs>
<func>
<name name="ensure_dir" arity="1"/>
- <fsummary>Ensure that all parent directories for a file or directory exist.</fsummary>
+ <fsummary>Ensure that all parent directories for a file or directory
+ exist.</fsummary>
<desc>
- <p>The <c>ensure_dir/1</c> function ensures that all parent
- directories for the given file or directory name <c><anno>Name</anno></c>
+ <p>Ensures that all parent directories for the specified file or
+ directory name <c><anno>Name</anno></c>
exist, trying to create them if necessary.</p>
<p>Returns <c>ok</c> if all parent directories already exist
- or could be created, or <c>{error, <anno>Reason</anno>}</c> if some parent
- directory does not exist and could not be created for some
- reason.</p>
+ or can be created. Returns <c>{error, <anno>Reason</anno>}</c> if
+ some parent directory does not exist and cannot be created.</p>
</desc>
</func>
+
<func>
<name name="file_size" arity="1"/>
- <fsummary>Return the size in bytes of the file.</fsummary>
+ <fsummary>Return the size in bytes of a file.</fsummary>
<desc>
- <p>The <c>file_size</c> function returns the size of the given file.</p>
+ <p>Returns the size of the specified file.</p>
</desc>
</func>
+
<func>
<name name="fold_files" arity="5"/>
<fsummary>Fold over all files matching a regular expression.</fsummary>
<desc>
- <p>The <c>fold_files/5</c> function folds the function
- <c><anno>Fun</anno></c> over all (regular) files <c><anno>F</anno></c> in the
- directory <c><anno>Dir</anno></c> that match the regular expression <c><anno>RegExp</anno></c>
- (see the <seealso marker="re">re</seealso> module for a description
- of the allowed regular expressions).
- If <c><anno>Recursive</anno></c> is true all sub-directories to <c>Dir</c>
- are processed. The regular expression matching is done on just
- the filename without the directory part.</p>
-
- <p>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
- <c>fun()</c> 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).</p>
-
- <p>For more information about raw file names, see the
- <seealso marker="kernel:file">file</seealso> module.</p>
+ <p>Folds function <c><anno>Fun</anno></c> over all (regular) files
+ <c><anno>F</anno></c> in directory <c><anno>Dir</anno></c> that match
+ the regular expression <c><anno>RegExp</anno></c> (for a description
+ of the allowed regular expressions,
+ see the <seealso marker="re"><c>re</c></seealso> module).
+ If <c><anno>Recursive</anno></c> is <c>true</c>, all subdirectories
+ to <c>Dir</c>
+ are processed. The regular expression matching is only done on
+ the filename without the directory part.</p>
+ <p>If Unicode filename translation is in effect and the file
+ system is transparent, filenames that cannot be
+ interpreted as Unicode can be encountered, in which case the
+ <c>fun()</c> must be prepared to handle raw filenames
+ (that is, binaries). If the regular expression contains
+ codepoints &gt; 255, it does not match filenames that do
+ not conform to the expected character encoding (that is, are not
+ encoded in valid UTF-8).</p>
+ <p>For more information about raw filenames, see the
+ <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
</desc>
</func>
+
<func>
<name name="is_dir" arity="1"/>
- <fsummary>Test whether Name refer to a directory or not</fsummary>
+ <fsummary>Test whether <c>Name</c> refers to a directory.</fsummary>
<desc>
- <p>The <c>is_dir/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
- refers to a directory, and <c>false</c> otherwise.</p>
+ <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+ refers to a directory, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="is_file" arity="1"/>
- <fsummary>Test whether Name refer to a file or directory.</fsummary>
+ <fsummary>Test whether <c>Name</c> refers to a file or directory.
+ </fsummary>
<desc>
- <p>The <c>is_file/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
- refers to a file or a directory, and <c>false</c> otherwise.</p>
+ <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+ refers to a file or a directory, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="is_regular" arity="1"/>
- <fsummary>Test whether Name refer to a (regular) file.</fsummary>
+ <fsummary>Test whether <c>Name</c> refers to a (regular) file.</fsummary>
<desc>
- <p>The <c>is_regular/1</c> function returns <c>true</c> if <c><anno>Name</anno></c>
- refers to a file (regular file), and <c>false</c> otherwise.</p>
+ <p>Returns <c>true</c> if <c><anno>Name</anno></c>
+ refers to a (regular) file, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="last_modified" arity="1"/>
- <fsummary>Return the local date and time when a file was last modified.</fsummary>
+ <fsummary>Return the local date and time when a file was last modified.
+ </fsummary>
<desc>
- <p>The <c>last_modified/1</c> function returns the date and time the
- given file or directory was last modified, or 0 if the file
- does not exist.</p>
+ <p>Returns the date and time the specified file or directory was last
+ modified, or <c>0</c> if the file does not exist.</p>
</desc>
</func>
+
<func>
<name name="wildcard" arity="1"/>
<fsummary>Match filenames using Unix-style wildcards.</fsummary>
<desc>
- <p>The <c>wildcard/1</c> function returns a list of all files
- that match Unix-style wildcard-string <c><anno>Wildcard</anno></c>.</p>
+ <p>Returns a list of all files that match Unix-style wildcard string
+ <c><anno>Wildcard</anno></c>.</p>
<p>The wildcard string looks like an ordinary filename, except
- that certain "wildcard characters" are interpreted in a special
- way. The following characters are special:
- </p>
+ that the following "wildcard characters" are interpreted in a special
+ way:</p>
<taglist>
<tag>?</tag>
<item>
@@ -160,14 +170,14 @@
</item>
<tag>**</tag>
<item>
- <p>Two adjacent <c>*</c>'s used as a single pattern will
- match all files and zero or more directories and subdirectories.</p>
+ <p>Two adjacent <c>*</c> used as a single pattern match
+ all files and zero or more directories and subdirectories.</p>
</item>
<tag>[Character1,Character2,...]</tag>
<item>
<p>Matches any of the characters listed. Two characters
- separated by a hyphen will match a range of characters.
- Example: <c>[A-Z]</c> will match any uppercase letter.</p>
+ separated by a hyphen match a range of characters.
+ Example: <c>[A-Z]</c> matches any uppercase letter.</p>
</item>
<tag>{Item,...}</tag>
<item>
@@ -175,49 +185,45 @@
</item>
</taglist>
<p>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").
- </p>
- <p>Note that multiple "*" characters are allowed
- (as in Unix wildcards, but opposed to Windows/DOS wildcards).
- </p>
- <p>Examples:</p>
+ have exactly the same character in the same position match.
+ Matching is case-sensitive, for example, "a" does not match "A".</p>
+ <p>Notice that multiple "*" characters are allowed
+ (as in Unix wildcards, but opposed to Windows/DOS wildcards).</p>
+ <p><em>Examples:</em></p>
<p>The following examples assume that the current directory is the
- top of an Erlang/OTP installation.
- </p>
- <p>To find all <c>.beam</c> files in all applications, the following
- line can be used:</p>
+ top of an Erlang/OTP installation.</p>
+ <p>To find all <c>.beam</c> files in all applications, use the
+ following line:</p>
<code type="none">
- filelib:wildcard("lib/*/ebin/*.beam"). </code>
- <p>To find either <c>.erl</c> or <c>.hrl</c> in all applications
- <c>src</c> directories, the following</p>
+filelib:wildcard("lib/*/ebin/*.beam").</code>
+ <p>To find <c>.erl</c> or <c>.hrl</c> in all applications <c>src</c>
+ directories, use either of the following lines:</p>
<code type="none">
- filelib:wildcard("lib/*/src/*.?rl") </code>
- <p>or the following line</p>
+filelib:wildcard("lib/*/src/*.?rl")</code>
<code type="none">
- filelib:wildcard("lib/*/src/*.{erl,hrl}") </code>
- <p>can be used.</p>
- <p>To find all <c>.hrl</c> files in either <c>src</c> or <c>include</c>
- directories, use:</p>
+filelib:wildcard("lib/*/src/*.{erl,hrl}")</code>
+ <p>To find all <c>.hrl</c> files in <c>src</c> or <c>include</c>
+ directories:</p>
<code type="none">
- filelib:wildcard("lib/*/{src,include}/*.hrl"). </code>
+filelib:wildcard("lib/*/{src,include}/*.hrl").</code>
<p>To find all <c>.erl</c> or <c>.hrl</c> files in either
- <c>src</c> or <c>include</c> directories, use:</p>
+ <c>src</c> or <c>include</c> directories:</p>
<code type="none">
- filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}") </code>
- <p>To find all <c>.erl</c> or <c>.hrl</c> files in any
- subdirectory, use:</p>
+filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")</code>
+ <p>To find all <c>.erl</c> or <c>.hrl</c> files in any subdirectory:</p>
<code type="none">
- filelib:wildcard("lib/**/*.{erl,hrl}") </code>
+filelib:wildcard("lib/**/*.{erl,hrl}")</code>
</desc>
</func>
+
<func>
<name name="wildcard" arity="2"/>
- <fsummary>Match filenames using Unix-style wildcards starting at a specified directory.</fsummary>
+ <fsummary>Match filenames using Unix-style wildcards starting at a
+ specified directory.</fsummary>
<desc>
- <p>The <c>wildcard/2</c> function works like <c>wildcard/1</c>,
- except that instead of the actual working directory, <c><anno>Cwd</anno></c>
- will be used.</p>
+ <p>Same as <seealso marker="#wildcard/1"><c>wildcard/1</c></seealso>,
+ except that <c><anno>Cwd</anno></c> is used instead of the working
+ directory.</p>
</desc>
</func>
</funcs>