utils (version 3.3)

globalVariables: Declarations Used in Checking a Package

Description

For globalVariables, the names supplied are of functions or other objects that should be regarded as defined globally when the check tool is applied to this package. The call to globalVariables will be included in the package's source. Repeated calls in the same package accumulate the names of the global variables.

Typical examples are the fields and methods in reference classes, which appear to be global objects to codetools. (This case is handled automatically by setRefClass() and friends, using the supplied field and method names.) For suppressForeignCheck, the names supplied are of variables used as .NAME in foreign function calls which should not be checked by checkFF(registration = TRUE). Without this declaration, expressions other than simple character strings are assumed to evaluate to registered native symbol objects. The type of call (.Call, .External, etc.) and argument counts will be checked. With this declaration, checks on those names will usually be suppressed. (If the code uses an expression that should only be evaluated at runtime, the message can be suppressed by wrapping it in a dontCheck function call, or by saving it to a local variable, and suppressing messages about that variable. See the example below.)

Usage

globalVariables(names, package, add = TRUE)
suppressForeignCheck(names, package, add = TRUE)

Arguments

names
The character vector of object names. If omitted, the current list of global variables declared in the package will be returned, unchanged.
package
The relevant package, usually the character string name of the package but optionally its corresponding namespace environment.

When the call to globalVariables or suppressForeignCheck comes in the package's source file, the argument is normally omitted, as in the example below.

add
Should the contents of names be added to the current global variables or replace it?

Value

  • globalVariables returns the current list of declared global variables, possibly modified by this call. suppressForeignCheck returns the current list of native symbol objects which are not to be checked.

code

globalVariables

R

2.15.1 and suppressForeignCheck was introduced in R3.1.0 so both should be used conditionally: see the example.

Details

The lists of declared global variables and native symbol objects are stored in a metadata object in the package's namespace, assuming the globalVariables or suppressForeignCheck call(s) occur as top-level calls in the package's source code.

The check command, as implemented in package tools, queries the list before checking the R

See Also

dontCheck.

Examples

Run this code
## assume your package has some code that assigns ".obj1" and ".obj2"
## but not in a way that codetools can find.
## In the same source file (to remind you that you did it) add:
if(getRversion() >= "2.15.1")  utils::globalVariables(c(".obj1", "obj2"))

## To suppress messages about a run-time calculated native symbol, 
## save it to a local variable.

## At top level, put this:
if(getRversion() >= "3.1.0") utils::suppressForeignCheck("localvariable")

## Within your function, do the call like this:
localvariable <- if (condition) entry1 else entry2
.Call(localvariable, 1, 2, 3)

## Alternatively, like this:
if(getRversion() < "3.1.0") dontCheck <- identity
.Call(dontCheck(if (condition) entry1 else entry2), 1, 2, 3)

## HOWEVER, it is much better practice to write code
## that can be checked thoroughly, e.g.
if(condition) .Call(entry1, 1, 2, 3) else .Call(entry2, 1, 2, 3)

Run the code above in your browser using DataCamp Workspace