jsonw

README

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 RecordWriters 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:

[
  {
    "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:

[1, "PENELOPE", "GUINESS", "2020-06-11T02:50:54Z"]
[2, "NICK", "WAHLBERG", "2020-06-11T02:50:54Z"]

Object aka JSON Lines --jsonl:

{"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 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.

Documentation

Overview

Package jsonw implements output writers for JSON.

Index

• func NewArrayRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter
• func NewConfigWriter(out io.Writer, pr *output.Printing) output.ConfigWriter
• func NewErrorWriter(log *slog.Logger, out io.Writer, pr *output.Printing) output.ErrorWriter
• func NewMetadataWriter(out io.Writer, pr *output.Printing) output.MetadataWriter
• func NewObjectRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter
• func NewPingWriter(out io.Writer, pr *output.Printing) output.PingWriter
• func NewSourceWriter(out io.Writer, pr *output.Printing) output.SourceWriter
• func NewStdRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter
• func NewVersionWriter(out io.Writer, pr *output.Printing) output.VersionWriter

Functions

func NewArrayRecordWriter

func NewArrayRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter

NewArrayRecordWriter returns a RecordWriter that outputs each record as a JSON array on its own line. For example:

[1, "PENELOPE", "GUINESS", "2020-06-11T02:50:54Z"]
[2, "NICK", "WAHLBERG", "2020-06-11T02:50:54Z"]

func NewConfigWriter

func NewConfigWriter(out io.Writer, pr *output.Printing) output.ConfigWriter

NewConfigWriter returns a new output.ConfigWriter.

func NewErrorWriter

func NewErrorWriter(log *slog.Logger, out io.Writer, pr *output.Printing) output.ErrorWriter

NewErrorWriter returns an output.ErrorWriter that outputs in JSON.

func NewMetadataWriter

func NewMetadataWriter(out io.Writer, pr *output.Printing) output.MetadataWriter

NewMetadataWriter returns a new output.MetadataWriter instance that outputs metadata in JSON.

func NewObjectRecordWriter

func NewObjectRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter

NewObjectRecordWriter writes out each record as a JSON object on its own line. For example:

{"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"}

func NewPingWriter

func NewPingWriter(out io.Writer, pr *output.Printing) output.PingWriter

NewPingWriter returns JSON impl of output.PingWriter.

func NewSourceWriter

func NewSourceWriter(out io.Writer, pr *output.Printing) output.SourceWriter

NewSourceWriter returns a source writer that outputs source details in text table format.

func NewStdRecordWriter

func NewStdRecordWriter(out io.Writer, pr *output.Printing) output.RecordWriter

NewStdRecordWriter returns a record writer that outputs each record as a JSON object that is an element of JSON array. This is to say, standard JSON. For example:

[
  {
    "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"
  }
]

func NewVersionWriter

func NewVersionWriter(out io.Writer, pr *output.Printing) output.VersionWriter

NewVersionWriter returns a new output.VersionWriter instance that outputs version info in JSON.