r-toml

Table of Contents

• Overview
• Installation
• Examples
• Comparison with {RccpTOML}
• Comparison with {blogdown}
• Related software

Overview

Currently this package only encodes R objects to TOML v1.0.

Depending on your TOML needs you may consider instead {RccpTOML} or {blogdown}.

{toml} provides the following functions to support encoding R objects to TOML.

• encode_toml() is an S3 generic that encodes R objects as TOML. Feel free to write a TOML encoder for any object you like---this package provides encoders for following:

  • named and unnamed lists
  • character, integer, logical, numeric (double) vectors
  • the 64-bit integer vectors from {bit64}
  • dates, datetimes, and times from {base}, {clock}, {datetimeoffset}, {nanotime}, and {parttime}

• write_toml() encodes an R object to TOML and then writes it to a connection.

Installation

remotes::install_github("trevorld/r-toml")

Examples

library("toml")
l <- list(title = "TOML Example",
          owner = list(name = "Tom Preston-Werner",
                       dob = as.POSIXct("1979-05-27 07:32:00",
                                        tz = "America/Los_Angeles")),
          database = list(server = "192.168.1.1",
                          ports = c(8001L, 8001L, 8002L),
                          connection_max = 5000L,
                          enabled = TRUE),
          servers = list(alpha = list(ip = "10.0.0.1", dc = "eqdc10"),
                         beta = list(ip = "10.0.0.2", dc = "eqdc10")),
          clients = list(data = list(c("gamma", "delta"), c(1L, 2L)),
                         hosts = c("alpha", "omega"))
          )
cat(encode_toml(l), sep = "\n")

## title = 'TOML Example'
## owner.name = 'Tom Preston-Werner'
## owner.dob = 1979-05-27T07:32:00.000000-07:00
## database.server = '192.168.1.1'
## database.ports = [8_001, 8_001, 8_002]
## database.connection_max = 5_000
## database.enabled = true
## servers.alpha.ip = '10.0.0.1'
## servers.alpha.dc = 'eqdc10'
## servers.beta.ip = '10.0.0.2'
## servers.beta.dc = 'eqdc10'
## clients.data = [['gamma', 'delta'], [1, 2]]
## clients.hosts = ['alpha', 'omega']

if (requireNamespace("bit64", quietly = TRUE)) {
  library("datetimeoffset")
  l <- list(int_64bit = bit64::as.integer64("9223372036854775807"),
            offset_datetime = as_datetimeoffset("2023-04-05T01:02:03-07:00"),
            local_datetime = as_datetimeoffset("2023-04-05T01:02:03"),
            local_date = as.Date("2023-04-05"),
            local_time = as_datetimeoffset("T01:02:03"))
  cat(encode_toml(l), sep = "\n")
}

## int_64bit = 9_223_372_036_854_775_807
## offset_datetime = 2023-04-05T01:02:03-07:00
## local_datetime = 2023-04-05T01:02:03
## local_date = 2023-04-05
## local_time = 01:02:03

Comparison with {RccpTOML}

Note: Please feel free to open a pull request to fix any {RccpTOML} mis-understandings or statements that are now out-of-date.

• Currently {RccpTOML} only decodes TOML files while this package only encodes TOML files.

Comparison with {blogdown}

Note: Please feel free to open a pull request to fix any {blogdown} mis-understandings or statements that are now out-of-date.

• The read_toml() / write_toml() functions in {blogdown} can read/write TOML documents either by using {RccpTOML} or alternatively by converting from/to YAML using {yaml} and then using Hugo to convert from/to TOML whereas this package writes TOML documents directly in R.
• TOML generated from by {blogdown} may be formatted more nicely than TOML generated from this package.
• This package (as of {blogdown} v1.18) seems to do a better job of encoding to TOML {bit64}'s "integer64" class as well as several datetime classes from {base}, {clock}, {datetimeoffset}, {nanotime}, and {parttime}.
• This package lets you write your own encode_toml() methods to support encoding additional R objects that {blogdown} may not support.

Related software

• TOML
• toml-test
• {RccpTOML} can read TOML documents using toml++
• {blogdown} can read/write TOML documents either by using {RccpTOML} or alternatively by converting from/to YAML using {yaml} and then using Hugo to convert from/to TOML.