README.Rmd

jqr
=======

```{r echo=FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  warning = FALSE,
  message = FALSE
)
```

[![Build Status](https://travis-ci.org/ropensci/jqr.png?branch=master)](https://travis-ci.org/ropensci/jqr)
[![Coverage Status](https://coveralls.io/repos/ropensci/jqr/badge.svg?branch=master)](https://coveralls.io/r/ropensci/jqr?branch=master)

R interface to jq http://stedolan.github.io/jq/

## Install

Get dependencies not on CRAN

```{r eval=FALSE}
devtools::install_github("vsbuffalo/rivr")
```

To install `jqr`, after cloning the repo the first time, run (from the command line)

```
./bootstrap.R
```

which will download the 1.4 release of [jq](http://stedolan.github.io/jq/).  This does not need to be run on subsequent runs, and will stop being required once [this issue](https://github.com/ropensci/jqr/issues/1) is resolved.

```{r}
library("jqr")
```

## Interfaces

### low level

There's a low level interface in which you can execute `jq` code just as you would on the command line:

```{r}
str <- '[{
    "foo": 1,
    "bar": 2
  },
  {
    "foo": 3,
    "bar": 4
  },
  {
    "foo": 5,
    "bar": 6
}]'
```

```{r}
jq_(str, ".[]")
```

```{r}
jq_(str, "[.[] | {name: .foo} | keys]")
```

### high level

The other is higher level, and uses a suite of functions to construct queries. Queries are constucted, then excuted with the function `jq()`.

Examples:

Index

```{r}
x <- '[{"message": "hello", "name": "jenn"}, {"message": "world", "name": "beth"}]'
x %>% index() %>% jq
```

Sort

```{r}
'[8,3,null,6]' %>% sort %>% jq
```

reverse order

```{r}
'[1,2,3,4]' %>%  reverse %>% jq
```

Show the query to be used using `peek()`

```{r}
'[1,2,3,4]' %>%  reverse %>% peek
```

#### string operations

join

```{r}
'["a","b,c,d","e"]' %>% join %>% jq
'["a","b,c,d","e"]' %>% join(`;`) %>% jq
```

ltrimstr

```{r}
'["fo", "foo", "barfoo", "foobar", "afoo"]' %>% index() %>% ltrimstr(foo) %>% jq
```

rtrimstr

```{r}
'["fo", "foo", "barfoo", "foobar", "foob"]' %>% index() %>% rtrimstr(foo) %>% jq
```

startswith

```{r}
'["fo", "foo", "barfoo", "foobar", "barfoob"]' %>% index %>% startswith(foo) %>% jq
```

endswith

```{r}
'["fo", "foo", "barfoo", "foobar", "barfoob"]' %>% index %>% endswith(foo) %>% jq
```

tojson, fromjson, tostring

```{r}
'[1, "foo", ["foo"]]' %>% index %>% tostring %>% jq
'[1, "foo", ["foo"]]' %>% index %>% tojson %>% jq
'[1, "foo", ["foo"]]' %>% index %>% tojson %>% fromjson %>% jq
```

contains

```{r}
'"foobar"' %>% contains("bar") %>% jq
```

unique

```{r}
'[1,2,5,3,5,3,1,3]' %>% unique %>% jq
```

#### types

get type information for each element

```{r}
'[0, false, [], {}, null, "hello"]' %>% types %>% jq
'[0, false, [], {}, null, "hello", true, [1,2,3]]' %>% types %>% jq
```

select elements by type

```{r}
'[0, false, [], {}, null, "hello"]' %>% index() %>% type(booleans) %>% jq
```

#### key operations

get keys

```{r}
str <- '{"foo": 5, "bar": 7}'
str %>% keys() %>% jq
```

delete by key name

```{r}
str %>% del(bar) %>% jq
```

check for key existence

```{r}
str3 <- '[[0,1], ["a","b","c"]]'
str3 %>% haskey(2) %>% jq
str3 %>% haskey(1,2) %>% jq
```

Select variables by name, and rename

```{r}
'{"foo": 5, "bar": 7}' %>% select(a = .foo) %>% jq
```

More complicated `select()`, using the included dataset `githubcommits`

```{r}
githubcommits %>%
  index() %>% 
  select(sha = .sha, name = .commit.committer.name) %>% 
  jq(TRUE)
```

#### Maths

```{r}
'{"a": 7}' %>%  do(.a + 1) %>% jq
'{"a": [1,2], "b": [3,4]}' %>%  do(.a + .b) %>% jq
'{"a": [1,2], "b": [3,4]}' %>%  do(.a - .b) %>% jq
'{"a": 3}' %>%  do(4 - .a) %>% jq
'["xml", "yaml", "json"]' %>%  do('. - ["xml", "yaml"]') %>% jq
'5' %>%  do(10 / . * 3) %>% jq
```

comparisons

```{r}
'[5,4,2,7]' %>% index() %>% do(. < 4) %>% jq
'[5,4,2,7]' %>% index() %>% do(. > 4) %>% jq
'[5,4,2,7]' %>% index() %>% do(. <= 4) %>% jq
'[5,4,2,7]' %>% index() %>% do(. >= 4) %>% jq
'[5,4,2,7]' %>% index() %>% do(. == 4) %>% jq
'[5,4,2,7]' %>% index() %>% do(. != 4) %>% jq
```

length

```{r}
'[[1,2], "string", {"a":2}, null]' %>% index %>% length %>% jq
```

sqrt

```{r}
'9' %>% sqrt %>% jq
```

floor

```{r}
'3.14159' %>% floor %>% jq
```

find minimum

```{r}
'[5,4,2,7]' %>% min %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% min %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% min(foo) %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% min(bar) %>% jq
```

find maximum

```{r}
'[5,4,2,7]' %>% max %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% max %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% max(foo) %>% jq
'[{"foo":1, "bar":14}, {"foo":2, "bar":3}]' %>% max(bar) %>% jq
```

#### Combine into valid JSON

`jq` sometimes creates pieces of JSON that are valid in themselves, but together are not. 
`combine()` is a way to make valid JSON.

This outputs a few pieces of JSON

```{r}
(x <- githubcommits %>% 
  index() %>%
  select(sha = .sha, name = .commit.committer.name) %>% 
  jq(TRUE))
```

Use `combine()` to put them together.

```{r}
combine(x)
```

#### Streaming

Write `mtcars` to a temporary file

```{r}
writeLines(jsonlite::toJSON(mtcars, collapse = FALSE),
             tmp <- tempfile())
```

Build a file iterator

```{r}
it_f <- rivr::file_iterator(tmp)
it_j <- jq_iterator(it_f, '{cyl: ."cyl"}')
replicate(NROW(mtcars), it_j$yield())
```

> the streaming bit is a [work in progress](https://github.com/ropensci/jqr/issues/8)

## Meta

* Please [report any issues or bugs](https://github.com/ropensci/jqr/issues).
* License: MIT
* Get citation information for `jqr` in R doing `citation(package = 'jqr')`

[![rofooter](http://ropensci.org/public_images/github_footer.png)](http://ropensci.org)