This functions checks the evaluation of an expression and, if an error is thrown, 64 | captures it and integrates the captured message after a custom error message.
65 |check_expr(expr, ..., clean, up = 0, arg_name, verbatim = FALSE)
69 |
70 | check_expr_hook(expr, ..., clean, arg_name, verbatim = FALSE)
71 |
72 | generate_check_expr_hook(namespace)An expression to be evaluated.
Character scalars. The values of ... will be coerced with the function
83 | string_magic.
84 | This means that string interpolation is allowed. Ex: "Arg. {arg} should be positive"
85 | leads to "Arg. power should be positive" if arg is equal to "power".
If argument verbatim is TRUE, the values are instead coereced with paste0.
Character vector, default is missing. If provided, the function
91 | string_clean
92 | is applied to the captured error message to clean it when necessary. Each element
93 | of the vector should be of the form "pat => rep" with pat a regular expression
94 | to be replace and rep the replacement.
Integer, default is 0. It is used to construct the call in the error message.
99 | By default the call reported is the function containing check_expr. If you want to
100 | report a function higher in the stack, use up = 1, or higher.
Character scalar, default is missing. Used when the expression in
105 | expr leads to an error and the custom message is missing (i.e. no element is
106 | provided in ...). In that case, the default message is: "The argument {arg_name} could not be evaluated.".
107 | The default value for arg_name is deparse(substitute(expr)), if this guess is wrong,
108 | use arg_name.
Logical scalar, default is FALSE. By default the elements of ...
113 | allow string interpolation with "{}" using stringmagic.
114 | If TRUE, no interpolation is performed.
Character scalar giving the namespace for which the hooks are valid. Only useful 119 | when hook functions are used in a package.
The purpose of this functions is to provide useful error messages to the user.
125 |check_expr_hook(): As check_expr but sets the error call at the level of the hooked function
generate_check_expr_hook(): Generates a package specific check_expr_hook function
For general argument checking, see check_arg() and check_set_arg().
144 | test = function(x, y){
145 | check_expr(mean(x, y), "Computing the mean didn't work:")
146 | }
147 |
148 |
149 | The main purpose of this package is twofold: i) to facilitate the developer's life, and ii) to provide to the users meaningful, useful error messages. These objectives are accomplished with a single function: check_arg. That function checks the arguments given by the user: it offers a compact syntax such that complex arguments can be simply stated by the developer. In turn, if the user provides an argument of the wrong type then an informative error message will be buit, stating the expected type and where the error comes from--saving the user quite some time in debugging.
Thus you can very easily make your package look professional with check_arg (checking arguments properly is professional).
It also offers a set of small tools to provide informative messages to the users. See stop_up and warn_up to throw errors and warnings in the appropriate location. There are many tools to form messages: enumerate_items to form textual list of elements (with many options including conjugating verbs, etc...), plural to conjugate verbs depending on the argument, and n_letter, n_th, n_times to write integers in words (which usually looks nicer).
To sum up in a few words, this package was created to enhance the user experience and facilitate package development.
71 |Useful links:
Report bugs at https://github.com/lrberge/dreamerr/issues
R/misc_funs.R
58 | fsignif.RdFormatting of numbers, when they are to appear in messages. Displays only significant digits in a "nice way" and adds commas to separate thousands. It does much less than the format function, but also a bit more though.
fsignif(x, s = 2, r = 0, commas = TRUE)
67 |
68 | signif_plusAn object of class function of length 1.
A numeric vector.
The number of significant digits to be displayed. Defaults to 2. All digits not in the decimal are always shown.
For large values, the number of digits after the decimals to be displayed (beyond the number of significant digits). Defaults to 0. It is useful to suggest that a number is not an integer.
Whether or not to add commas to separate thousands. Defaults to TRUE.
It returns a character vector of the same length as the input.
98 |
103 | x = rnorm(1e5)
104 | x[sample(1e5, 1e4, TRUE)] = NA
105 |
106 | # Dumb function telling the number of NA values
107 | tell_na = function(x) message("x contains ", fsignif(sum(is.na(x))), " NA values.")
108 |
109 | tell_na(x)
110 | #> x contains 9,473 NA values.
111 |
112 | # Some differences with signif:
113 | show_diff = function(x, d = 2) cat("signif(x, ", d, ") -> ", signif(x, d),
114 | " vs fsignif(x, ", d, ") -> ",
115 | fsignif(x, d), "\n", sep = "")
116 |
117 | # Main difference is for large numbers
118 | show_diff(95123.125)
119 | #> signif(x, 2) -> 95000 vs fsignif(x, 2) -> 95,123
120 | show_diff(95123.125, 7)
121 | #> signif(x, 7) -> 95123.12 vs fsignif(x, 7) -> 95,123.12
122 |
123 | # Identical for small numbers
124 | show_diff(pi / 500)
125 | #> signif(x, 2) -> 0.0063 vs fsignif(x, 2) -> 0.0063
126 |
127 |
128 |
60 | All functions61 | 62 | |
63 | |
|---|---|
|
64 |
|
66 | Checks arguments and informs the user appropriately |
67 |
| 68 | 69 | | 70 |Checks the evaluation of an expression |
71 |
| 72 | 73 | | 74 |Error Handling Made Easy |
75 |
| 76 | 77 | | 78 |Enumerates the elements of a vector |
79 |
| 80 | 81 | | 82 |Nicely fits a message in the current R console |
83 |
| 84 | 85 | | 86 |Formatting numbers with display of significant digits |
87 |
| 88 | 89 | | 90 |Conditional element selection |
91 |
| 92 | 93 | | 94 |Numbers in letters |
95 |
| 96 | 97 | | 98 |Provides package statistics |
99 |
| 100 | 101 | | 102 |Adds an s and/or a singular/plural verb depending on the argument's length |
103 |
| 104 | 105 | | 106 |Sets dreamerr argument checking functions on or off |
107 |
| 108 | 109 | | 110 |Sets the developer mode to help form check_arg calls |
111 |
| 112 | 113 | | 114 |Settings telling whether or not to display the full call stack on errors |
115 |
| 116 | 117 | | 118 |Sets argument checking on/off "semi-globally" |
119 |
| 120 | 121 | | 122 |Sets "semi-globally" the 'up' argument of dreamerr's functions |
123 |
| 124 | 125 | | 126 |Fills a string vector with a symbol |
127 |
|
128 |
|
130 | Error displaying a call located at a hook location |
131 |
| 132 | 133 | | 134 |Stops (or warns in) sub-function execution |
135 |
| 136 | 137 | | 138 |Suggest the the closest elements from a string vector |
139 |
| 140 | 141 | | 142 |Checks the arguments in dots from methods |
143 |
Set of (tiny) functions that convert integers into words.
63 |n_times(n)
67 |
68 | n_th(n)
69 |
70 | n_letter(n)An integer vector.
It returns a character vector of length one.
84 |n_th(): Transforms the integer n to nth appropiately.
n_letter(): Transforms small integers to words.
99 | find = function(v, x){
100 | if(x %in% v){
101 | message("The number ", n_letter(x), " appears ", n_times(sum(v == x)),
102 | ", the first occurrence is the ", n_th(which(v==x)[1]), " element.")
103 | } else message("The number ", n_letter(x), " was not found.")
104 | }
105 |
106 | v = sample(100, 500, TRUE)
107 | find(v, 6)
108 | #> The number six appears 7 times, the first occurrence is the 104th element.
109 |
110 |
111 |
112 | Summary statistics of a packages: number of lines, number of functions, etc...
63 |package_stats()Doesn't return anything, just a prompt in the console.
74 |This function looks for files in the R/ and src/ folders and gives some stats. If there is no R/ folder directly accessible from the working directory, there will be no stats displayed.
Why this function? Well, it's just some goodies for package developers trying to be user-friendly!
79 |The number of documentation lines (and number of words) corresponds to the number of non-empty roxygen documentation lines. So if you don't document your code with roxygen, well, this stat won't prompt.
80 |Code lines correspond to non-commented, non-empty lines (by non empty: at least one letter must appear).
81 |Comment lines are non-empty comments.
82 |
87 | package_stats()
88 | #> Your project doesn't look like a package... Sorry, no stats!
89 |
90 | R/stop.R
58 | setDreamerr_check.RdThis function allows to disable, or re-enable, all calls to check_arg within any function. Useful only when running (very) large loops (>100K iter.) over small functions that use dreamerr's check_arg.
setDreamerr_check(check = TRUE)Strict logical: either TRUE of FALSE. Default is TRUE.
83 | # Let's create a small function that returns the argument
84 | # if it is a single character string, and throws an error
85 | # otherwise:
86 |
87 | test = function(x){
88 | check_arg(x, "scalar character")
89 | x
90 | }
91 |
92 | # works:
93 | test("hey")
94 | #> [1] "hey"
95 | # error:
96 | try(test(55))
97 | #> Error : in test(55):
98 | #> Argument `x` must be a character scalar.
99 | #> PROBLEM: it is not of type character (instead it is of type 'numeric').
100 |
101 | # Now we disable argument checking
102 | setDreamerr_check(FALSE)
103 | # works (although it shouldn't!):
104 | test(55)
105 | #> [1] 55
106 |
107 | # re-setting argument checking on:
108 | setDreamerr_check(TRUE)
109 |
110 |
111 |