ns-hooks {base}R Documentation

Hooks for Name Space events

Description

Packages with namespaces can supply functions to be called when loaded, attached or unloaded.

Usage

.onLoad(libname, pkgname)
.onAttach(libname, pkgname)
.onUnload(libpath)

Arguments

libname

a character string giving the library directory where the package defining the namespace was found.

pkgname

a character string giving the name of the package.

libpath

a character string giving the complete path to the package.

Details

These functions apply only to packages with namespaces.

After loading, loadNamespace looks for a hook function named .onLoad and calls it (with two unnamed arguments) before sealing the namespace and processing exports.

When the package is attached (via library or attachNamespace), the hook function .onAttach is looked for and if found is called (with two unnamed arguments) before the package environment is sealed.

If a function .Last.lib is exported in the package, it will be called (with a single argument) when the package is detached. Beware that it might be called if .onAttach has failed, so it should be written defensively. (It is called within try, so errors will not stop the package being detached.)

If a namespace is unloaded (via unloadNamespace), a hook function .onUnload is run (with a single argument) before final unloading.

Note that the code in .onLoad and .onUnload is run without the package being on the search path, but (unless circumvented) lexical scope will make objects in the namespace and its imports visible. (Do not use the double colon operator in .onLoad as exports have not been processed at the point it is run.)

When the package is attached (via library), the hook function .onAttach is looked for and if found is called after the exported functions are attached and before the package environment is sealed. This is less likely to be useful than .onLoad, which should be seen as the analogue of .First.lib (which is only used for packages without a namespace).

.onLoad, .onUnload and .onAttach are looked for as internal objects in the namespace and should not be exported (whereas .Last.lib should be).

If a function .Last.lib is visible in the package, it will be called when the package is detached: this does need to be exported.

Anything needed for the functioning of the namespace should be handled at load/unload times by the .onLoad and .onUnload hooks. For example, DLLs can be loaded (unless done by a useDynLib directive in the ‘NAMESPACE’ file) and initialized in .onLoad and unloaded in .onUnload. Use .onAttach only for actions that are needed only when the package becomes visible to the user, for example a start-up message.

Good practice

Loading a namespace should where possible be silent, with startup messages given by .onAttach. These messages (and any essential ones from .onLoad) should use packageStartupMessage so they can be silenced where they would be a distraction.

There should be no calls to library nor require in these hooks. The way for a package to load other packages is via the Depends field in the ‘DESCRIPTION’ file: this ensures that the dependence is documented and packages are loaded in the correct order. Loading a namespace should not change the search path, so rather than attach a package, dependence of a namespace on another package is best achieved by (selectively) importing from the other package's namespace.

See Also

setHook shows how users can set hooks on the same events.


[Package base version 2.13.2 Index]