ehmry
/
preserves
forked from syndicate-lang/preserves
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

hexchunk was a bad idea; introduce IOList instead

This commit is contained in:
Tony Garnock-Jones 2019-07-11 12:34:47 -04:00
parent 2b1e2f2fba
commit 098cbe58ac
1 changed files with 26 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
preserves.md
View File

@ -336,8 +336,7 @@ value with `\x`.
The second is as a sequence of pairs of hexadecimal digits interleaved The second is as a sequence of pairs of hexadecimal digits interleaved
with whitespace and surrounded by `#hex{` and `}`. with whitespace and surrounded by `#hex{` and `}`.
ByteString =/ %s"#hex{" *(ws / hexchunk) ws "}" ByteString =/ %s"#hex{" *(ws / 2HEXDIG) ws "}"
hexchunk = 1*(2HEXDIG)
The third is as a sequence of The third is as a sequence of
[Base64](https://tools.ietf.org/html/rfc4648) characters, interleaved [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 Each annotation is preceded by `@`; the underlying annotated value
follows its annotations. 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`; **Equivalence.** Annotations appear within syntax denoting a `Value`;
however, the annotations are not part of the denoted value. They are however, the annotations are not part of the denoted value. They are
only part of the syntax. Annotations do not play a part in 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, and one which enforces validity (i.e. side-conditions) when reading,
writing, or constructing `Value`s. 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. ### Comments.
`String` values used as annotations are conventionally interpreted as `String` values used as annotations are conventionally interpreted as
@ -919,10 +926,18 @@ comments.
value value
} }
#hex{00010203 @"I am a comment for this entire IOList"
@"I am a comment for the next chunk of ByteString data" [
04050607 #hex{00010203}
08090A0B} @"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. ### MIME-type tagged binary data.