ndjson

README

What is it?

The ndjson package implements reading and writing files according to the ndjson specification.

Example:

package ndjson_test

import (
	"fmt"
	"os"
	"strings"

	"github.com/olivere/ndjson"
)

type Location struct {
	City string `json:"city"`
}

func ExampleReader() {
	r := ndjson.NewReader(strings.NewReader(`{"city":"Munich"}
{"city":"Berlin"}
{"city":"London"}`))
	for r.Next() {
		var loc Location
		if err := r.Decode(&loc); err != nil {
			fmt.Fprintf(os.Stderr, "Decode failed: %v", err)
			return
		}
		fmt.Println(loc.City)
	}
	if err := r.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "Reader failed: %v", err)
		return
	}
	// Output:
	// Munich
	// Berlin
	// London
}

func ExampleWriter() {
	locations := []Location{
		{City: "Munich"},
		{City: "Berlin"},
		{City: "London"},
	}
	r := ndjson.NewWriter(os.Stdout)
	for _, loc := range locations {
		if err := r.Encode(loc); err != nil {
			fmt.Fprintf(os.Stderr, "Encode failed: %v", err)
			return
		}
	}
	// Output:
	// {"city":"Munich"}
	// {"city":"Berlin"}
	// {"city":"London"}
}

License

MIT. See LICENSE file.

Documentation

Overview

Package ndjson implements reading and writing files according to the ndjson specification (http://ndjson.org/).

Index

• type Reader
  • func NewReader(r io.Reader) *Reader
  • func NewReaderSize(r io.Reader, maxSize int) *Reader
  • func (r *Reader) Bytes() []byte
  • func (r *Reader) Decode(v interface{}) error
  • func (r *Reader) Err() error
  • func (r *Reader) Next() bool
  • func (r *Reader) Read(p []byte) (n int, err error)
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func (w *Writer) Encode(v interface{}) error
  • func (w *Writer) Write(p []byte) (n int, err error)

Examples

• Reader
• Reader.Bytes
• Writer

Types

type Reader

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

Reader allows reading line-oriented JSON data following the ndjson spec at http://ndjson.org/.

Example

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/olivere/ndjson"
)

type Location struct {
	City string `json:"city"`
}

func main() {
	r := ndjson.NewReader(strings.NewReader(`{"city":"Munich"}
{"city":"Berlin"}
{"city":"London"}`))
	for r.Next() {
		var loc Location
		if err := r.Decode(&loc); err != nil {
			fmt.Fprintf(os.Stderr, "Decode failed: %v", err)
			return
		}
		fmt.Println(loc.City)
	}
	if err := r.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "Reader failed: %v", err)
		return
	}
}

Output:

Munich
Berlin
London

func NewReader

func NewReader(r io.Reader) *Reader

NewReader returns a new reader, using the underlying io.Reader as input.

func NewReaderSize

func NewReaderSize(r io.Reader, maxSize int) *Reader

NewReaderSize returns a new reader whose buffer has the specified max size, using the underlying io.Reader as input.

func (*Reader) Bytes

func (r *Reader) Bytes() []byte

Bytes returns the most recent buffer generated by a call to Next. The underlying array may point to data that will be overwritten by a subsequent call to Next. It does no allocation.

Example

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/olivere/ndjson"
)

type Location struct {
	City string `json:"city"`
}

func main() {
	r := ndjson.NewReader(strings.NewReader(`{"city":"Munich"}
{"city":"Invalid"
{"city":"London"}`))
	for r.Next() {
		var loc Location
		if err := r.Decode(&loc); err != nil {
			fmt.Printf("Decode failed: %v. Last read: %s\n", err, string(r.Bytes()))
			return
		}
		fmt.Println(loc.City)
	}
	if err := r.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "Reader failed: %v", err)
		return
	}
}

Output:

Munich
Decode failed: unexpected end of JSON input. Last read: {"city":"Invalid"

func (*Reader) Decode

func (r *Reader) Decode(v interface{}) error

Decode decodes the bytes read after the last call to Next into the specified value.

func (*Reader) Err

func (r *Reader) Err() error

Err returns the first non-EOF error that was encountered by the Reader.

func (*Reader) Next

func (r *Reader) Next() bool

Next advances the Reader to the next line, which will then be available through the Decode method. It returns false when the reader stops, either by reaching the end of the input or an error. After Next returns false, the Err method will return any error that occured while reading, except if it was io.EOF, Err will return nil.

Next might panic if the underlying split function returns too many tokens without advancing the input.

func (*Reader) Read

func (r *Reader) Read(p []byte) (n int, err error)

Read reads data into p. It returns the number of bytes read into p. The bytes are taken from the underlying reader. Read follows the protocol defined by io.Reader.

type Writer

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

Writer implements writing line-oriented JSON data following the ndjson spec at http://ndjson.org/.

Example

package main

import (
	"fmt"
	"os"

	"github.com/olivere/ndjson"
)

type Location struct {
	City string `json:"city"`
}

func main() {
	locations := []Location{
		{City: "Munich"},
		{City: "Berlin"},
		{City: "London"},
	}
	r := ndjson.NewWriter(os.Stdout)
	for _, loc := range locations {
		if err := r.Encode(loc); err != nil {
			fmt.Fprintf(os.Stderr, "Encode failed: %v", err)
			return
		}
	}
}

Output:

{"city":"Munich"}
{"city":"Berlin"}
{"city":"London"}

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a new Writer, using the underlying writer for output.

func (*Writer) Encode

func (w *Writer) Encode(v interface{}) error

Encode encodes v with a JSON encoder and writes the output to the underlying writer.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write writes the contents of p into the buffer. It returns the number of bytes written. if n < len(p), it also returns an error explaining why the write is short.