tsitter

Common tree-sitter parsing tools for R.

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.

Installation

Install tsitter from CRAN:

install.packages("tsitter")

Documentation

See at https://r-lib.github.io/tsitter/ and also in the installed package: help(package = "tsitter").

Parsers that use tsitter

• JSONC (JSON with comments and trailing commas): tsjsonc.
• TOML: tstoml.

Quickstart

In this document I show examples with the tsjsonc package.

Create a tree-sitter tree

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

Select nodes of a tree

Selecting nodes is the basis of editing and querying tree-sitter trees.

Select element by objects key:

ts_tree_select(json, "a")

Select element inside element:

ts_tree_select(json, "a", "a1")

Select element(s) of an array:

ts_tree_select(json, "a", "a1", 1:2)

Select multiple keys from an object:

ts_tree_select(json, "a", c("a1", "a2"))

Select nodes that match a tree-sitter query:

json |> ts_tree_select(query = "((pair value: (false) @val))")

Delete elements

Delete selected elements:

ts_tree_select(json, "a", "a1") |> ts_tree_delete()

Insert elements

Insert element into an array:

ts_tree_select(json, "a", "a1") |> ts_tree_insert(at = 2, "new")

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"))

Update elements

Update existing element:

ts_tree_select(json, "a", c("a1", "a2")) |> ts_tree_update("new value")

Inserts the element if some parents are missing:

json <- ts_parse_jsonc(text = "{ \"a\": { \"b\": true } }")
json

ts_tree_select(json, "a", "x", "y") |> ts_tree_update(list(1,2,3))

Write out a document

Use stdout() to write it to the screen instread of a file:

json |> ts_tree_write(stdout())

Formatting

Format the whole document:

json |> ts_tree_format()

Format part of the document:

json |> ts_tree_select("a") |>
  ts_tree_format(options = list(format = "compact"))

Unserializing

Unserialize a whole document:

json |> 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()

Again, ts_tree_unserialize() returns a list, with one element for each selected node.

Exploring a tree-sitter tree

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)

Print the document object model:

ts_tree_dom(json)

Print the structural summary of a tree:

ts_tree_sexpr(json)

License

MIT © Posit Software, PBC