packages(3erl)						     Erlang Module Definition						    packages(3erl)

NAME

       packages - Packages in Erlang

DESCRIPTION

   Warning:
       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 main-
       tain 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  consecu-
       tive  period  characters  or  end with a period, as in 'foo..bar' , foo.'.bar' , or foo.'bar.' . The periods must not be followed by white-
       space.

       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 mod-
       ule 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  mod-
       ule	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/bar-
       ney/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 mod-
       ule. 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 declara-
       tion - 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.

EXPORTS

       no functions exported

Ericsson AB							   kernel 2.14.3						    packages(3erl)