diff options
Diffstat (limited to 'lib/stdlib/doc/src/filelib.xml')
| -rw-r--r-- | lib/stdlib/doc/src/filelib.xml | 186 |
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 > 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> |