jsonseq

README

jsonseq

A Go package providing methods for reading and writing JSON text sequences (application/json-seq) as defined in RFC 7464 (https://tools.ietf.org/html/rfc7464).

Usage

_ = jsonseq.NewEncoder(os.Stdout).Encode("Test")
// "Test"

_ = jsonseq.WriteRecord(os.Stdout, []byte(`{"id":2}`))
// {"id":2}

var i interface{}
d := jsonseq.NewDecoder(strings.NewReader(`{"id":1} 12341234 true discarded junk`))
_ = d.Decode(&i)
fmt.Println(i)
// map[id:1]

See the GoDoc for more information and examples.

Documentation

Overview

Package jsonseq provides methods for reading and writing JSON text sequences (`application/json-seq`) as defined in RFC 7464 (https://tools.ietf.org/html/rfc7464).

_ = jsonseq.NewEncoder(os.Stdout).Encode("Test")
// �"Test"

_ = jsonseq.WriteRecord(os.Stdout, []byte(`{"id":2}`))
// �{"id":2}

var i interface{}
d := jsonseq.NewDecoder(strings.NewReader(`�{"id":1} �1234�1234 �true discarded junk`))
_ = d.Decode(&i)
fmt.Println(i)
// map[id:1]
...

Index

• Constants
• func NewEncoder(w io.Writer) *json.Encoder
• func RecordValue(b []byte) ([]byte, bool)
• func ScanRecord(data []byte, atEOF bool) (advance int, token []byte, err error)
• func WriteRecord(w io.Writer, json []byte) error
• type Decode
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func NewDecoderFn(r io.Reader, fn Decode) *Decoder
  • func (d *Decoder) Decode(v interface{}) error
• type RecordWriter
  • func (w *RecordWriter) Write(record []byte) (int, error)

Examples

• Decoder.Decode
• NewEncoder
• WriteRecord

Constants

const ContentType = `application/json-seq`

ContentType is the MIME media type for JSON text sequences. See: https://tools.ietf.org/html/rfc7464#section-4

Functions

func NewEncoder

func NewEncoder(w io.Writer) *json.Encoder

NewEncoder returns a standard library json.Encoder that writes a JSON text sequence to w.

The Encoder calls Write just once for each value and always with a trailing line feed.

Example

package main

import (
	"os"

	"github.com/jmank88/jsonseq"
)

func main() {
	encoder := jsonseq.NewEncoder(os.Stdout)
	_ = encoder.Encode("Test")
	_ = encoder.Encode(123.456)
	_ = encoder.Encode(struct{ Id int }{Id: 1})

}

Output:

�"Test"
�123.456
�{"Id":1}

func RecordValue

func RecordValue(b []byte) ([]byte, bool)

RecordValue returns the *value* bytes from a JSON text sequence record and a flag indicating if the *record* is valid. This is *NOT* a validation of any contained JSON, which could itself be invalid or contain extra trailing values.

See section 2.4: Top-Level Values: numbers, true, false, and null. https://tools.ietf.org/html/rfc7464#section-2.4

func ScanRecord

func ScanRecord(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanRecord is a bufio.SplitFunc which splits JSON text sequence records. Scanned bytes must be validated with the RecordValue function.

func WriteRecord

func WriteRecord(w io.Writer, json []byte) error

WriteRecord writes a JSON text sequence record with beginning (RS) and end (LF) marker bytes.

Example

package main

import (
	"os"

	"github.com/jmank88/jsonseq"
)

func main() {
	_ = jsonseq.WriteRecord(os.Stdout, []byte(`{"id":1}`))
	_ = jsonseq.WriteRecord(os.Stdout, []byte(`{"id":2}`))
	_ = jsonseq.WriteRecord(os.Stdout, []byte(`{"id":3}`))

}

Output:

�{"id":1}
�{"id":2}
�{"id":3}

Types

type Decode

type Decode func(b []byte, v interface{}) error

Decode functions decode the JSON-encoded data and store the result in the value pointed to by v, or return an error if invalid. Note that the encoded data may have extra trailing data, which is perfectly valid. This disqualifies parsers which assume a single value (e.g. json.Unmarshal).

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads and decodes JSON text sequence records from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new Decoder backed by the standard library's encoding/json Decoder. Any extra trailing data is discarded.

func NewDecoderFn

func NewDecoderFn(r io.Reader, fn Decode) *Decoder

NewDecoderFn creates a new Decoder backed by a custom Decode function.

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

Decode scans the next record, or returns an error. The Decoder remains valid until io.EOF is returned.

Example

package main

import (
	"fmt"
	"io"
	"strings"

	"github.com/jmank88/jsonseq"
)

func main() {
	d := jsonseq.NewDecoder(strings.NewReader(`�{"id":1} �1234�1234 �true discarded junk`))
	for {
		var i interface{}
		if err := d.Decode(&i); err != nil {
			if err == io.EOF {
				break
			}
			fmt.Println(err)
		} else {
			fmt.Println(i)
		}
	}

}

Output:

map[id:1]
invalid record: "1234"
1234
true

type RecordWriter

type RecordWriter struct {
	io.Writer
}

A RecordWriter prefixes Write calls with a record separator.

Callers must only call Write once for each value, and are responsible for including trailing line feeds when necessary or desired.

func (*RecordWriter) Write

func (w *RecordWriter) Write(record []byte) (int, error)

Write prefixes every written record with an ASCII record separator.