eddelbuettel / rcpptoml

Rcpp Bindings to C++ parser for TOML files

RcppTOML: Rcpp bindings for TOML

What is TOML?

TOML is a configuration file grammar for humans. It is easier to read and edit than the alternatives yet arguably more useful as it is strongly typed: values come back as integer, double, (multiline-) character (strings), boolean or Datetime. Moreover, complex nesting and arrays are supported as well.

For several years, this package used the C++11 library cpptoml written by Chase Geigle. However, as that library is no longer maintained, current versions now use the newer C++17 library toml++ by Mark Gillard.

Example

Consider the following TOML input example input:

# This is a TOML document.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

It can be read in one statement and once parsed, R now has properly typed input as shown in default print method:

R> library(RcppTOML)
R> parseTOML("inst/toml/example.toml")
List of 5
 $ clients :List of 2
  ..$ data :List of 2
  .. ..$ : chr [1:2] "gamma" "delta"
  .. ..$ : int [1:2] 1 2
  ..$ hosts: chr [1:2] "alpha" "omega"
 $ database:List of 4
  ..$ connection_max: int 5000
  ..$ enabled       : logi TRUE
  ..$ ports         : int [1:3] 8001 8001 8002
  ..$ server        : chr "192.168.1.1"
 $ owner   :List of 2
  ..$ dob : POSIXct[1:1], format: "1979-05-27 15:32:00"
  ..$ name: chr "Tom Preston-Werner"
 $ servers :List of 2
  ..$ alpha:List of 2
  .. ..$ dc: chr "eqdc10"
  .. ..$ ip: chr "10.0.0.1"
  ..$ beta :List of 2
  .. ..$ dc: chr "eqdc10"
  .. ..$ ip: chr "10.0.0.2"
 $ title   : chr "TOML Example"
R>

See the other examples and the upstream documentation for more. Also note that most decent editors have proper TOML support which makes editing and previewing a breeze:

Installation

Installation from source requires a C++17 compiler, and g++ versions 8 and onward should suffice.

From CRAN

The package is on CRAN and can be installed from every mirror via

install.packages("RcppTOML")

From the ghrr-drat

Development releases may be provided by the ghrr repository which can accessed via

## if needed, first do:  install.packages("drat")
drat::addRepo("ghrr")

after which install.packages("RcppTOML) which access this repo.

Alternatively, set the repo information on the fly as e.g. in

repos <- c("https://ghrr.github.io/drat", "https://cloud.r-project.org")
install.packages("RcppTOML", repos=repos)

which points to the ghrr repository as well as a standard CRAN mirror, but just for the length of this installation step.

Status

Earlier versions relied upon cpptoml and were feature-complete with TOML v0.5.0 (see the tests/ directory). They already parsed everything that the underlying cpptoml parsed with the same (sole) exception of unicode escape characters in strings.

Since switching to toml++ the package takes advantage of its comprehensive TOML v1.0.0 support and should now be fully 1.0.0 compliant. Some new tests were added to demonstrate this.

As toml++ also offers export to JSON and YAML as well as TOML writing, we may add support to some of these features going forward.

Continued Testing

As we rely on the tinytest package, the already-installed package can also be verified via

tinytest::test_package("RcppTOML")

at any point in time.

Author

Dirk Eddelbuettel

License

GPL (>= 2)