json

package
v0.3.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2023 License: BSD-3-Clause, GPL-2.0-or-later Imports: 11 Imported by: 0

README

lowmemjson/compat/json

lowmemjson/compat/json is a wrapper around lowmemjson that is a (mostly) drop-in replacement for the standard library's encoding/json.

This package does not bother to duplicate encoding/json's documentation; you should instead refer to encoding/json's own documentation.

Incompatibilities

Tokens

Because the lowmemjson parser is fundamentally different than the encoding/json parser and does not have any notion of tokens, the token API is not included in lowmemjson/compat/json:

Types

When possible, lowmemjson/compat/json uses type aliases for the encoding/json types, but in several cases that is not possible (Encoder, Decoder, SyntaxError, MarshalError). This means that while lowmemjson/compat/json is source-compatible with encoding/json, it may not interoperate with code that also uses encoding/json and relies on those type identities.

The errors returned by the various functions are the same errors as returned by encoding/json (with the exception that SyntaxError and MarshalError are not type aliases).

Deprecations

Types that are deprecated in encoding/json are not mimiced here:

Documentation

Overview

Package json is a wrapper around lowmemjson that is a (mostly) drop-in replacement for the standard library's encoding/json.

Example (CustomMarshalJSON) 
package main

import (
	"fmt"
	"log"
	"strings"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

type Animal int

const (
	Unknown Animal = iota
	Gopher
	Zebra
)

func (a *Animal) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	switch strings.ToLower(s) {
	default:
		*a = Unknown
	case "gopher":
		*a = Gopher
	case "zebra":
		*a = Zebra
	}

	return nil
}

func (a Animal) MarshalJSON() ([]byte, error) {
	var s string
	switch a {
	default:
		s = "unknown"
	case Gopher:
		s = "gopher"
	case Zebra:
		s = "zebra"
	}

	return json.Marshal(s)
}

func main() {
	blob := `["gopher","armadillo","zebra","unknown","gopher","bee","gopher","zebra"]`
	var zoo []Animal
	if err := json.Unmarshal([]byte(blob), &zoo); err != nil {
		log.Fatal(err)
	}

	census := make(map[Animal]int)
	for _, animal := range zoo {
		census[animal] += 1
	}

	fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras:  %d\n* Unknown: %d\n",
		census[Gopher], census[Zebra], census[Unknown])

}

Output:

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3
Example (TextMarshalJSON) 
package main

import (
	"fmt"
	"log"
	"strings"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

type Size int

const (
	Unrecognized Size = iota
	Small
	Large
)

func (s *Size) UnmarshalText(text []byte) error {
	switch strings.ToLower(string(text)) {
	default:
		*s = Unrecognized
	case "small":
		*s = Small
	case "large":
		*s = Large
	}
	return nil
}

func (s Size) MarshalText() ([]byte, error) {
	var name string
	switch s {
	default:
		name = "unrecognized"
	case Small:
		name = "small"
	case Large:
		name = "large"
	}
	return []byte(name), nil
}

func main() {
	blob := `["small","regular","large","unrecognized","small","normal","small","large"]`
	var inventory []Size
	if err := json.Unmarshal([]byte(blob), &inventory); err != nil {
		log.Fatal(err)
	}

	counts := make(map[Size]int)
	for _, size := range inventory {
		counts[size] += 1
	}

	fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
		counts[Small], counts[Large], counts[Unrecognized])

}

Output:

Inventory Counts:
* Small:        3
* Large:        2
* Unrecognized: 3

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Compact 

func Compact(dst *bytes.Buffer, src []byte) error

func HTMLEscape 

func HTMLEscape(dst *bytes.Buffer, src []byte)
Example 
package main

import (
	"bytes"
	"os"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	var out bytes.Buffer
	json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`))
	out.WriteTo(os.Stdout)
}

Output:

{"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}

func Indent 

func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
Example 
package main

import (
	"bytes"
	"log"
	"os"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	type Road struct {
		Name   string
		Number int
	}
	roads := []Road{
		{"Diamond Fork", 29},
		{"Sheep Creek", 51},
	}

	b, err := json.Marshal(roads)
	if err != nil {
		log.Fatal(err)
	}

	var out bytes.Buffer
	json.Indent(&out, b, "=", "\t")
	out.WriteTo(os.Stdout)
}

Output:

[
=	{
=		"Name": "Diamond Fork",
=		"Number": 29
=	},
=	{
=		"Name": "Sheep Creek",
=		"Number": 51
=	}
=]

func Marshal 

func Marshal(v any) ([]byte, error)
Example 
package main

import (
	"fmt"
	"os"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	type ColorGroup struct {
		ID     int
		Name   string
		Colors []string
	}
	group := ColorGroup{
		ID:     1,
		Name:   "Reds",
		Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
	}
	b, err := json.Marshal(group)
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)
}

Output:

{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}

func MarshalIndent 

func MarshalIndent(v any, prefix, indent string) ([]byte, error)
Example 
package main

import (
	"fmt"
	"log"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	data := map[string]int{
		"a": 1,
		"b": 2,
	}

	b, err := json.MarshalIndent(data, "<prefix>", "<indent>")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))
}

Output:

{
<prefix><indent>"a": 1,
<prefix><indent>"b": 2
<prefix>}

func Unmarshal 

func Unmarshal(data []byte, ptr any) error
Example 
package main

import (
	"fmt"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	var jsonBlob = []byte(`[
	{"Name": "Platypus", "Order": "Monotremata"},
	{"Name": "Quoll",    "Order": "Dasyuromorphia"}
]`)
	type Animal struct {
		Name  string
		Order string
	}
	var animals []Animal
	err := json.Unmarshal(jsonBlob, &animals)
	if err != nil {
		fmt.Println("error:", err)
	}
	fmt.Printf("%+v", animals)
}

Output:

[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]

func Valid 

func Valid(data []byte) bool
Example 
package main

import (
	"fmt"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	goodJSON := `{"example": 1}`
	badJSON := `{"example":2:]}}`

	fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON)))
}

Output:

true false

Types

type Decoder 

type Decoder struct {
	*lowmemjson.Decoder
	// contains filtered or unexported fields
}
Example

This example uses a Decoder to decode a stream of distinct JSON values. 

package main

import (
	"fmt"
	"io"
	"log"
	"strings"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	const jsonStream = `
	{"Name": "Ed", "Text": "Knock knock."}
	{"Name": "Sam", "Text": "Who's there?"}
	{"Name": "Ed", "Text": "Go fmt."}
	{"Name": "Sam", "Text": "Go fmt who?"}
	{"Name": "Ed", "Text": "Go fmt yourself!"}
