Title: Parse, Read, and Edit 'TOML'
Version: 0.1.1
Description: A toolkit for working with 'TOML' files in R while preserving formatting, comments, and structure. 'tomledit' enables serialization of R objects such as lists, data.frames, numeric, logical, and date vectors.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en
RoxygenNote: 7.3.2
Config/rextendr/version: 0.3.1.9001
SystemRequirements: Cargo (Rust's package manager), rustc
Depends: R (≥ 4.2)
Imports: rlang (≥ 1.1.0)
URL: https://extendr.github.io/tomledit/, https://github.com/extendr/tomledit
BugReports: https://github.com/extendr/tomledit/issues
NeedsCompilation: yes
Packaged: 2025-04-10 03:23:33 UTC; josiahparry
Author: Josiah Parry ORCID iD [aut, cre]
Maintainer: Josiah Parry <josiah.parry@gmail.com>
Repository: CRAN
Date/Publication: 2025-04-10 03:40:01 UTC

tomledit: Parse, Read, and Edit 'TOML'

Description

A toolkit for working with 'TOML' files in R while preserving formatting, comments, and structure. 'tomledit' enables serialization of R objects such as lists, data.frames, numeric, logical, and date vectors.

Author(s)

Maintainer: Josiah Parry josiah.parry@gmail.com (ORCID)

See Also

Useful links:

Create Toml objects

Description

Use as_toml() to convert a named list to a Toml object. Or, create a Toml object by passing in named values to toml().

Usage

as_toml(x, df_as_array = TRUE)

toml(..., df_as_array = TRUE)

Arguments

x

a named list

df_as_array

default TRUE. Creates an array of tables from a data.frame. When FALSE, creates a single table with an array for each column in the data.frame.

...

named items to be serialized to TOML.

Details

If you are serializing a data.frame to a single table with df_as_array = FALSE, note that missing values are omitted when serializing a vector to an array as there is no concept of missing values in TOML.

Value

an object of class Toml

Examples

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

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

Convert Toml to an R object

Description

Use from_toml() to convert a Toml document to an R object. Note that that due to the encoding of values in the TOML specification a perfect round trip from TOML to R is not always possible.

Usage

from_toml(x)

Arguments

x

a Toml object.

Value

a list

Examples

from_toml(toml(hello = "world"))

Read and parse TOML

Description

Use parse_toml() to parse a string into a Toml document. Use read_toml() to read a .toml file from disk.

Usage

parse_toml(x)

read_toml(file)

Arguments

x

a character scalar containing valid TOML

file

path to the file to write.

Value

an object of class Toml

Examples

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

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

# write the TOML string to a temp file
tmp <- tempfile()
writeLines(raw_toml, tmp)

# parse the TOML string
parse_toml(raw_toml)

# read the TOML file
read_toml(tmp)

Modify a Toml object

Description

remove_items() removes one or more items from the TOML document. Alternatively, insert_items() inserts key value pairs into the TOML document.

Usage

remove_items(x, keys)

insert_items(x, ..., df_as_array = TRUE)

get_item(x, key)

Arguments

x

an object of class Toml.

keys

a character vector of key names to remove. Cannot contain missing values.

...

named items to be serialized to TOML.

df_as_array

default TRUE. Creates an array of tables from a data.frame. When FALSE, creates a single table with an array for each column in the data.frame.

key

a character vector of key values. The keys are used recursively. For example with key = c("a", "b") the item a is grabbed first, then b is searched for inside of a.

Value

an object of class Toml

Examples

x <- toml(
  date = list(
    full = as.Date("2025-02-07"),
    parts = list(year = 2015L, month = "February", day = 7L)
  ),
  season = "winter"
)

# fetch the date table
get_item(x, "date")

# fetch the month value
get_item(x, c("date", "parts", "month"))

# remove an item based on name
remove_items(x, "season")

# add multiple items
insert_items(x, temperature = 31, cloudy = TRUE)

Generate TOML

Description

Write a Toml object to a file or to a string. Use write_toml() to write to a file on disk. Or, use to_toml() to create a string containing TOML.

Usage

write_toml(x, file)

to_toml(x)

Arguments

x

an object of class Toml.

file

path to the file to write.

Value

write_toml() returns a Toml object invisibly. to_toml() returns a string.

Examples

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

x <- toml(
  today = Sys.Date(),
  human = list(person = "Greg", age = 29, bday = "1969-07-02"),
)

write_toml(x, tmp)
read_toml(tmp)
to_toml(x)