Build an empty array of tables header node ([[path.to.table]]\n).

cst.build_array_of_tables(["plugins"])  // -> [[plugins]]
cst.build_array_of_tables(["app", "hooks"])  // -> [[app.hooks]]

builder

Build comment trivia for attaching to a node via greenwood.set_trivia or similar. Leading comments appear on lines before the node; the trailing comment appears on the same line after the value.

cst.build_comment_trivia(
  leading: ["# Section start"],
  trailing: Some("inline note"),
)

builder

Build a key/value node for use inside inline tables (no trailing newline).

builder

Build a key/value node with standard formatting (key = value\n).

The key will be quoted if necessary. The value should be produced via value.to_cst.

cst.build_kv(key: "host", value: value.to_cst(value.string("localhost")))

builder

Build an empty table header node ([path.to.table]\n).

cst.build_table(["settings"])  // -> [settings]
cst.build_table(["database", "connection"])  // -> [database.connection]

builder

Delete the node at the given path. Returns the modified root. Works for key/values, tables, and array of table entries.

cst.delete(example, [KeySegment("plugins"), IndexSegment(0)])
// -> plugins[0] (name = 'formatter') has been removed

cst.delete(example, [KeySegment("database"), KeySegment("connection")])
// -> All of database.connection has been removed

edit

Delete a node at path matching a predicate.

cst.delete_where(
  example,
  [KeySegment("database"), KeySegment("connection"), KeySegment("host")],
  fn(n) { cst.value_text(n) == "'prod'"}
)
// -> NotFound as database.connection.host is 'localhost'

edit

