TOML API

TOML parsing and editing helpers are available under ptool.toml and p.toml.

ptool.toml.parse

v0.1.0 - Introduced.

ptool.toml.parse(input) parses a TOML string into a Lua table.

• input (string, required): The TOML text.
• Returns: A Lua table (the root node is always a table).

Type mapping:

• TOML table / inline table -> Lua table
• TOML array -> Lua sequence table (1-based)
• TOML string -> Lua string
• TOML integer -> Lua integer
• TOML float -> Lua number
• TOML boolean -> Lua boolean
• TOML datetime/date/time -> Lua string

Error behavior:

• An error is raised if input is not a string.
• A TOML syntax error raises an error whose message includes line and column information.

Example:

local text = ptool.fs.read("ptool.toml")
local conf = ptool.toml.parse(text)

print(conf.project.name)
print(conf.build.jobs)
print(conf.release_date) -- datetime/date/time values are strings

ptool.toml.get

v0.1.0 - Introduced.

v0.4.0 - Added numeric path segments for array indexing.

ptool.toml.get(input, path) reads the value at a specified path from TOML text.

• input (string, required): The TOML text.
• path ((string|integer)[], required): A non-empty path array, such as {"package", "version"} or {"bin", 1, "name"}.
• Returns: The corresponding Lua value, or nil if the path does not exist.

Behavior:

• String path segments select table keys.
• Integer path segments select array elements using Lua's 1-based indexing.

Example:

local text = ptool.fs.read("Cargo.toml")
local version = ptool.toml.get(text, {"package", "version"})
print(version)

local first_bin_name = ptool.toml.get(text, {"bin", 1, "name"})
print(first_bin_name)

ptool.toml.set

v0.1.0 - Introduced.

v0.4.0 - Added composite value writes and numeric path segments.

ptool.toml.set(input, path, value) sets the value at a specified path and returns the updated TOML text.

• input (string, required): The TOML text.
• path ((string|integer)[], required): A non-empty path array, such as {"package", "version"} or {"bin", 1, "name"}.
• value (string|integer|number|boolean|table, required): The value to write.
• Returns: The updated TOML string.

Behavior:

• Missing intermediate paths are created automatically as tables.
• If an intermediate path exists but is not a table, an error is raised.
• Lua tables with only string keys are written as TOML tables.
• Lua sequence tables are written as TOML arrays.
• A Lua sequence of string-keyed tables is written as a TOML array of tables.
• Empty Lua tables are currently written as TOML tables.
• Parsing and writing back are based on toml_edit, which preserves original comments and formatting as much as possible.

Example:

local text = ptool.fs.read("Cargo.toml")
local updated = ptool.toml.set(text, {"package", "version"}, "0.2.0")
ptool.fs.write("Cargo.toml", updated)

local text2 = ptool.toml.set(text, {"package", "keywords"}, {"lua", "toml"})
local text3 = ptool.toml.set(text2, {"package", "metadata"}, {
  channel = "stable",
  maintainers = {"peterlits"},
})

ptool.toml.remove

v0.1.0 - Introduced.

v0.4.0 - Added numeric path segments for array indexing.

ptool.toml.remove(input, path) removes the specified path and returns the updated TOML text.

• input (string, required): The TOML text.
• path ((string|integer)[], required): A non-empty path array, such as {"package", "name"} or {"bin", 1}.
• Returns: The updated TOML string.

Behavior:

• If the path does not exist, no error is raised and the original text (or an equivalent form) is returned.
• If an intermediate path exists but is not a table, an error is raised.

Example:

local text = ptool.fs.read("Cargo.toml")
local updated = ptool.toml.remove(text, {"package", "description"})
ptool.fs.write("Cargo.toml", updated)

ptool.toml.stringify

v0.4.0 - Introduced.

ptool.toml.stringify(value) converts a Lua value to TOML text.

• value (table, required): The root TOML table to encode.
• Returns: The encoded TOML string.

Behavior:

• The root value must be a Lua table representing a TOML table.
• Nested Lua tables follow the same table/array rules as ptool.toml.set.
• Empty Lua tables are currently encoded as TOML tables.

Example:

local text = ptool.toml.stringify({
  package = {
    name = "ptool",
    version = "0.4.0",
    keywords = {"lua", "toml"},
  },
})

print(text)

Notes:

• The path argument for ptool.toml.get/set/remove must be a non-empty array of strings and/or positive integers.
• Integer path segments are 1-based so they match Lua array indexing.
• TOML datetime/date/time values are still read back as Lua strings.