Human readable serialization

The goal is to output something that is easier to read than JSON. Something along the lines of NomDL but for values.

Requirements

• Machine readable
  • This implies that nothing can be ambiguous. We can solve this by knowing the type.
• Human readable
  • No numeric enum values.
  • No extra quotes.
  • No extra []. We can define our own syntax for set and map.
  • Optionally hide type
  • Short hashes
  • Indent output
  • Partial lists/strings/blobs/collections. When a list gets too large we could write ...

We probably need a --depth flag to follow refs.

Background can be found in. https://github.com/attic-labs/noms/issues/1153. However, this uses JSON which is not what we want.

The encoding of this is always UTF-8.

Rules

Numbers

Numbers are using exact representation when possible. We allow -/+ and e/E.

Strings

Strings are double quoted and " and \n are escaped. TBD what else is escaped.

Booleans

true or false

Blobs

base64 encoded

The main issue is how to represent an empty blob?

NomsList

[ value (, value)* ,? ]

NomsSet

{ value (, value)* ,? }

NomsMap

{ value : value (, value : value)* ,? }

Ref

sha1-12345

We'll probably have a flag to output full vs abbreviated hashes

Struct

StructName { name : value (, name : value)* ,? }

Type

All but Struct are just using the tag... Number, List<String> etc.

struct Color {
  red: Number,
  green: Number,
  blue: Number,
  opacity: Number,
}

Value

Not valid. A concrete value cannot have the type Value.

Tagged Values

When the type is not known from the context we need to tag the Value. This is done as T(V).

Strings, Booleans, Numbers

No need to tag it. The syntax is unique.

Blobs

Tagged by Blob.

Blob(TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvb)

NomsList

Tagged by List.

List<Number>([0, 1])

One option would be to omit the parens here but I left them for consistency.

NomsSet

Tagged by Set.

Set<String>({"a", "b"})

NomsMap

Tagged by Map.

Map<Number, String>({97: "a", 98: "b"})

Ref

Tagged by Ref.

Ref<Number>(sha1-3123419)

Struct

Tagged by Struct.

struct Person {
  name: String,
  age: Number,
}({
  name: "John Smith",
  age: 45,
})

Type

Tagged by Type

Type(Number)
Type(List<Bool>>)