jsonc

README

JSON with comments for GO

• Decodes a "commented json" to "json". Provided, the input must be a valid jsonc document.
• Supports io.Reader
• With this, we can use commented json files as configuration for go applications.

Inspired by muhammadmuzzammil1998

{
	/*
        some block comment
  */
	"string": "foo", // a string
	"bool": false, // a boolean
	"number": 42, // a number
	// "object":{
	//     "key":"val"
	// },
	"array": [
		// example of an array
		1,
		2,
		3
	]
}

Gets converted to (spaces omitted)

{ "string": "foo", "bool": false, "number": 42, "array": [1, 2, 3] }

Motivation

jsonc is great. But this package provides significant performance improvements and simple API to use it with standard library. See benchmarks

Usage

Get this package

go get github.com/akshaybharambe14/go-jsonc

Benchmarks

Here is the performance comparison as compared to JSONC

go-jsonc avoids allocations to heap to gain the performance.

goos: windows
goarch: amd64
pkg: github.com/akshaybharambe14/go-jsonc/benchmarks
BenchmarkOwnSmallJSONBytes-4              256599              4952 ns/op         353.00 MB/s           0 B/op          0 allocs/op
BenchmarkOwnSmallJSONBytesReader-4        206823              5832 ns/op         299.70 MB/s        6224 B/op          5 allocs/op
BenchmarkJSONCSmallJSONBytes-4            171474              6925 ns/op         252.41 MB/s        1792 B/op          1 allocs/op
BenchmarkOwnBigJSONBytes-4                 33517             35921 ns/op         462.26 MB/s           0 B/op          0 allocs/op
BenchmarkOwnBigJSONBytesReader-4          105244             11292 ns/op        1470.45 MB/s        6224 B/op          5 allocs/op
BenchmarkJSONCBigJSONBytes-4               19599             61422 ns/op         270.34 MB/s       18432 B/op          1 allocs/op
PASS
ok      github.com/akshaybharambe14/go-jsonc/benchmarks 26.250s

Example

see examples

License

go-jsonc is open source and available under MIT License

Documentation

Index

• Variables
• func DecodeBytes(p []byte) (int, error)
• func DecodeString(s string) (string, error)
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Read(p []byte) (int, error)

Variables

var (
	ErrUnexpectedEndOfComment = errors.New("unexpected end of comment")
)

Functions

func DecodeBytes

func DecodeBytes(p []byte) (int, error)

DecodeBytes decodes passed commented json byte slice to normal json. It modifies the passed slice. The passed slice must be refferred till returned count, if there is no error.

The error doesn't include errors related to invalid json. If not nil, it must be ErrUnexpectedEndOfComment.

The returned json must be checked for validity.

func DecodeString

func DecodeString(s string) (string, error)

DecodeString decodes passed commented json to normal json. It uses "unsafe" way to convert a byte slice to result string. This saves allocations and improves performance is case of large json.

The error doesn't include errors related to invalid json. If not nil, it must be ErrUnexpectedEndOfComment.

The returned json must be checked for validity.

Types

type Decoder

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

Decoder represents a .jsonc decoder. It implements io.Reader.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new Decoder wrapping the provided io.Reader.

func (*Decoder) Read

func (d *Decoder) Read(p []byte) (int, error)

Read reads from underlying reader and processes the stream to omit comments. A single read doesn't guaranttee a valid JSON. Depends on length of passed slice.

Produces ErrUnexpectedEndOfComment for incomplete comments else if not nil, then it is an error from underlying reader.