77 lines
2.2 KiB
Markdown
77 lines
2.2 KiB
Markdown
|
# `fj api --jq` syntax
|
||
|
|
|
||
|
|
`fj api` ships a small jq-flavored JSON projector. It's not a full jq
|
||
|
|
implementation; it covers the 95% of cases gh users use `--jq` for.
|
||
|
|
|
||
|
|
If you need anything more complex, pipe the raw JSON through real `jq`:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
fj api /repos/foo/bar | jq '.<full expression>'
|
||
|
|
```
|
||
|
|
|
||
|
|
## Stages
|
||
|
|
|
||
|
|
Expressions are split on `|` into stages. Each stage runs against the
|
||
|
|
output of the previous stage.
|
||
|
|
|
||
|
|
```
|
||
|
|
fj api /repos/foo/bar | head
|
||
|
|
# vs
|
||
|
|
fj api /repos/foo/bar -q '.owner | .login'
|
||
|
|
```
|
||
|
|
|
||
|
|
## Path segments
|
||
|
|
|
||
|
|
Within a stage, dot-separated segments traverse the JSON tree. Each
|
||
|
|
segment is one of:
|
||
|
|
|
||
|
|
| Segment | Meaning |
|
||
|
|
| ------------ | --------------------------------------------- |
|
||
|
|
| `.field` | Object field lookup |
|
||
|
|
| `.0` | Array index (positional) |
|
||
|
|
| `.[0]` | Same as `.0`, bracket form |
|
||
|
|
| `.[-1]` | Last element of an array |
|
||
|
|
| `.[-2]` | Second-to-last element |
|
||
|
|
|
||
|
|
Bracket form and dot form are interchangeable: `.data.0.name` and
|
||
|
|
`.data[0].name` mean the same thing.
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
|
||
|
|
Given:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"data": [
|
||
|
|
{"id": 1, "owner": {"login": "alice"}},
|
||
|
|
{"id": 2, "owner": {"login": "bob"}}
|
||
|
|
],
|
||
|
|
"total": 2
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
| Query | Output |
|
||
|
|
| ------------------------------ | ------------------ |
|
||
|
|
| `.total` | `2` |
|
||
|
|
| `.data.0.id` | `1` |
|
||
|
|
| `.data[0].owner.login` | `"alice"` |
|
||
|
|
| `.data[-1].owner.login` | `"bob"` |
|
||
|
|
| `.data | .[0]` | first element |
|
||
|
|
| `.data[0] | .owner | .login` | `"alice"` |
|
||
|
|
|
||
|
|
## Errors
|
||
|
|
|
||
|
|
- A missing field returns a hard error with the field name.
|
||
|
|
- An out-of-range index returns a hard error with the index.
|
||
|
|
- Negative indices that overshoot (e.g. `[-5]` on a 3-element array)
|
||
|
|
also error.
|
||
|
|
|
||
|
|
## Not supported
|
||
|
|
|
||
|
|
The following are intentionally NOT implemented; reach for real jq:
|
||
|
|
|
||
|
|
- Filters like `.[] | select(.state == "open")`
|
||
|
|
- Functions: `map`, `length`, `keys`, etc.
|
||
|
|
- String interpolation
|
||
|
|
- Multiple outputs from a single expression
|