| setLoadActions {methods} | R Documentation |
These functions provide a mechanism for packages to specify computations to be done during the loading of a package namespace. Such actions are a flexible way to provide information only available at load time (such as locations in a dynamically linked library).
A call to setLoadAction() or setLoadActions() specifies
one or more functions to be called when the corresponding namespace is
loaded, with the ... argument names being used as identifying
names for the actions.
getLoadActions reports the currently defined load actions,
given a package's namespace as its argument.
hasLoadAction returns TRUE if a load action
corresponding to the given name has previously been set for the
where namespace.
evalOnLoad() and evalqOnLoad() schedule a specific
expression for evaluation at load time.
setLoadAction(action, aname=, where=) setLoadActions(..., .where=) getLoadActions(where=) hasLoadAction(aname, where=) evalOnLoad(expr, where=, aname=) evalqOnLoad(expr, where=, aname=)
action, ... |
functions of one or more arguments, to be called when this package is loaded. The functions will be called with one argument (the package namespace) so all following arguments must have default values. If the elements of ... are named, these names will be used for the corresponding load metadata. |
where, .where |
the namespace of the package for which the list of load actions are defined. This argument is normally omitted if the call comes from the source code for the package itself, but will be needed if a package supplies load actions for another package. |
aname |
the name for the action. If an action is set without
supplying a name, the default uses the position in the sequence of
actions specified ( |
expr |
an expression to be evaluated in a load action in
environment |
The evalOnLoad() and evalqOnLoad() functions are for
convenience. They construct a function to evaluate the expression and
call setLoadAction() to schedule a call to that function.
Each of the functions supplied as an argument to setLoadAction()
or setLoadActions() is saved as metadata in the namespace,
typically that of the package containing the call to
setLoadActions(). When this package's namespace is loaded, each
of these functions will be called. Action functions are called in the
order they are supplied to setLoadActions(). The objects
assigned have metadata names constructed from the names supplied in the
call; unnamed arguments are taken to be named by their position in the
list of actions (".1", etc.).
Multiple calls to setLoadAction() or setLoadActions()
can be used in a package's code; the actions will be scheduled after any
previously specified, except if the name given to setLoadAction()
is that of an existing action. In typical applications,
setLoadActions() is more convenient when calling from the
package's own code to set several actions. Calls to
setLoadAction() are more convenient if the action name is to be
constructed, which is more typical when one package constructs load
actions for another package.
Actions can be revised by assigning with the same name, actual or constructed, in a subsequent call. The replacement must still be a valid function, but can of course do nothing if the intention was to remove a previously specified action.
The functions must have at least one argument. They will be called with
one argument, the namespace of the package. The functions will be
called at the end of processing of S4 metadata, after dynamically
linking any compiled code, the call to .onLoad(), if any, and
caching method and class definitions, but before the namespace is
sealed. (Load actions are only called if methods dispatch is on.)
Functions may therefore assign or modify objects in the namespace supplied as the argument in the call. The mechanism allows packages to save information not available until load time, such as values obtained from a dynamically linked library.
Load actions should be contrasted with user load hooks supplied by
setHook(). User hooks are generally provided from
outside the package and are run after the namespace has been sealed.
Load actions are normally part of the package code, and the list of
actions is normally established when the package is installed.
Load actions can be supplied directly in the source code for a package. It is also possible and useful to provide facilities in one package to create load actions in another package. The software needs to be careful to assign the action functions in the correct environment, namely the namespace of the target package.
setLoadAction() and setLoadActions() are called for
their side effect and return no useful value.
getLoadActions() returns a named list of the actions in the
supplied namespace.
hasLoadAction() returns TRUE if the specified action
name appears in the actions for this package.
setHook for safer (since they are run after the
namespace is sealed) and more comprehensive versions in the
base package.
## Not run:
## in the code for some package
## ... somewhere else
setLoadActions(function(ns)
cat("Loaded package", sQuote(getNamespaceName(ns)),
"at", format(Sys.time()), "\n"),
setCount = function(ns) assign("myCount", 1, envir = ns),
function(ns) assign("myPointer", getMyExternalPointer(), envir = ns))
... somewhere later
if(countShouldBe0)
setLoadAction(function(ns) assign("myCount", 0, envir = ns), "setCount")
## End(Not run)