# Tutorial

jsq can be used for a lot of the same tasks as [jq](https://jqlang.github.io/jq/). Below is a copy
of the [jq tutorial](https://jqlang.github.io/jq/tutorial/) with all the jq translated to jsq.

---

GitHub has a JSON API, so let's play with that. This URL gets us the last 5 commits from the jsq
repo.

```
curl 'https://api.github.com/repos/callum-oakley/jsq/commits?per_page=5'
```

GitHub returns nicely formatted JSON. For servers that don't, it can be helpful to pipe the response
through jsq to pretty-print it. The `-j` flag parses the input as JSON before passing it to the
script, and the `-J` flag prints the result as JSON. The default script is `$` which returns the
input unchanged.

```
curl 'https://api.github.com/repos/callum-oakley/jsq/commits?per_page=5' | jsq -jJ
```

We can use jsq to extract just the first commit. `$` is the result of parsing STDIN as JSON, so
`$[0]` is the first commit.

```
curl 'https://api.github.com/repos/callum-oakley/jsq/commits?per_page=5' | jsq -jJ '$[0]'
```

For the rest of the examples, I'll leave out the `curl` command - it's not going to change.

There's a lot of info we don't care about there, so we'll restrict it down to the most interesting
fields.

```
jsq -jJ 'const a = $[0]; ({ message: a.commit.message, name: a.commit.committer.name })'
```

We assign `$[0]` to a variable and then use that variable to construct a new object with only the
fields we care about. (Note that we have to wrap the object literal in parentheses, so as not to
have it be confused with a block statement.)

Now let's get the rest of the commits by applying the same transformation to every commit with
`map`.

```
jsq -jJ '$.map(a => ({ message: a.commit.message, name: a.commit.committer.name }))'
```

Next, let's try getting the URLs of the parent commits out of the API results as well. In each
commit, the GitHub API includes information about "parent" commits. There can be one or many.

```
"parents": [
  {
    "sha": "66ec47a4f84d3ab2dfe95595a57461fa4d19f8d6",
    "url": "https://api.github.com/repos/callum-oakley/jsq/commits/66ec47a4f84d3ab2dfe95595a57461fa4d19f8d6",
    "html_url": "https://github.com/callum-oakley/jsq/commit/66ec47a4f84d3ab2dfe95595a57461fa4d19f8d6"
  }
]
```

We want to pull out all of the "html_url" fields inside that array of parent commits and make a
simple list of strings to go along with the "message" and "author" fields we already have.

```
jsq -jJ '$.map(a => ({
  message: a.commit.message,
  name: a.commit.committer.name,
  parents: a.parents.map(b => b.html_url),
}))'
```

Here we're making a new object for each commit as before, but this time we use another nested `map`
to pull the commit URLs out of each parent object.

---

Here endeth the tutorial! There's lots more to play with. [Install jsq](/README.md) if you haven't
already, and check out `jsq --help` to see all the available options.
