| % File src/library/methods/man/setLoadActions.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2012-2014 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{setLoadActions} |
| \alias{setLoadAction} |
| \alias{setLoadActions} |
| \alias{getLoadActions} |
| \alias{hasLoadAction} |
| \alias{evalOnLoad} |
| \alias{evalqOnLoad} |
| \title{ |
| Set Actions For Package Loading |
| } |
| \description{ |
| 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 \code{setLoadAction()} or \code{setLoadActions()} specifies |
| one or more functions to be called when the corresponding namespace is |
| loaded, with the \dots{} argument names being used as identifying |
| names for the actions. |
| |
| \code{getLoadActions} reports the currently defined load actions, |
| given a package's namespace as its argument. |
| |
| \code{hasLoadAction} returns \code{TRUE} if a load action |
| corresponding to the given name has previously been set for the |
| \code{where} namespace. |
| |
| \code{evalOnLoad()} and \code{evalqOnLoad()} schedule a specific |
| expression for evaluation at load time. |
| } |
| \usage{ |
| setLoadAction(action, aname=, where=) |
| |
| setLoadActions(..., .where=) |
| |
| getLoadActions(where=) |
| |
| hasLoadAction(aname, where=) |
| |
| evalOnLoad(expr, where=, aname=) |
| |
| evalqOnLoad(expr, where=, aname=) |
| } |
| \arguments{ |
| |
| \item{action, \dots}{ |
| 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 \dots{} are named, these names will be used for the |
| corresponding load metadata. |
| } |
| |
| \item{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. |
| } |
| |
| \item{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 (\code{".1"}, etc.). |
| } |
| |
| \item{expr}{an expression to be evaluated in a load action in |
| environment \code{where}. In the case of \code{evalqOnLoad()}, |
| the expression is interpreted literally, in that of |
| \code{evalOnLoad()} it must be precomputed, typically as an object |
| of type \code{"language"}. |
| } |
| } |
| \details{ |
| The \code{evalOnLoad()} and \code{evalqOnLoad()} functions are for |
| convenience. They construct a function to evaluate the expression and |
| call \code{setLoadAction()} to schedule a call to that function. |
| |
| Each of the functions supplied as an argument to \code{setLoadAction()} |
| or \code{setLoadActions()} is saved as metadata in the namespace, |
| typically that of the package containing the call to |
| \code{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 \code{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 (\code{".1"}, etc.). |
| |
| Multiple calls to \code{setLoadAction()} or \code{setLoadActions()} |
| can be used in a package's code; the actions will be scheduled after any |
| previously specified, except if the name given to \code{setLoadAction()} |
| is that of an existing action. In typical applications, |
| \code{setLoadActions()} is more convenient when calling from the |
| package's own code to set several actions. Calls to |
| \code{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 \code{.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 |
| \code{\link{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. |
| } |
| |
| \value{ |
| \code{setLoadAction()} and \code{setLoadActions()} are called for |
| their side effect and return no useful value. |
| |
| \code{getLoadActions()} returns a named list of the actions in the |
| supplied namespace. |
| |
| \code{hasLoadAction()} returns \code{TRUE} if the specified action |
| name appears in the actions for this package. |
| } |
| |
| \seealso{ |
| \code{\link{setHook}} for safer (since they are run after the |
| namespace is sealed) and more comprehensive versions in the |
| base package. |
| } |
| |
| \examples{ |
| \dontrun{ |
| ## 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") |
| } |
| } |
| \keyword{ package } |
| |