Add PrintAsJSON interface

json/json.go

@@ -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.