The R13B03 release.OTP_R13B03

1 files changed, 214 insertions, 0 deletions

diff --git a/lib/kernel/doc/src/packages.xml b/lib/kernel/doc/src/packages.xml
new file mode 100644
index 0000000000..80de2e05fc
--- /dev/null
+++ b/lib/kernel/doc/src/packages.xml
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2004</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>packages</title>
+    <prepared>Kenneth Lundin</prepared>
+    <responsible>Kenneth Lundin</responsible>
+    <docno>1</docno>
+    <approved>Kenneth Lundin</approved>
+    <checked></checked>
+    <date>2004-09-07</date>
+    <rev>A</rev>
+    <file>packages.sgml</file>
+  </header>
+  <module>packages</module>
+  <modulesummary>Packages in Erlang</modulesummary>
+  <description>
+    <warning><p>
+      Packages has since it was introduced more than 5 years ago been an 
+      experimental feature. Use it at your own risk, we do not
+      actively maintain and develop this feature. It might however be 
+      supported some 
+      day.
+      </p>
+      <p>
+	In spite of this packages work quite well, but there are some 
+	known issues in tools and other parts where packages don't work well.
+    </p>
+    </warning>
+    <p><em>Introduction</em></p>
+    <p>Packages are simply namespaces for modules. 
+      All old Erlang modules automatically belong to the top level 
+      ("empty-string") namespace, and do not need any changes.</p>
+    <p>The full name of a packaged module is written as e.g. 
+      "<c>fee.fie.foe.foo</c>",
+      i.e., as atoms separated by periods, 
+      where the package name is the part up to
+      but not including the last period; 
+      in this case "<c>fee.fie.foe</c>".
+      A more concrete example is the module <c>erl.lang.term</c>, 
+      which is in the
+      package <c>erl.lang</c>. 
+      Package names can have any number of segments, as in 
+      <c>erl.lang.list.sort</c>.
+      The atoms in the name can be quoted, as in <c>foo.'Bar'.baz</c>, 
+      or even the
+      whole name, as in <c>'foo.bar.baz'</c> but the concatenation of 
+      atoms and
+      periods must not contain two consecutive period characters or 
+      end with a period,
+      as in <c>'foo..bar'</c>, <c>foo.'.bar'</c>, or <c>foo.'bar.'</c>. 
+      The periods must not be followed by whitespace.</p>
+    <p>The code loader maps module names onto the file system directory 
+      structure.
+      E.g., the module <c>erl.lang.term</c> corresponds to a file 
+      <c>.../erl/lang/term.beam</c>
+      in the search path. 
+      Note that the name of the actual object file corresponds to
+      the last part only of the full module name. 
+      (Thus, old existing modules such as <c>lists</c>
+      simply map to <c>.../lists.beam</c>, exactly as before.)</p>
+    <p>A packaged module in a file "<c>foo/bar/fred.erl</c>" is declared
+      as:</p>
+    <code type="none">
+-module(foo.bar.fred).</code>
+    <p>This can be compiled and loaded from the Erlang shell using 
+      <c>c(fred)</c>, if
+      your current directory is the same as that of the file. 
+      The object file will be named <c>fred.beam</c>.</p>
+    <p>The Erlang search path works exactly as before, 
+      except that the package segments will be appended to each 
+      directory in the path in order to find the
+      file. E.g., assume the path is <c>["/usr/lib/erl", "/usr/local/lib/otp/legacy/ebin", "/home/barney/erl"]</c>.
+      Then, the code for a module named <c>foo.bar.fred</c> will be 
+      searched for
+      first as <c>"/usr/lib/erl/foo/bar/fred.beam"</c>, then 
+      <c>"/usr/local/lib/otp/legacy/ebin/foo/bar/fred.beam"</c>
+      and lastly <c>"/home/barney/erl/foo/bar/fred.beam"</c>. 
+      A module
+      like <c>lists</c>, which is in the top-level package, 
+      will be looked for as <c>"/usr/lib/erl/lists.beam"</c>,
+      <c>"/usr/local/lib/otp/legacy/ebin/lists.beam"</c> and 
+      <c>"/home/barney/erl/lists.beam"</c>.</p>
+    <p><em>Programming</em></p>
+    <p>Normally, if a call is made from one module to another, 
+      it is assumed that the
+      called module belongs to the same package as the source module. 
+      The compiler
+      automatically expands such calls. E.g., in:</p>
+    <code type="none">
+-module(foo.bar.m1).
+-export([f/1]).
+
+f(X) -> m2:g(X).</code>
+    <p><c>m2:g(X)</c> becomes a call to <c>foo.bar.m2</c>
+      If this is not what was intended, the call can be written 
+      explicitly, as in</p>
+    <code type="none">
+-module(foo.bar.m1).
+-export([f/1]).
+
+f(X) -> fee.fie.foe.m2:g(X).</code>
+    <p>Because the called module is given with an explicit package name, 
+      no expansion is done in this case.</p>
+    <p>If a module from another package is used repeatedly in a module, 
+      an import declaration can make life easier:</p>
+    <code type="none">
+-module(foo.bar.m1).
+-export([f/1, g/1]).
+-import(fee.fie.foe.m2).
+
+f(X) -> m2:g(X).
+g(X) -> m2:h(X).</code>
+    <p>will make the calls to <c>m2</c> refer to <c>fee.fie.foe.m2</c>. 
+      More generally, a declaration <c>-import(Package.Module).</c> 
+      will cause calls to <c>Module</c>
+      to be expanded to <c>Package.Module</c>.</p>
+    <p>Old-style function imports work as normal (but full module 
+      names must be
+      used); e.g.:</p>
+    <code type="none">
+-import(fee.fie.foe.m2, [g/1, h/1]).</code>
+    <p>however, it is probably better to avoid this form of import 
+      altogether in new
+      code, since it makes it hard to see what calls are really "remote".</p>
+    <p>If it is necessary to call a module in the top-level package 
+      from within a
+      named package, the module name can be written either with an 
+      initial period as
+      in e.g. "<c>.lists</c>", or with an empty initial atom, as in 
+      "<c>''.lists</c>".
+      However, the best way is to use an import declaration - 
+      this is most obvious to
+      the eye, and makes sure we don't forget adding a period somewhere:</p>
+    <code type="none">
+-module(foo.bar.fred).
+-export([f/1]).
+-import(lists).
+
+f(X) -> lists:reverse(X).</code>
+    <p>The dot-syntax for module names can be used in any expression. 
+      All segments must
+      be constant atoms, and the result must be a well-formed 
+      package/module name.
+      E.g.:</p>
+    <code type="none">
+spawn(foo.bar.fred, f, [X])</code>
+    <p>is equivalent to <c>spawn('foo.bar.fred', f, [X])</c>.</p>
+    <p><em>The Erlang Shell</em></p>
+    <p>The shell also automatically expands remote calls, 
+      however currently no
+      expansions are made by default. 
+      The user can change the behaviour by using the <c>import/1</c>
+      shell command (or its abbreviation <c>use/1</c>). E.g.:</p>
+    <pre>
+1> <input>import(foo.bar.m).</input>
+ok
+2> <input>m:f().</input></pre>
+    <p>will evaluate <c>foo.bar.m:f()</c>. 
+      If a new import is made of the same name,
+      this overrides any previous import. 
+      (It is likely that in the future, some
+      system packages will be pre-imported.)</p>
+    <p>In addition, the shell command <c>import_all/1</c> 
+      (and its alias <c>use_all/1</c>)
+      imports all modules currently found in the path for a given 
+      package name. E.g.,
+      assuming the files "<c>.../foo/bar/fred.beam</c>", 
+      "<c>.../foo/bar/barney.beam</c>"
+      and "<c>.../foo/bar/bambam.beam</c>" can be found from our current
+      path,</p>
+    <pre>
+1> <input>import_all(foo.bar).</input></pre>
+    <p>will make <c>fred</c>, <c>barney</c> and <c>bambam</c> 
+      expand to <c>foo.bar.fred</c>,
+      <c>foo.bar.barney</c> and <c>foo.bar.bambam</c>, respectively.</p>
+    <p>Note: The compiler does not have an "import all" directive, for the
+      reason that Erlang has no compile time type checking. 
+      E.g. if the wrong search
+      path is used at compile time, a call <c>m:f(...)</c> 
+      could be expanded to <c>foo.bar.m:f(...)</c>
+      without any warning, instead of the intended 
+      <c>frob.ozz.m:f(...)</c>, if
+      package <c>foo.bar</c> happens to be found first in the path. 
+      Explicitly
+      declaring each use of a module makes for safe code.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>no functions exported</name>
+      <fsummary>x</fsummary>
+    </func>
+  </funcs>
+</erlref>
+