ns-hooks {base}R Documentation

Hooks for Name Space events

Description

Packages with name spaces 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, including the version number if the package was installed with --with-package-versions.
libpath a character string giving the complete path to the package.

Details

These functions apply only to packages with name spaces.

After loading, loadNamespace looks for a hook function named .onLoad and runs it before sealing the namespace and processing exports.

If a name space is unloaded (via unloadNamespace), a hook function .onUnload is run 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 name space).

.onLoad, .onUnload and .onAttach are looked for as internal variables in the name space and should not be exported.

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 name space should be handled at load/unload times by the .onLoad and .onUnload hooks. For example, shared libraries can be loaded (unless done by a useDynib 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.

If a package was installed with --with-package-versions, the pkgname supplied will be something like tree_1.0-16.

See Also

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


[Package base version 2.2.1 Index]