`
	type Message struct {
		Name, Text string
	}
	dec := json.NewDecoder(strings.NewReader(jsonStream))
	for {
		var m Message
		if err := dec.Decode(&m); err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%s: %s\n", m.Name, m.Text)
	}
}

Output:

Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Buffered 

func (dec *Decoder) Buffered() io.Reader

func (*Decoder) Decode 

func (dec *Decoder) Decode(ptr any) error

type Encoder 

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

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

func (*Encoder) Encode 

func (enc *Encoder) Encode(v any) error

func (*Encoder) SetEscapeHTML 

func (enc *Encoder) SetEscapeHTML(on bool)

func (*Encoder) SetIndent 

func (enc *Encoder) SetIndent(prefix, indent string)

type InvalidUnmarshalError 

type InvalidUnmarshalError = json.InvalidUnmarshalError

high-level decode errors.

type Marshaler 

type Marshaler = json.Marshaler

type MarshalerError 

type MarshalerError struct {
	Type reflect.Type
	Err  error
	// contains filtered or unexported fields
}

A MarshalerError represents an error from calling a MarshalJSON or MarshalText method.

func (*MarshalerError) Error 

func (e *MarshalerError) Error() string

func (*MarshalerError) Unwrap 

func (e *MarshalerError) Unwrap() error

Unwrap returns the underlying error.

type Number 

type Number = json.Number

type RawMessage 

type RawMessage = json.RawMessage
Example (Marshal)

This example uses RawMessage to use a precomputed JSON during marshal. 

package main

import (
	"fmt"
	"os"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	h := json.RawMessage(`{"precomputed": true}`)

	c := struct {
		Header *json.RawMessage `json:"header"`
		Body   string           `json:"body"`
	}{Header: &h, Body: "Hello Gophers!"}

	b, err := json.MarshalIndent(&c, "", "\t")
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)

}

Output:

{
	"header": {
		"precomputed": true
	},
	"body": "Hello Gophers!"
}
Example (Unmarshal)

This example uses RawMessage to delay parsing part of a JSON message. 

package main

import (
	"fmt"
	"log"

	"git.lukeshu.com/go/lowmemjson/compat/json"
)

func main() {
	type Color struct {
		Space string
		Point json.RawMessage // delay parsing until we know the color space
	}
	type RGB struct {
		R uint8
		G uint8
		B uint8
	}
	type YCbCr struct {
		Y  uint8
		Cb int8
		Cr int8
	}

	var j = []byte(`[
	{"Space": "YCbCr", "Point": {"Y": 255, "Cb": 0, "Cr": -10}},
	{"Space": "RGB",   "Point": {"R": 98, "G": 218, "B": 255}}
]`)
	var colors []Color
	err := json.Unmarshal(j, &colors)
	if err != nil {
		log.Fatalln("error:", err)
	}

	for _, c := range colors {
		var dst any
		switch c.Space {
		case "RGB":
			dst = new(RGB)
		case "YCbCr":
			dst = new(YCbCr)
		}
		err := json.Unmarshal(c.Point, dst)
		if err != nil {
			log.Fatalln("error:", err)
		}
		fmt.Println(c.Space, dst)
	}
}

Output:

YCbCr &{255 0 -10}
RGB &{98 218 255}

type SyntaxError 

type SyntaxError struct {
	Offset int64 // error occurred after reading Offset bytes
	// contains filtered or unexported fields
}

A SyntaxError is a description of a JSON syntax error. Unmarshal will return a SyntaxError if the JSON can't be parsed.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

type UnmarshalTypeError 

type UnmarshalTypeError = json.UnmarshalTypeError

low-level decode errors.

type Unmarshaler added in v0.2.0 

type Unmarshaler = json.Unmarshaler

type UnsupportedTypeError 

type UnsupportedTypeError = json.UnsupportedTypeError

marshal errors.

type UnsupportedValueError 

type UnsupportedValueError = json.UnsupportedValueError

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.