From 483803d8b80eac291864aa0cc894b4e6405076ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 16 Jan 2013 15:43:20 +0100 Subject: Remove documentation about packages --- lib/kernel/doc/src/packages.xml | 208 ---------------------------------------- lib/kernel/doc/src/ref_man.xml | 1 - 2 files changed, 209 deletions(-) delete mode 100644 lib/kernel/doc/src/packages.xml (limited to 'lib/kernel') diff --git a/lib/kernel/doc/src/packages.xml b/lib/kernel/doc/src/packages.xml deleted file mode 100644 index 8a82b91a90..0000000000 --- a/lib/kernel/doc/src/packages.xml +++ /dev/null @@ -1,208 +0,0 @@ - - - - -
- - 20042012 - 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.

- - - diff --git a/lib/kernel/doc/src/ref_man.xml b/lib/kernel/doc/src/ref_man.xml index 9ef0959271..67d91ba585 100644 --- a/lib/kernel/doc/src/ref_man.xml +++ b/lib/kernel/doc/src/ref_man.xml @@ -64,6 +64,5 @@ - -- cgit v1.2.3