diff options
Diffstat (limited to 'lib/stdlib/doc/src/filename.xml')
| -rw-r--r-- | lib/stdlib/doc/src/filename.xml | 426 |
1 files changed, 310 insertions, 116 deletions
diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 1d4ffc10f9..2a413835d0 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,39 +25,55 @@ <title>filename</title> <prepared>Kenneth Lundin</prepared> <docno>1</docno> - <date>97-11-13</date> + <date>1997-11-13</date> <rev>B</rev> </header> <module>filename</module> - <modulesummary>Filename Manipulation Functions</modulesummary> + <modulesummary>Filename manipulation functions.</modulesummary> <description> - <p>The module <c>filename</c> provides a number of useful functions - for analyzing and manipulating file names. These functions are + <p>This module provides functions + for analyzing and manipulating filenames. These functions are designed so that the Erlang code can work on many different - platforms with different formats for file names. With file name - is meant all strings that can be used to denote a file. They can - be short relative names like <c>foo.erl</c>, very long absolute - name which include a drive designator and directory names like + platforms with different filename formats. With filename + is meant all strings that can be used to denote a file. The filename + can be a short relative name like <c>foo.erl</c>, a long absolute + name including a drive designator, a directory name like <c>D:\usr/local\bin\erl/lib\tools\foo.erl</c>, or any variations in between.</p> - <p>In Windows, all functions return file names with forward slashes - only, even if the arguments contain back slashes. Use - <c>join/1</c> to normalize a file name by removing redundant - directory separators.</p> - <p>The module supports raw file names in the way that if a binary is present, or the file name cannot be interpreted according to the return value of - <seealso marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p> - </description> + <p>In Windows, all functions return filenames with forward slashes + only, even if the arguments contain backslashes. To normalize a + filename by removing redundant directory separators, use + <seealso marker="#join/1"><c>join/1</c></seealso>.</p> + + <p>The module supports raw filenames in the way that if a binary is + present, or the filename cannot be interpreted according to the return + value of <seealso marker="kernel:file#native_name_encoding/0"> + <c>file:native_name_encoding/0</c></seealso>, a raw filename is also + returned. For example, <c>join/1</c> provided with a path component + that is a binary (and cannot be interpreted under the current + native filename encoding) results in a raw filename that is returned + (the join operation is performed of course). For more information + about raw filenames, see the + <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + </description> + <datatypes> + <datatype> + <name name="basedir_type"/> + </datatype> + </datatypes> + <funcs> <func> <name name="absname" arity="1"/> - <fsummary>Convert a filename to an absolute name, relative the working directory</fsummary> + <fsummary>Convert a filename to an absolute name, relative the working + directory.</fsummary> <desc> - <p>Converts a relative <c><anno>Filename</anno></c> and returns an absolute - name. No attempt is made to create the shortest absolute name, - because this can give incorrect results on file systems which + <p>Converts a relative <c><anno>Filename</anno></c> and returns an + absolute name. No attempt is made to create the shortest absolute + name, as this can give incorrect results on file systems that allow links.</p> - <p>Unix examples:</p> + <p><em>Unix examples:</em></p> <pre> 1> <input>pwd().</input> "/usr/local" @@ -67,7 +83,7 @@ "/usr/local/../x" 4> <input>filename:absname("/").</input> "/"</pre> - <p>Windows examples:</p> + <p><em>Windows examples:</em></p> <pre> 1> <input>pwd().</input> "D:/usr/local" @@ -79,35 +95,191 @@ "D:/"</pre> </desc> </func> + <func> <name name="absname" arity="2"/> - <fsummary>Convert a filename to an absolute name, relative a specified directory</fsummary> + <fsummary>Convert a filename to an absolute name, relative a specified + directory.</fsummary> <desc> - <p>This function works like <c>absname/1</c>, except that - the directory to which the file name should be made relative - is given explicitly in the <c><anno>Dir</anno></c> argument.</p> + <p>Same as <seealso marker="#absname/1"><c>absname/1</c></seealso>, + except that the directory to which the filename is to be made + relative is specified in argument <c><anno>Dir</anno></c>.</p> </desc> </func> + <func> <name name="absname_join" arity="2"/> - <fsummary>Join an absolute directory with a relative filename</fsummary> + <fsummary>Join an absolute directory with a relative filename.</fsummary> <desc> - <p>Joins an absolute directory with a relative filename. - Similar to <c>join/2</c>, but on platforms with tight - restrictions on raw filename length and no support for - symbolic links (read: VxWorks), leading parent directory - components in <c><anno>Filename</anno></c> are matched against trailing - directory components in <c><anno>Dir</anno></c> so they can be removed - from the result - minimizing its length.</p> + <p>Joins an absolute directory with a relative filename. Similar to + <seealso marker="#join/2"><c>join/2</c></seealso>, but on platforms + with tight restrictions on raw filename length and no support for + symbolic links (read: VxWorks), leading parent directory components + in <c><anno>Filename</anno></c> are matched against trailing + directory components in <c><anno>Dir</anno></c> so they can be + removed from the result - minimizing its length.</p> + </desc> + </func> + + <func> + <name name="basedir" arity="2"/> + <fsummary>Equivalent to <c>basedir(<anno>Type</anno>,<anno>Application</anno>,#{})</c>.</fsummary> + <desc> + <p> + Equivalent to <seealso marker="#basedir-3"> + basedir(<anno>Type</anno>, <anno>Application</anno>, #{})</seealso>. + </p> + </desc> + </func> + <func> + <name name="basedir" arity="3"/> + <fsummary></fsummary> + <desc><marker id="basedir-3"/> + <p> + Returns a suitable path, or paths, for a given type. If + <c>os</c> is not set in <c><anno>Opts</anno></c> the + function will default to the native option, that is + <c>'linux'</c>, <c>'darwin'</c> or <c>'windows'</c>, as + understood by <c>os:type/0</c>. Anything not recognized + as <c>'darwin'</c> or <c>'windows'</c> is interpreted as + <c>'linux'</c>.</p> + <p> + The options <c>'author'</c> and <c>'version'</c> are only used with <c>'windows'</c> option mode. + </p> + <list type="bulleted"> + <item><c>user_cache</c> + <p>The path location is intended for transient data files on a local machine.</p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CACHE_HOME</c>. + </p> + <pre> +1> <input>filename:basedir(user_cache, "my_application", #{os=>linux}).</input> +"/home/otptest/.cache/my_application"</pre> + On Darwin: <pre> +1> <input>filename:basedir(user_cache, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Caches/my_application"</pre> + On Windows: <pre> +1> <input>filename:basedir(user_cache, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Cache" +2> <input>filename:basedir(user_cache, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Cache" +3> <input>filename:basedir(user_cache, "My App", #{author=>"Erlang"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/Cache" +4> <input>filename:basedir(user_cache, "My App", #{version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/My App/1.2/Cache" +5> <input>filename:basedir(user_cache, "My App", #{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Cache"</pre> + </item> + <item><c>user_config</c> + <p> + The path location is intended for persistent configuration files. + </p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CONFIG_HOME</c>. + </p> + <pre> +2> <input>filename:basedir(user_config, "my_application", #{os=>linux}).</input> +"/home/otptest/.config/my_application"</pre> + On Darwin:<pre> +2> <input>filename:basedir(user_config, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Application Support/my_application"</pre> + On Windows:<pre> +1> <input>filename:basedir(user_config, "My App").</input> +"c:/Users/otptest/AppData/Roaming/My App" +2> <input>filename:basedir(user_config, "My App", #{author=>"Erlang", version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Roaming/Erlang/My App/1.2"</pre> + </item> + <item><c>user_data</c> + <p> + The path location is intended for persistent data files. + </p> + <p> + On Linux: + Respects the os environment variable <c>XDG_DATA_HOME</c>. + </p> + <pre> +3> <input>filename:basedir(user_data, "my_application", #{os=>linux}).</input> +"/home/otptest/.local/my_application"</pre> + On Darwin:<pre> +3> <input>filename:basedir(user_data, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Application Support/my_application"</pre> + On Windows:<pre> +8> <input>filename:basedir(user_data, "My App").</input> +"c:/Users/otptest/AppData/Local/My App" +9> <input>filename:basedir(user_data, "My App",#{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2"</pre> + </item> + <item><c>user_log</c> + <p>The path location is intended for transient log files on a local machine.</p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CACHE_HOME</c>.</p> + <pre> +4> <input>filename:basedir(user_log, "my_application", #{os=>linux}).</input> +"/home/otptest/.cache/my_application/log"</pre> + On Darwin:<pre> +4> <input>filename:basedir(user_log, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Caches/my_application"</pre> + On Windows:<pre> +12> <input>filename:basedir(user_log, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Logs" +13> <input>filename:basedir(user_log, "My App",#{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Logs"</pre> + </item> + <item><c>site_config</c><p> + On Linux: + Respects the os environment variable <c>XDG_CONFIG_DIRS</c>.</p> +<pre> +5> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/local/share/my_application", + "/usr/share/my_application"] +6> <input>os:getenv("XDG_CONFIG_DIRS").</input> +"/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg" +7> <input>filename:basedir(site_config, "my_application", #{os=>linux}).</input> +["/etc/xdg/xdg-ubuntu/my_application", + "/usr/share/upstart/xdg/my_application", + "/etc/xdg/my_application"] +8> <input>os:unsetenv("XDG_CONFIG_DIRS").</input> +true +9> <input>filename:basedir(site_config, "my_application", #{os=>linux}).</input> +["/etc/xdg/my_application"]</pre> + On Darwin:<pre> +5> <input>filename:basedir(site_config, "my_application", #{os=>darwin}).</input> +["/Library/Application Support/my_application"]</pre> + </item> + <item><c>site_data</c><p> + On Linux: + Respects the os environment variable <c>XDG_DATA_DIRS</c>.</p> + <pre> +10> <input>os:getenv("XDG_DATA_DIRS").</input> +"/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/" +11> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/share/ubuntu/my_application", + "/usr/share/gnome/my_application", + "/usr/local/share/my_application", + "/usr/share/my_application"] +12> <input>os:unsetenv("XDG_DATA_DIRS").</input> +true +13> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/local/share/my_application", + "/usr/share/my_application"]</pre> + On Darwin:<pre> +5> <input>filename:basedir(site_data, "my_application", #{os=>darwin}).</input> +["/Library/Application Support/my_application"]</pre> + </item> + </list> </desc> </func> <func> <name name="basename" arity="1"/> - <fsummary>Return the last component of a filename</fsummary> + <fsummary>Return the last component of a filename.</fsummary> <desc> <p>Returns the last component of <c><anno>Filename</anno></c>, or - <c><anno>Filename</anno></c> itself if it does not contain any directory - separators.</p> + <c><anno>Filename</anno></c> itself if it does not contain any + directory separators.</p> + <p><em>Examples:</em></p> <pre> 5> <input>filename:basename("foo").</input> "foo" @@ -117,15 +289,18 @@ []</pre> </desc> </func> + <func> <name name="basename" arity="2"/> - <fsummary>Return the last component of a filename, stripped of the specified extension</fsummary> + <fsummary>Return the last component of a filename, stripped of the + specified extension.</fsummary> <desc> - <p>Returns the last component of <c><anno>Filename</anno></c> with the - extension <c><anno>Ext</anno></c> stripped. This function should be used - to remove a specific extension which might, or might not, be - there. Use <c>rootname(basename(Filename))</c> to remove an - extension that exists, but you are not sure which one it is.</p> + <p>Returns the last component of <c><anno>Filename</anno></c> with + extension <c><anno>Ext</anno></c> stripped. This function is to be + used to remove a (possible) specific extension. To remove an + existing extension when you are unsure which one it is, use + <c>rootname(basename(Filename))</c>.</p> + <p><em>Examples:</em></p> <pre> 8> <input>filename:basename("~/src/kalle.erl", ".erl").</input> "kalle" @@ -139,27 +314,32 @@ "kalle"</pre> </desc> </func> + <func> <name name="dirname" arity="1"/> - <fsummary>Return the directory part of a path name</fsummary> + <fsummary>Return the directory part of a path name.</fsummary> <desc> <p>Returns the directory part of <c><anno>Filename</anno></c>.</p> + <p><em>Examples:</em></p> <pre> 13> <input>filename:dirname("/usr/src/kalle.erl").</input> "/usr/src" 14> <input>filename:dirname("kalle.erl").</input> -"." - +"."</pre> + <pre> 5> <input>filename:dirname("\\usr\\src/kalle.erl").</input> % Windows "/usr/src"</pre> </desc> </func> + <func> <name name="extension" arity="1"/> - <fsummary>Return the file extension</fsummary> + <fsummary>Return the file extension.</fsummary> <desc> - <p>Returns the file extension of <c><anno>Filename</anno></c>, including - the period. Returns an empty string if there is no extension.</p> + <p>Returns the file extension of <c><anno>Filename</anno></c>, + including the period. Returns an empty string if no extension + exists.</p> + <p><em>Examples:</em></p> <pre> 15> <input>filename:extension("foo.erl").</input> ".erl" @@ -167,69 +347,123 @@ []</pre> </desc> </func> + + <func> + <name name="find_src" arity="1"/> + <name name="find_src" arity="2"/> + <fsummary>Find the filename and compiler options for a module.</fsummary> + <desc> + <p>Finds the source filename and compiler options for a module. + The result can be fed to <seealso marker="compiler:compile#file/2"> + <c>compile:file/2</c></seealso> to compile the file again.</p> + <warning><p>It is not recommended to use this function. If possible, + use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso> + module to extract the abstract code format from the Beam file and + compile that instead.</p></warning> + <p>Argument <c><anno>Beam</anno></c>, which can be a string or an atom, + specifies either the module name or the path to the source + code, with or without extension <c>".erl"</c>. In either + case, the module must be known by the code server, that is, + <c>code:which(<anno>Module</anno>)</c> must succeed.</p> + <p><c><anno>Rules</anno></c> describes how the source directory can be + found when the object code directory is known. It is a list of + tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and + is interpreted as follows: if the end of the directory name where the + object is located matches <c><anno>BinSuffix</anno></c>, then the + source code directory has the same name, but with + <c><anno>BinSuffix</anno></c> replaced by + <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults + to:</p> + <code type="none"> +[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code> + <p>If the source file is found in the resulting directory, the function + returns that location together with <c><anno>Options</anno></c>. + Otherwise the next rule is tried, and so on.</p> + <p>The function returns <c>{<anno>SourceFile</anno>, + <anno>Options</anno>}</c> if it succeeds. + <c><anno>SourceFile</anno></c> is the absolute path to the source + file without extension <c>".erl"</c>. <c><anno>Options</anno></c> + includes the options that are necessary to recompile the file with + <c>compile:file/2</c>, but excludes options such as <c>report</c> + and <c>verbose</c>, which do not change the way code is generated. + The paths in options <c>{outdir, <anno>Path</anno>}</c> and + <c>{i, Path}</c> are guaranteed to be absolute.</p> + </desc> + </func> + <func> <name name="flatten" arity="1"/> - <fsummary>Convert a filename to a flat string</fsummary> + <fsummary>Convert a filename to a flat string.</fsummary> <desc> <p>Converts a possibly deep list filename consisting of characters and atoms into the corresponding flat string filename.</p> </desc> </func> + <func> <name name="join" arity="1"/> - <fsummary>Join a list of filename components with directory separators</fsummary> + <fsummary>Join a list of filename components with directory separators. + </fsummary> <desc> - <p>Joins a list of file name <c><anno>Components</anno></c> with directory - separators. If one of the elements of <c><anno>Components</anno></c> - includes an absolute path, for example <c>"/xxx"</c>, + <p>Joins a list of filename <c><anno>Components</anno></c> with + directory separators. + If one of the elements of <c><anno>Components</anno></c> + includes an absolute path, such as <c>"/xxx"</c>, the preceding elements, if any, are removed from the result.</p> <p>The result is "normalized":</p> <list type="bulleted"> <item>Redundant directory separators are removed.</item> <item>In Windows, all directory separators are forward - slashes and the drive letter is in lower case.</item> + slashes and the drive letter is in lower case.</item> </list> + <p><em>Examples:</em></p> <pre> 17> <input>filename:join(["/usr", "local", "bin"]).</input> "/usr/local/bin" 18> <input>filename:join(["a/b///c/"]).</input> -"a/b/c" - +"a/b/c"</pre> + <pre> 6> <input>filename:join(["B:a\\b///c/"]).</input> % Windows "b:a/b/c"</pre> </desc> </func> + <func> <name name="join" arity="2"/> - <fsummary>Join two filename components with directory separators</fsummary> + <fsummary>Join two filename components with directory separators. + </fsummary> <desc> - <p>Joins two file name components with directory separators. - Equivalent to <c>join([<anno>Name1</anno>, <anno>Name2</anno>])</c>.</p> + <p>Joins two filename components with directory separators. + Equivalent to <c>join([<anno>Name1</anno>, <anno>Name2</anno>])</c>. + </p> </desc> </func> + <func> <name name="nativename" arity="1"/> - <fsummary>Return the native form of a file path</fsummary> + <fsummary>Return the native form of a file path.</fsummary> <desc> - <p>Converts <c><anno>Path</anno></c> to a form accepted by the command shell - and native applications on the current platform. On Windows, + <p>Converts <c><anno>Path</anno></c> to a form accepted by the command + shell and native applications on the current platform. On Windows, forward slashes are converted to backward slashes. On all - platforms, the name is normalized as done by <c>join/1</c>.</p> + platforms, the name is normalized as done by + <seealso marker="#join/1"><c>join/1</c></seealso>.</p> + <p><em>Examples:</em></p> <pre> 19> <input>filename:nativename("/usr/local/bin/").</input> % Unix -"/usr/local/bin" - +"/usr/local/bin"</pre> + <pre> 7> <input>filename:nativename("/usr/local/bin/").</input> % Windows "\\usr\\local\\bin"</pre> </desc> </func> + <func> <name name="pathtype" arity="1"/> - <fsummary>Return the type of a path</fsummary> + <fsummary>Return the path type.</fsummary> <desc> - <p>Returns the type of path, one of <c>absolute</c>, - <c>relative</c>, or <c>volumerelative</c>.</p> + <p>Returns the path type, which is one of the following:</p> <taglist> <tag><c>absolute</c></tag> <item> @@ -254,14 +488,16 @@ </taglist> </desc> </func> + <func> <name name="rootname" arity="1"/> <name name="rootname" arity="2"/> - <fsummary>Remove a filename extension</fsummary> + <fsummary>Remove a filename extension.</fsummary> <desc> - <p>Remove a filename extension. <c>rootname/2</c> works as + <p>Removes a filename extension. <c>rootname/2</c> works as <c>rootname/1</c>, except that the extension is removed only if it is <c><anno>Ext</anno></c>.</p> + <p><em>Examples:</em></p> <pre> 20> <input>filename:rootname("/beam.src/kalle").</input> /beam.src/kalle" @@ -273,12 +509,14 @@ "/beam.src/foo.beam"</pre> </desc> </func> + <func> <name name="split" arity="1"/> - <fsummary>Split a filename into its path components</fsummary> + <fsummary>Split a filename into its path components.</fsummary> <desc> <p>Returns a list whose elements are the path components of <c><anno>Filename</anno></c>.</p> + <p><em>Examples:</em></p> <pre> 24> <input>filename:split("/usr/local/bin").</input> ["/","usr","local","bin"] @@ -288,50 +526,6 @@ ["a:/","msdev","include"]</pre> </desc> </func> - <func> - <name name="find_src" arity="1"/> - <name name="find_src" arity="2"/> - <fsummary>Find the filename and compiler options for a module</fsummary> - <desc> - <p>Finds the source filename and compiler options for a module. - The result can be fed to <c>compile:file/2</c> in order to - compile the file again.</p> - - <warning><p>We don't recommend using this function. If possible, - use <seealso marker="beam_lib">beam_lib(3)</seealso> to extract - the abstract code format from the BEAM file and compile that - instead.</p></warning> - - <p>The <c><anno>Beam</anno></c> argument, which can be a string or an atom, - specifies either the module name or the path to the source - code, with or without the <c>".erl"</c> extension. In either - case, the module must be known by the code server, i.e. - <c>code:which(<anno>Module</anno>)</c> must succeed.</p> - <p><c><anno>Rules</anno></c> describes how the source directory can be found, - when the object code directory is known. It is a list of - tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and is interpreted - as follows: If the end of the directory name where the object - is located matches <c><anno>BinSuffix</anno></c>, then the source code - directory has the same name, but with <c><anno>BinSuffix</anno></c> - replaced by <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults to:</p> - <code type="none"> -[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code> - <p>If the source file is found in the resulting directory, then - the function returns that location together with - <c><anno>Options</anno></c>. Otherwise, the next rule is tried, and so on.</p> - - <p>The function returns <c>{<anno>SourceFile</anno>, <anno>Options</anno>}</c> if it succeeds. - <c><anno>SourceFile</anno></c> is the absolute path to the source file - without the <c>".erl"</c> extension. <c><anno>Options</anno></c> include - the options which are necessary to recompile the file with - <c>compile:file/2</c>, but excludes options such as - <c>report</c> or <c>verbose</c> which do not change the way - code is generated. The paths in the <c>{outdir, <anno>Path</anno>}</c> - and <c>{i, Path}</c> options are guaranteed to be - absolute.</p> - - </desc> - </func> </funcs> </erlref> |