tomledit

Create or edit TOML documents from R using tomledit.

tomledit is written in Rust using extendr and the toml_edit crate.

Installation

While the package is still under development, install the package from GitHub using:

remotes::install_github("josiahparry/tomledit")

Usage

TOML can be created using either the as_toml() or toml() functions.

Use as_toml() to convert a list to TOML:

library(tomledit)

as_toml(
  list(
    person = list(age = 30L, name = "Wilma")
  )
)

<Toml>
[person]
age = 30
name = "Wilma"

Create TOML directly by passing key values to toml():

x <- toml(person = list(age = 30L, name = "Wilma"))
x

<Toml>
[person]
age = 30
name = "Wilma"

Or, parse a string as TOML while preserving comments:

raw_toml <- '# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04'

x <- parse_toml(raw_toml)
x

<Toml>
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

Write a Toml object to a file using write_toml().

tmp <- tempfile(fileext = ".toml")

write_toml(x, tmp)

Read a TOML file using read_toml().

read_toml(tmp)

<Toml>
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

Items can be inserted into a Toml document using insert_items()

y <- x |> 
  insert_items(
    date = Sys.Date(),
    date_parts = list(year = 2015L, month = "February", day = 7L)
  )

y

<Toml>
# Top-level table begins.
name = "Fido"
breed = "pug"
date = 2025-02-20

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

[date_parts]
year = 2015
month = "February"
day = 7

Or items can be removed as well using remove_items()

remove_items(y, c("date", "date_parts"))

<Toml>
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

Individual items can be fetched recursively from the Toml document.

get_item(y, c("date_parts", "month"))

[1] "February"

Or the entire Toml document can be converted to a list. Note, though, that it is not always possible to perform a perfect round trip of R objects and TOML.

from_toml(y)

$name
[1] "Fido"

$breed
[1] "pug"

$owner
$owner$name
[1] "Regina Dogman"

$owner$member_since
[1] "1999-08-04"


$date
[1] "2025-02-20"

$date_parts
$date_parts$year
[1] 2015

$date_parts$month
[1] "February"

$date_parts$day
[1] 7

Array of Tables

By default tomledit converts data.frame objects to an array of tables.

toml(iris = iris[1:3,])

<Toml>
[[iris]]
"Sepal.Length" = 5.1
"Sepal.Width" = 3.5
"Petal.Length" = 1.4
"Petal.Width" = 0.2
Species = "setosa"

[[iris]]
"Sepal.Length" = 4.9
"Sepal.Width" = 3.0
"Petal.Length" = 1.4
"Petal.Width" = 0.2
Species = "setosa"

[[iris]]
"Sepal.Length" = 4.7
"Sepal.Width" = 3.2
"Petal.Length" = 1.3
"Petal.Width" = 0.2
Species = "setosa"

This is the default behavior as it is most consistent with TOML files that are encountered in the wild. To create a single table from a data.frame, set the argument df_as_array = FALSE.

toml(
  iris = iris[1:3,],
  df_as_array = FALSE
)

<Toml>
[iris]
"Sepal.Length" = [5.1, 4.9, 4.7]
"Sepal.Width" = [3.5, 3.0, 3.2]
"Petal.Length" = [1.4, 1.4, 1.3]
"Petal.Width" = [0.2, 0.2, 0.2]
Species = ["setosa", "setosa", "setosa"]

Missing Values

One reason why array of tables are recommended for data.frames is because there is no concept of a missing or null value in TOML.

Take the following example:

x <- data.frame(
  x = c(1L, NA, 2L),
  y = letters[1:3]
) 

Notice that when this data.frame is serialized to TOML the missing x value is omitted:

toml(table = x)

<Toml>
[[table]]
x = 1
y = "a"

[[table]]
y = "b"

[[table]]
x = 2
y = "c"

Whereas when serializing to a single table the x array has 2 elements whereas the y element has 3 elements.

toml(table = x, df_as_array = FALSE)

<Toml>
[table]
x = [1, 2]
y = ["a", "b", "c"]