Read the document-head comments: the Root node’s own leading-trivia comment lines, returned verbatim (with the leading #). These are the comments that belong to the file rather than to any one statement.

comments

Read the document-tail comments: the leading-trivia comment lines of the PostScript tombstone, if the document has one (it has one exactly when trivia dangles after the final statement). Returns [] otherwise.

comments

Ensure a table or array of table exists at path. Creates it if missing. The new declaration is placed before any existing descendant headers so that parent tables always precede their children.

cst.ensure(example, path: [KeySegment("my app")], kind: types.Table)
// -> creates a new table header ["my app"] at the end of the document

cst.ensure(example, path: [KeySegment("database")], kind: types.Table)
// -> creates a new table header [database] before [database.connection]

edit

Extracts the concrete syntax tree from the parsed molt document.

conversion

Retrieves a child node at the given path relative to node.

cst.get(example, [])
// -> the document root itself

cst.get(example, [KeySegment("rating")])
// -> The `rating` key/value node from root

let assert Ok(plugins2) = cst.get(example, [KeySegment("plugins"), IndexSegment(1)])
// -> The second `plugins` entry.

cst.get(plugins2, [KeySegment("name")])
// -> The `name` key/value node from the second `plugins` entry.

query

Look up a node at path matching a predicate. Useful for disambiguating duplicate keys or selecting by node kind.

assert cst.get_where(example, [KeySegment("plugins")], fn(n) {
  list.contains(cst.list_keys(n), "options")
}) == cst.get(example, path: [KeySegment("plugins"), IndexSegment(-1)])

query

Insert an array of tables entry node into an existing [[array.of.tables]] group.

The array of tables entry must be located using into of only KeySegments to find the appropriate siblings to place the table in the correct location.

let entry = cst.build_array_of_tables(["plugins"])

// Append after the last [[plugins]].
insert_array_of_tables_entry(
  doc,
  into: [KeySegment("plugins")],
  entry:,
  at: EntryAtEnd
)

// Insert before the 2nd [[a.b]] entry.
insert_array_of_tables_entry(
  doc,
  into: [KeySegment("a"), KeySegment("b")],
  entry:,
  at: BeforeIndex(2)
)

edit

Insert a key/value node into a table-like container resolved by the into path segments.

The into target must be the document root ([]), a table declaration [KeySegment("x"), KeySegment("y")], or a specific array of tables entry ([KeySegment("a"), IndexSegment(2)]).

Local consistency checks prevent the insertion of a key/value node with a key name already present in the target table. If a key/value node is to be inserted Before a key that does not exist, an error result will be returned.

// Append, region-aware: lands before any [sub] headers.
insert_kv(doc, into: [KeySegment("database")], kv:, at: KvAtEnd)

// Before a named sibling key.
insert_kv(doc, into: [KeySegment("database")], kv:, at: BeforeKey("port"))

// Into a specific AoT entry.
insert_kv(doc, into: [KeySegment("a"), IndexSegment(2)], kv:, at: KvAtEnd)

edit

Inserts a table or array of tables node into the document, placing it before any existing descendant headers so that parent tables always precede their children.

let table = cst.build_table(path: ["database"])
cst.insert_table_node(example, table)
// -> Inserts a new table node before [database.connection]

edit

Get the key name from a key/value node.

let assert Ok(kv) = cst.get(example, [KeySegment("rating")])
assert Some("rating") == cst.key_name(kv)

query

Get leading comments attached to the node at path.

cst.leading_comments(
  example,
  [KeySegment("database"), KeySegment("connection"), KeySegment("host")]
)
// -> Ok(["# Default host is localhost"])

comments

List key names in a table (direct children only, no dotted key merging).

query

List all explicit table or array table paths that are immediate children of the provided node if it is a document or table node. Returns None if the node is neither the root of the tree nor a table.

let assert Some([
  ["database", "connection"],
  ["settings"],
  ["settings", "debug"],
  ["plugins"],
  ["plugins"],
  ["extensions"],
  ["app", "Microsoft Word", "options"],
]) = cst.list_tables(example)

query

Move a node from one path to another.

cst.move(
  example,
  from: [KeySegment("settings"), KeySegment("timeout")],
  to: [
    KeySegment("database"),
    KeySegment("connection"),
    KeySegment("connection_timeout")
  ],
)
// -> Moves settings.timeout to database.connection.connection_timeout

edit

Converts a path string into a list of path segments required by molt/cst functions, returning a InvalidPath if the path syntax is invalid.

The path format is fully documented in the molt module.

parse_path("a.b.c.d")
// -> [KeySegment("a"), KeySegment("b"), KeySegment("c"), KeySegment("d")]

parse_path("a.b.-1.d")
// -> [KeySegment("a"), KeySegment("b"), KeySegment("-1"), KeySegment("d")]

parse_path("a.b.\"with space\".d")
// -> [KeySegment("a"), KeySegment("b"), KeySegment("with space"), KeySegment("d")]

parse_path("a.b.\"\f\".'\\f'")
// -> [KeySegment("a"), KeySegment("b"), KeySegment("\f"), KeySegment("\\f")]

parse_path("a.b[-1].c")
// -> [KeySegment("a"), KeySegment("b"), IndexSegment(-1), KeySegment("c")]

parse_path("a.b[3].c")
// -> [KeySegment("a"), KeySegment("b"), IndexSegment(3), KeySegment("c")]

Rename the last segment of the path. Works for key/values, tables, and array of tables headers.

cst.rename(
  example,
  path: [KeySegment("plugins"), IndexSegment(1), KeySegment("name")],
  to: "id",
)
// -> renames plugins[1].name to plugins[1].id

cst.rename(
  example,
  path: [KeySegment("database"), KeySegment("connection")],
  to: "conn",
)
// -> renames [database.connection] to [database.conn]

edit

Replace the node at path with a new node.

let assert Ok(existing) =
  cst.get(example, path: [
    KeySegment("plugins"),
    IndexSegment(0),
    KeySegment("priority"),
  ])

let assert Ok(new_kv) =
  cst.set_kv_value(kv: existing, value: value.to_cst(value.int(10)))
cst.replace(
  example,
  path: [KeySegment("plugins"), IndexSegment(0), KeySegment("priority")],
  new: new_kv,
)
// -> changes plugins[0].priority to 10

edit

Replace the document-head comments on the Root node’s leading trivia, preserving a leading BOM. An empty list clears the comments (keeping the BOM). The blank line that separates the head comment from the first statement is added at emit time (see emitter.ensure_head_separation), so it tracks the document’s content and line-ending style rather than being baked in here.

comments

Replace the document-tail comments. A non-empty list materializes (or updates) the PostScript tombstone as the document’s last child; an empty list drops the tombstone entirely so no empty node lingers.

comments

Replace the value of a key/value pair node, preserving the key, surrounding whitespace, and any attached comments.

The value is a CST element produced from a value.Value with value.to_cst, so the replacement is a correctly-typed value node (integer, string, array, inline table, etc.). Build it from a value.Value rather than from raw text.

import molt/value

let assert Ok(existing) =
  cst.get(example, path: [
    KeySegment("plugins"),
    IndexSegment(0),
    KeySegment("priority"),
  ])

let assert Ok(new_kv) =
  cst.set_kv_value(kv: existing, value: value.to_cst(value.int(10)))

edit

Set leading comments on the node at path.

cst.set_leading_comments(
  example,
  path: [KeySegment("database"), KeySegment("connection"), KeySegment("port")],
  comments: ["Listen port"],
)
// -> Adds "# Listen port" before database.connection.port

comments

Set or clear the trailing comment on the node at path. Pass None to remove an existing trailing comment.

cst.set_trailing_comment(example, [KeySegment("rating")], Some("Higher!"))
// -> Adds "# Higher!" to rating

cst.set_trailing_comment(
  example,
  [KeySegment("enabled")],
  None
)
// -> Removes the comment from enabled.

comments

Recursively strip all comments from the tree.

cst.strip_all_comments(example)
// -> Removes all leading and trailing comments from the tree

comments

Converts the concrete syntax tree to a parsed TOML 1.1 document.

The tree is validated on conversion (counting any errors), so the resulting Document has an accurate error_count and is ready for the molt logical API. Inspect errors with molt.has_errors / molt.document_errors.

conversion

Converts the concrete syntax tree to a parsed TOML document using the specified TOML version.

The tree is validated on conversion (counting any errors), so the resulting Document has an accurate error_count and is ready for the molt logical API. Inspect errors with molt.has_errors / molt.document_errors.

conversion

Get the trailing comment on the node at path, if any.

cst.trailing_comment(example, [KeySegment("enabled")])
// -> Ok(Some("# Do we need this?"))

comments

Update the node at path via a transform function.

cst.update(example,
  path: [
    KeySegment("database"),
    KeySegment("connection"),
    KeySegment("port")
  ],
  with: fn(kv) {
    let assert Ok(updated) =
      cst.set_kv_value(kv:, value: value.to_cst(value.int(9090)))
    updated
  }
)
// -> Updates database.connection.port to 9090

edit

Update a node at path matching a predicate via a transform function.

cst.update_where(
  example,
  path: [KeySegment("database"), KeySegment("connection"), KeySegment("port")],
  where: fn(n) { cst.value_text(n) == "9999" },
  with: fn(n) {
    let assert Ok(updated) =
      cst.set_kv_value(kv: n, value: value.to_cst(value.int(9090)))
    updated
  },
)
// -> Returns not found because database.connection.port is 5432, not 9999.

edit

Get the raw value text from a key/value node.

let assert Ok(kv) = cst.get(example, [KeySegment("rating")])
assert "4.5" == cst.value_text(kv)

query

Returns a zipper focused on the first node matching the concrete path.

cst.zipper_at(example, [KeySegment("plugins"), IndexSegment(1)])
// -> a zipper focused on plugins[1]

cst.zipper_at(example:, [KeySegment("database"), KeySegment("connection"), KeySegment("port")])
// -> a zipper focused on database.connection.port

advanced

Returns a zipper for the given path using a predicate to disambiguate duplicate keys or node kind.

cst.zipper_where(
  example:,
  [KeySegment("database"), KeySegment("connection"), KeySegment("port")],
  fn(n) { cst.value_text(n) == "5432" },
)

// -> a zipper focused on database.connection.port

advanced