|
|
|
@ -14,29 +14,35 @@ default string marshaling format.
|
|
|
|
|
package json
|
|
|
|
|
|
|
|
|
|
// PrintAsJSON provides a consistent representation of any structure
|
|
|
|
|
// such that it an easily be read and compared during testing. Sadly,
|
|
|
|
|
// the default string representations for most types in Go are virtually
|
|
|
|
|
// unusable for consistent, structured representations of any structure.
|
|
|
|
|
// such that it an easily be read and compared as JSON whenever printed
|
|
|
|
|
// and test. Sadly, the default string representations for most types in
|
|
|
|
|
// Go are virtually unusable for consistent representations of any
|
|
|
|
|
// structure. And while it is true that JSON data should be supported in
|
|
|
|
|
// any way that is it presented, some consistent output makes for more
|
|
|
|
|
// consistent debugging, documentation, and testing.
|
|
|
|
|
//
|
|
|
|
|
// PrintAsJSON implementations must fulfill their marshaling to any
|
|
|
|
|
// textual/printable representation by producing parsable, shareable
|
|
|
|
|
// JSON() data, either in a multi-line (strictly 2-space indented) or
|
|
|
|
|
// a compressed single line form (JSONL) with no spacing.
|
|
|
|
|
// textual/printable representation by producing compressed,
|
|
|
|
|
// single-line, no-spaces, parsable, shareable not-unnecessarily-escaped
|
|
|
|
|
// JSON data. When indented, long-form JSON is wanted utility functions
|
|
|
|
|
// and utilities (such as jq) can be used to expand the compressed,
|
|
|
|
|
// default JSON.
|
|
|
|
|
//
|
|
|
|
|
// All implementations must also implement the fmt.Stringer interface by
|
|
|
|
|
// calling the JSON() multi-line (pretty) form. Thankfully, Go does
|
|
|
|
|
// ensure that the order of elements in any type will appear
|
|
|
|
|
// consistently in that same order during testing even though they
|
|
|
|
|
// should never be relied upon for such ordering other than in testing.
|
|
|
|
|
// calling JSON(), which most closely approximates the Go standard
|
|
|
|
|
// string marshalling. Thankfully, Go does ensure that the order of
|
|
|
|
|
// elements in any type will appear consistently in that same order
|
|
|
|
|
// during testing even though they should never be relied upon for such
|
|
|
|
|
// ordering other than in testing.
|
|
|
|
|
//
|
|
|
|
|
// All implementations must promise they will never escape any string
|
|
|
|
|
// character that is not specifically required to be escaped by the JSON
|
|
|
|
|
// standard as described in this PEGN specification:
|
|
|
|
|
//
|
|
|
|
|
// String <-- DQ (Escaped / [x20-x21] / [x23-x5B]
|
|
|
|
|
// / [x5D-x10FFFF])* DQ
|
|
|
|
|
// Escaped <- BKSLASH ("b" / "f" / "n" / "r"
|
|
|
|
|
// / "t" / "u" hex{4} / DQ / BKSLASH / SLASH)
|
|
|
|
|
// / [x5D-x10FFFF])* DQ
|
|
|
|
|
// Escaped <- BKSLASH ("b" / "f" / "n" / "r" / "t" / "u" hex{4}
|
|
|
|
|
// / DQ / BKSLASH / SLASH)
|
|
|
|
|
//
|
|
|
|
|
// This means that binary data will never be represented as Unicode
|
|
|
|
|
// escapes of any kind and should always be converted to base64 encoding
|
|
|
|
@ -48,7 +54,7 @@ package json
|
|
|
|
|
// safe and accepted standard (and always have been). PrintAsJSON
|
|
|
|
|
// implementers promise those using their implementations will produce
|
|
|
|
|
// JSON output that is highly consistent. To facilitate this,
|
|
|
|
|
// implementations may implement MarshalJSON methods that delegatet to
|
|
|
|
|
// implementations may implement MarshalJSON methods that delegate to
|
|
|
|
|
// bonzai/json.Marshal as a quick fix.
|
|
|
|
|
//
|
|
|
|
|
// In general, implementers of PrintAsJSON should not depend on
|
|
|
|
@ -58,10 +64,11 @@ package json
|
|
|
|
|
// unmarshaled values are within acceptable ranges. Errors are only
|
|
|
|
|
// generated if the actual JSON syntax itself is incorrect.
|
|
|
|
|
type PrintAsJSON interface {
|
|
|
|
|
JSON() string // multi-line, 2-space indent, never escape unicode
|
|
|
|
|
JSONL() string // single line, no spacing, never escape unicode
|
|
|
|
|
String() string // must call JSON()
|
|
|
|
|
Print() string // must call String()
|
|
|
|
|
// MarshalJSON() ([]byte, error) // encouraged, but not required
|
|
|
|
|
JSON() string // compressed, single line, no spaces, no extra escapes
|
|
|
|
|
String() string // must return s.JSON()
|
|
|
|
|
Print() string // must call fmt.Println(s.JSON())
|
|
|
|
|
Log() string // must call log.Print(s.JSON())
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// WS contains all JSON valid whitespace values.
|
|
|
|
|