---
title: "Using the 'jsoncons' Library in R"
author:
- name: Martin Morgan
  affiliation: Roswell Park Comprehensive Cancer Center, Buffalo, NY, US
- name: Marcel Ramos
  affiliation: CUNY School of Public Health at Hunter College, New York, NY, US
output:
  BiocStyle::html_document
vignette: |
  %\VignetteIndexEntry{Using the 'jsoncons' Library in R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE
)
```

# Introduction & Installation

<!-- badges: start -->
<!-- badges: end -->

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.

[jsoncons]: https://github.com/danielaparker/jsoncons
[rjsoncons]: https://github.com/mtmorgan/rjsoncons

Install the in-development version with

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

# Examples

For interactive use, load the library

```{r}
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.)

[JSONpath]: https://goessner.net/articles/JsonPath/
[JMESpath]: https://jmespath.org/

```{r}
rjsoncons::version()  # C++ library version

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

jsonpath(json, "$..name") |>
    noquote()

jmespath(json, "locations[?state == 'WA'].name | sort(@)") |>
    noquote()
```

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

```{r}
jmespath(json, "locations[?state == 'WA'].name | sort(@)") |>
    jsonlite::fromJSON()
```

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.

```{r}
lst <- jsonlite::fromJSON(json, simplifyVector = FALSE)
jmespath(lst, "locations[?state == 'WA'].name | sort(@)", auto_unbox = TRUE) |>
    noquote()
```

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

[jsonlite]: https://cran.r-project.org/package=jsonlite


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

[cpp11]: https://cran.r-project.org/package=cpp11
[Rcpp]: https://cran.r-project.org/package=Rcpp

# Session Information

This vignette was compiled using the following software versions

```{r}
sessionInfo()
```
