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: 5 months ago
JSON representation
Rcpp Bindings to C++ parser for TOML files
- Host: GitHub
- URL: https://github.com/eddelbuettel/rcpptoml
- Owner: eddelbuettel
- License: gpl-2.0
- Created: 2015-03-28T16:11:30.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2025-03-08T15:02:58.000Z (about 1 year ago)
- Last Synced: 2025-03-31T03:11:13.697Z (12 months ago)
- Topics: c-plus-plus-11, cran, r, r-package, toml, toml-parser, toml-parsing
- Language: C++
- Size: 617 KB
- Stars: 36
- Watchers: 4
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-R - RcppTOML - Rcpp Bindings to C++ parser for TOML files. (Data Formats)
- awesome-R - RcppTOML - Rcpp Bindings to C++ parser for TOML files. (Data Formats)
README
## RcppTOML: Rcpp bindings for [TOML](https://toml.io/en/)
[](https://github.com/eddelbuettel/rcpptoml/actions?query=workflow%3Aci)
[](https://www.gnu.org/licenses/gpl-2.0.html)
[](https://cran.r-project.org/package=RcppTOML)
[](https://cran.r-project.org/package=RcppTOML)
[](https://www.r-pkg.org/pkg/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:
### 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)