| Title: | Tree-Sitter Parsing Tools |
|---|---|
| Description: | Common tree-sitter parsing tools for R. It is meant to be used by other packages that specialize in particular languages and file formats. |
| Authors: | Gábor Csárdi [aut, cre], Posit Software, PBC [cph, fnd] (ROR: <https://ror.org/03wc8by49>), Tree-sitter authors [cph] (Tree-sitter C library) |
| Maintainer: | Gábor Csárdi <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.0.9000 |
| Built: | 2026-05-23 09:04:16 UTC |
| Source: | https://github.com/r-lib/tsitter |
The [[ operator works similarly to the combination of
ts_tree_select() and
ts_tree_unserialize(), but it
might be more readable.
## S3 method for class 'ts_tree' x[[i, ...]]## S3 method for class 'ts_tree' x[[i, ...]]
x |
A |
i |
Selection expressions in a list, see details in
|
... |
Additional arguments, passed to
|
The following two expressions are equivalent:
ts_tree_select(tree, <selectors>) |> ts_tree_unserialize()
and
tree[[list(<selectors>)]]
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json[[list("b", 1)]]
#> [[1]] #> [1] 10 #>
[[<- replacement operatorThe [[<- operator works similarly to the combination of
ts_tree_select() and
ts_tree_update(), (and also to the
replacement function ts_tree_select<-()),
but it might be more readable.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json[[list("b", 1)]] <- 100
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [100, 20, 30], "c": { "c1": true, "c2": null } }
List of R objects, with one entry for each selected element.
Other ts_tree generics:
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
Other serialization functions:
ts_tree_unserialize()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree[[list("a")]] # Last two elements of "b" tree[[list("b", -(1:2))]]# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree[[list("a")]] # Last two elements of "b" tree[[list("b", -(1:2))]]
The [[<- operator works similarly to the combination of
ts_tree_select() and
ts_tree_update(), (and also to the
replacement function ts_tree_select<-()),
but it might be more readable.
## S3 replacement method for class 'ts_tree' x[[i]] <- value## S3 replacement method for class 'ts_tree' x[[i]] <- value
x |
A |
i |
A list with selection expressions, see
|
value |
An R expression to serialize or
|
The following two expressions are equivalent:
tree <- ts_tree_select(tree, <selectors>) |> ts_tree_update(value)
and
tree[[list(<selectors>)]] <- value
The modified ts_tree object.
Other ts_tree generics:
[[.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree[[list("a")]] <- 42 tree[[list("b", -1)]] <- ts_tree_deleted() tree# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree[[list("a")]] <- 42 tree[[list("b", -1)]] <- ts_tree_deleted() tree
tsitter is a common interface to tree-sitter parsers, implemented in other R packages. It has a common API to
query,
edit,
format, and
unserialize
tree-sitter parse trees.
In this document I show examples with the tsjsonc package.
Create a ts_tree (ts_tree_jsonc) object from a string:
txt <- r"(
// this is a comment
{
"a": {
"a1": [1, 2, 3],
// comment
"a2": "string"
},
"b": [
{
"b11": true,
"b12": false
},
{
"b21": false,
"b22": false
}
]
}
)"
json <- tsjsonc::ts_parse_jsonc(txt)
#>
Pretty print a ts_tree object:
json
#> # jsonc (19 lines) #> 1 | #> 2 | // this is a comment #> 3 | { #> 4 | "a": { #> 5 | "a1": [1, 2, 3], #> 6 | // comment #> 7 | "a2": "string" #> 8 | }, #> 9 | "b": [ #> 10 | { #> ℹ 9 more lines #> ℹ Use `print(n = ...)` to see more lines
Selecting nodes is the basis of editing and querying tree-sitter trees.
Select element by objects key:
ts_tree_select(json, "a")
#> Error in ts_tree_select(json, "a") : #> could not find function "ts_tree_select"
Select element inside element:
ts_tree_select(json, "a", "a1")
#> Error in ts_tree_select(json, "a", "a1") : #> could not find function "ts_tree_select"
Select element(s) of an array:
ts_tree_select(json, "a", "a1", 1:2)
#> Error in ts_tree_select(json, "a", "a1", 1:2) : #> could not find function "ts_tree_select"
Select multiple keys from an object:
ts_tree_select(json, "a", c("a1", "a2"))
#> Error in ts_tree_select(json, "a", c("a1", "a2")) :
#> could not find function "ts_tree_select"
Select nodes that match a tree-sitter query:
json |> ts_tree_select(query = "((pair value: (false) @val))")
#> Error in ts_tree_select(json, query = "((pair value: (false) @val))") : #> could not find function "ts_tree_select"
Delete selected elements:
ts_tree_select(json, "a", "a1") |> ts_tree_delete()
#> Error in ts_tree_delete(ts_tree_select(json, "a", "a1")) : #> could not find function "ts_tree_delete"
Insert element into an array:
ts_tree_select(json, "a", "a1") |> ts_tree_insert(at = 2, "new")
#> Error in ts_tree_insert(ts_tree_select(json, "a", "a1"), at = 2, "new") : #> could not find function "ts_tree_insert"
Inserting into an array reformats the array.
Insert element into an object, at the specified key:
ts_tree_select(json, "a") |>
ts_tree_insert(key = "a0", at = 0, list("new", "element"))
#> Error in ts_tree_insert(ts_tree_select(json, "a"), key = "a0", at = 0, : #> could not find function "ts_tree_insert"
Update existing element:
ts_tree_select(json, "a", c("a1", "a2")) |> ts_tree_update("new value")
#> #> could not find function "ts_tree_update"
Inserts the element if some parents are missing:
json <- ts_parse_jsonc(text = "{ \"a\": { \"b\": true } }")
json
#> Error in ts_parse_jsonc(text = "{ \"a\": { \"b\": true } }") :
#> could not find function "ts_parse_jsonc"
#> # jsonc (19 lines)
#> 1 |
#> 2 | // this is a comment
#> 3 | {
#> 4 | "a": {
#> 5 | "a1": [1, 2, 3],
#> 6 | // comment
#> 7 | "a2": "string"
#> 8 | },
#> 9 | "b": [
#> 10 | {
#> ℹ 9 more lines
#> ℹ Use `print(n = ...)` to see more lines
ts_tree_select(json, "a", "x", "y") |> ts_tree_update(list(1,2,3))
#> Error in ts_tree_update(ts_tree_select(json, "a", "x", "y"), list(1, 2, : #> could not find function "ts_tree_update"
Use stdout() to write it to the screen instread of a file:
json |> ts_tree_write(stdout())
#> Error in ts_tree_write(json, stdout()) : #> could not find function "ts_tree_write"
Format the whole document:
json |> ts_tree_format()
#> Error in ts_tree_format(json) : could not find function "ts_tree_format"
Format part of the document:
json |> ts_tree_select("a") |>
ts_tree_format(options = list(format = "compact"))
#> act")) : #> could not find function "ts_tree_format"
Unserialize a whole document:
json |> ts_tree_unserialize()
#> Error in ts_tree_unserialize(json) : #> could not find function "ts_tree_unserialize"
Note that ts_tree_unserialize() always returns a list, the first element
of the list is the unserialized document.
Unserialize part(s) of the document:
json |> ts_tree_select("b") |> ts_tree_unserialize()
#> Error in ts_tree_unserialize(ts_tree_select(json, "b")) : #> could not find function "ts_tree_unserialize"
Again, ts_tree_unserialize() returns a list, with one element for each
selected node.
It is often useful to explore the structure of a (JSONC) tree-sitter tree, to help writing the right selection or tree-sitter queries.
Print the annotated syntax tree:
ts_tree_ast(json)
#> Error in ts_tree_ast(json) : could not find function "ts_tree_ast"
Print the document object model:
ts_tree_dom(json)
#> Error in ts_tree_dom(json) : could not find function "ts_tree_dom"
Print the structural summary of a tree:
ts_tree_sexpr(json)
#> Error in ts_tree_sexpr(json) : could not find function "ts_tree_sexpr" #> #> #> #> #> #>
Not applicable.
# See above please.# See above please.
The document of a tree-sitter tree as a character scalar
## S3 method for class 'ts_tree' as.character(x, ...)## S3 method for class 'ts_tree' as.character(x, ...)
x |
A |
... |
Ignored. |
A character scalar containing the document of the tree.
as.raw.ts_tree() to get the document as a raw vector.
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree as.character(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree as.character(tree)
Raw bytes of a document of a tree-sitter tree
## S3 method for class 'ts_tree' as.raw(x)## S3 method for class 'ts_tree' as.raw(x)
x |
A |
A raw vector containing the bytes of the document of the tree.
as.character.ts_tree() to get the document as a character scalar.
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree as.raw(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree as.raw(tree)
Format a ts_tree object for printing.
## S3 method for class 'ts_tree' format(x, n = 10, ...)## S3 method for class 'ts_tree' format(x, n = 10, ...)
x |
|
n |
Number of lines, or number of selections to print. |
... |
Currently ignored. |
This is the engine of print.ts_tree(),
possibly useful to obtain a printed representation without doing the
actual printing.
If there are selected nodes in the tree, those will be highlighted
in the output. See ts_tree_select() to
select nodes in a tree.
Character vector of lines to print.
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) format(json)# Create a parse tree with tsjsonc ------------------------------------- json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) format(json)
Print a ts_tree object to the screen.
## S3 method for class 'ts_tree' print(x, n = 10, ...)## S3 method for class 'ts_tree' print(x, n = 10, ...)
x |
|
n |
Number of lines, or number of selections to print. |
... |
Not used currently. |
Calls format.ts_tree() to format the
ts_tree object, writes the formatted object to the standard output, and
returns the original object invisibly.
Invisibly returns the original ts_tree object.
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) print(json)# Create a parse tree with tsjsonc ------------------------------------- json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) print(json)
The ts_tree_select<-() replacement
function works similarly to the combination of
ts_tree_select() and
ts_tree_update(), but
it might be more readable.
ts_tree_select(tree, ...) <- valuets_tree_select(tree, ...) <- value
tree |
A |
... |
Selection expressions, see |
value |
An R expression to serialize or
|
The following two expressions are equivalent:
tree <- ts_tree_select(tree, <selectors>) |> ts_tree_update(value)
and
ts_tree_select(tree, <selectors>) <- value
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
ts_tree_select(json, "b", 1) <- 100 json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [100, 20, 30], "c": { "c1": true, "c2": null } }
ts_tree_deleted() is a special marker to delete elements from a
ts_tree object with ts_tree_select<- or the double bracket operator.
A ts_tree object with the selected parts updated.
ts_tree_deleted() returns a marker object to be used at the right
hand side of the ts_tree_select<- or the double bracket replacement
functions, see examples below.
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree ts_tree_select(tree, "a") <- 42 ts_tree_select(tree, "b", -1) <- ts_tree_deleted() tree# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree ts_tree_select(tree, "a") <- 42 ts_tree_select(tree, "b", -1) <- ts_tree_deleted() tree
The ts package contains a common interface to several tree-sitter
parsers, implemented in other R packages. ts_list_parsers() lists
the available parsers installed in the system.
ts_list_parsers(lib_path = .libPaths())ts_list_parsers(lib_path = .libPaths())
lib_path |
Library paths to search for installed packages.
Default is |
To see tree-sitter parser packages that are available on CRAN, but not installed on your system, see the packages that depend on ts and have a name with a 'ts' prefix.
Here is an example that includes all tree-sitter parsers at this time:
ts_list_parsers()
#> Error in ts_list_parsers() : could not find function "ts_list_parsers"
A data frame with columns:
package: character, the name of the package.
version: character, the version of the package.
title: character, the title of the package.
library: character, the library path where the package is installed.
loaded: logical, whether the package is currently loaded.
ts_list_parsers()ts_list_parsers()
ts_tree_ast() prints the annotated syntax tree of a ts_tree object.
This syntax tree contains all tree-sitter nodes, and it shows the
source code associated with each node, along with line numbers.
This is the manual page of the ts_tree_ast() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | |
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_ast(tree)ts_tree_ast(tree)
tree |
A |
This syntax tree contains all nodes of the tree-sitter parse tree, including both named and unnamed nodes and comments. E.g. for a JSON(C) document it includes the pairs, brackets, braces, commas, colons, double quotes and string escape sequences as separate nodes.
See tsitter::ts_tree_dom() for a tree that
shows the semantic structure of the parsed document, which may be
different from the syntax tree.
tree <- ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
ts_tree_ast(tree)
#> document (1) 1|
#> └─object (2) |
#> ├─{ (3) |{
#> ├─pair (4) |
#> │ ├─string (5) |
#> │ │ ├─" (6) | "
#> │ │ ├─string_content (7) | a
#> │ │ └─" (8) | "
#> │ ├─: (9) | :
#> │ └─true (10) | true
#> ├─, (11) | ,
#> ├─pair (12) |
#> │ ├─string (13) |
#> │ │ ├─" (14) | "
#> │ │ ├─string_content (15) | b
#> │ │ └─" (16) | "
#> │ ├─: (17) | :
#> │ └─array (18) |
#> │ ├─[ (19) | [
#> │ ├─number (20) | 1
#> │ ├─, (21) | ,
#> │ ├─number (22) | 2
#> │ ├─, (23) | ,
#> │ ├─number (24) | 3
#> │ └─] (25) | ]
#> └─} (26) | }
ts_tree_dom(tree)
#> document (1) #> └─object (2) #> ├─true (10) # a #> └─array (18) # b #> ├─number (20) #> ├─number (22) #> └─number (24)
Character vector, the formatted annotated syntax tree, line by line. It has class cli_tree, from the cli package. It may contain ANSI escape sequences for coloring and hyperlinks.
ts_tree_dom() to show the document object model (DOM) of a
ts_tree object.
Other ts_tree exploration:
ts_tree-brackets,
ts_tree_dom(),
ts_tree_query(),
ts_tree_sexpr()
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree ts_tree_ast(tree) ts_tree_dom(tree) # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 )") tree ts_tree_ast(tree) ts_tree_dom(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree ts_tree_ast(tree) ts_tree_dom(tree) # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 )") tree ts_tree_ast(tree) ts_tree_dom(tree)
Use ts_tree_select() to select the
elements to be deleted, and then call ts_tree_delete() to remove them
from the tree.
This is the manual page of the ts_tree_delete() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_delete(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. | ts_tree_delete(<ts_tree_tstoml>)
|
ts_tree_delete(tree, ...)ts_tree_delete(tree, ...)
tree |
A |
... |
Extra arguments for methods. |
The formatting of the rest of the document is left as is.
jsonc <- tsjsonc::ts_parse_jsonc(
"{ \"a\": true, \"b\": [1, 2, 3] }"
) |>
tsitter::ts_tree_format()
jsonc
#> # jsonc (8 lines) #> 1 | { #> 2 | "a": true, #> 3 | "b": [ #> 4 | 1, #> 5 | 2, #> 6 | 3 #> 7 | ] #> 8 | }
jsonc |> ts_tree_select("a") |> ts_tree_delete()
#> # jsonc (7 lines) #> 1 | { #> 2 | "b": [ #> 3 | 1, #> 4 | 2, #> 5 | 3 #> 6 | ] #> 7 | }
If the tree does not have a selection, the tree corresponding to the empty document is returned, i.e. the whole content is deleted.
jsonc <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
jsonc |> ts_tree_delete()
#> # jsonc (0 lines)
If the tree has a selection, but it is the empty selection, then the tree is returned unchanged.
jsonc <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
jsonc |> ts_tree_select("c") |> ts_tree_delete()
#> # jsonc (1 line) #> 1 | { "a": true, "b": [1, 2, 3] }
For parsers that support comments, deleting elements that include comments typically delete the comments as well. Other comments are kept as is. See details in the manual of the specific parser.
jsonc <- tsjsonc::ts_parse_jsonc(
"// top comment\n{ \"a\": // comment\n true,\n \"b\": [1, 2, 3] }"
) |> tsitter::ts_tree_format()
jsonc
#> # jsonc (11 lines) #> 1 | // top comment #> 2 | { #> 3 | "a": #> 4 | // comment #> 5 | true, #> 6 | "b": [ #> 7 | 1, #> 8 | 2, #> 9 | 3 #> 10 | ] #> ℹ 1 more line #> ℹ Use `print(n = ...)` to see more lines
jsonc |> ts_tree_select("a") |> ts_tree_delete()
#> # jsonc (8 lines) #> 1 | // top comment #> 2 | { #> 3 | "b": [ #> 4 | 1, #> 5 | 2, #> 6 | 3 #> 7 | ] #> 8 | }
The modified ts_tree object with the selected elements removed.
Methods in installed packages: ts_tree_delete(<ts_tree_tsjsonc>) and ts_tree_delete(<ts_tree_tstoml>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc( "{ \"a\": //comment\ntrue, \"b\": [1, 2, 3] }" ) tree tree |> ts_tree_select("a") tree |> ts_tree_select("a") |> ts_tree_delete() # 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" } )") tree tree |> ts_tree_select("servers", TRUE, "dc") tree |> ts_tree_select("servers", TRUE, "dc") |> ts_tree_delete()# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc( "{ \"a\": //comment\ntrue, \"b\": [1, 2, 3] }" ) tree tree |> ts_tree_select("a") tree |> ts_tree_select("a") |> ts_tree_delete() # 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" } )") tree tree |> ts_tree_select("servers", TRUE, "dc") tree |> ts_tree_select("servers", TRUE, "dc") |> ts_tree_delete()
ts_tree_dom() prints the document object model (DOM) tree of a ts_tree
object. This tree only includes semantic elements. E.g. for a JSON(C)
document it includes objects, arrays and various value types, but not
the syntax elements like brackets, commas or colons.
This is the manual page of the ts_tree_dom() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | |
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_dom(tree)ts_tree_dom(tree)
tree |
A |
See ts_tree_ast() for the complete
tree-sitter syntax tree that includes all nodes, including syntax
elements like brackets and commas.
tree <- ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
ts_tree_ast(tree)
#> document (1) 1|
#> └─object (2) |
#> ├─{ (3) |{
#> ├─pair (4) |
#> │ ├─string (5) |
#> │ │ ├─" (6) | "
#> │ │ ├─string_content (7) | a
#> │ │ └─" (8) | "
#> │ ├─: (9) | :
#> │ └─true (10) | true
#> ├─, (11) | ,
#> ├─pair (12) |
#> │ ├─string (13) |
#> │ │ ├─" (14) | "
#> │ │ ├─string_content (15) | b
#> │ │ └─" (16) | "
#> │ ├─: (17) | :
#> │ └─array (18) |
#> │ ├─[ (19) | [
#> │ ├─number (20) | 1
#> │ ├─, (21) | ,
#> │ ├─number (22) | 2
#> │ ├─, (23) | ,
#> │ ├─number (24) | 3
#> │ └─] (25) | ]
#> └─} (26) | }
ts_tree_dom(tree)
#> document (1) #> └─object (2) #> ├─true (10) # a #> └─array (18) # b #> ├─number (20) #> ├─number (22) #> └─number (24)
Character vector, the formatted annotated syntax tree, line by line. It has class cli_tree, from the cli package. It may contain ANSI escape sequences for coloring and hyperlinks.
ts_tree_ast() to show the annotated syntax tree of a
ts_tree object.
Other ts_tree exploration:
ts_tree-brackets,
ts_tree_ast(),
ts_tree_query(),
ts_tree_sexpr()
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree ts_tree_ast(tree) ts_tree_dom(tree) # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 )") tree ts_tree_ast(tree) ts_tree_dom(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree ts_tree_ast(tree) ts_tree_dom(tree) # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 )") tree ts_tree_ast(tree) ts_tree_dom(tree)
(Re)format the selected elements of the document represented by a tree-sitter tree, if the tree-sitter parser supports formatting.
This is the manual page of the ts_tree_format() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_format(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. | ts_tree_format(<ts_tree_tstoml>)
|
ts_tree_format(tree, options, ...)ts_tree_format(tree, options, ...)
tree |
A |
options |
A list of options for the formatting. See details in the manual of the specific parser. |
... |
Extra arguments for methods. |
If tree does not have a selection, then the whole document is
formatted.
jsonc <- tsjsonc::ts_parse_jsonc("{ \"a\": [1,2,3] }")
jsonc |> ts_tree_format()
#> # jsonc (7 lines) #> 1 | { #> 2 | "a": [ #> 3 | 1, #> 4 | 2, #> 5 | 3 #> 6 | ] #> 7 | }
If tree has an empty selection, then it is returned unchanged.
jsonc <- tsjsonc::ts_parse_jsonc("{ \"a\": [1,2,3] }")
jsonc |> ts_tree_select("c") |> ts_tree_format()
#> # jsonc (1 line) #> 1 | { "a": [1,2,3] }
Some parsers support options to customize the formatting. See details in the manual of the specific parser.
jsonc <- tsjsonc::ts_parse_jsonc("{ \"a\": [1,2,3] }") |>
ts_tree_format()
jsonc |> ts_tree_select(TRUE) |> ts_tree_format(options = list(format = "oneline"))
#> # jsonc (3 lines) #> 1 | { #> 2 | "a": [ 1, 2, 3 ] #> 3 | }
The ts_tree object of the reformatted document.
Methods in installed packages: ts_tree_format(<ts_tree_tsjsonc>) and ts_tree_format(<ts_tree_tstoml>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{ "a":true, "b": [1,2,3] }') tree # Format whole document tree |> ts_tree_format() # Format each top element under the document node in one line tree |> ts_tree_format() |> ts_tree_select(TRUE) |> ts_tree_format(options = list(format = "oneline")) # 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" } )") tree tree |> ts_tree_format()# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{ "a":true, "b": [1,2,3] }') tree # Format whole document tree |> ts_tree_format() # Format each top element under the document node in one line tree |> ts_tree_format() |> ts_tree_select(TRUE) |> ts_tree_format(options = list(format = "oneline")) # 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" } )") tree tree |> ts_tree_format()
Insert a new element into each selected element.
This is the manual page of the ts_tree_insert() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_insert(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_insert(tree, new, key, at, options, ...)ts_tree_insert(tree, new, key, at, options, ...)
tree |
A |
new |
The new element to insert. The type of |
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. |
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:
See the details in the manual of the specific parser. |
options |
A list of options for the insertion. See details in the manual of the specific parser. |
... |
Extra arguments for methods. |
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.
json <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
json |> ts_tree_select("a") |> ts_tree_insert("foo")
#> Cannot insert into a 'true' JSON element. Can only insert into 'array' and 'ob #> ject' elements and empty JSON documents.
If tree does not have a selection, the new element is inserted into
at the top level.
json <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
json |> ts_tree_insert(key = "c", new = "foo")
#> # jsonc (9 lines) #> 1 | { #> 2 | "a": true, #> 3 | "b": [ #> 4 | 1, #> 5 | 2, #> 6 | 3 #> 7 | ], #> 8 | "c": "foo" #> 9 | }
If tree has an empty selection, then it is returned unchanged, i.e.
no new element is inserted.
json <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
json |> ts_tree_select("nonexistent") |> ts_tree_insert("foo")
#> # jsonc (1 line, 0 selected elements) #> 1 | { "a": true, "b": [1, 2, 3] }
A ts_tree object representing the modified parse tree.
Method in installed package: ts_tree_insert(<ts_tree_tsjsonc>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{ "a": true, "b": [1, 2, 3] }') tree |> ts_tree_select("b") |> ts_tree_insert(4, at = Inf) # 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" } )") tree |> ts_tree_select("servers", TRUE) |> ts_tree_insert(key = "active", TRUE)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{ "a": true, "b": [1, 2, 3] }') tree |> ts_tree_select("b") |> ts_tree_insert(4, at = Inf) # 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" } )") tree |> ts_tree_select("servers", TRUE) |> ts_tree_insert(key = "active", TRUE)
This function are for packages implementing new parsers based on the ts package. It is very unlikely that you will need to call this function directly.
ts_tree_mark_selection1(tree, node) ## S3 method for class 'ts_tree' ts_tree_mark_selection1(tree, node)ts_tree_mark_selection1(tree, node) ## S3 method for class 'ts_tree' ts_tree_mark_selection1(tree, node)
tree |
Tree-sitter tree. |
node |
Node id, integer scalar. |
In parsers where AST nodes do not correspond one-to-one to DOM nodes it is useful to highlight multiple AST nodes for a single selected DOM node. This generic function can be overridden in such parsers to return multiple AST node ids for a single selected (DOM) node id.
The default implementation simply returns the input node id.
Integer vector of node ids to highlight.
# This is an internal generic for parser implementations, see the # tsjsonc and tstoml packages for examples of methods implementing # custom behavior.# This is an internal generic for parser implementations, see the # tsjsonc and tstoml packages for examples of methods implementing # custom behavior.
This is the main function to create a tree-sitter parse tree, using a
ts parser implemented in another package.
The result is a ts_tree object. A ts_tree object may be queried,
edited, formatted, written to file, etc. using ts_tree methods.
| Package | Version | Loaded | Title |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. |
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_new( language, file = NULL, text = NULL, ranges = NULL, fail_on_parse_error = TRUE, ... )ts_tree_new( language, file = NULL, text = NULL, ranges = NULL, fail_on_parse_error = TRUE, ... )
language |
Language of the file or string, a |
file |
Path of a file to parse. Use either |
text |
String to parse. Use either |
ranges |
Can be used to parse part(s) of the input. It must be a data frame with
integer columns |
fail_on_parse_error |
Logical, whether to error if there are parse errors in the document.
Default is |
... |
Additional arguments for methods. |
A package that implements a tree-sitter parser provides a function that
creates a ts_language object for that parser. E.g.
tsjsonc has tsjsonc::ts_language_jsonc().
You need to use the returned ts_language object as the language
argument of ts_tree_new().
jsonc <- tsitter::ts_tree_new(
tsjsonc::ts_language_jsonc(),
text = "{ \"a\": true, // comment\n \"b\": [1, 2, 3], }"
)
jsonc
#> # jsonc (2 lines) #> 1 | { "a": true, // comment #> 2 | "b": [1, 2, 3], }
A ts_tree object representing the parse tree of the input. You can
use the single bracket '['
operator to convert it to a data frame.
The tree-sitter parser packages typically include shortcuts to
create parse trees from strings and file, e.g.
tsjsonc::ts_parse_jsonc() and tsjsonc::ts_read_jsonc().
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# JSONC example, needs the tsjsonc package ----------------------------- json <- ts_tree_new( tsjsonc::ts_language_jsonc(), text = '{ "a": 1, "b": 2 }' ) json json |> ts_tree_format() # TOML example, needs the tstoml package ------------------------------- toml <- ts_tree_new( tstoml::ts_language_toml(), text = '[section]\nkey = "value"\nnumber = 42\n' ) toml toml |> ts_tree_format()# JSONC example, needs the tsjsonc package ----------------------------- json <- ts_tree_new( tsjsonc::ts_language_jsonc(), text = '{ "a": 1, "b": 2 }' ) json json |> ts_tree_format() # TOML example, needs the tstoml package ------------------------------- toml <- ts_tree_new( tstoml::ts_language_toml(), text = '[section]\nkey = "value"\nnumber = 42\n' ) toml toml |> ts_tree_format()
Use tree-sitter's query language to find nodes in a tree-sitter tree.
This is the manual page of the ts_tree_query() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_query(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. | ts_tree_query(<ts_tree_tstoml>)
|
ts_tree_query(tree, query)ts_tree_query(tree, query)
tree |
A |
query |
Character string, the tree-sitter query to run. |
You probably need to know some details about the specific tree-sitter parser you are using, to write effective queries. See the documentation of the parser package you are using for details about the node types and the query language support. See links below.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }'
)
json |> ts_tree_query("(number) @number")
#> $patterns #> # A data frame: 1 × 4 #> id name pattern match_count #> <int> <chr> <chr> <int> #> 1 1 NA "(number) @number\n" 5 #> #> $captures #> # A data frame: 1 × 2 #> id name #> <int> <chr> #> 1 1 number #> #> $matched_captures #> # A data frame: 5 × 12 #> id pattern match type start_byte end_byte start_row start_column #> <int> <int> <int> <chr> <int> <int> <int> <int> #> 1 1 1 1 numb… 7 8 0 7 #> 2 1 1 2 numb… 16 18 0 16 #> 3 1 1 3 numb… 20 22 0 20 #> 4 1 1 4 numb… 24 26 0 24 #> 5 1 1 5 numb… 54 57 0 54 #> # ℹ 4 more variables: end_row <int>, end_column <int>, name <chr>, #> # code <chr> #>
A list with entries patterns and matched_captures.
patterns contains information about all patterns in the queries and
it is a data frame with columns: id, name, pattern, match_count.
matched_captures contains information about all matches, and it has
columns id, pattern, match, start_byte, end_byte, start_row,
start_column, end_row, end_column, name, code.
The pattern column of matched_captured refers to the id column of
patterns.
ts_tree_select() to select the nodes matching a query.
Methods in installed packages: ts_tree_query(<ts_tree_tsjsonc>) and ts_tree_query(<ts_tree_tstoml>).
Other ts_tree exploration:
ts_tree-brackets,
ts_tree_ast(),
ts_tree_dom(),
ts_tree_sexpr()
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Select all numbers in a JSONC document ------------------------------------ json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) json |> ts_tree_query("(number) @number")# Select all numbers in a JSONC document ------------------------------------ json <- tsjsonc::ts_parse_jsonc( '{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }' ) json |> ts_tree_query("(number) @number")
This function is the heart of ts. To edit a tree-sitter tree, you first need to select the parts you want to delete or update.
This is the manual page of the ts_tree_select() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_select(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. | ts_tree_select(<ts_tree_tstoml>)
|
ts_tree_select(tree, ..., refine = FALSE)ts_tree_select(tree, ..., refine = FALSE)
tree |
A |
... |
Selection expressions, see details. |
refine |
Logical, whether to refine the current selection or start a new selection. |
The selection process is iterative. Selection expressions (selectors) are applied one by one, and each selector selects nodes from the currently selected nodes. For each selector, it is applied individually to each currently selected node, and the results are concatenated.
The selection process starts from the root of the DOM tree, the document
node (see ts_tree_dom()), unless
refine = TRUE is set, in which case it starts from the current
selection.
See the various types of selection expressions below.
TRUE
Selects all child nodes of the current nodes.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select(c("b", "c"), TRUE)
#> # jsonc (1 line, 5 selected elements) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
Selects child nodes with the given names from nodes with named children. If a node has no named children, it selects nothing from that node.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select(c("a", "c"), c("c1"))
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
Selects child nodes by position. Positive indices count from the start, negative indices count from the end. Zero indices are not allowed.
For JSONC positional indices can be used both for arrays and objects. For other nodes nothing is selected.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select(c("b", "c"), -1)
#> # jsonc (1 line, 2 selected elements) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
A character scalar named regex can be used to select child nodes
whose names match the given regular expression, from nodes with named
children. If a node has no named children, it selects nothing from that
node.
json <- tsjsonc::ts_parse_jsonc(
'{ "apple": 1, "almond": 2, "banana": 3, "cherry": 4 }'
)
json |> ts_tree_select(regex = "^a")
#> # jsonc (1 line, 2 selected elements) #> > 1 | { "apple": 1, "almond": 2, "banana": 3, "cherry": 4 }
A character scalar named query can be used to select nodes matching
a tree-sitter query. See ts_tree_query()
for details on tree-sitter queries.
Instead of a character scalar this can also be a two-element list, where the first element is the query string and the second element is a character vector of capture names to select. In this case only nodes matching the given capture names will be selected.
See ts_language_jsonc() for
details on the JSONC grammar.
This example selects all numbers in the JSON document.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }'
)
json |> ts_tree_select(query = "(number) @number")
#> # jsonc (1 line, 5 selected elements) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": 100 } }
You can use I(c(...)) to select nodes by their ids directly. This is
for advanced use cases only.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
ts_tree_dom(json)
#> document (1) #> └─object (2) #> ├─number (10) # a #> ├─array (18) # b #> │ ├─number (20) #> │ ├─number (22) #> │ └─number (24) #> └─object (33) # c #> ├─true (41) # c1 #> └─null (49) # c2
json |> ts_tree_select(I(18))
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
If the refine argument of
ts_tree_select() is TRUE, then
the selection starts from the already selected elements (all of them
simultanously), instead of starting from the document element.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json <- json |> ts_tree_select(c("b", "c"))
json |> ts_tree_select(1:2)
#> # jsonc (1 line, 2 selected elements) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json |> ts_tree_select(1:2, refine = TRUE)
#> # jsonc (1 line, 4 selected elements) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
ts_tree_select<-() replacement functionThe ts_tree_select<-() replacement
function works similarly to the combination of
ts_tree_select() and
ts_tree_update(), but it might be more
readable.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
ts_tree_select(json, "b", 1) <- 100 json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [100, 20, 30], "c": { "c1": true, "c2": null } }
[[ and [[<- operatorsThe [[ operator works similarly to the combination of
ts_tree_select() and
ts_tree_unserialize(), but it
might be more readable.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json[[list("b", 1)]]
#> [[1]] #> [1] 10 #>
The [[<- operator works similarly to the combination of
ts_tree_select() and
ts_tree_update(), (and also to the
replacement function ts_tree_select<-()),
but it might be more readable.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json[[list("b", 1)]] <- 100
json
#> # jsonc (1 line) #> 1 | { "a": 1, "b": [100, 20, 30], "c": { "c1": true, "c2": null } }
A ts_tree object with the selected parts.
Methods in installed packages: ts_tree_select(<ts_tree_tsjsonc>) and ts_tree_select(<ts_tree_tstoml>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# ---------------------------------------------------------------------- # Create a JSONC tree, needs the tsjsonc package json <- ts_tree_new( tsjsonc::ts_language_jsonc(), text = '{ "a": 1, "b": 2, "c": { "d": 3, "e": 4 } }' ) json |> ts_tree_select("c", "d") # ---------------------------------------------------------------------- # Create a TOML tree, needs the tstoml package toml <- ts_tree_new( tstoml::ts_language_toml(), text = tstoml::toml_example_text() ) toml |> ts_tree_select("servers", TRUE, "ip")# ---------------------------------------------------------------------- # Create a JSONC tree, needs the tsjsonc package json <- ts_tree_new( tsjsonc::ts_language_jsonc(), text = '{ "a": 1, "b": 2, "c": { "d": 3, "e": 4 } }' ) json |> ts_tree_select("c", "d") # ---------------------------------------------------------------------- # Create a TOML tree, needs the tstoml package toml <- ts_tree_new( tstoml::ts_language_toml(), text = tstoml::toml_example_text() ) toml |> ts_tree_select("servers", TRUE, "ip")
This function is for packages implementing new parsers based on the ts package. It is very unlikely that you will need to call this function directly.
ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_default' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.NULL' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_ids' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_tsquery' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.character' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.integer' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.numeric' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_regex' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.logical' ts_tree_select1(tree, node, slt)ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_default' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.NULL' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_ids' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_tsquery' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.character' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.integer' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.numeric' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.ts_tree_selector_regex' ts_tree_select1(tree, node, slt) ## S3 method for class 'ts_tree.logical' ts_tree_select1(tree, node, slt)
tree |
A |
node |
Integer scalar, the node id to select from. |
slt |
A selector object, see details in |
A parser package may implement methods for this generic to change the
behavior of ts_tree_select() for a
certain selector type, or even add new selector types.
Each new method should be named as
ts_tree_select.<ts_tree_class>.<selector_class>
The ts package implement deault methods for the selector types described
in the ts_tree_select() manual page.
ts_tree_selector_default selectorMethod: ts_tree_select1.ts_tree.ts_tree_selector_default
This method is used to select the default element(s), when there is no selected element. E.g. when starting a new selection from the root of the DOM tree.
The default implementation returns the ids of all children of the document root in the AST, except comments. If there are no such children, it returns the id of the document root of the AST itself (always id 1).
NULL selectorMethod: ts_tree_select1.ts_tree.NULL
This method is used for the NULL selector, that is supposed to
clear the selection. You probably do not need to override this method.
The default implementation returns an empty integer vector.
ts_tree_selector_ids selectorMethod: ts_tree_select1.ts_tree.ts_tree_selector_ids
This method is used to select nodes by their ids directly. You probably do not need to override this method. The default implementation returns the ids stored in the selector.
This behaviour may change in the future to select only nodes in the subtree of the current node.
ts_tree_selector_tsquery selectorMethod: ts_tree_select1.ts_tree.ts_tree_selector_tsquery
This method is used to select nodes matching a tree-sitter query. You probably do not need to override this method. The default implementation returns the ids stored in the selector.
This behaviour may change in the future to select only nodes in the subtree of the current node.
character (character vector) selectorMethod: ts_tree_select1.ts_tree.character
This method is used when the selector is a character vector.
The default implementation selects DOM children of node whose names
are in the character vector. If not all children o node are named,
it returns an empty integer vector. (E.g. in a JSONC document it returns
an empty integer vector when nodes is an array.)
integer (integer vector) selectorMethod: ts_tree_select1.ts_tree.integer
This method is used when the selector is an integer vector.
The default implementation selects DOM children of node by position.
Positive indices count from the start, negative indices count from the
end. Zero indices are not allowed and an error is raised if any are
used.
numeric (numeric, double vector) selectorMethod: ts_tree_select1.ts_tree.numeric
This method is used when the selector is a numeric (double) vector. It currrently coerces the numeric vector to integer and calls the integer method.
ts_tree_selector_regex (regular expression) selectorMethod: ts_tree_select1.ts_tree.ts_tree_selector_regex
This method is used when the selector is a regular expression.
The default implementation selects DOM children of node whose names
match the regular expression. If not all children o node are named,
it returns an empty integer vector. (E.g. in a JSONC document it
returns an empty integer vector when nodes is an array.)
logical (logical vector) selectorMethod: ts_tree_select1.ts_tree.logical
This method is used when the selector is a logical vector.
The default implementation only supports scalar TRUE, which selects
all DOM children of node. Other values raise an error.
Must return an integer vector of selected node ids.
# This is an internal generic for parser implementations, see the # tsjsonc and tstoml packages for examples of methods implementing # selector types.# This is an internal generic for parser implementations, see the # tsjsonc and tstoml packages for examples of methods implementing # selector types.
These functions are for packages implementing new parsers based on the ts package. It is very unlikely that you will need to call these functions directly.
ts_tree_selection(tree, default = TRUE) ts_tree_selected_nodes(tree, default = TRUE)ts_tree_selection(tree, default = TRUE) ts_tree_selected_nodes(tree, default = TRUE)
tree |
A |
default |
Logical, whether to return the default selection if there
is no explicit selection, or |
ts_tree_selection() returns the current selection, as a list
of selectors.
ts_tree_selected_nodes() returns the ids of the currently
selected nodes.
ts_tree_selection() returns a list of selection records.
ts_tree_selected_nodes() returns the ids of the currently
selected nodes.
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree <- ts_tree_select(tree, "b", -1) ts_tree_selection(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree <- ts_tree_select(tree, "b", -1) ts_tree_selection(tree)
Show the structure of a tree-sitter tree as an S-expression.
This is the manual page of the ts_tree_sexpr() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | |
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_sexpr(tree)ts_tree_sexpr(tree)
tree |
A |
This function returns a nested list representation of the syntax tree, where each node is represented as a list with its type and children.
A string representing the S-expression of the syntax tree.
Other ts_tree exploration:
ts_tree-brackets,
ts_tree_ast(),
ts_tree_dom(),
ts_tree_query()
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_unserialize(),
ts_tree_update(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc( "{ \"a\": //comment\ntrue, \"b\": [1, 2, 3] }" ) ts_tree_sexpr(tree) # 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_sexpr(tree)# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc( "{ \"a\": //comment\ntrue, \"b\": [1, 2, 3] }" ) ts_tree_sexpr(tree) # 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_sexpr(tree)
Unserialize the selected elements of a ts_tree object, i.e. convert
them to R objects.
This is the manual page of the ts_tree_unserialize() S3 generic function.
Methods in parser packages may override this generic.
For the ones that do see the links to their manual pages in the table.
| Package | Version | Loaded | Title | Method |
| tsjsonc | 0.0.0.9000 | no | Edit JSON Files. | ts_tree_unserialize(<ts_tree_tsjsonc>)
|
| tstoml | 0.0.0.9000 | no | Edit TOML Files. |
ts_tree_unserialize(tree)ts_tree_unserialize(tree)
tree |
A |
If no elements are selected in the tree, then the whole document is unserialized.
tree <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
ts_tree_unserialize(tree)
#> [[1]] #> [[1]]$a #> [1] TRUE #> #> [[1]]$b #> [[1]]$b[[1]] #> [1] 1 #> #> [[1]]$b[[2]] #> [1] 2 #> #> [[1]]$b[[3]] #> [1] 3 #> #> #>
If the tree has an empty selection, then an empty list is returned.
tree <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
tree |> ts_tree_select("nope") |> ts_tree_unserialize()
#> list()
[[ operatorThe [[ operator works similarly to the combination of
ts_tree_select() and
ts_tree_unserialize(), but it might be more readable.
json <- tsjsonc::ts_parse_jsonc(
'{ "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }'
)
json |> ts_tree_select("b", 1)
#> # jsonc (1 line, 1 selected element) #> > 1 | { "a": 1, "b": [10, 20, 30], "c": { "c1": true, "c2": null } }
json[[list("b", 1)]]
#> [[1]] #> [1] 10 #>
For the details on how the selected elements are mapped to R objects, see the documentation of the methods in the parser packages. The methods in the installed parser packages are linked below.
List of R objects, with one entry for each selected element.
Method in installed package: ts_tree_unserialize(<ts_tree_tsjsonc>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_update(),
ts_tree_write()
Other serialization functions:
[[.ts_tree()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree |> ts_tree_select(c("b", "c")) |> ts_tree_unserialize() tree |> ts_tree_select("b") |> ts_tree_unserialize()# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"a": 13, "b": [1, 2, 3], "c": "x"}') tree tree |> ts_tree_select(c("b", "c")) |> ts_tree_unserialize() tree |> ts_tree_select("b") |> ts_tree_unserialize()
Replace all selected elements with a new element.
ts_tree_update(tree, new, options, ...)ts_tree_update(tree, new, options, ...)
tree |
A |
new |
The new element to replace the selected elements with. The type of |
options |
A list of options for the update. See details in the manual of the specific parser. |
... |
Extra arguments for methods. |
If the tree does not have a selection, the new element replaces the whole document.
tree <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
tree |> ts_tree_update(as.list(4:6))
#> # jsonc (5 lines) #> 1 | [ #> 2 | 4, #> 3 | 5, #> 4 | 6 #> 5 | ]
If the tree has an empty selection, the new element is inserted at the position of where the selected elements would be.
tree <- tsjsonc::ts_parse_jsonc("{ \"a\": true, \"b\": [1, 2, 3] }")
tree |> ts_tree_select("new") |> ts_tree_update(as.list(4:6))
#> # jsonc (13 lines) #> 1 | { #> 2 | "a": true, #> 3 | "b": [ #> 4 | 1, #> 5 | 2, #> 6 | 3 #> 7 | ], #> 8 | "new": [ #> 9 | 4, #> 10 | 5, #> ℹ 3 more lines #> ℹ Use `print(n = ...)` to see more lines
The modified ts_tree object with the selected elements replaced
by the new element.
Methods in installed packages: ts_tree_update(<ts_tree_tsjsonc>) and ts_tree_update(<ts_tree_tstoml>).
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_write()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc(r"( { "name": "example", "version": "1.0.0", "dependencies": { "tsjsonc": "^0.1.0" } } )") tree |> ts_tree_select("version") |> ts_tree_update("2.0.0") # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( [package] name = "example" version = "1.0.0" depdendencies = { tstoml = "0.1.0" } )") tree |> ts_tree_select("package", "version") |> ts_tree_update("2.0.0")# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc(r"( { "name": "example", "version": "1.0.0", "dependencies": { "tsjsonc": "^0.1.0" } } )") tree |> ts_tree_select("version") |> ts_tree_update("2.0.0") # Create a parse tree with tstoml -------------------------------------- tree <- tstoml::ts_parse_toml(r"( [package] name = "example" version = "1.0.0" depdendencies = { tstoml = "0.1.0" } )") tree |> ts_tree_select("package", "version") |> ts_tree_update("2.0.0")
Writes the document of a ts ts_tree object to a file or connection.
ts_tree_write(tree, file = NULL)ts_tree_write(tree, file = NULL)
tree |
A |
file |
Character string, connection, or |
If tree was created from a file, then ts_tree_write() by default
writes it back to the same file. Otherwise, the file argument must be
specified.
Format a JSONC file:
tree <- tsjsonc::ts_read_jsonc("config.json")
tree |> ts_tree_format() |> ts_tree_write()
To write to a connection, pass a connection object to the file
argument. If the connection is opened in binary mode, the raw bytes
are written using base::writeBin(). Otherwise, the raw bytes are
converted to characters using the system encoding before writing using
base::rawToChar().
Use file = stdout() to write to the standard output, i.e. to the
console in an interactive R session.
Invisibly returns NULL.
Other ts_tree generics:
[[.ts_tree(),
[[<-.ts_tree(),
format.ts_tree(),
print.ts_tree(),
select-set,
ts_tree_ast(),
ts_tree_delete(),
ts_tree_dom(),
ts_tree_format(),
ts_tree_insert(),
ts_tree_new(),
ts_tree_query(),
ts_tree_select(),
ts_tree_sexpr(),
ts_tree_unserialize(),
ts_tree_update()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') # Format and write to file tree |> ts_tree_format() |> ts_tree_write("example.json")# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') # Format and write to file tree |> ts_tree_format() |> ts_tree_write("example.json")
Create a data frame for the syntax tree of a JSON document, by indexing a ts_tree object with single brackets. This is occasionally useful for exploration and debugging.
## S3 method for class 'ts_tree' x[i, j, drop = FALSE]## S3 method for class 'ts_tree' x[i, j, drop = FALSE]
x |
A |
i, j
|
Incides, passed to the regular data.frame indexing method, see
|
drop |
Passed to the regular data.frame indexing method, see
|
A tree-sitter tree object has at least four classes:
ts_tree_<parser_name>, e.g. ts_tree_tsjsonc,
ts_tree,
tbl, from the pillar package, for better printing when converted
to a data frame, and
data.frame, since it is a data frame internally.
The ts_tree class has custom format() and print() methods, that
show (part of) the underlying document, and also the selected elements,
if any.
It is sometimes useful to treat a tree ts_tree object as a data
frame, and drop the ts_tree classes. This can be done by indexing with
single brackets, e.g. tree[]. This returns a data frame with one
row per token, and various columns with information about the tokens.
See details in the 'Value' section or this page.
A data frame with one row per token, and columns:
id: integer, the id of the token. The (root) document node has id 1.
parent: integer, the id of the parent token. The root token has
parent NA
field_name: character, the field name of the token in its parent.
type: character, the type of the token.
code: character, the actual code of the token.
start_byte, end_byte: integer, the byte positions of the token
in the input.
start_row, start_column, end_row, end_column: integer, the
position of the token in the input.
is_missing: logical, whether the token is a missing token added by
the parser to recover from errors.
has_error: logical, whether the token has a parse error.
children: list of integer vectors, the ids of the children tokens.
dom_type: character, the type of the node in the DOM tree. See
ts_tree_dom(). Nodes that are not part
of the DOM tree have NA_character_ here.
dom_children: list of integer vectors, the ids of the children in the
DOM tree. See ts_tree_dom().
dom_parent: integer, the parent of the node in the DOM tree. See
ts_tree_dom(). Nodes that are not part
of the DOM tree and the document node have have NA_integer_ here.
Other, undocumented columns may also be present, these are considered internal and may change without notice.
Other ts_tree exploration:
ts_tree_ast(),
ts_tree_dom(),
ts_tree_query(),
ts_tree_sexpr()
# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree tree[]# Create a parse tree with tsjsonc ------------------------------------- tree <- tsjsonc::ts_parse_jsonc('{"foo": 42, "bar": [1, 2, 3]}') tree tree[]