annotater came about after teaching workshops or helping
peers and realizing that many issues relate to package installation
failures and dependency issues for packages that were not even used in a
problematic script. Scripts get passed around, code is copied and
pasted, and we might not know what certain packages are for.
Additionally, it is often useful to specify a package’s source and
version within a script, for reproducibility purposes and to keep a
record of where any the packages can be obtained.
This package works around a suite of functions that match package
load calls (i.e.
require) in a
character string with one line per element, and replace them with
annotated versions. As of version 0.2.0, loading packages with
pacman::p_load is also supported.
match_pkg_names produces a tibble of package load
calls and package names.
<- c("library(boot)\nrequire(Matrix)") pkgs_string match_pkg_names(pkgs_string) #> # A tibble: 2 × 3 #> call package_name pkgname_clean #> <chr> <chr> <chr> #> 1 library(boot) boot boot #> 2 require(Matrix) Matrix Matrix
The values in this tabular output are then passed to
utils::packageDescription, which parses and returns the
‘DESCRIPTION’ file of an installed package. Fields of interest from
these descriptions are then used to build the annotations.
The ‘Title’ field from a package’s description makes for a good
summary of what it does, so
annotate_pkg_calls uses it to
build annotations. These titles are inserted after each package load
call, separated by a commenting symbol.
<- c("library(boot)\nrequire(tools)") pkgs_string annotate_pkg_calls(pkgs_string) #>  "library(boot) # Bootstrap Functions (Originally by Angelo Canty for S)\nrequire(tools) # Tools for Package Development"
A similar approach is used by
paste the repository source and version number.
<- c("library(boot)\nrequire(lattice)") pkgs_string annotate_repo_source(pkgs_string) #>  "library(boot) # CRAN v1.3-28\nrequire(lattice) # CRAN v0.20-45"
Titles, repositories and version numbers can be annotated together in
the output from
<- c("library(boot)\nrequire(lattice)") pkgs_string annotate_repostitle(pkgs_string) #>  "boot # Bootstrap Functions (Originally by Angelo Canty for S), CRAN v1.3-28\nlattice # Trellis Graphics for R, CRAN v0.20-45"
To annotate which functions are being called from each loaded
<- c('library(purrr) testcode x <- list("a", 1, c("bo","bi","bu")) pluck(x, 1) map(x, pluck, 2)') annotate_fun_calls(testcode) #>  "library(purrr) # pluck map \nx <- list(\"a\", 1, c(\"bo\",\"bi\",\"bu\"))\npluck(x, 1)\nmap(x, pluck, 2)"
tidyverse package is a meta-package with few
exported functions of its own, so the annotation tools provided here
annotate_fun_calls) will not match the functions from the
various individual packages (such as
readr) that get attached when loading
tidyverse. This is by design, so consider loading
individual packages if annotations for function calls are desired.
These main package functions can be called through their respective RStudio addins, written to work on the active .R or .Rmd file open in the Source pane.
Describes the packages being loaded by calling
Adds the source and version by calling
annotate_repo_source. This addin aligns the commenting
symbols vertically for aesthetic purposes.
Adds titles, sources, and versions by calling
Adds all the unique functions being called by each loaded package,