RcppTOML

Rcpp bindings for TOML

So 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 stronly types: values come back as integer, double, (multiline-) character (strings), boolean or Datetime. Moreover, complex nesting and arrays are supported as well.

This package uses the C++11 implementation written by Chase Geigle in cpptoml to implement a parser used by R.

Key Features of TOML

The are many, but in brief:

  • Comments are allowed anywhere
  • Actual Types: Integer, Float, String, Datetime (!!), Tables, Arrays
  • Nested Data Types such as Vector/Arrays and Tables
  • Designed to be easily readable by humans yet expressive for machine-readable uses

See eg the tests/ in the sources for examples, or see the TOML documentation.

Quick Example

Here we parse the a TOML example file derived from what is part of the main TOML README

R> p <- parseTOML(system.file("toml", "example.toml", package="RcppTOML"))
R> summary(p)
toml object with top-level slots:
   clients, database, owner, servers, title
read from /usr/local/lib/R/site-library/RcppTOML/toml/example.toml
R> p
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 4
  ..$ bio         : chr "GitHub Cofounder & CEO\\nLikes tater tots and beer."
  ..$ dob         : POSIXct[1:1], format: "1979-05-27 07:32:00"
  ..$ name        : chr "Tom Preston-Werner"
  ..$ organization: chr "GitHub"
 $ 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"
NULL
R> 

This already shows nesting, vectors as well as four different native (!!) data types including POSIXct mapping. Once again, compare to original in the TOML README or the file in our package sources.

We also use the entire TOML v0.4.0 spec, broken into "topics" as input in the tests/ directory in the sources.

Status

Feature-complete with TOML v0.4.0, see the tests/ directory. It parses everything that the underlying cpptoml parses with the same (sole) exception of unicode escape characters in strings.

Starting with release 0.1.0, builds on Windows are also supported.

Installation

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

install.packages("RcppTOML")

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

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

Author

Dirk Eddelbuettel

License

GPL (>= 2)

Initially created: Mon Apr 27 20:44:45 CDT 2015
Last modified: Thu Jan 05 21:01:59 CST 2017