Symbol Locations In An R Script

Description Usage Arguments Details Value Author(s)

Function scriptmap uses parse and getParseData to identify symbols (i.e. names) representing R objects in an R script and plots their locations within the script.

1 2	scriptmap(file, tokenType = "SYMBOL", rgx = NULL, lmin = NULL, lmax = NULL, sortTokens = FALSE, ...)

`file`	character: the path to the R script file to be 'mapped'.
`tokenType`	Choice of `getParseData` token type to plot. Default value "SYMBOL".
`rgx`	character: a vector of regular expressions, to be used to filter the set of symbols to be plotted. Default is `NULL`, implying no filtering.
`lmin`	integer: minimum token line number used to produce the plot. This argument doesn't simply adjust the range of the plot (which can be done via the ggplot2 `xlim` function) - it removes occurances of tokens having line number below `lmin` prior to sorting the data ( see the `sortTokens` argument below.
`lmax`	integer: maximum token line number used to produce the plot.
`sortTokens`	logical: if TRUE, the order of the tokens on the plot y axis is sorted by the minimum line number in which the token appears. Default is FALSE.
`...`	other arguments to be passed to `grepl`.

When analysing multiple reponses in a single script file, the workflow invariably involves a lot of copy/paste/edit'ing of code, and this leads to the possibility of errors or oversights in the editing of code. Function scriptmap provides a graphical overview of where object names ('tokens') appear in a script file, so that names that appear out of place may be more easily noticed. Note that scriptmap is intended as an aid to spotting name-out-of-place coding errors, but should NOT be regarded as a tool for definitively identifying all such errors - see the Caveat below.

Function scriptmap uses parse and getParseData to identify symbols (i.e. names) representing R objects in an R script and plots their locations within the script. The 'location' of a symbol is defined as the line number (in the R script) of the beginning of the statement containing the symbol (and hence may not be the line actually containing the symbol, in a multi-line statement). This limitation is a consequence of the information provided by getParseData.

The option sortTokens is provided to specify that the order of the tokens on the y-axis is to be sorted according to the line number at which each token first appears in the script. Such a sort order may aid in spotting name-out-of-place errors. The default is sortTokens=FALSE.

Arguments lmin and lmax can be specified to restrict the line range of tokens to be plotted. Note that lmin and lmax do not directly restrict the range of the plot (which can be achieved by the dplyr xlim function). Rather, these arguments remove token occurrences lying outside the lmin:lmax range prior to sorting the tokens and constructing the plot. Hence they (lmin particularly) can impact on the sort order used when sortTokens=TRUE.

Caveat: A limitation of scriptmap is that it only works with object names that are recognised by the parsing of the R script via parse. Character strings in a script are not parsed for R object names by parse, so new or misspelled object names that appear only in character strings will not be plotted by scriptmap. So do take extra care to check, for example, character arguments to functions.

A ggplot object.

Alexander Zwart (alec.zwart at csiro.au)

aleczwart/scriptmapr documentation built on May 11, 2019, 11:23 p.m.