getGlobals: Compute information about uses of globals, etc. for a...
In duncantl/CodeAnalysis: Tools for Static Analysis of R code

getGlobals

R Documentation

Compute information about uses of globals, etc. for a function

Description

This is an alternative version of findGlobals in the codetools package for finding the names of global variables and functions used in the code of an R function. This version uses more context, has additional features we need, and also computes additional information that we use in compilation of R code in the RLLVMCompile package and which also may be useful for other purposes.

I also find this function easier to understand and adapt as it is more direct. (However, I wrote it so of course I understand it!)

Usage

getGlobals(f, expressionsFor = character(), .ignoreDefaultArgs = FALSE,
           skip = c(".R", ".typeInfo", ".signature", ".pragma", ".Internal", ".Primitive"),
           .debug = TRUE, .assert = TRUE, localVars = character(),
           mergeSubFunGlobals = TRUE, old = TRUE,
           indirectCallFunctions = names(getIndirectCallFunList()),
           handleTextConnections = TRUE)

Arguments

`f`	the function to be analyzed
`expressionsFor`	names of R functions we are interested in so that we collect all calls to those functions in the body of this function
`.ignoreDefaultArgs`	a logical value which controls whether we ignore or process the code in the default values of the parameters/formal arguments of the function.
`localVars`	this is not intended to be provided by the caller. a character vector
`skip`	a character vector that allows us to ignore calls to particular functions, e.g. `.R` or `.debug`. These are typically functions that will be handled in a special way by, e.g., a compiler.
`.debug`	whether ignore calls to `.debug` or another debugging function. This can be a logical value to enable/disable skipping `.debug` calls, or it can be the name of another function, e.g. `"myDebug"` which we will add to the `skip` vector.
`.assert`	whether ignore calls to `.assert` or another assertion function. This can be a logical value to enable/disable skipping `.assert` calls, or it can be the name of another function, e.g. `"assert_that"` which we will add to the `skip` vector.
`mergeSubFunGlobals`	a logical scalar value that controls whether we merge the global functions used in any function defined within this functions `f` into the answer or keep them separate.
`old`	a logical value controlling whether we use the old mechanism or the new mechanism. Will be removed in the future when we decide on correct approach.
`indirectCallFunctions`	a character vector specifying the names of functions which treat one of the arguments as a function, e.g., `do.call`, `lapply`.
`handleTextConnections`	a logical value that controls whether we treat calls to `textConnection` such as `textConnection("bob", open = "w", local = TRUE)`. This creates a local variable named `bob` and if code uses that (rather than `textConnectionValue`) that is a legitimate local variable.

Value

A list of class GlobalUses with numerous elements:

`localVariables`	the names of all the variables that are assigned in the body of the function.
`variables`	the names of non-local/global variables referenced in this code.
`functions`	the names of non-local/global functions referenced in this code.
`variablesByFun`	a list with an element for each globally referenced function. Each element is a frequency table of the symbols (i.e., variables/functions) that are in the calls for this function. In other words, these are the symbols used in the calls to the external function.
`expressions`	a list with an element for each function named in `expressionsFor` that was actually invoked in the body of the function. Each such element is a collection of the expressions which called that function in `expressionsFor`.
`subFunctions`	a list with an element for each of the nested functions defined within the body of this code. Each element is the result from calling `getGlobals` on that function definition.
`skippedExpressions`	a list containing all of the call expressions that were skipped based on the call contents of `skip`.

Author(s)

Duncan Temple Lang

Examples

g =
function(a = x, b = y)
{
   x = 1
   y = 2
   a + b * (x + y)
}

getGlobals(g)$variables

tmp = substituteDefaultValues(g)
getGlobals(tmp, .ignoreDefaultArgs = TRUE)$variables


#############

account =
function(balance = 0L)
{
    deposit = function(amt)
                  balance <<- balance + amt
    withdrawl = function(amt)
                    balance <<- balance - amt

    list(deposit = deposit, withdraw = withdrawl,  balance = function() balance)
}
g

duncantl/CodeAnalysis documentation built on April 28, 2024, 6:01 p.m.