Messages should provide users with readable information about R objects without flooding their console. 'cc()' concatenates vector and data frame values into a grammatically correct string using commas, an ellipsis and conjunction. 'cn()' allows the user to define a string which varies based on a count. 'co()' combines the two to produce a customizable object aware string. The package further facilitates this process by providing five 'sprintf'-like types such as '%n' for the length of an object and '%o' for its name as well as wrappers for pasting objects and issuing errors, warnings and messages.
err
is a light-weight R package to produce customizable number and
object sensitive error and warning messages.
The co
functions produce object sensitive strings.
library(err)fox <- c("The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog")co(fox)#> [1] "fox has 9 values: 'The', 'quick', 'brown', 'fox', 'jumps', 'over', 'the', 'lazy', 'dog'"co(fox[1])#> [1] "fox[1] has 1 value: 'The'"co(fox[0])#> [1] "fox[0] has 0 values"co(fox, nlots = 5)#> [1] "fox has 9 values: 'The', 'quick', 'brown', ..., 'dog'"
The object sensitive strings are fully customized.
one <- "darn! the vector %o of length %n has the following value: %c"none <- "phew! vector %o is empty"some <- "rats! vector %o has the following %n element%s: %c"lots <- "really?! the %n elements of vector %o are too numerous to print"co(fox[0], one = one, none = none, some = some, lots = lots, nlots = 5)#> [1] "phew! vector fox[0] is empty"co(fox[1], one = one, none = none, some = some, lots = lots, nlots = 5)#> [1] "darn! the vector fox[1] of length 1 has the following value: 'The'"co(fox[1:3], one = one, none = none, some = some, lots = lots, nlots = 5)#> [1] "rats! vector fox[1:3] has the following 3 elements: 'The', 'quick', 'brown'"co(fox[1:5], one = one, none = none, some = some, lots = lots, nlots = 5)#> [1] "really?! the 5 elements of vector fox[1:5] are too numerous to print"
The following sprintf
-like types can be used in the custom messages:
%c
: the object as a comma separated list (producted by a cc
function)%n
: the length of the object%o
: the name of the object%s
: ‘s’ if n != 1 otherwise ’’%r
: ‘are’ if n != 1 otherwise ‘is’And there are various formatting options
co(fox[1:6], conjunction = "or", bracket = "|", oxford = TRUE, ellipsis = 5)#> [1] "fox[1:6] has 6 values: |The|, |quick|, |brown|, ..., or |over|"
There is also a method for data frames.
cat(co(datasets::mtcars, conjunction = "and", oxford = TRUE, ellipsis = 5))#> datasets::mtcars has 11 columns#> mpg: 21, 21, 22.8, ..., and 21.4#> cyl: 6, 6, 4, ..., and 4#> disp: 160, 160, 108, ..., and 121#> ...#> and carb: 4, 4, 1, ..., and 2
The cn
function produces number sensitive customizable messages
cn(0)#> [1] "there are 0 values"cn(1)#> [1] "there is 1 value"cn(2)#> [1] "there are 2 values"cn(100, lots = "there %r %n value%s - this is a lot")#> [1] "there are 100 values - this is a lot"
The co
and cn
functions can be combined with the wrappers msg
,
wrn
and err
to produce a message, warning and error (without the
call as part of the warning/error message).
msg(cn(2))#> there are 2 valueswrn(cn(2))#> Warning: there are 2 valueserr(cn(2))#> Error: there are 2 values
To install the latest development version from GitHub
# install.packages("devtools")
devtools::install_github("poissonconsulting/err")
To install the latest development version from the Poisson drat repository
# install.packages("drat")
drat::addRepo("poissonconsulting")
install.packages("err")
To cite package 'err' in publications use:
Joe Thorley and James Dunham (2018). err: Customizable Object
Sensitive Messages. R package version 0.0.1.
https://github.com/poissonconsulting/err
A BibTeX entry for LaTeX users is
@Manual{,
title = {err: Customizable Object Sensitive Messages},
author = {Joe Thorley and James Dunham},
year = {2018},
note = {R package version 0.0.1},
url = {https://github.com/poissonconsulting/err},
}
Please report any issues.
Pull requests are always welcome.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.