handlers: Specifying custom processing behavior, Function handlers and...

In duncantl/CodeDepends: Analysis of R Code for Reproducible Research and Code Comprehension

Specifying custom processing behavior, Function handlers and handler factories

Description

Custom behavior when processing calls to certain functions is implemented by specifying function handlers for those functions. This can be used to alter CodeDepends' behavior when it sees these functions, or if desired, to ignore them entirely when processing the parent expression.

Function handlers should never be called directly by end users.

CodeDepends attempts to provide reasonable defaults, in the form of the defaultFuncHandlers list, which should be suitable for most users.

Arguments

e	The (sub)expression being processed. This will be a call to the function your handler is assigned to work on.
collector	The input collector in use. Represents state as the expression tree is walked.
basedir	The base directory when checking if a string literal is a file path
input	Are we in a part of the whole expression that specifies inputs
formulaInputs	Are symbols within formulas to be counted as inputs (TRUE) or non-standardly evaluated variables (FALSE)
update	Are we in a part of the expression that indicates a variable's value is being updated (i.e., complex right hand side)
pipe	Are we in a direct pipe call
nseval	Should any symbols that appear to be inputs be treated as nonstandardly-evaluated instead
...	unused

Details

Custom handling of functions and, rarely, some types of non functions (currently only inlined NativeSymbol objects) by the getInputs function is specified via function handlers, which are passed in a named list to inputCollector when creating a collector for use by getInputs.

Function handlers should only be used to construct an input collector (i.e., as an argument to inputCollector). They should not ever be called directly by end users.

When creating new function handlers, they should accept the arguments specified above (other than those to the factories). The first argument, e, will be an expression representing a call to the function the handler is specified for, and second collector will be the collector object. Handlers are expected to recursively process all aspects of the call expression to the extent desired. This will often be done by calling getInputs again on, e.g., some or all arguments passed into the function call.

Function handlers are also expected to respect the pipe and nseval arguments they receive.

duncantl/CodeDepends documentation built on Oct. 22, 2023, 9:16 p.m.