% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/insert_text.R
\name{insert_text}
\alias{insert_text}
\title{Insert Text from a Data Frame by Chunk Name}
\usage{
insert_text(data, chunk, before = TRUE, error_on_empty = NULL, enabled = TRUE)
}
\arguments{
\item{data}{A data frame with columns \code{chunk}, \code{before}, and \code{text}.}

\item{chunk}{Character. The chunk name to look up in \code{data}.
If the file extension is \code{"rmarkdown"}, it is stripped automatically.}

\item{before}{Logical. Whether to retrieve the text marked as "before"
(\code{TRUE}, default) or "after" (\code{FALSE}) the chunk.}

\item{error_on_empty}{Controls behaviour when no matching text is found:
\itemize{
\item \code{TRUE}: throws an error via \code{\link[cli:cli_abort]{cli::cli_abort()}}.
\item \code{FALSE}: issues a warning via \code{\link[cli:cli_abort]{cli::cli_warn()}}.
\item \code{NULL} (default): silently returns an empty \code{AsIs} object.
}}

\item{enabled}{Logical. If \code{FALSE}, the function returns \code{I(character(0))}
immediately without any lookup. Can be set globally via
\code{global_settings_set(new = list(enabled = FALSE), fn_name = "insert_text")}.}
}
\value{
An \code{\link[=I]{I()}}-wrapped character string. If no match is found and
\code{error_on_empty} is \code{NULL}, an empty \code{AsIs} character vector.
}
\description{
Looks up a text string from a data frame based on a chunk name and
position (before/after). Optionally expands knitr templating syntax
(\code{{{...}}}) found in the text.
}
\details{
The function filters \code{data} for rows matching the given \code{chunk} and
\code{before} values. If exactly one row matches, its \code{text} column is
returned. If the text contains knitr templating delimiters (\verb{\{\{}),
it is expanded with \code{\link[knitr:knit_expand]{knitr::knit_expand()}}.
}
\examples{
\dontrun{
texts <- data.frame(
  chunk = c("intro", "intro"),
  before = c(TRUE, FALSE),
  text = c("Before the chunk.", "After the chunk.")
)
insert_text(texts, "intro", before = TRUE)
insert_text(texts, "intro", before = FALSE)
}
}
