% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-builtins.R
\name{ppVerbSwitch}
\alias{ppVerbSwitch}
\title{Switchable pipeline-stage wrapper}
\usage{
ppVerbSwitch(.data, verb_expr, switch_on = TRUE, label = NULL)
}
\arguments{
\item{.data}{A data frame or pipe-supplied dataset (the implicit
\code{.data} slot when used as a pipeline stage).}

\item{verb_expr}{A data-pipeline verb call (e.g. \code{mutate(mpg = mpg + 100)}, \code{filter(cyl == 6)}). Evaluated with \code{.data} inserted as the
first positional argument only when \code{switch_on = TRUE}.}

\item{switch_on}{A length-1 non-NA logical literal. In \code{ptr_app()}
formulas this MUST be a literal — the translator aborts on a
non-literal so the formula remains the single source of truth for
the app's boot state. Defaults to \code{TRUE} (apply the verb).}

\item{label}{Optional length-1 character used as the checkbox label
inside \code{ptr_app()}. Ignored by the naked-R path. Defaults to \code{NULL}.}
}
\value{
Outside \code{ptr_app()}: returns \code{.data} unchanged when
\code{switch_on = FALSE}, otherwise the result of \code{verb_expr} applied to
\code{.data}.
}
\description{
ADR-0021 \emph{structural} keyword that marks a pipeline stage as user-
toggleable in \code{ptr_app()}. The boolean argument is \code{switch_on}
(positive sense: TRUE applies the verb, FALSE skips it) and an optional
\code{label} carries the UI text for the resulting checkbox. Inside
\code{ptr_app()} / \code{ptr_server()}
the parser sees the wrapper and unwraps it at translate time, stamping
the boot-state metadata + UI label onto the resulting node. The
wrapper itself never appears in the typed tree.
}
\details{
Outside \code{ptr_app()} it behaves per its R semantics so naked-dplyr
scripts still render: \code{ppVerbSwitch(.data, mutate(x = 1), FALSE)}
returns \code{.data} unchanged; \code{ppVerbSwitch(.data, mutate(x = 1), TRUE)}
routes \code{.data} through the verb call. \code{label} is metadata-only
outside \code{ptr_app()} (the naked-R path ignores it).
}
\section{Data-argument position}{

\code{ppVerbSwitch(.data, verb_expr, switch_on = TRUE)} inserts \code{.data} as
the \strong{first positional argument} of \code{verb_expr} when \code{switch_on} is
TRUE. This matches the tidyverse convention and the translator's
pipeline-stage handling; non-tidyverse verbs that take data in a
later argument are not supported (use a lambda stage or a named
wrapper instead).
}

\examples{
if (requireNamespace("dplyr", quietly = TRUE)) {
  # Naked-R semantics: switch_on = FALSE leaves the data unchanged.
  identical(
    ppVerbSwitch(mtcars, dplyr::mutate(mpg = mpg + 100), FALSE),
    mtcars
  )

  # switch_on = TRUE routes .data through the verb.
  result <- ppVerbSwitch(mtcars, dplyr::filter(mpg > 20), TRUE)
  nrow(result)  # 14
}

# Inside ptr_app(), the wrapper becomes a node-level default + a
# labelled boot-state-on checkbox:
if (interactive()) {
  ptr_app(
    "mtcars |> ppVerbSwitch(dplyr::filter(mpg > 20), TRUE, label = 'Filter') |>
     ggplot(aes(x = mpg, y = wt)) + geom_point()"
  )
}

}
