inputCollector {CodeDepends}

Create customized input/output collector for use in getInputs

Description

Create a custom input collector which will be used by getInputs to process to collect various aspects of the code as it is being processed. Custom collector functions can be specified which will be called when a particular function is called within the code.One major use for this is leveraging knowledge of specific functions' behavior to track side effects relevant to a particular use-case.

Usage

inputCollector(..., functionHandlers = list(...), inclPrevOutput =
FALSE, checkLibrarySymbols = FALSE, funcsAsInputs = checkLibrarySymbols)

Arguments

...

Custom information collection functions. Argument names correspond to R functions, with the custom collection function being called when a call to the named function is detected within the code being processed. Overridden by functionHandlers

functionHandlers

A named list of custom collection functions.

inclPrevOutput

Should variables which were output previously within the code be treated as inputs in subsequent expressions. If TRUE each expression within the code is treated separately with respect to detecting input variables, if FALSE the code is treated as a single block. Defaults to FALSE

checkLibrarySymbols

If TRUE symbols exported by default package and packages loaded within the code via library or require calls are tracked and excluded from the list of input variables. Defaults toFALSE

funcsAsInputs

If TRUE functions called by the code being processed are treated as input variables and listed as such. Defaults to the value of checkLibrarySymbols. A value of funcsAsInputs which does not agree with the value of checkLibrarySymbols is NOT recommended.

Details

Each custom collection function should accept three arguments:

e:

the code or expression currently being processed

collector:

the current inputCollector

basedir:

the base directory in which the processing is taking place, e.g. to determine whether strings correspond to files

These functions should process the expression and then use collector's collection functions and/or the <<- assignment operator to update the lists of found entities.

Currently trackable entities, updatable by ⁠<entity><<-c(<entity>, value)⁠ or as specified, include:

libraries:

libraries loaded by the code via library or require. Updatable by calling collector$library

libSymbols:

symbols exported by available libraries. Tracked automatically within collector$library

files:

string constants which correspond to an existing file in basedir. Tracked automatically when strings are passed to collector$string

strings:

string constants which do not correspond to existing files. Tracked automatically when strings are passed to collector$string

vars:

all variable names used in the code. Updatable by calling collector$vars with input as TRUE or FALSE as appropriate

set:

variable names which are assigned to in the code (input variables). Updatable by calling collector$set or collector$vars with input=TRUE

functions:

functions called by the code. Updatable by calling collector$calls. This will also update vars if the collector was created with funcsAsInputs=TRUE

removes:

variables removed by the vode via calls to collector$removes

updates:

variables which have had elements within them updated, e.g. via x$foo <- bar. Updatable via calls to collector$update

sideEffects:

side effects generated by the code. Experimental, default side effect detection should not be assumed to be robust or exhaustive. Updatable via calls to sideEffects

formulaVariables:

If formulaInputs is FALSE within the call to getInputs, this tracks variables which appear within formulas, otherwise this is unused and such variables are treated as input. Updatable via the modelVars argument in calls to collector$addInfo

Value

A list of functions used to update internal tracking variables (see Details) as well as the following:

functionHandlers:

The list of function handlers in use by the collector.

reset:

A function which resets the internal tracking variables.

results:

A function which returns a ScriptNodeInfo object representing the current state of the collection.

Note

Custom handlers take precedence over default proccessing mechanism. Care should be taken when overriding core functions such as =, ~, $, library, etc.

Note

Specific internal behaviors of the default collection mechanisms are experimental and may change in future versions.

Author(s)

Duncan Temple Lang

See Also

ScriptNodeInfo getInputs

Examples

   f = system.file("samples", "results-multi.R", package="CodeDepends")
   sc = readScript(f)
  collector = inputCollector(library = function(e, collector, basedir, ...)
  {
    print(paste("loaded library",  e[[2]]))
    collector$library(as.character(e[[2]]))
})
  res = getInputs(sc, collector = collector )
  #[1] "loaded library splines"
  #[1] "loaded library tsModel"