Notes
A to-do list is only useful if it is still there tomorrow. This program keeps one as JSON in a file: it saves a list, loads it back as if it were a new session, adds a note, saves again, and then deals with the two things that go wrong with real files — one that someone damaged by hand, and one that is not there at all.
It is the checkpoint for Part 21: Data formats, and it brings together files from Part 19, JSON from Part 21, and the error handling of Part 9 at full strength: five different error types meet in one program.
How it is put together
Each note is a small JSON object, {"title": "...", "done": false}, and the list is a JSON array of them. Saving turns the tree of JsonValues into text and writes it; loading reads the text and parses it back into a tree:
flowchart LR
tree["`JsonValue` tree<br/>in memory"] -- "`Encode`<br/>`WriteValue`, pretty" --> text["JSON text<br/>`String`"]
text -- "`Save`<br/>`WriteAtomically`" --> file[("`Bin/notes.json`")]
file -- "`Load`<br/>`Open`, `Size`, `ReadExact`" --> bytes["bytes"]
bytes -- "`Parse`" --> tree| Function | Its job | Throws | Lessons it uses |
|---|---|---|---|
Note | Builds one note object | TextError, JsonError | Writing JSON, Move |
Encode | Turns the tree into indented text | FormatError | Writing JSON, String builder |
Save | Replaces the file in one step | IoError | Atomic file |
Load | Reads the whole file and parses it | IoError, JsonParseError | File, Dynamic array, JSON |
PrintNotes | Prints the list, tolerating missing members | nothing | JSON, Presence |
Main | Two sessions, a damaged file, a missing file | all five | Error sum, Typed pattern |
Building a note
A note is an object with two members. Building it can throw in two ways — String::FromBytes throws a TextError when the bytes are not valid text, and Insert throws a JsonError when the value is not an object — so the function throws the sum of the two, and every step is marked with try:
func Note(allocator: Allocator, title: char8[..], done: bool) -> JsonValue throws (TextError | JsonError) {
var note = JsonValue::Object(allocator);
try note.Insert(String::FromBytes(allocator, "title"), JsonValue::Text(allocator, title));
try note.Insert(String::FromBytes(allocator, "done"), JsonValue::Boolean(allocator, done));
return move note;
}
One try covers its whole expression, so try note.Insert(String::FromBytes(...), ...) marks both throwing calls at once. A JsonValue owns the memory of everything inside it, so it cannot be copied — only moved. return move note; hands it to the caller.
Saving whole or not at all
Save is one call, and the call is the point:
func Save(allocator: Allocator, path: Path, text: char8[..]) throws IoError {
try WriteAtomically(allocator, path, text);
}
WriteAtomically writes the new text beside the old file and swaps it in only once it is complete. If the program crashes halfway through a save, the old list is still there, whole. Writing over the file directly would risk leaving half a list behind — the one outcome a notes file must never have.
Loading, step by step
Load asks the file how big it is, reads exactly that many bytes into an array of that size, and parses them:
func Load(allocator: Allocator, path: Path)
-> JsonValue throws (IoError | JsonParseError) {
var file = try File::Open(allocator, path, OpenOptions::Reading());
let size = try file.Size();
var bytes = Array::Filled<char8>(allocator, size as uint, c8' ');
try ReadExact(file, bytes.AsMutableSlice());
try file.Close();
return try Parse(allocator, bytes.AsSlice());
}
Opening, sizing, reading and closing can each throw an IoError, and parsing a JsonParseError. The throws clause lists both as a sum, and every plain try passes its error through unchanged. Making the array is the one step without a try: running out of memory is not an error a caller handles, so Array::Filled cannot throw.
Reading what may not be there
A file read from disk may have been edited by hand, so PrintNotes does not assume a note has both members. Find returns an optional reference, none when the member is missing, and AsBoolean returns bool?, none when the member is not a boolean:
let note = notes.At(i) ?? continue;
var done = false;
if note.Find(StringView::FromValidated("done")) is .Some(flag) {
done = flag.AsBoolean() ?? false;
}
if ... is .Some(flag) runs its block only when the member is there, with flag bound to it, and ?? false covers a member of the wrong kind. The title is read the same way, so a note with no title prints as (untitled).
Expected failures, and the rest
Main is declared throws (IoError | TextError | FormatError | JsonError | JsonParseError), so a plain try can pass anything up — and an error that leaves Main ends the program with status 1. But two failures are expected, and those are handled where they happen, with a try { } catch { } block. A damaged file is a JsonParseError, which knows the byte where the text stopped making sense:
try {
let _ = Load(allocator, path);
PrintLine("the damaged file loaded?");
} catch {
error: JsonParseError => PrintLine("damaged file refused at byte {}: {}", error.Offset(), error),
error => throw error
}
Inside the block every throwing call is covered, so Load needs no try of its own. The error is the sum IoError | JsonParseError, and the typed pattern error: JsonParseError picks out one member of it. A missing file is an IoError of kind NotFound, picked out with a typed pattern and a guard. In a real program, that arm is where "start a new, empty list" would go:
error: IoError if error.kind == IoErrorKind::NotFound =>
PrintLine("no notes file any more: starting a new list would begin here"),
error => throw error
In both blocks the last arm, error => throw error, passes anything unexpected out of Main, which ends the program with status 1.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// Notes: a to-do list that outlives the program, kept as JSON in a file.
//
// Each note is a small JSON object, `{"title": "...", "done": false}`, and the list is an array
// of them. Saving turns the tree of `JsonValue`s into text and writes it to disk; loading reads
// the text back and parses it into a tree again. Between the two, the program could stop and
// start a hundred times, which is the whole point of a file.
//
// A file is also where things go wrong. It may be missing, or it may hold something that is not
// JSON, perhaps because someone edited it by hand. Every step that touches the disk or parses
// text can throw, and the program catches the two failures it expects — a damaged file and a
// missing one — while `try` passes anything stranger on to `Main`, which then ends with status 1.
//
// The file lives in this package's `Bin/` folder, and the program deletes it at the end.
import Allocator::{ Allocator, SystemAllocator };
import Collections::Array;
import FileSystem::{ DeleteFile, File, OpenOptions, WriteAtomically };
import Io::{ IoError, IoErrorKind, PrintLine, ReadExact };
import Json::{ JsonError, JsonParseError, JsonStyle, JsonValue, Parse, WriteValue };
import Path::{ OsString, Path };
import Text::{ FormatError, String, StringBuilder, StringView, TextError, TextWriter };
func Note(allocator: Allocator, title: char8[..], done: bool) -> JsonValue throws (TextError | JsonError) {
var note = JsonValue::Object(allocator);
try note.Insert(String::FromBytes(allocator, "title"), JsonValue::Text(allocator, title));
try note.Insert(String::FromBytes(allocator, "done"), JsonValue::Boolean(allocator, done));
return move note;
}
// Turns the notes into indented JSON text, ready to be written or shown.
func Encode(allocator: Allocator, notes: &JsonValue) -> String throws FormatError {
var builder = StringBuilder(allocator);
let sink: &var TextWriter = builder;
try WriteValue(sink, notes, JsonStyle::Pretty());
return builder.TakeString();
}
// Writing atomically means the old file is replaced only once the new one is complete, so a
// crash halfway through a save can never leave half a list behind.
func Save(allocator: Allocator, path: Path, text: char8[..]) throws IoError {
try WriteAtomically(allocator, path, text);
}
// Asks the file how big it is, reads exactly that many bytes, and parses them.
func Load(allocator: Allocator, path: Path)
-> JsonValue throws (IoError | JsonParseError) {
var file = try File::Open(allocator, path, OpenOptions::Reading());
let size = try file.Size();
var bytes = Array::Filled<char8>(allocator, size as uint, c8' ');
try ReadExact(file, bytes.AsMutableSlice());
try file.Close();
return try Parse(allocator, bytes.AsSlice());
}
// A note read from a file might lack a member, or hold one of the wrong kind, so each lookup
// gives an optional that is checked before it is read.
func PrintNotes(notes: &JsonValue) {
for i in 0..(notes.Length() ?? 0) {
let note = notes.At(i) ?? continue;
var done = false;
if note.Find(StringView::FromValidated("done")) is .Some(flag) {
done = flag.AsBoolean() ?? false;
}
let mark = if done { "x" } else { " " };
var title = StringView::FromValidated("(untitled)");
if note.Find(StringView::FromValidated("title")) is .Some(member) {
title = member.AsText() ?? title;
}
PrintLine(" [{}] {}", mark, title);
}
}
func Main() throws (IoError | TextError | FormatError | JsonError | JsonParseError) {
let allocator = SystemAllocator();
var holder = OsString::FromText(allocator, "Bin/notes.json");
let path = Path::FromView(holder.View());
// The first session: start a list and save it.
var notes = JsonValue::Array(allocator);
try notes.Push(Note(allocator, "buy milk", true));
try notes.Push(Note(allocator, "water the plants", false));
let first = try Encode(allocator, notes);
try Save(allocator, path, first.View().Bytes());
PrintLine("saved {} notes to {}", notes.Length() ?? 0, path);
// The next session knows nothing but the file: load it, add a note, save it again.
var loaded = try Load(allocator, path);
try loaded.Push(Note(allocator, "write a Rux program", false));
let second = try Encode(allocator, loaded);
try Save(allocator, path, second.View().Bytes());
PrintLine("added a note; the file now reads:");
PrintLine("{}", second.View());
// And one more time, to read the list as a person would.
let final = try Load(allocator, path);
PrintLine("{} notes:", final.Length() ?? 0);
PrintNotes(final);
// Someone edits the file by hand and cuts it short. Loading now fails as a parse error, which
// says where the text stopped making sense.
try Save(allocator, path, "[{\"title\": \"half a note\"");
try {
let _ = Load(allocator, path);
PrintLine("the damaged file loaded?");
} catch {
error: JsonParseError => PrintLine("damaged file refused at byte {}: {}", error.Offset(), error),
error => throw error
}
// Clean up, then show that a missing file is told apart from every other I/O failure.
try DeleteFile(allocator, path);
try {
let _ = Load(allocator, path);
PrintLine("the deleted file loaded?");
} catch {
error: IoError if error.kind == IoErrorKind::NotFound =>
PrintLine("no notes file any more: starting a new list would begin here"),
error => throw error
}
}
Besides Io, its Rux.toml lists Allocator, Collections, FileSystem, Json, Path and Text under [Dependencies].
Run it
cd Examples/Projects/Notes
rux run
saved 2 notes to Bin/notes.json
added a note; the file now reads:
[
{
"title": "buy milk",
"done": true
},
{
"title": "water the plants",
"done": false
},
{
"title": "write a Rux program",
"done": false
}
]
3 notes:
[x] buy milk
[ ] water the plants
[ ] write a Rux program
damaged file refused at byte 24: document ended in the middle of a value
no notes file any more: starting a new list would begin here
The file is written to the package's Bin/ folder, next to the build output, and the program deletes it before it ends, so a second run starts from nothing again.
Common mistakes
Try it yourself
- Mark a note as done: load the list, find "water the plants", set its
donemember totrue, and save it again. - Turn the missing-file arm into real behaviour: when the file is not there, start with an empty array instead of failing.
- Make the program a tiny command-line tool: read one line from the input with Input, add it as a note, save, and print the list. Remove the
DeleteFilecall so the notes survive between runs. - Damage the file differently — a missing comma, a stray
}— and see what offset and message the parser reports for each.
Learn more
- JSON and Writing JSON
- File and Atomic file
- Error sum and Typed pattern — one function, several kinds of failure
- Next project: Melody, the checkpoint for Platform
27.14 Launch
Run a mission checklist, ask for a countdown from 1 to 10, count down and launch a rocket up the terminal.
27.16 Melody
Play the opening of Ode to Joy through the console speaker by calling the Windows Beep function directly. Each call sits in an unsafe block with a // Safety: comment, because the compiler cannot check what a foreign function does.