aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/filename.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/filename.xml')
-rw-r--r--lib/stdlib/doc/src/filename.xml426
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>