.. _lua-funcs-package: Modules (package) ================= Original document, see: http://www.lua.org/manual/5.1/manual.html The package library provides basic facilities for loading and building modules in Lua. It exports two of its functions directly in the global environment: :ref:`lua-func-require` and :ref:`lua-func-module`. Everything else is exported in a table ``package``. .. _lua-func-module: module ----------------- .. function:: module (name [, ...]) Creates a module. If there is a table in ``package.loaded[name]``, this table is the module. Otherwise, if there is a global table ``t`` with the given name, this table is the module. Otherwise creates a new table ``t`` and sets it as the value of the global ``name`` and the value of ``package.loaded[name]``. This function also initializes ``t._NAME`` with the given name, ``t._M`` with the module (``t`` itself), and ``t._PACKAGE`` with the package name (the full module name minus last component; see below). Finally, ``module`` sets ``t`` as the new environment of the current function and the new value of ``package.loaded[name]``, so that :ref:`lua-func-require` returns ``t``. If ``name`` is a compound name (that is, one with components separated by dots), ``module`` creates (or reuses, if they already exist) tables for each component. For instance, if ``name`` is ``a.b.c``, then ``module`` stores the module table in field ``c`` of field ``b`` of global ``a``. This function can receive optional *options* after the module name, where each option is a function to be applied over the module. .. _lua-func-require: require ----------------- .. function:: require (modname) Loads the given module. The function starts by looking into the :ref:`lua-func-package.loaded` table to determine whether ``modname`` is already loaded. If it is, then ``require`` returns the value stored at ``package.loaded[modname]``. Otherwise, it tries to find a *loader* for the module. To find a loader, ``require`` is guided by the :ref:`lua-func-package.loaders` array. By changing this array, we can change how ``require`` looks for a module. The following explanation is based on the default configuration for :ref:`lua-func-package.loaders`. First ``require`` queries ``package.preload[modname]``. If it has a value, this value (which should be a function) is the loader. Otherwise ``require`` searches for a Lua loader using the path stored in :ref:`lua-func-package.path`. If that also fails, it searches for a C loader using the path stored in :ref:`lua-func-package.cpath`. If that also fails, it tries an *all-in-one* loader (see :ref:`lua-func-package.loaders`). Once a loader is found, ``require`` calls the loader with a single argument, ``modname``. If the loader returns any value, ``require`` assigns the returned value to ``package.loaded[modname]``. If the loader returns no value and has not assigned any value to ``package.loaded[modname]``, then ``require`` assigns **true** to this entry. In any case, ``require`` returns the final value of ``package.loaded[modname]``. If there is any error loading or running the module, or if it cannot find any loader for the module, then ``require`` signals an error. .. _lua-func-package.cpath: package.cpath ----------------- .. uparam:: package.cpath The path used by :ref:`lua-func-require` to search for a C loader. Lua initializes the C path :ref:`lua-func-package.cpath` in the same way it initializes the Lua path :ref:`lua-func-package.path`, using the environment variable ``LUA_CPATH`` or a default path defined in ``luaconf.h``. .. _lua-func-package.loaded: package.loaded ----------------- .. uparam:: package.loaded A table used by :ref:`lua-func-require` to control which modules are already loaded. When you require a module ``modname`` and ``package.loaded[modname]`` is not false, :ref:`lua-func-require` simply returns the value stored there. .. _lua-func-package.loaders: package.loaders ----------------- .. uparam:: package.loaders A table used by :ref:`lua-func-require` to control how to load modules. Each entry in this table is a *searcher function*. When looking for a module, :ref:`lua-func-require` calls each of these searchers in ascending order, with the module name (the argument given to :ref:`lua-func-require`) as its sole parameter. The function can return another function (the module *loader*) or a string explaining why it did not find that module (or **nil** if it has nothing to say). Lua initializes this table with four functions. The first searcher simply looks for a loader in the :ref:`lua-func-package.preload` table. The second searcher looks for a loader as a Lua library, using the path stored at :ref:`lua-func-package.path`. A path is a sequence of *templates* separated by semicolons. For each template, the searcher will change each interrogation mark in the template by ``filename``, which is the module name with each dot replaced by a "directory separator" (such as "``/``" in Unix); then it will try to open the resulting file name. So, for instance, if the Lua path is the string :: "./?.lua;./?.lc;/usr/local/?/init.lua" the search for a Lua file for module ``foo`` will try to open the files ``./foo.lua``, ``./foo.lc``, and ``/usr/local/foo/init.lua``, in that order. The third searcher looks for a loader as a C library, using the path given by the variable :ref:`lua-func-package.cpath`. For instance, if the C path is the string :: "./?.so;./?.dll;/usr/local/?/init.so" the searcher for module ``foo`` will try to open the files ``./foo.so``, ``./foo.dll``, and ``/usr/local/foo/init.so``, in that order. Once it finds a C library, this searcher first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside the library to be used as the loader. The name of this C function is the string "``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 ``a.v1-b.c``, the function name will be ``luaopen_b_c``. The fourth searcher tries an *all-in-one loader*. It searches the C path for a library for the root name of the given module. For instance, when requiring ``a.b.c``, it will search for a C library for ``a``. If found, it looks into it for an open function for the submodule; in our example, that would be ``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. .. _lua-func-package.loadlib: package.loadlib ----------------- .. function:: package.loadlib (libname, funcname) Dynamically links the host program with the C library ``libname``. Inside this library, looks for a function ``funcname`` and returns this function as a C function. (So, ``funcname`` must follow the protocol. This is a low-level function. It completely bypasses the package and module system. Unlike :ref:`lua-func-require`, it does not perform any path searching and does not automatically adds extensions. ``libname`` must be the complete file name of the C library, including if necessary a path and extension. ``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 ``dlfcn`` standard). .. _lua-func-package.path: package.path ----------------- .. uparam:: package.path The path used by :ref:`lua-func-require` to search for a Lua loader. At start-up, Lua initializes this variable with the value of the environment variable ``LUA_PATH`` or with a default path defined in ``luaconf.h``, if the environment variable is not defined. Any "``;;``" in the value of the environment variable is replaced by the default path. .. _lua-func-package.preload: package.preload ----------------- .. uparam:: package.preload A table to store loaders for specific modules (see :ref:`lua-func-require`). .. _lua-func-package.seeall: package.seeall ----------------- .. function:: package.seeall (module) Sets a metatable for ``module`` with its ``__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 :ref:`lua-func-module`. :sub:`id-1096722`