| Title: | Identify Global Objects in R Expressions |
|---|---|
| Description: | Identifies global ("unknown" or "free") objects in R expressions by code inspection using various strategies (ordered, liberal, or conservative). The objective of this package is to make it as simple as possible to identify global objects for the purpose of exporting them in parallel, distributed compute environments. |
| Authors: | Henrik Bengtsson [aut, cre, cph], Davis Vaughan [ctb] |
| Maintainer: | Henrik Bengtsson <[email protected]> |
| License: | LGPL (>= 2.1) |
| Version: | 0.16.2 |
| Built: | 2024-05-14 05:23:29 UTC |
| Source: | https://github.com/HenrikBengtsson/globals |
Drop certain types of globals
## S3 method for class 'Globals'
cleanup(globals, drop = c("missing", "base-packages", "nativesymbolinfo"), ...)globals |
A Globals object. |
drop |
A character vector specifying what type of globals to drop. |
... |
Not used |
Get all global objects of an expression
findGlobals(
expr,
envir = parent.frame(),
...,
attributes = TRUE,
tweak = NULL,
dotdotdot = c("warning", "error", "return", "ignore"),
method = c("ordered", "conservative", "liberal"),
substitute = FALSE,
unlist = TRUE,
trace = FALSE
)
globalsOf(
expr,
envir = parent.frame(),
...,
method = c("ordered", "conservative", "liberal"),
tweak = NULL,
locals = NA,
substitute = FALSE,
mustExist = TRUE,
unlist = TRUE,
recursive = TRUE,
skip = NULL
)expr |
An R expression. |
envir |
The environment from where to search for globals. |
... |
Not used. |
attributes |
If TRUE (default), attributes of 'expr' are also searched. If FALSE, they are not. If a character vector, then attributes with matching names are searched. Note, the attributes of the attributes elements are not searched, that is, attributes are not searched recursively. Also, attributes are searched with 'dotdotdot = "ignore". |
tweak |
An optional function that takes an expression and returns a tweaked expression. |
dotdotdot |
TBD. |
method |
A character string specifying what type of search algorithm to use. |
substitute |
If TRUE, the expression is |
unlist |
If TRUE, a list of unique objects is returned.
If FALSE, a list of |
trace |
TBD. |
locals |
Should globals part of any "local" environment of a function be included or not? |
mustExist |
If TRUE, an error is thrown if the object of the identified global cannot be located. Otherwise, the global is not returned. |
recursive |
If TRUE, globals that are closures (functions) and that exist outside of namespaces ("packages"), will be recursively scanned for globals. |
skip |
(internal) A list of globals not to be searched for
additional globals. Ignored unless |
There currently three strategies for identifying global objects.
The method = "ordered" search method identifies globals such that
a global variable preceding a local variable with the same name
is not dropped (which the "conservative" method would).
The method = "conservative" search method tries to keep the number
of false positive to a minimum, i.e. the identified objects are
most likely true global objects. At the same time, there is
a risk that some true globals are not identified (see example).
This search method returns the exact same result as the
findGlobals() function of the
codetools package.
The method = "liberal" search method tries to keep the
true-positive ratio as high as possible, i.e. the true globals
are most likely among the identified ones. At the same time,
there is a risk that some false positives are also identified.
With recursive = TRUE, globals part of locally defined
functions will also be found, otherwise not.
findGlobals() returns a character vector.
globalsOf() returns a Globals object.
Internally, the codetools package is utilized for code inspections.
b <- 2
expr <- substitute({ a <- b; b <- 1 })
## Will _not_ identify 'b' (because it's also a local)
globalsC <- globalsOf(expr, method = "conservative")
print(globalsC)
## Will identify 'b'
globalsL <- globalsOf(expr, method = "liberal")
print(globalsL)A representation of a set of globals
Globals(object, ...)object |
A named list. |
... |
Not used. |
An object of class Globals, which is a named list
of the value of the globals, where the element names are the names of
the globals. Attribute where is a named list of the same length
and with the same names.
The globalsOf() function identifies globals
from an R expression and returns a Globals object.
Locates and retrieves a set of global variables by their names
globalsByName(names, envir = parent.frame(), mustExist = TRUE, ...)names |
A character vector of global variable names. |
envir |
The environment from where to search for globals. |
mustExist |
If TRUE, an error is thrown if the object of the identified global cannot be located. Otherwise, the global is not returned. |
... |
Not used. |
A Globals object.
Identify the packages of the globals
## S3 method for class 'Globals'
packagesOf(globals, ...)globals |
A Globals object. |
... |
Not used. |
Returns a character vector of package names.