From 098cbe58ac84237242b7ca784fd58a3c81ca8889 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Thu, 11 Jul 2019 12:34:47 -0400
Subject: [PATCH] hexchunk was a bad idea; introduce IOList instead

---
 preserves.md | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/preserves.md b/preserves.md
index 1018dd5..688d4b0 100644
--- a/preserves.md
+++ b/preserves.md
@@ -336,8 +336,7 @@ value with `\x`.
 The second is as a sequence of pairs of hexadecimal digits interleaved
 with whitespace and surrounded by `#hex{` and `}`.
 
-       ByteString =/ %s"#hex{" *(ws / hexchunk) ws "}"
-          hexchunk = 1*(2HEXDIG)
+       ByteString =/ %s"#hex{" *(ws / 2HEXDIG) ws "}"
 
 The third is as a sequence of
 [Base64](https://tools.ietf.org/html/rfc4648) characters, interleaved
@@ -403,11 +402,6 @@ itself have annotations.
 Each annotation is preceded by `@`; the underlying annotated value
 follows its annotations.
 
-Any chunk of hexadecimal digits in a `#hex{`...`}` `ByteString` may
-similarly be annotated.
-
-         hexchunk =/ ws "@" Value hexchunk
-
 **Equivalence.** Annotations appear within syntax denoting a `Value`;
 however, the annotations are not part of the denoted value. They are
 only part of the syntax. Annotations do not play a part in
@@ -907,6 +901,19 @@ treat them specially.
   and one which enforces validity (i.e. side-conditions) when reading,
   writing, or constructing `Value`s.
 
+### IOLists.
+
+Inspired by Erlang's notions of
+[`iolist()` and `iodata()`](http://erlang.org/doc/reference_manual/typespec.html),
+an `IOList` is any tree constructed from `ByteString`s and
+`Sequence`s. Formally, an `IOList` is either a `ByteString` or a
+`Sequence` of `IOList`s.
+
+`IOList`s can be useful for
+[vectored I/O](https://en.wikipedia.org/wiki/Vectored_I/O).
+Additionally, the flexibility of `IOList` trees allows annotation of
+interior portions of a tree.
+
 ### Comments.
 
 `String` values used as annotations are conventionally interpreted as
@@ -919,10 +926,18 @@ comments.
            value
     }
 
-    #hex{00010203
-         @"I am a comment for the next chunk of ByteString data"
-         04050607
-         08090A0B}
+    @"I am a comment for this entire IOList"
+    [
+      #hex{00010203}
+      @"I am a comment for the middle half of the IOList"
+      @"A second comment for the same portion of the IOList"
+      [
+        @"I am a comment for the following ByteString"
+        #hex{04050607}
+        #hex{08090A0B}
+      ]
+      #hex{0C0D0E0F}
+    ]
 
 ### MIME-type tagged binary data.