% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ts-tree-insert.R
\name{ts_tree_insert}
\alias{ts_tree_insert}
\title{Insert a new element into a tree-sitter tree}
\usage{
ts_tree_insert(tree, new, key, at, options, ...)
}
\arguments{
\item{tree}{A \code{ts_tree} object.}

\item{new}{The new element to insert.

The type of \code{new} depends on the parser and the method that implements
the insertion. See details in the manual of the specific parser.}

\item{key}{The key of the new element, if inserting into a keyed element.

For example a JSON(C) object or a TOML table are keyed elements.}

\item{at}{The position to insert the new element at.

The interpretation of this argument depends on the method that
implements the insertion. Typically the followings are supported:
\itemize{
\item \code{0} inserts at the beginning.
\item \code{Inf} inserts at the end.
\item A positive integer \code{n} inserts \emph{after} the \code{n}-th element.
\item A character scalar inserts \emph{after} the element with the given key,
in keyed elements.
}

See the details in the manual of the specific parser.}

\item{options}{A list of options for the insertion.

See details in the manual of the specific parser.}

\item{...}{Extra arguments for methods.}
}
\value{
A \code{ts_tree} object representing the modified parse tree.
}
\description{
Insert a new element into each selected element.
}
\details{
It is not always possible to insert a new element into a selected
element. For example in a JSONC document you can only insert a new
element into an array or an object, but not into scalar elements.
If the insertion is not possible, an error is raised.

If \code{tree} does not have a selection, the new element is inserted into
at the top level.

If \code{tree} has an empty selection, then it is returned unchanged, i.e.
no new element is inserted.
}
\examples{
\dontshow{if (requireNamespace("tsjsonc", quietly = TRUE)) withAutoprint(\{ # examplesIf}
# Create a parse tree with tsjsonc -------------------------------------
tree <- tsjsonc::ts_parse_jsonc('{ "a": true, "b": [1, 2, 3] }')

ts_tree_insert(ts_tree_select(tree, "b"), 4, at = Inf)
\dontshow{\}) # examplesIf}
\dontshow{if (requireNamespace("tstoml", quietly = TRUE)) withAutoprint(\{ # examplesIf}

# Create a parse tree with tstoml --------------------------------------
tree <- tstoml::ts_parse_toml(r"(
  [servers]
  alpha = { ip = "127.0.0.1", dc = "eqdc10" }
  beta = { ip = "127.0.0.2", dc = "eqdc20" }
)")

ts_tree_insert(
  ts_tree_select(tree, "servers", TRUE),
  key = "active",
  TRUE
)
\dontshow{\}) # examplesIf}
}
\seealso{
Other ts_tree generics:
\code{\link[=[[.ts_tree]{[[.ts_tree()}},
\code{\link[=[[<-.ts_tree]{[[<-.ts_tree()}},
\code{\link[=format.ts_tree]{format.ts_tree()}},
\code{\link[=print.ts_tree]{print.ts_tree()}},
\code{\link{select-set}},
\code{\link[=ts_tree_ast]{ts_tree_ast()}},
\code{\link[=ts_tree_delete]{ts_tree_delete()}},
\code{\link[=ts_tree_dom]{ts_tree_dom()}},
\code{\link[=ts_tree_format]{ts_tree_format()}},
\code{\link[=ts_tree_new]{ts_tree_new()}},
\code{\link[=ts_tree_query]{ts_tree_query()}},
\code{\link[=ts_tree_select]{ts_tree_select()}},
\code{\link[=ts_tree_sexpr]{ts_tree_sexpr()}},
\code{\link[=ts_tree_unserialize]{ts_tree_unserialize()}},
\code{\link[=ts_tree_update]{ts_tree_update()}},
\code{\link[=ts_tree_write]{ts_tree_write()}}
}
\concept{ts_tree generics}
