From 35b6adc056061075c6b27decbb8d1792ced0bfbe Mon Sep 17 00:00:00 2001
From: Davis Vaughan <davis@posit.co>
Date: Wed, 19 Jun 2024 10:58:14 -0400
Subject: [PATCH] Add `text_parse()` utility

---
 NAMESPACE         |  1 +
 R/parse.R         | 24 ++++++++++++++++++++++++
 man/text_parse.Rd | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 man/text_parse.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 4fec22e..2b721fa 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -86,6 +86,7 @@ export(range_end_byte)
 export(range_end_point)
 export(range_start_byte)
 export(range_start_point)
+export(text_parse)
 export(tree_included_ranges)
 export(tree_language)
 export(tree_root_node)
diff --git a/R/parse.R b/R/parse.R
index 2a36bfd..078bd16 100644
--- a/R/parse.R
+++ b/R/parse.R
@@ -1,3 +1,27 @@
+#' Parse a snippet of text
+#'
+#' @description
+#' `text_parse()` is a convenience utility for quickly parsing a small snippet
+#' of text using a particular language and getting access to its root node. It
+#' is meant for demonstration purposes. If you are going to need to reparse the
+#' text after an edit has been made, you should create a full parser with
+#' [parser()] and use [parser_parse()] instead.
+#'
+#' @param x `[string]`
+#'
+#'   The text to parse.
+#'
+#' @param language `[tree_sitter_language]`
+#'
+#'   The language to parse with.
+#'
+#' @export
+#' @examplesIf rlang::is_installed("treesitter.r")
+#' language <- treesitter.r::language()
+#' text <- "map(xs, function(x) 1 + 1)"
+#'
+#' # Note that this directly returns the root node, not the tree
+#' text_parse(text, language)
 text_parse <- function(x, language) {
   check_string(x)
   check_language(language)
diff --git a/man/text_parse.Rd b/man/text_parse.Rd
new file mode 100644
index 0000000..5d9d07a
--- /dev/null
+++ b/man/text_parse.Rd
@@ -0,0 +1,33 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/parse.R
+\name{text_parse}
+\alias{text_parse}
+\title{Parse a snippet of text}
+\usage{
+text_parse(x, language)
+}
+\arguments{
+\item{x}{\verb{[string]}
+
+The text to parse.}
+
+\item{language}{\verb{[tree_sitter_language]}
+
+The language to parse with.}
+}
+\description{
+\code{text_parse()} is a convenience utility for quickly parsing a small snippet
+of text using a particular language and getting access to its root node. It
+is meant for demonstration purposes. If you are going to need to reparse the
+text after an edit has been made, you should create a full parser with
+\code{\link[=parser]{parser()}} and use \code{\link[=parser_parse]{parser_parse()}} instead.
+}
+\examples{
+\dontshow{if (rlang::is_installed("treesitter.r")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+language <- treesitter.r::language()
+text <- "map(xs, function(x) 1 + 1)"
+
+# Note that this directly returns the root node, not the tree
+text_parse(text, language)
+\dontshow{\}) # examplesIf}
+}