Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eddelbuettel/rcpptoml

Rcpp Bindings to C++ parser for TOML files
https://github.com/eddelbuettel/rcpptoml

c-plus-plus-11 cran r r-package toml toml-parser toml-parsing

Last synced: 11 days ago
JSON representation

Rcpp Bindings to C++ parser for TOML files

Awesome Lists containing this project

README 

        
## RcppTOML: Rcpp bindings for [TOML](https://toml.io/en/)



[![CI](https://github.com/eddelbuettel/rcpptoml/workflows/ci/badge.svg)](https://github.com/eddelbuettel/rcpptoml/actions?query=workflow%3Aci)

[![License](https://img.shields.io/badge/license-GPL%20%28%3E=%202%29-brightgreen.svg?style=flat)](https://www.gnu.org/licenses/gpl-2.0.html)

[![CRAN](https://www.r-pkg.org/badges/version/RcppTOML)](https://cran.r-project.org/package=RcppTOML)

[![Dependencies](https://tinyverse.netlify.app/badge/RcppTOML)](https://cran.r-project.org/package=RcppTOML)

[![Downloads](https://cranlogs.r-pkg.org/badges/RcppTOML?color=brightgreen)](https://www.r-pkg.org/pkg/RcppTOML)

[![Last Commit](https://img.shields.io/github/last-commit/eddelbuettel/rcpptoml)](https://github.com/eddelbuettel/rcpptoml)



### What is TOML?



[TOML](https://toml.io/en/) 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](https://github.com/skystrife/cpptoml) written by [Chase

Geigle](https://github.com/skystrife).  However, as that library is no longer maintained, current

versions now use the newer C++17 library [toml++](https://github.com/marzer/tomlplusplus) by [Mark

Gillard](https://github.com/marzer).



### Example



Consider the following [TOML](https://toml.io/en/) input example input:



```toml

# 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

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](https://toml.io/en/) for more.

Also note that most decent editors have proper [TOML](https://toml.io/en/) support

which makes editing and previewing a breeze:



![](https://raw.githubusercontent.com/eddelbuettel/rcpptoml/master/local/emacsAndTOML.png)



### Installation



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



#### From CRAN



The package is on [CRAN](https://cran.r-project.org) and can be installed

from every mirror via



```{.r}

install.packages("RcppTOML")

```



#### From the ghrr-drat



Development releases may be provided by the

[ghrr](https://ghrr.github.io/drat/) repository which can accessed via



```{.r}

## 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



```r

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

install.packages("RcppTOML", repos=repos)

```



which points to the [ghrr](https://ghrr.github.io/drat/) repository as well as a standard CRAN

mirror, but just for the length of this installation step.



### Status



Earlier versions relied upon [cpptoml](https://github.com/skystrife/cpptoml) and were feature-complete with

[TOML v0.5.0](https://toml.io/en/v0.5.0) (see the

[tests/](https://github.com/eddelbuettel/rcpptoml/tree/master/tests) directory).  They already parsed

everything that the underlying [cpptoml](https://github.com/skystrife/cpptoml) parsed with the same

(sole) exception of unicode escape characters in strings.



Since switching to [toml++](https://github.com/marzer/tomlplusplus) 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++](https://github.com/marzer/tomlplusplus) 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](https://cran.r-project.org/package=tinytest) package, the

already-installed package can also be verified via



```r

tinytest::test_package("RcppTOML")

```



at any point in time.



### Author



Dirk Eddelbuettel



### License



GPL (>= 2)