mirror of
https://github.com/neilotoole/sq.git
synced 2024-12-22 15:41:35 +03:00
f0aa65791b
* CHANGELOG text clarification * Dialing in config/options * Yet more dialing in of config/options * Refactor output writers * YAML output for more commands
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# Package `jsonw`
|
|
|
|
Package `jsonw` implements JSON output writers.
|
|
|
|
Note that there are three implementations of `output.RecordWriter`.
|
|
|
|
- `NewStdRecordWriter` returns a writer that outputs in "standard" JSON.
|
|
- `NewArrayRecordWriter` outputs each record on its own line as an element of a JSON array.
|
|
- `NewObjectRecordWriter` outputs each record as a JSON object on its own line.
|
|
|
|
These `RecordWriter`s correspond to the `--json`, `--jsona`, and `--jsonl` flags
|
|
(where `jsonl` means "JSON Lines"). There are also other writer implementations,
|
|
such as an `output.ErrorWriter` and an `output.MetadataWriter`.
|
|
|
|
|
|
#### Standard JSON `--json`:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"actor_id": 1,
|
|
"first_name": "PENELOPE",
|
|
"last_name": "GUINESS",
|
|
"last_update": "2020-06-11T02:50:54Z"
|
|
},
|
|
{
|
|
"actor_id": 2,
|
|
"first_name": "NICK",
|
|
"last_name": "WAHLBERG",
|
|
"last_update": "2020-06-11T02:50:54Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
#### JSON Array `--jsona`:
|
|
|
|
```json
|
|
[1, "PENELOPE", "GUINESS", "2020-06-11T02:50:54Z"]
|
|
[2, "NICK", "WAHLBERG", "2020-06-11T02:50:54Z"]
|
|
```
|
|
|
|
#### Object aka JSON Lines `--jsonl`:
|
|
|
|
```json
|
|
{"actor_id": 1, "first_name": "PENELOPE", "last_name": "GUINESS", "last_update": "2020-06-11T02:50:54Z"}
|
|
{"actor_id": 2, "first_name": "NICK", "last_name": "WAHLBERG", "last_update": "2020-06-11T02:50:54Z"}
|
|
```
|
|
|
|
## Notes
|
|
|
|
At the time of development there was not a JSON encoder library available that provided the functionality that `sq` required. These requirements:
|
|
|
|
- Optional colorization
|
|
- Optional pretty-printing (indentation, spacing)
|
|
- Preservation of the order of record fields (columns).
|
|
|
|
For the `RecordWriter` implementations, given the known "flat" structure of a record, it was relatively straightforward to create custom writers for each type of JSON output.
|
|
|
|
For general-purpose JSON output (such as metadata output), it was necessary to modify an existing JSON library to provide colorization (and also on-the-fly indentation). After benchmarking, the [segmentio.io encoder](https://github.com/segmentio/encoding) was selected as the base library. Rather than a separate forked project (which probably would not make sense to ever merge with its parent project), the modified encoder is found in `jsonw/internal/jcolorenc`.
|