README.md

salim: A Wild Mix of Functions Serving Various Purposes

salim includes a diverse mix of functions which have not found their home in a more suitable place yet. The package kinda serves as an incubator for not yet fully matured code and thus will most probably never be made available through CRAN.

This is arguably a low-cohesion package.

Installation

To install the latest development version of salim, run the following in R:

if (!("remotes" %in% rownames(installed.packages()))) {
  install.packages(pkgs = "remotes",
                   repos = "https://cloud.r-project.org/")
}

remotes::install_gitlab(repo = "salim_b/r/pkgs/salim")

Development

R Markdown format

This package’s source code is written in the R Markdown file format to facilitate practices commonly referred to as literate programming. It allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format instead of having to rely on # comments only.

All the -GEN.R suffixed R source code found under R/ is generated from the respective R Markdown counterparts under Rmd/ using pkgpurl::purl_rmd()[^1]. Always make changes only to the .Rmd files – never the .R files – and then run pkgpurl::purl_rmd() to regenerate the R source files.

Coding style

This package borrows a lot of the Tidyverse design philosophies. The R code adheres to the principles specified in the Tidyverse Design Guide wherever possible and is formatted according to the Tidyverse Style Guide (TSG) with the following exceptions:

As far as possible, these deviations from the TSG plus some additional restrictions are formally specified in the lintr configuration file .lintr, so lintr can be used right away to check for formatting issues:

pkgpurl::lint_rmd()

See also

[^1]: This naming convention as well as the very idea to leverage the R Markdown format to author R packages was originally proposed by Yihui Xie. See his excellent blog post for more detailed information about the benefits of literate programming techniques and some practical examples. Note that using pkgpurl::purl_rmd() is a less cumbersome alternative to the Makefile approach outlined by him.

[^2]: The TSG explicitly instructs to avoid this operator – presumably because it’s relatively unknown and therefore might be confused with the forward pipe operator %>% when skimming code only briefly. I don’t consider this to be an actual issue since there aren’t many sensible usage patterns of %>% at the beginning of a pipe sequence inside a function – I can only think of creating side effects and relying on R’s implicit return of the last evaluated expression. Therefore – and because I really like the %<>% operator – it’s usage is welcome.

[^3]: The TSG explicitly accepts -> for assignments at the end of a pipe sequence while Google’s R Style Guide considers this bad practice because it “makes it harder to see in code where an object is defined”. I second the latter.



salim-b/salim documentation built on April 6, 2021, 10:15 a.m.