origin - 1.1.2

CRAN_Status_Badge metacran downloads codecov R-CMD-check

branch main dev
R CMD check main dev
test coverage main-test-coverage dev-test-coverage
lints main-lints dev-lints

An R package that adds pkg:: to functions to be more explicit

To install the latest version use remotes::install_github("mnist91/origin")

Overview

origin adds the correct package specification to all functions in your script while giving full control about the outcome. This makes it much easier to both convert legacy code into the pkg::fun() convention as well as it allows you to write short code first and adapt it later.

Additionally, it provides an overview of all actually used packages in a project. That means, it does not only check which packages are called via library(), require(), etc. but determines which functions from which packages are eventually used. Useful for quickly checking a project for which packages are actually still needed when dealing with a huge barrage of library calls.

Usage

Originize Code

To originize code either use the delivered RStudio addins or call the origin functions directly, i.e. origin::originize_file or origin::originize_dir.

origin::originize_file("testfile.R", pkgs = c("dplyr", "data.table"))

Check Package Usage

Again, either use the delivered RStudio addin or call the function explicitly

origin::check_pkg_usage(path = ".",
                        pkgs = c("dplyr", "data.table"),
                        use_markes = FALSE)

Settings

Most argument defaults of origin functions can be set via options(). This is especially useful when using the RStudio Addins.

Considered Packages

By default, orgigin considers all attached packages as given by .packages() except the standard R packages (base, methods, stats, utils, graphics, datasets). For the current list of loaded packages also check search(). Note that, in case of namespace conflicts, the order in the search list determines which namespace masks which. origin uses the same rule as R, i.e. the latest loaded package masks the other packages. Therefore, in case there is a potential namespace conflict in your code, the changes made by origin should yield the same result as before but being more explicit about it. Since this can break code functionality, origin issues a warning and user input is required.

To overwrite the default just use a character vector of package names.

Exclude Functions

Especially useful to solve namespace conflicts or ignore infix functions like the pipe operator %>%. Listed functions are not considered by origin neither in adding pkg:: nor logging. It is a list of function names. When unnamed, the function is generally excluded. To be more specific, a named list excludes functions from these packages only.

Examples:

# unnamed list
opitions(origin.excluded_functions = list("last", "%>%", "%<>%"))

# named list
opitions(origin.excluded_functions = list(data.table = c("last", %between%),
                                          magrittr = c("%>%", "%<>%")))

# both named and unnamed
opitions(origin.excluded_functions = list(data.table = c("last", %between%),
                                          "%>%", "%<>%"))

Logging Interpretation

The logging highlights three cases: - insertion: pkg:: is inserted prior to a function - missing: an object that has the same name as a function but not undoubtedly used as a function. In R it is usually no problem to have variables that name like functions (data or df are popular examples). While it is always clear when a function is directly used as one, functions can also be arguments of other functions, most famously in functional programming like the *apply family or purrr. origin highlights such cases in the logging output. - infix: functions like %>% are exported by packages but cannot be called with the pkg::fun() convention. Such functions are highlighted by default to point the user that these stem from a package. When using dplyr-style code, consider to exclude the pipe-operator via exclude_functions.

Discussion

Whether or not to add pkg:: to each (imported) function is a controversial issue in the R community. While the tidyverse style guide does not mention explicit namespacing, R Packages and the Google R style guide are in favor of it.

Pros

Cons