diff --git a/man/glue-operators.Rd b/man/glue-operators.Rd index 1e9ed4831..95e103c58 100644 --- a/man/glue-operators.Rd +++ b/man/glue-operators.Rd @@ -42,7 +42,8 @@ See also \code{\link[=englue]{englue()}} to string-embrace outside of dynamic do g(1 + 1) #> [1] "var: 1 + 1" }\if{html}{\out{}} - +} +\section{Examples}{ Technically, \verb{"\{\{"} \link[=topic-defuse]{defuses} a function argument, calls \code{\link[=as_label]{as_label()}} on the expression supplied as argument, and inserts the result in the string. \subsection{\verb{"\{"} and \verb{"\{\{"}}{ @@ -152,3 +153,4 @@ Since rlang does not depend directly on glue, you will have to ensure that glue }\if{html}{\out{}} } } + diff --git a/man/rmd/glue-operators.Rmd b/man/rmd/glue-operators.Rmd index 3d6e09b8a..754b37eb5 100644 --- a/man/rmd/glue-operators.Rmd +++ b/man/rmd/glue-operators.Rmd @@ -30,6 +30,8 @@ g <- function(x) { g(1 + 1) ``` +# Examples + Technically, `r text("'{{'")` [defuses][topic-defuse] a function argument, calls [as_label()] on the expression supplied as argument, and inserts the result in the string. diff --git a/man/rmd/topic-condition-formatting.Rmd b/man/rmd/topic-condition-formatting.Rmd index f534ca09a..1ce4f88ce 100644 --- a/man/rmd/topic-condition-formatting.Rmd +++ b/man/rmd/topic-condition-formatting.Rmd @@ -21,7 +21,7 @@ Condition formatting is a set of operations applied to raw inputs for error mess While the rlang package embeds rudimentary formatting routines, the main formatting engine is implemented in the [cli package](https://cli.r-lib.org/). -## Formatting messages with cli +# Formatting messages with cli By default, rlang uses an internal mechanism to format bullets. It is preferable to delegate formatting to the [cli package](https://cli.r-lib.org/) by using [cli::cli_abort()], [cli::cli_warn()], and [cli::cli_inform()] instead of the rlang versions. These wrappers enable cli formatting with sophisticated paragraph wrapping and bullet indenting that make long lines easier to read. In the following example, a long `!` bullet is broken with an indented newline: @@ -53,7 +53,7 @@ inform_marbles(2) ``` -## Transitioning from `abort()` to `cli_abort()` +# Transitioning from `abort()` to `cli_abort()` If you plan to mass-rename calls from `abort()` to `cli::cli_abort()`, be careful if you assemble error messages from user inputs. If these individual pieces contain cli or glue syntax, this will result in hard-to-debug errors and possibly [unexpected behaviour](https://xkcd.com/327/). @@ -70,7 +70,7 @@ cli::cli_abort("Can't handle input {.code {user_input}}.") ``` -## Enabling cli formatting globally +# Enabling cli formatting globally To enable cli formatting for all `abort()` calls in your namespace, call [local_use_cli()] in the `onLoad` hook of your package. Using [on_load()] (make sure to call [run_on_load()] in your hook): diff --git a/man/rmd/topic-defuse.Rmd b/man/rmd/topic-defuse.Rmd index 0556bb92a..8388dd20c 100644 --- a/man/rmd/topic-defuse.Rmd +++ b/man/rmd/topic-defuse.Rmd @@ -5,6 +5,10 @@ When a piece of R code is defused, R doesn't return its value like it normally w Using [expr()] we can observe the difference between computing an expression and defusing it: +Evaluation of a defused expression can be resumed at any time with [eval()] (see also [eval_tidy()]). + +# Example + ```{r, comment = "#>", collapse = TRUE} # Return the result of `1 + 1` 1 + 1 @@ -13,8 +17,6 @@ Using [expr()] we can observe the difference between computing an expression and expr(1 + 1) ``` -Evaluation of a defused expression can be resumed at any time with [eval()] (see also [eval_tidy()]). - ```{r, comment = "#>", collapse = TRUE} # Return the expression `1 + 1` e <- expr(1 + 1) diff --git a/man/rmd/topic-error-chaining.Rmd b/man/rmd/topic-error-chaining.Rmd index 9079e1681..96653e2fe 100644 --- a/man/rmd/topic-error-chaining.Rmd +++ b/man/rmd/topic-error-chaining.Rmd @@ -1,7 +1,9 @@ ```{r, child = "setup.Rmd", include = FALSE} ``` -Error chaining is a mechanism for providing contextual information when an error occurs. There are multiple situations in which you might be able to provide context that is helpful to quickly understand the cause or origin of an error: +Error chaining is a mechanism for providing contextual information when an error occurs. There are multiple situations in which you might be able to provide context that is helpful to quickly understand the cause or origin of an error. + +# Context where chaining is useful - Mentioning the _high level context_ in which a low level error arised. E.g. chaining a low-level HTTP error to a high-level download error. diff --git a/man/topic-condition-formatting.Rd b/man/topic-condition-formatting.Rd index 0fd2e908c..b879a0e9f 100644 --- a/man/topic-condition-formatting.Rd +++ b/man/topic-condition-formatting.Rd @@ -26,8 +26,8 @@ See the \href{https://style.tidyverse.org/error-messages.html}{tidyverse error s } While the rlang package embeds rudimentary formatting routines, the main formatting engine is implemented in the \href{https://cli.r-lib.org/}{cli package}. -\subsection{Formatting messages with cli}{ - +} +\section{Formatting messages with cli}{ By default, rlang uses an internal mechanism to format bullets. It is preferable to delegate formatting to the \href{https://cli.r-lib.org/}{cli package} by using \code{\link[cli:cli_abort]{cli::cli_abort()}}, \code{\link[cli:cli_abort]{cli::cli_warn()}}, and \code{\link[cli:cli_abort]{cli::cli_inform()}} instead of the rlang versions. These wrappers enable cli formatting with sophisticated paragraph wrapping and bullet indenting that make long lines easier to read. In the following example, a long \code{!} bullet is broken with an indented newline: \if{html}{\out{
}}\preformatted{rlang::global_entrace(class = "errorr") @@ -56,8 +56,7 @@ inform_marbles(2) }\if{html}{\out{
}} } -\subsection{Transitioning from \code{abort()} to \code{cli_abort()}}{ - +\section{Transitioning from \code{abort()} to \code{cli_abort()}}{ If you plan to mass-rename calls from \code{abort()} to \code{cli::cli_abort()}, be careful if you assemble error messages from user inputs. If these individual pieces contain cli or glue syntax, this will result in hard-to-debug errors and possibly \href{https://xkcd.com/327/}{unexpected behaviour}. \if{html}{\out{
}}\preformatted{user_input <- "\{base::stop('Wrong message.', call. = FALSE)\}" @@ -77,8 +76,7 @@ cli::cli_abort("Can't handle input \{.code \{user_input\}\}.") }\if{html}{\out{
}} } -\subsection{Enabling cli formatting globally}{ - +\section{Enabling cli formatting globally}{ To enable cli formatting for all \code{abort()} calls in your namespace, call \code{\link[=local_use_cli]{local_use_cli()}} in the \code{onLoad} hook of your package. Using \code{\link[=on_load]{on_load()}} (make sure to call \code{\link[=run_on_load]{run_on_load()}} in your hook): \if{html}{\out{
}}\preformatted{on_load(local_use_cli()) @@ -91,5 +89,5 @@ Enabling cli formatting in \code{abort()} is useful for: \item Creating error conditions with \code{error_cnd()}. These condition messages will be automatically formatted with cli as well. } } -} + \keyword{internal} diff --git a/man/topic-defuse.Rd b/man/topic-defuse.Rd index c84cf7c2c..2ab806a9b 100644 --- a/man/topic-defuse.Rd +++ b/man/topic-defuse.Rd @@ -10,6 +10,9 @@ When a piece of R code is defused, R doesn't return its value like it normally w Using \code{\link[=expr]{expr()}} we can observe the difference between computing an expression and defusing it: +Evaluation of a defused expression can be resumed at any time with \code{\link[=eval]{eval()}} (see also \code{\link[=eval_tidy]{eval_tidy()}}). +} +\section{Example}{ \if{html}{\out{
}}\preformatted{# Return the result of `1 + 1` 1 + 1 #> [1] 2 @@ -19,8 +22,6 @@ expr(1 + 1) #> 1 + 1 }\if{html}{\out{
}} -Evaluation of a defused expression can be resumed at any time with \code{\link[=eval]{eval()}} (see also \code{\link[=eval_tidy]{eval_tidy()}}). - \if{html}{\out{
}}\preformatted{# Return the expression `1 + 1` e <- expr(1 + 1) @@ -36,6 +37,7 @@ eval(e, mtcars) #> [1] 6.1875 }\if{html}{\out{
}} } + \section{Do I need to know about defused expressions?}{ As a tidyverse user you will rarely need to defuse expressions manually with \code{expr()}, and even more rarely need to resume evaluation with \code{\link[=eval]{eval()}} or \code{\link[=eval_tidy]{eval_tidy()}}. Instead, you call \link[=topic-data-mask]{data-masking} functions which take care of defusing your arguments and resuming them in the context of a data mask. diff --git a/man/topic-error-call.Rd b/man/topic-error-call.Rd index f7be3fd4b..17bda3797 100644 --- a/man/topic-error-call.Rd +++ b/man/topic-error-call.Rd @@ -54,7 +54,7 @@ In both cases, the default error call is not very helpful to the end user becaus #> ! Unimplemented }\if{html}{\out{
}} -To fix this, let \code{abort()} knows about the function that it is throwing the error for by passing the corresponding function environment as \code{call} argument: +To fix this, let \code{abort()} know about the function that it is throwing the error for by passing the corresponding function environment as the \code{call} argument: \if{html}{\out{
}}\preformatted{stop_my_class <- function(message, call = caller_env()) \{ abort(message, class = "my_class", call = call) @@ -143,7 +143,7 @@ their_function() #> Run rlang::last_trace(drop = FALSE) to see 1 hidden frame. }\if{html}{\out{
}} -With the correct \code{call}, the backtrace is much simpler and let the user focus on the part of the stack that is relevant to them: +With the correct \code{call}, the backtrace is much simpler and lets the user focus on the part of the stack that is relevant to them: \if{html}{\out{
}}\preformatted{use_call <- TRUE their_function() diff --git a/man/topic-error-chaining.Rd b/man/topic-error-chaining.Rd index e076d82bb..4a63b8a7d 100644 --- a/man/topic-error-chaining.Rd +++ b/man/topic-error-chaining.Rd @@ -4,7 +4,9 @@ \alias{topic-error-chaining} \title{Including contextual information with error chains} \description{ -Error chaining is a mechanism for providing contextual information when an error occurs. There are multiple situations in which you might be able to provide context that is helpful to quickly understand the cause or origin of an error: +Error chaining is a mechanism for providing contextual information when an error occurs. There are multiple situations in which you might be able to provide context that is helpful to quickly understand the cause or origin of an error. +} +\section{Context where chaining is useful}{ \itemize{ \item Mentioning the \emph{high level context} in which a low level error arised. E.g. chaining a low-level HTTP error to a high-level download error. \item Mentioning the \emph{pipeline step} in which a user error occured. This is a major use-case for NSE interfaces in the tidyverse, e.g. in dplyr, tidymodels or ggplot2. @@ -33,6 +35,7 @@ In all these cases, there are two errors in play, chained together: There may be more than one contextual error in an error chain, but there is always only one causal error. } + \section{Rethrowing errors}{ To create an error chain, you must first capture causal errors when they occur. We recommend using \code{try_fetch()} instead of \code{tryCatch()} or \code{withCallingHandlers()}. \itemize{