More on annotations

This commit is contained in:
Tony Garnock-Jones 2019-07-10 21:52:04 -04:00
parent c6700c2f2b
commit 7933e34766
1 changed files with 32 additions and 9 deletions

View File

@ -336,7 +336,8 @@ 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 / 2HEXDIG) ws "}"
ByteString =/ %s"#hex{" *(ws / hexchunk) ws "}"
hexchunk = 1*(2HEXDIG)
The third is as a sequence of
[Base64](https://tools.ietf.org/html/rfc4648) characters, interleaved
@ -392,20 +393,25 @@ prefixing a `ByteString` containing the binary representation of the
### Annotations.
When written down, a `Value` may have an associated sequence of
*annotations* carrying “out-of-band” contextual metadata about the
value. Each annotation is, in turn, a `Value`, and may itself have
annotations.
**Syntax.** When written down, a `Value` may have an associated
sequence of *annotations* carrying “out-of-band” contextual metadata
about the value. Each annotation is, in turn, a `Value`, and may
itself have annotations.
Value =/ ws "@" Value Value
Each annotation is preceded by `@`; the underlying annotated value
follows its annotations.
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 equivalences and
orderings of `Value`s.
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
equivalences and orderings of `Value`s.
Reflective tools such as debuggers, user interfaces, and message
routers and relays---tools which process `Value`s generically---may
@ -901,6 +907,23 @@ treat them specially.
and one which enforces validity (i.e. side-conditions) when reading,
writing, or constructing `Value`s.
### Comments.
`String` values used as annotations are conventionally interpreted as
comments.
@"I am a comment for the Dictionary"
{
@"I am a comment for the key"
key: @"I am a comment for the value"
value
}
#hex{00010203
@"I am a comment for the next chunk of ByteString data"
04050607
08090A0B}
### MIME-type tagged binary data.
Many internet protocols use