From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/kernel/doc/src/packages.xml | 214 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 lib/kernel/doc/src/packages.xml (limited to 'lib/kernel/doc/src/packages.xml') 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 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + packages + Kenneth Lundin + Kenneth Lundin + 1 + Kenneth Lundin + + 2004-09-07 + A + packages.sgml +
+ packages + Packages in Erlang + +

+ 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. +

+

+ 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. +

+ +

Introduction

+

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.

+

The full name of a packaged module is written as e.g. + "fee.fie.foe.foo", + 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 "fee.fie.foe". + A more concrete example is the module erl.lang.term, + which is in the + package erl.lang. + Package names can have any number of segments, as in + erl.lang.list.sort. + The atoms in the name can be quoted, as in foo.'Bar'.baz, + or even the + whole name, as in 'foo.bar.baz' but the concatenation of + atoms and + periods must not contain two consecutive period characters or + end with a period, + as in 'foo..bar', foo.'.bar', or foo.'bar.'. + The periods must not be followed by whitespace.

+

The code loader maps module names onto the file system directory + structure. + E.g., the module erl.lang.term corresponds to a file + .../erl/lang/term.beam + 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 lists + simply map to .../lists.beam, exactly as before.)

+

A packaged module in a file "foo/bar/fred.erl" is declared + as:

+ +-module(foo.bar.fred). +

This can be compiled and loaded from the Erlang shell using + c(fred), if + your current directory is the same as that of the file. + The object file will be named fred.beam.

+

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 ["/usr/lib/erl", "/usr/local/lib/otp/legacy/ebin", "/home/barney/erl"]. + Then, the code for a module named foo.bar.fred will be + searched for + first as "/usr/lib/erl/foo/bar/fred.beam", then + "/usr/local/lib/otp/legacy/ebin/foo/bar/fred.beam" + and lastly "/home/barney/erl/foo/bar/fred.beam". + A module + like lists, which is in the top-level package, + will be looked for as "/usr/lib/erl/lists.beam", + "/usr/local/lib/otp/legacy/ebin/lists.beam" and + "/home/barney/erl/lists.beam".

+

Programming

+

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:

+ +-module(foo.bar.m1). +-export([f/1]). + +f(X) -> m2:g(X). +

m2:g(X) becomes a call to foo.bar.m2 + If this is not what was intended, the call can be written + explicitly, as in

+ +-module(foo.bar.m1). +-export([f/1]). + +f(X) -> fee.fie.foe.m2:g(X). +

Because the called module is given with an explicit package name, + no expansion is done in this case.

+

If a module from another package is used repeatedly in a module, + an import declaration can make life easier:

+ +-module(foo.bar.m1). +-export([f/1, g/1]). +-import(fee.fie.foe.m2). + +f(X) -> m2:g(X). +g(X) -> m2:h(X). +

will make the calls to m2 refer to fee.fie.foe.m2. + More generally, a declaration -import(Package.Module). + will cause calls to Module + to be expanded to Package.Module.

+

Old-style function imports work as normal (but full module + names must be + used); e.g.:

+ +-import(fee.fie.foe.m2, [g/1, h/1]). +

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".

+

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. ".lists", or with an empty initial atom, as in + "''.lists". + 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:

+ +-module(foo.bar.fred). +-export([f/1]). +-import(lists). + +f(X) -> lists:reverse(X). +

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.:

+ +spawn(foo.bar.fred, f, [X]) +

is equivalent to spawn('foo.bar.fred', f, [X]).

+

The Erlang Shell

+

The shell also automatically expands remote calls, + however currently no + expansions are made by default. + The user can change the behaviour by using the import/1 + shell command (or its abbreviation use/1). E.g.:

+ 
+1> import(foo.bar.m).
+ok
+2> m:f().
+

will evaluate foo.bar.m:f(). + 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.)

+

In addition, the shell command import_all/1 + (and its alias use_all/1) + imports all modules currently found in the path for a given + package name. E.g., + assuming the files ".../foo/bar/fred.beam", + ".../foo/bar/barney.beam" + and ".../foo/bar/bambam.beam" can be found from our current + path,

+ 
+1> import_all(foo.bar).
+

will make fred, barney and bambam + expand to foo.bar.fred, + foo.bar.barney and foo.bar.bambam, respectively.

+

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 m:f(...) + could be expanded to foo.bar.m:f(...) + without any warning, instead of the intended + frob.ozz.m:f(...), if + package foo.bar happens to be found first in the path. + Explicitly + declaring each use of a module makes for safe code.

+ + + + no functions exported + x + + + + -- cgit v1.2.3