Categorygithub.com/pschou/go-json
modulepackage
0.0.0-20210517164541-5569032ece7d
Repository: https://github.com/pschou/go-json.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
15
Dependents
2
Files
3.6k SLOC

# README

Go Package JSON

This package is very similar to the built-in go package called json, implementing encoding and decoding of JSON as defined in RFC 7159. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions.

Documentation: https://pkg.go.dev/github.com/pschou/go-json

Differences

The differences in this implementation are some additional functions and interfaces.

In the Decoder type, one will find two additional functions:

  • UseAutoConvert() - When enabled, this will attempt to convert any strings into defined element types, such as Integer, Boolean, or the CustomType interface
  • UseSlice() - When enabled, this will automatically convert an object into a slice if a slice is specified in the type declaration. When vendors provide JSON output, and this output is broken in that it can vary when one or more elements are returned, this decoder will try overcome this by creating a slice when specified and if one object is provided it will be a slice of one with that object.

Note: the encoding has two types TextMarshaler and TextUnmarshaler which can be interfaced via a custom type to implement readers and writers for non-standard JSON literals

    MarshalText() (text []byte, err error)
    UnmarshalText(text []byte) error

An example of how this could be useful is encoding and decoding custom time formats into a custom time.Duration type. Take for example a JSON API provides a time as "1D3H2M0S". With the use of a custom ToString / FromString this can be encoded / decoded when the JSON is being read in or written out.

# Functions

Compact appends to dst the JSON-encoded src with insignificant space characters elided.
HTMLEscape appends to dst the JSON-encoded src with <, >, &, U+2028 and U+2029 characters inside string literals changed to \u003c, \u003e, \u0026, \u2028, \u2029 so that the JSON will be safe to embed inside HTML <script> tags.
Indent appends to dst an indented form of the JSON-encoded src.
Marshal returns the JSON encoding of v.
MarshalIndent is like Marshal but applies Indent to format the output.
NewDecoder returns a new decoder that reads from r.
NewEncoder returns a new encoder that writes to w.
Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v.
Valid reports whether data is a valid JSON encoding.

# Structs

A Decoder reads and decodes JSON values from an input stream.
An Encoder writes JSON values to an output stream.
An InvalidUnmarshalError describes an invalid argument passed to Unmarshal.
Before Go 1.2, an InvalidUTF8Error was returned by Marshal when attempting to encode a string value with invalid UTF-8 sequences.
A MarshalerError represents an error from calling a MarshalJSON or MarshalText method.
A SyntaxError is a description of a JSON syntax error.
An UnmarshalFieldError describes a JSON object key that led to an unexported (and therefore unwritable) struct field.
An UnmarshalTypeError describes a JSON value that was not appropriate for a value of a specific Go type.
An UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.
An UnsupportedValueError is returned by Marshal when attempting to encode an unsupported value.

# Interfaces

Marshaler is the interface implemented by types that can marshal themselves into valid JSON.
A Token holds a value of one of these types: Delim, for the four JSON delimiters [ ] { } bool, for JSON booleans float64, for JSON numbers Number, for JSON numbers string, for JSON string literals nil, for JSON null .
Unmarshaler is the interface implemented by types that can unmarshal a JSON description of themselves.

# Type aliases

A Delim is a JSON array or object delimiter, one of [ ] { or }.
A Number represents a JSON number literal.
RawMessage is a raw encoded JSON value.