aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/filename.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/stdlib/doc/src/filename.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/stdlib/doc/src/filename.xml')
-rw-r--r--lib/stdlib/doc/src/filename.xml385
1 files changed, 385 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml
new file mode 100644
index 0000000000..3a6c5e0b60
--- /dev/null
+++ b/lib/stdlib/doc/src/filename.xml
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>filename</title>
+ <prepared>Kenneth Lundin</prepared>
+ <docno>1</docno>
+ <date>97-11-13</date>
+ <rev>B</rev>
+ </header>
+ <module>filename</module>
+ <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
+ 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
+ <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>
+ </description>
+
+ <section>
+ <title>DATA TYPES</title>
+ <code type="none">
+name() = string() | atom() | DeepList
+ DeepList = [char() | atom() | DeepList]</code>
+ </section>
+ <funcs>
+ <func>
+ <name>absname(Filename) -> string()</name>
+ <fsummary>Convert a filename to an absolute name, relative the working directory</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ </type>
+ <desc>
+ <p>Converts a relative <c>Filename</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
+ allow links.</p>
+ <p>Unix examples:</p>
+ <pre>
+1> <input>pwd().</input>
+"/usr/local"
+2> <input>filename:absname("foo").</input>
+"/usr/local/foo"
+3> <input>filename:absname("../x").</input>
+"/usr/local/../x"
+4> <input>filename:absname("/").</input>
+"/"</pre>
+ <p>Windows examples:</p>
+ <pre>
+1> <input>pwd().</input>
+"D:/usr/local"
+2> <input>filename:absname("foo").</input>
+"D:/usr/local/foo"
+3> <input>filename:absname("../x").</input>
+"D:/usr/local/../x"
+4> <input>filename:absname("/").</input>
+"D:/"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>absname(Filename, Dir) -> string()</name>
+ <fsummary>Convert a filename to an absolute name, relative a specified directory</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ <v>Dir = string()</v>
+ </type>
+ <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>Dir</c> argument.</p>
+ </desc>
+ </func>
+ <func>
+ <name>absname_join(Dir, Filename) -> string()</name>
+ <fsummary>Join an absolute directory with a relative filename</fsummary>
+ <type>
+ <v>Dir = string()</v>
+ <v>Filename = name()</v>
+ </type>
+ <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>Filename</c> are matched against trailing
+ directory components in <c>Dir</c> so they can be removed
+ from the result - minimizing its length.</p>
+ </desc>
+ </func>
+ <func>
+ <name>basename(Filename) -> string()</name>
+ <fsummary>Return the last component of a filename</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ </type>
+ <desc>
+ <p>Returns the last component of <c>Filename</c>, or
+ <c>Filename</c> itself if it does not contain any directory
+ separators.</p>
+ <pre>
+5> <input>filename:basename("foo").</input>
+"foo"
+6> <input>filename:basename("/usr/foo").</input>
+"foo"
+7> <input>filename:basename("/").</input>
+[]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>basename(Filename, Ext) -> string()</name>
+ <fsummary>Return the last component of a filename, stripped of the specified extension</fsummary>
+ <type>
+ <v>Filename = Ext = name()</v>
+ </type>
+ <desc>
+ <p>Returns the last component of <c>Filename</c> with the
+ extension <c>Ext</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>
+ <pre>
+8> <input>filename:basename("~/src/kalle.erl", ".erl").</input>
+"kalle"
+9> <input>filename:basename("~/src/kalle.beam", ".erl").</input>
+"kalle.beam"
+10> <input>filename:basename("~/src/kalle.old.erl", ".erl").</input>
+"kalle.old"
+11> <input>filename:rootname(filename:basename("~/src/kalle.erl")).</input>
+"kalle"
+12> <input>filename:rootname(filename:basename("~/src/kalle.beam")).</input>
+"kalle"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>dirname(Filename) -> string()</name>
+ <fsummary>Return the directory part of a path name</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ </type>
+ <desc>
+ <p>Returns the directory part of <c>Filename</c>.</p>
+ <pre>
+13> <input>filename:dirname("/usr/src/kalle.erl").</input>
+"/usr/src"
+14> <input>filename:dirname("kalle.erl").</input>
+"."
+
+5> <input>filename:dirname("\\\\usr\\\\src/kalle.erl").</input> % Windows
+"/usr/src"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>extension(Filename) -> string()</name>
+ <fsummary>Return the file extension</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ </type>
+ <desc>
+ <p>Returns the file extension of <c>Filename</c>, including
+ the period. Returns an empty string if there is no extension.</p>
+ <pre>
+15> <input>filename:extension("foo.erl").</input>
+".erl"
+16> <input>filename:extension("beam.src/kalle").</input>
+[]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>flatten(Filename) -> string()</name>
+ <fsummary>Convert a filename to a flat string</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ </type>
+ <desc>
+ <p>Converts a possibly deep list filename consisting of
+ characters and atoms into the corresponding flat string
+ filename.</p>
+ </desc>
+ </func>
+ <func>
+ <name>join(Components) -> string()</name>
+ <fsummary>Join a list of filename components with directory separators</fsummary>
+ <type>
+ <v>Components = [string()]</v>
+ </type>
+ <desc>
+ <p>Joins a list of file name <c>Components</c> with directory
+ separators. If one of the elements of <c>Components</c>
+ includes an absolute path, for example <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>
+ </list>
+ <pre>
+17> <input>filename:join(["/usr", "local", "bin"]).</input>
+"/usr/local/bin"
+18> <input>filename:join(["a/b///c/"]).</input>
+"a/b/c"
+
+6> <input>filename:join(["B:a\\\\b///c/"]).</input> % Windows
+"b:a/b/c"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>join(Name1, Name2) -> string()</name>
+ <fsummary>Join two filename components with directory separators</fsummary>
+ <type>
+ <v>Name1 = Name2 = string()</v>
+ </type>
+ <desc>
+ <p>Joins two file name components with directory separators.
+ Equivalent to <c>join([Name1, Name2])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>nativename(Path) -> string()</name>
+ <fsummary>Return the native form of a file path</fsummary>
+ <type>
+ <v>Path = string()</v>
+ </type>
+ <desc>
+ <p>Converts <c>Path</c> to a form accepted by the command shell
+ and native applications on the current platform. On Windows,
+ forward slashes is converted to backward slashes. On all
+ platforms, the name is normalized as done by <c>join/1</c>.</p>
+ <pre>
+19> <input>filename:nativename("/usr/local/bin/").</input> % Unix
+"/usr/local/bin"
+
+7> <input>filename:nativename("/usr/local/bin/").</input> % Windows
+"\\\\usr\\\\local\\\\bin"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>pathtype(Path) -> absolute | relative | volumerelative</name>
+ <fsummary>Return the type of a path</fsummary>
+ <desc>
+ <p>Returns the type of path, one of <c>absolute</c>,
+ <c>relative</c>, or <c>volumerelative</c>.</p>
+ <taglist>
+ <tag><c>absolute</c></tag>
+ <item>
+ <p>The path name refers to a specific file on a specific
+ volume.</p>
+ <p>Unix example: <c>/usr/local/bin</c></p>
+ <p>Windows example: <c>D:/usr/local/bin</c></p>
+ </item>
+ <tag><c>relative</c></tag>
+ <item>
+ <p>The path name is relative to the current working
+ directory on the current volume.</p>
+ <p>Example: <c>foo/bar, ../src</c></p>
+ </item>
+ <tag><c>volumerelative</c></tag>
+ <item>
+ <p>The path name is relative to the current working
+ directory on a specified volume, or it is a specific file
+ on the current working volume.</p>
+ <p>Windows example: <c>D:bar.erl, /bar/foo.erl</c></p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>rootname(Filename) -> string()</name>
+ <name>rootname(Filename, Ext) -> string()</name>
+ <fsummary>Remove a filename extension</fsummary>
+ <type>
+ <v>Filename = Ext = name()</v>
+ </type>
+ <desc>
+ <p>Remove a filename extension. <c>rootname/2</c> works as
+ <c>rootname/1</c>, except that the extension is removed only
+ if it is <c>Ext</c>.</p>
+ <pre>
+20> <input>filename:rootname("/beam.src/kalle").</input>
+/beam.src/kalle"
+21> <input>filename:rootname("/beam.src/foo.erl").</input>
+"/beam.src/foo"
+22> <input>filename:rootname("/beam.src/foo.erl", ".erl").</input>
+"/beam.src/foo"
+23> <input>filename:rootname("/beam.src/foo.beam", ".erl").</input>
+"/beam.src/foo.beam"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>split(Filename) -> Components</name>
+ <fsummary>Split a filename into its path components</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ <v>Components = [string()]</v>
+ </type>
+ <desc>
+ <p>Returns a list whose elements are the path components of
+ <c>Filename</c>.</p>
+ <pre>
+24> <input>filename:split("/usr/local/bin").</input>
+["/","usr","local","bin"]
+25> <input>filename:split("foo/bar").</input>
+["foo","bar"]
+26> <input>filename:split("a:\\\\msdev\\\\include").</input>
+["a:/","msdev","include"]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>find_src(Beam) -> {SourceFile, Options} | {error,{ErrorReason,Module}}</name>
+ <name>find_src(Beam, Rules) -> {SourceFile, Options} | {error,{ErrorReason,Module}}</name>
+ <fsummary>Find the filename and compiler options for a module</fsummary>
+ <type>
+ <v>Beam = Module | Filename</v>
+ <v>&nbsp;Module = atom()</v>
+ <v>&nbsp;Filename = string() | atom()</v>
+ <v>SourceFile = string()</v>
+ <v>Options = [Opt]</v>
+ <v>&nbsp;Opt = {i, string()} | {outdir, string()} | {d, atom()}</v>
+ <v>ErrorReason = non_existing | preloaded | interpreted</v>
+ </type>
+ <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>
+ <p>The <c>Beam</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(Module)</c> must succeed.</p>
+ <p><c>Rules</c> describes how the source directory can be found,
+ when the object code directory is known. It is a list of
+ tuples <c>{BinSuffix, SourceSuffix}</c> and is interpreted
+ as follows: If the end of the directory name where the object
+ is located matches <c>BinSuffix</c>, then the source code
+ directory has the same name, but with <c>BinSuffix</c>
+ replaced by <c>SourceSuffix</c>. <c>Rules</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>Options</c>. Otherwise, the next rule is tried, and so on.</p>
+
+ <p>The function returns <c>{SourceFile, Options}</c> if it succeeds.
+ <c>SourceFile</c> is the absolute path to the source file
+ without the <c>".erl"</c> extension. <c>Options</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, Path}</c>
+ and <c>{i, Path}</c> options are guaranteed to be
+ absolute.</p>
+
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+