README
¶
HuJSON - "Human JSON" (JWCC)
The github.com/tailscale/hujson package implements
the JWCC extension
of standard JSON.
This package is a fork of the Go standard library's encoding/json.
The JWCC format permits two things over standard JSON:
- C-style line comments and block comments intermixed with whitespace,
- allows trailing commas after the last member/element in an object/array.
All JSON is valid JWCC.
For details, see the JWCC docs at:
https://nigeltao.github.io/blog/2021/json-with-commas-comments.html
Documentation
¶
Overview ¶
Package hujson contains a parser and packer for the JWCC format: JSON With Commas and Comments (or "human JSON").
JWCC is an extension of standard JSON (as defined in RFC 8259) in order to make it more suitable for humans and configuration files. In particular, it supports line comments (e.g., //...), block comments (e.g., /*...*/), and trailing commas after the last member or element in a JSON object or array.
See https://nigeltao.github.io/blog/2021/json-with-commas-comments.html
Functionality ¶
The Parse function parses HuJSON input as a Value, which is a syntax tree exactly representing the input. Comments and whitespace are represented using the Extra type. Composite types in JSON are represented using the Object and Array types. Primitive types in JSON are represented using the Literal type. The Value.Pack method serializes the syntax tree as raw output, which is byte-for-byte identical to the input if no transformations were performed on the value.
Grammar ¶
The changes to the JSON grammar are:
--- grammar.json +++ grammar.hujson @@ -1,13 +1,31 @@ members member + member ',' ws member ',' members elements element + element ',' ws element ',' elements +comments + "*/" + comment comments + +comment + '0000' . '10FFFF' + +linecomments + '\n' + linecomment linecomments + +linecomment + '0000' . '10FFFF' - '\n' + ws "" + "/*" comments + "//" linecomments '0020' ws '000A' ws '000D' ws
Use with the Standard Library ¶
This package operates with HuJSON as an AST. In order to parse HuJSON into arbitrary Go types, use this package to parse HuJSON input as an AST, strip the AST of any HuJSON-specific lexicographical elements, and then pack the AST as a standard JSON output.
Example usage:
ast, err := hujson.Parse(b)
if err != nil {
... // handle err
}
ast.Standardize()
b = ast.Pack()
if err := json.Unmarshal(b, &v); err != nil {
... // handle err
}
Index ¶
- func Compact(dst *bytes.Buffer, src []byte) errordeprecated
- func HTMLEscape(dst *bytes.Buffer, src []byte)deprecated
- func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) errordeprecated
- func Marshal(v interface{}) ([]byte, error)deprecated
- func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)deprecated
- func Unmarshal(data []byte, v interface{}) errordeprecated
- func Valid(data []byte) booldeprecated
- type Array
- type ArrayElement
- type Decoderdeprecated
- func NewDecoder(r io.Reader) *Decoderdeprecated
- type Delimdeprecated
- type Encoderdeprecated
- func NewEncoder(w io.Writer) *Encoderdeprecated
- type Extra
- type InvalidUTF8Errordeprecated
- type InvalidUnmarshalErrordeprecated
- type Kind
- type Literal
- type Marshalerdeprecated
- type MarshalerErrordeprecated
- type Numberdeprecated
- type Object
- type ObjectMember
- type RawMessagedeprecated
- type SyntaxErrordeprecated
- type Tokendeprecated
- type UnmarshalFieldErrordeprecated
- type UnmarshalTypeErrordeprecated
- type Unmarshalerdeprecated
- type UnsupportedTypeErrordeprecated
- type UnsupportedValueErrordeprecated
- type Value
- type ValueTrimmed
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HTMLEscape
deprecated
func MarshalIndent
deprecated
Types ¶
type Array ¶
type Array struct {
// Elements are the elements of a JSON array.
// A trailing comma is emitted only if the Value.AfterExtra
// on the last value is non-nil. Otherwise it is omitted.
Elements []ArrayElement
// AfterExtra are the comments and whitespace
// after the preceding open bracket or comma and before the closing bracket.
AfterExtra Extra
}
Array is an exact syntactic representation of a JSON array.
type ArrayElement ¶
type ArrayElement = Value
type Decoder
deprecated
Deprecated: Do not use. This will be deleted in the near future. See the "Use with the Standard Library" section for alternatives.
func NewDecoder
deprecated
type Extra ¶
type Extra []byte
Extra is the raw bytes for whitespace and comments. Whitespace per RFC 8259, section 2 are permitted. Line comments that start with "//" and end with "\n" are permitted. Block comments that start with "/*" and end with "*/" are permitted.
func (Extra) IsStandard ¶
IsStandard reports whether this is standard JSON whitespace.
type InvalidUTF8Error
deprecated
type InvalidUTF8Error = json.InvalidUTF8Error
Deprecated: Do not use. This will be deleted in the near future.
type InvalidUnmarshalError
deprecated
type InvalidUnmarshalError = json.InvalidUnmarshalError
Deprecated: Do not use. This will be deleted in the near future.
type Kind ¶
type Kind byte
Kind reports the kind of the JSON value. It is the first byte of the grammar for that JSON value, with the exception that JSON numbers are represented as a '0'.
'n': null
'f': false
't': true
'"': string
'0': number
'{': object
'[': array
type Literal ¶
type Literal []byte // e.g., null, false, true, "string", or 3.14159
Literal is the raw bytes for a JSON null, boolean, string, or number. It contains no surrounding whitespace or comments.
func Float ¶
Float construct a JSON literal for a floating-point number. The values NaN, +Inf, and -Inf will be represented as a JSON string with the values "NaN", "Infinity", and "-Infinity".
func String ¶
String constructs a JSON literal for string. Invalid UTF-8 is mangled with the Unicode replacement character.
func (Literal) Bool ¶
Bool returns the value for a JSON boolean. It returns false if the literal is not a JSON boolean.
func (Literal) Float ¶
Float returns the floating-point value for a JSON number. It returns a NaN, +Inf, or -Inf value for any JSON string with the values "NaN", "Infinity", or "-Infinity". It returns 0 for all other cases.
func (Literal) Int ¶
Int returns the signed integer value for a JSON number. It returns 0 if the literal is not a signed integer.
func (Literal) IsValid ¶
IsValid reports whether b is a valid JSON null, boolean, string, or number. The literal must not have surrounding whitespace.
func (Literal) Kind ¶
Kind represents each possible JSON literal kind with a single byte, which is conveniently the first byte of that kind's grammar with the restriction that numbers always be represented with '0'.
type MarshalerError
deprecated
type MarshalerError = json.MarshalerError
Deprecated: Do not use. This will be deleted in the near future.
type Object ¶
type Object struct {
// Members are the members of a JSON object.
// A trailing comma is emitted only if the Value.AfterExtra
// on the last value is non-nil. Otherwise it is omitted.
Members []ObjectMember
// AfterExtra are the comments and whitespace
// after the preceding open brace or comma and before the closing brace.
AfterExtra Extra
}
Object is an exact syntactic representation of a JSON object.
type ObjectMember ¶
type ObjectMember = struct {
Name, Value Value
}
type RawMessage
deprecated
type RawMessage = json.RawMessage
Deprecated: Do not use. This will be deleted in the near future.
type SyntaxError
deprecated
type SyntaxError = json.SyntaxError
Deprecated: Do not use. This will be deleted in the near future.
type UnmarshalFieldError
deprecated
type UnmarshalFieldError = json.UnmarshalFieldError
Deprecated: Do not use. This will be deleted in the near future.
type UnmarshalTypeError
deprecated
type UnmarshalTypeError = json.UnmarshalTypeError
Deprecated: Do not use. This will be deleted in the near future.
type Unmarshaler
deprecated
type Unmarshaler = json.Unmarshaler
Deprecated: Do not use. This will be deleted in the near future.
type UnsupportedTypeError
deprecated
type UnsupportedTypeError = json.UnsupportedTypeError
Deprecated: Do not use. This will be deleted in the near future.
type UnsupportedValueError
deprecated
type UnsupportedValueError = json.UnsupportedValueError
Deprecated: Do not use. This will be deleted in the near future.
type Value ¶
type Value struct {
// BeforeExtra are the comments and whitespace before Value.
// This is the extra after the preceding open brace, open bracket,
// colon, comma, or start of input.
BeforeExtra Extra
// StartOffset is the offset of the first byte in Value.
StartOffset int
// Value is the JSON value without surrounding whitespace or comments.
Value ValueTrimmed
// EndOffset is the offset of the next byte after Value.
EndOffset int
// AfterExtra are the comments and whitespace after Value.
// This is the extra before the succeeding colon, comma, or end of input.
AfterExtra Extra
}
Value is an exact syntactic representation of a JSON value. The starting and ending byte offsets are populated when parsing, but are otherwise ignored when packing.
By convention, code should operate on a non-pointer Value as a soft signal that the value should not be mutated, while operating on a pointer to Value to indicate that the value may be mutated. A non-pointer Value does not provide any language-enforced guarantees that it cannot be mutated. The Value.Clone method can be used to produce a deep copy of Value such that mutations on it will not be observed in the original Value.
func Parse ¶
Parse parses a HuJSON value as a Value. Extra and Literal values in v will alias the provided input buffer.
func (Value) IsStandard ¶
IsStandard reports whether this is standard JSON by checking that there are no comments and no trailing commas.
func (*Value) Minimize ¶
func (v *Value) Minimize()
Minimize removes all whitespace, comments, and trailing commas from v, making it compliant with standard JSON per RFC 8259.
func (Value) Pack ¶
Pack serializes the value as HuJSON. The output is valid so long as every Extra and Literal in the Value is valid. The output does not alias the memory of any buffers referenced by v.
func (*Value) Standardize ¶
func (v *Value) Standardize()
Standardize strips any features specific to HuJSON from v, making it compliant with standard JSON per RFC 8259. All comments and trailing commas are replaced with a space character in order to preserve the original line numbers and byte offsets.
func (*Value) UpdateOffsets ¶
func (v *Value) UpdateOffsets()
UpdateOffsets iterates through v and updates all Value.StartOffset and Value.EndOffset fields so that they are accurate.
type ValueTrimmed ¶
type ValueTrimmed interface {
// Kind reports the kind of the JSON value.
Kind() Kind
// contains filtered or unexported methods
}
ValueTrimmed is a JSON value without surrounding whitespace or comments. This is a sum type consisting of Literal, *Object, or *Array.
Source Files
Directories