Writing JSON
Writing JSON is the parse lesson run backwards: a tree of JsonValues goes in, text comes out. The tree can come from Parse, or — as here — be built by hand, one value at a time. This lesson builds a small document, writes it two ways, and proves the writing is faithful by reading the output back.
import Json::{ JsonError, JsonStyle, JsonValue, Parse, WriteValue };
import Text::{ FormatError, String, StringBuilder, TextError, TextWriter };
Building a tree by hand
Each kind has a constructor: JsonValue::Text, Number, Boolean, Null, Array and Object. Containers start empty; Push appends to an array and Insert adds a member to an object:
var tags = JsonValue::Array(allocator);
try tags.Push(JsonValue::Text(allocator, "fast"));
try tags.Push(JsonValue::Number(allocator, "2.50"));
var root = JsonValue::Object(allocator);
try root.Insert(String::FromBytes(allocator, "name"), JsonValue::Text(allocator, "Rux"));
try root.Insert(String::FromBytes(allocator, "quote"),
JsonValue::Text(allocator, "say \"hi\"\n"));
try root.Insert(String::FromBytes(allocator, "tags"), move tags);
try root.Insert(String::FromBytes(allocator, "license"), JsonValue::Null(allocator));
Four things to notice:
- Text is copied into the tree.
TextandString::FromBytescopy their bytes into memory from the allocator, and they throw aTextErrorwhen the bytes are not valid UTF-8. - A number is given as text.
"2.50"stays2.50, exactly as written, the same way a parsed number keeps its text.NumberthrowsJsonError::MalformedNumberfor text that is not a JSON number. - The containers check their kind.
Pushinto a value that is not an array, orInsertinto one that is not an object, throwsJsonError::WrongKind. - Values are move-only. A
JsonValueowns everything under it, so it cannot be copied.PushandInserttake ownership of what they are given, and handing over the finishedtagsarray is an explicit move:move tags. After that linetagsis gone, and the array lives on insideroot.
So almost every line can throw, and each one is marked with try. One try covers the whole expression to its right, so try tags.Push(JsonValue::Text(allocator, "fast")) marks both the Text call and the Push. Main is declared throws (TextError | FormatError | JsonError) — an error sum — so plain try passes a failure of any of the three kinds on, and a throwing Main turns it into the program's exit status.
Writing it out
WriteValue writes a tree into any TextWriter:
WriteValue(writer, value, style) throws FormatError
Written points it at a StringBuilder, so the text can be kept, measured and parsed again, and hands the result back as a String the caller owns:
func Written(allocator: Allocator, value: &JsonValue, style: JsonStyle) -> String throws FormatError {
var builder = StringBuilder(allocator);
let sink: &var TextWriter = builder;
try WriteValue(sink, value, style);
return builder.TakeString();
}
JsonStyle chooses the layout:
| Style | Layout | Size of this document | For |
|---|---|---|---|
JsonStyle::Compact() | no whitespace at all | 73 bytes | a wire, a file |
JsonStyle::Pretty() | one value per line, two-space indent | 103 bytes | a person |
Either way the writer escapes exactly what JSON requires inside strings and nothing more: the quote's " and its newline come out as \" and \n.
The round trip
A writer is only trustworthy if what it writes reads back as the same thing. The program parses the pretty text and writes it compact again. A failed parse here is handled on the spot by the catch arms, which print the reason and leave Main:
let again = try Parse(allocator, pretty.View().Bytes()) catch {
reason => {
PrintLine("the written text did not parse: {}", reason);
return;
}
};
let rewritten = try Written(allocator, again, JsonStyle::Compact());
PrintLine("round trip gives the same text: {}", rewritten.View().Equals(compact.View()));
flowchart LR
tree["Tree built<br/>by hand"] -- "`Compact`" --> c1["compact text"]
tree -- "`Pretty`" --> p["pretty text"]
p -- "`Parse`" --> tree2["Tree read back"]
tree2 -- "`Compact`" --> c2["compact text"]
c2 -. "the same bytes as" .-> c1The layout was only presentation, so the same 73 bytes come back — including 2.50, which did not become 2.5, because a number keeps the text it was written with.
What JSON cannot say
JSON has no spelling for NaN or infinity. A number with the text "NaN" is refused as soon as it is made, so it never reaches the tree and is never written out as something invented. The try block sees two kinds of error — JsonError from Number, FormatError from Written — so its arms take each type in turn:
try {
let notANumber = JsonValue::Number(allocator, "NaN");
let text = Written(allocator, notANumber, JsonStyle::Compact());
PrintLine("wrote {}", text.View());
} catch {
_: JsonError => PrintLine("NaN refused: not a JSON number"),
error: FormatError => PrintLine("NaN not written: {}", error)
}
The first arm runs, and the program prints NaN refused: not a JSON number.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// Writing JSON is the parse lesson run backwards: a tree of `JsonValue`s goes in, text comes
// out. The tree can come from `Parse` or be built by hand, and `WriteValue` writes it into any
// `TextWriter` — a StringBuilder here, so the text can be kept and parsed again.
//
// WriteValue(writer, value, style) throws FormatError
//
// `JsonStyle` chooses the layout. `Compact()` writes no whitespace at all, for a document going
// over a wire; `Pretty()` indents by two spaces, for a person. Either way the writer escapes
// exactly what JSON requires inside strings, and nothing more.
import Allocator::{ Allocator, SystemAllocator };
import Io::PrintLine;
import Json::{ JsonError, JsonStyle, JsonValue, Parse, WriteValue };
import Text::{ FormatError, String, StringBuilder, TextError, TextWriter };
// Writes `value` in `style` and hands the text back as a String the caller owns.
func Written(allocator: Allocator, value: &JsonValue, style: JsonStyle) -> String throws FormatError {
var builder = StringBuilder(allocator);
let sink: &var TextWriter = builder;
try WriteValue(sink, value, style);
return builder.TakeString();
}
func Main() throws (TextError | FormatError | JsonError) {
let allocator = SystemAllocator();
// Building by hand. Values are move-only: `Push` and `Insert` take ownership of what they
// are given, and a member's name is an owned String. `Push` into a value that is not an
// array, or `Insert` into one that is not an object, throws `JsonError::WrongKind`.
var tags = JsonValue::Array(allocator);
try tags.Push(JsonValue::Text(allocator, "fast"));
try tags.Push(JsonValue::Number(allocator, "2.50"));
var root = JsonValue::Object(allocator);
try root.Insert(String::FromBytes(allocator, "name"), JsonValue::Text(allocator, "Rux"));
try root.Insert(String::FromBytes(allocator, "quote"),
JsonValue::Text(allocator, "say \"hi\"\n"));
try root.Insert(String::FromBytes(allocator, "tags"), move tags);
try root.Insert(String::FromBytes(allocator, "license"), JsonValue::Null(allocator));
let compact = try Written(allocator, root, JsonStyle::Compact());
let pretty = try Written(allocator, root, JsonStyle::Pretty());
PrintLine("compact, {} bytes:\n{}", compact.Length(), compact.View());
PrintLine("pretty, {} bytes:\n{}", pretty.Length(), pretty.View());
// The round trip: parse the pretty text and write it compact again. The layout was only
// presentation, so the same bytes come back. A number keeps the text it was written with,
// which is why `2.50` did not become `2.5`.
let again = try Parse(allocator, pretty.View().Bytes()) catch {
reason => {
PrintLine("the written text did not parse: {}", reason);
return;
}
};
let rewritten = try Written(allocator, again, JsonStyle::Compact());
PrintLine("round trip gives the same text: {}", rewritten.View().Equals(compact.View()));
// JSON cannot spell NaN or infinity, so a number with that text is refused as soon as it is
// made, and never written out as something invented. The `try` block sees both errors, so
// its arms take each type in turn.
try {
let notANumber = JsonValue::Number(allocator, "NaN");
let text = Written(allocator, notANumber, JsonStyle::Compact());
PrintLine("wrote {}", text.View());
} catch {
_: JsonError => PrintLine("NaN refused: not a JSON number"),
error: FormatError => PrintLine("NaN not written: {}", error)
}
}
Besides Io, its Rux.toml lists Allocator, Json and Text under [Dependencies].
Run it
cd Examples/DataFormats/JsonWrite
rux run
compact, 73 bytes:
{"name":"Rux","quote":"say \"hi\"\n","tags":["fast",2.50],"license":null}
pretty, 103 bytes:
{
"name": "Rux",
"quote": "say \"hi\"\n",
"tags": [
"fast",
2.50
],
"license": null
}
round trip gives the same text: true
NaN refused: not a JSON number
Common mistakes
Try it yourself
- Add a boolean member,
"beta": true, withJsonValue::Boolean(allocator, true). How many bytes is the compact text now? - Build a nested object — say
"author": {"name": "Ada"}— and look at howPretty()indents it. - Try
"Infinity"and"01"instead of"NaN". Are they refused too? Insertnever replaces: insert"name"a second time and write the tree. What doesParsesay when it reads that text back?- Parse the document from the JSON lesson and write it out with
Pretty().
Learn more
- JSON — reading a document into the tree this lesson writes
- Move — what
movedoes, and why aJsonValuecannot be copied - String builder — the
TextWriterthat collects the text - Error sum — one throwing
Mainfor three kinds of error - Passing errors on in the Rux Reference
- Notes — a checkpoint project that saves a to-do list as JSON and loads it back