Contents

1 Introduction & Installation

This package provides the header-only ‘jsoncons’ library for manipulating JSON objects. Use rjsoncons for querying JSON or R objects using ‘JMESpath’ or ‘JSONpath’, or link to the package for direct access to the C++ library.

Install the in-development version with

if (!requireNamespace("remotes", quiety = TRUE))
    install.packages("remotes", repos = "https://cran.r-project.org")
remotes::install_github("mtmorgan/rjsoncons")

2 Examples

For interactive use, load the library

library(rjsoncons)

The package implements basic functionality, including querying a JSON document represented as character(1) using JSONpath or JMESpath syntax. (In the following, noquote() is used to print the result with fewer escaped quotation marks, increasing readability.)

rjsoncons::version()  # C++ library version
## [1] "0.168.7"

json <- '{
  "locations": [
    {"name": "Seattle", "state": "WA"},
    {"name": "New York", "state": "NY"},
    {"name": "Bellevue", "state": "WA"},
    {"name": "Olympia", "state": "WA"}
  ]
}'

jsonpath(json, "$..name") |>
    noquote()
## [1] ["Seattle","New York","Bellevue","Olympia"]

jmespath(json, "locations[?state == 'WA'].name | sort(@)") |>
    noquote()
## [1] ["Bellevue","Olympia","Seattle"]

For an R representation of the results use, e.g., jsonlite

jmespath(json, "locations[?state == 'WA'].name | sort(@)") |>
    jsonlite::fromJSON()
## [1] "Bellevue" "Olympia"  "Seattle"

It is also possible to provide list-of-list style R objects that are converted using jsonlite::toJSON() before queries are made; toJSON() arguments like auto_unbox = TRUE can be added to the function call.

lst <- jsonlite::fromJSON(json, simplifyVector = FALSE)
jmespath(lst, "locations[?state == 'WA'].name | sort(@)", auto_unbox = TRUE) |>
    noquote()
## [1] ["Bellevue","Olympia","Seattle"]

Additional examples illustrating features available are on the help pages, e.g., ?jmespath.

3 C++ Library Use in Other Packages

The package includes the complete ‘jsoncons’ C++ header-only library, available to other R packages by adding

LinkingTo: rjsoncons
SystemRequirements: C++11

to the DESCRIPTION file. Typical use in an R package would also include LinkingTo: specifications for the cpp11 or Rcpp (this package uses cpp11) packages to provide a C / C++ interface between R and the C++ ‘jsoncons’ library.

4 Session Information

This vignette was compiled using the following software versions

sessionInfo()
## R version 4.2.1 Patched (2022-06-23 r82518)
## Platform: aarch64-apple-darwin21.5.0 (64-bit)
## Running under: macOS Monterey 12.6
## 
## Matrix products: default
## BLAS:   /Users/ma38727/bin/R-4-2-branch/lib/libRblas.dylib
## LAPACK: /Users/ma38727/bin/R-4-2-branch/lib/libRlapack.dylib
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] rjsoncons_1.0.0  BiocStyle_2.25.0
## 
## loaded via a namespace (and not attached):
##  [1] bookdown_0.29       digest_0.6.29       R6_2.5.1           
##  [4] jsonlite_1.8.0      magrittr_2.0.3      evaluate_0.16      
##  [7] stringi_1.7.8       cachem_1.0.6        rlang_1.0.6        
## [10] cli_3.4.1           jquerylib_0.1.4     bslib_0.4.0        
## [13] rmarkdown_2.16      tools_4.2.1         stringr_1.4.1      
## [16] xfun_0.33           yaml_2.3.5          fastmap_1.1.0      
## [19] compiler_4.2.1      BiocManager_1.30.18 htmltools_0.5.3    
## [22] knitr_1.40          sass_0.4.2