mirror of
https://github.com/rstudio/shiny.git
synced 2026-02-05 12:15:14 -05:00
87 lines
2.9 KiB
R
87 lines
2.9 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/utils.R
|
|
\name{req}
|
|
\alias{req}
|
|
\title{Check for required values}
|
|
\usage{
|
|
req(...)
|
|
}
|
|
\arguments{
|
|
\item{...}{Values to check for truthiness.}
|
|
}
|
|
\value{
|
|
The first value that was passed in.
|
|
}
|
|
\description{
|
|
Ensure that values are available ("truthy"--see Details) before proceeding
|
|
with a calculation or action. If any of the given values is not truthy, the
|
|
operation is stopped by raising a "silent" exception (not logged by Shiny,
|
|
nor displayed in the Shiny app's UI).
|
|
}
|
|
\details{
|
|
The \code{req} function was designed to be used in one of two ways. The first
|
|
is to call it like a statement (ignoring its return value) before attempting
|
|
operations using the required values:
|
|
|
|
\preformatted{rv <- reactiveValues(state = FALSE)
|
|
r <- reactive({
|
|
req(input$a, input$b, rv$state)
|
|
# Code that uses input$a, input$b, and/or rv$state...
|
|
})}
|
|
|
|
In this example, if \code{r()} is called and any of \code{input$a},
|
|
\code{input$b}, and \code{rv$state} are \code{NULL}, \code{FALSE}, \code{""},
|
|
etc., then the \code{req} call will trigger an error that propagates all the
|
|
way up to whatever render block or observer is executing.
|
|
|
|
The second is to use it to wrap an expression that must be truthy:
|
|
|
|
\preformatted{output$plot <- renderPlot({
|
|
if (req(input$plotType) == "histogram") {
|
|
hist(dataset())
|
|
} else if (input$plotType == "scatter") {
|
|
qplot(dataset(), aes(x = x, y = y))
|
|
}
|
|
})}
|
|
|
|
In this example, \code{req(input$plotType)} first checks that
|
|
\code{input$plotType} is truthy, and if so, returns it. This is a convenient
|
|
way to check for a value "inline" with its first use.
|
|
|
|
\strong{Truthy and falsy values}
|
|
|
|
The terms "truthy" and "falsy" generally indicate whether a value, when
|
|
coerced to a \code{\link{logical}}, is \code{TRUE} or \code{FALSE}. We use
|
|
the term a little loosely here; our usage tries to match the intuitive
|
|
notions of "Is this value missing or available?", or "Has the user provided
|
|
an answer?", or in the case of action buttons, "Has the button been
|
|
clicked?".
|
|
|
|
For example, a \code{textInput} that has not been filled out by the user has
|
|
a value of \code{""}, so that is considered a falsy value.
|
|
|
|
To be precise, \code{req} considers a value truthy \emph{unless} it is one
|
|
of:
|
|
|
|
\itemize{
|
|
\item{\code{FALSE}}
|
|
\item{\code{NULL}}
|
|
\item{\code{""}}
|
|
\item{An empty atomic vector}
|
|
\item{An atomic vector that contains only missing values}
|
|
\item{A logical vector that contains all \code{FALSE} or missing values}
|
|
\item{An object of class \code{"try-error"}}
|
|
\item{A value that represents an unclicked \code{\link{actionButton}}}
|
|
}
|
|
|
|
Note in particular that the value \code{0} is considered truthy, even though
|
|
\code{as.logical(0)} is \code{FALSE}.
|
|
|
|
If the built-in rules for truthiness do not match your requirements, you can
|
|
always work around them. Since \code{FALSE} is falsy, you can simply provide
|
|
the results of your own checks to \code{req}:
|
|
|
|
\code{req(input$a != 0)}
|
|
}
|
|
|