=head1 NAME

package - module support (standard library)

=head1 OVERVIEW

The package library provides basic facilities for loading and building
modules in Lua.  It exports two of its functions directly in the
global environment: L</require> and L</module>.  Everything else is
exported in a table C<package>.

=head2 C<module>

  module (name [, ...])

Creates a module.  If there is a table in C<package.loaded[name]>,
this table is the module.  Otherwise, if there is a global table C<t>
with the given name, this table is the module.  Otherwise creates a
new table C<t> and sets it as the value of the global C<name> and the
value of L</package.loaded>C<[name]>.  This function also initializes
C<t._NAME> with the given name, C<t._M> with the module (C<t> itself),
and C<t._PACKAGE> with the package name (the full module name minus
last component; see below).  Finally, L</module> sets C<t> as the new
environment of the current function and the new value of
L</package.loaded>C<[name]>, so that L</require> returns C<t>.

If C<name> is a compound name (that is, one with components separated
by dots), L</module> creates (or reuses, if they already exist) tables
for each component.  For instance, if C<name> is C<a.b.c>, then
L</module> stores the module table in field C<c> of field C<b> of
global C<a>.

This function may receive optional I<options> after the module name,
where each option is a function to be applied over the module.

=head2 C<require>

  require (modname)

Loads the given module.  The function starts by looking into the table
L</package.loaded> to determine whether C<modname> is already loaded.
If it is, then C<require> returns the value stored at
L</package.loaded>C<[modname]>.  Otherwise, it tries to find a I<loader>
for the module.

To find a loader, first L</require> queries
L</package.preload>C<[modname]>.  If it has a value, this value (which
should be a function) is the loader.  Otherwise L</require> searches
for a Lua loader using the path stored in L</package.path>.  If that
also fails, it searches for a C loader using the path stored in
L</package.cpath>.  If that also fails, it tries an I<all-in-one>
loader (see below).

When loading a C library, L</require> first uses a dynamic link
facility to link the application with the library.  Then it tries to
find a C function inside this library to be used as the loader.  The
name of this C function is the string "C<luaopen_>" concatenated with
a copy of the module name where each dot is replaced by an underscore.
Moreover, if the module name has a hyphen, its prefix up to (and
including) the first hyphen is removed.  For instance, if the module
name is C<a.v1-b.c>, the function name will be C<luaopen_b_c>.

If L</require> finds neither a Lua library nor a C library for a
module, it calls the I<all-in-one loader>.  This loader searches the C
path for a library for the root name of the given module.  For
instance, when requiring C<a.b.c>, it will search for a C library for
C<a>.  If found, it looks into it for an open function for the
submodule; in our example, that would be C<luaopen_a_b_c>.  With this
facility, a package can pack several C submodules into one single
library, with each submodule keeping its original open function.

Once a loader is found, L</require> calls the loader with a single
argument, C<modname>.  If the loader returns any value, C<require>
assigns it to L</package.loaded>C<[modname]>.  If the loader returns no
value and has not assigned any value to L</package.loaded>C<[modname]>,
then L</require> assigns C<true> to this entry.  In any case,
L</require> returns the final value of C<package.loaded[modname]>.

If there is any error loading or running the module, or if it cannot
find any loader for the module, then L</require> signals an error.

=head2 C<package.cpath>

  package.cpath

The path used by C<require> to search for a C loader.

Lua initializes the C path C<package.cpath> in the same way it
initializes the Lua path L</package.path>, using the environment
variable C<LUA_CPATH> (plus another default path defined in
C<luaconf.h>).

=head2 C<package.loaded>

  package.loaded

A table used by L</require> to control which modules are already
loaded.  When you require a module C<modname> and
C<package.loaded[modname]> is not false, L</require> simply returns the
value stored there.

=head2 C<package.loadlib>

  package.loadlib (libname, funcname)

Dynamically links the host program with the C library C<libname>.
Inside this library, looks for a function C<funcname> and returns this
function as a C function.  (So, C<funcname> must follow the protocol
(see C<lua_CFunction>)).

This is a low-level function.  It completely bypasses the package and
module system.  Unlike L</require>, it does not perform any path
searching and does not automatically adds extensions.  C<libname> must
be the complete file name of the C library, including if necessary a
path and extension.  C<funcname> must be the exact name exported by
the C library (which may depend on the C compiler and linker used).

This function is not supported by ANSI C.  As such, it is only
available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD,
plus other Unix systems that support the C<dlfcn> standard).

=head2 C<package.path>

  package.path

The path used by L</require> to search for a Lua loader.

At start-up, Lua initializes this variable with the value of the
environment variable C<LUA_PATH> or with a default path defined in
C<luaconf.h>, if the environment variable is not defined.  Any "C<;;>"
in the value of the environment variable is replaced by the default
path.

A path is a sequence of I<templates> separated by semicolons.  For
each template, L</require> will change each interrogation mark in the
template by C<filename>, which is C<modname> with each dot replaced by
a "directory separator" (such as "C</>" in Unix); then it will try to
load the resulting file name.  So, for instance, if the Lua path is

  "./?.lua;./?.lc;/usr/local/?/init.lua"

the search for a Lua loader for module C<foo> will try to load the
files C<./foo.lua>, C<./foo.lc>, and C</usr/local/foo/init.lua>, in
that order.

=head2 C<package.preload>

  package.preload

A table to store loaders for specific modules (see L</require>).

=head2 C<package.seeall>

  package.seeall (module)

Sets a metatable for C<module> with its C<__index> field referring to
the global environment, so that this module inherits values from the
global environment.  To be used as an option to function C<module>.

=head1 VERSION

This is Lua version 5.1.1.

=head1 CREDITS

Lua is developed at Lua.org, a laboratory of the Department of
Computer Science of PUC-Rio (the Pontifical Catholic University of Rio
de Janeiro in Brazil).  For more information about the authors, see
http://www.lua.org/authors.html .

=head1 LICENSE

Lua is licensed under the terms of the MIT license reproduced below.
This means that Lua is free software and can be used for both academic
and commercial purposes at absolutely no cost.

For details and rationale, see http://www.lua.org/license.html .

~~~~~

Copyright (C) 1994-2006 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

~~~~~