The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.