More on annotations
This commit is contained in:
parent
c6700c2f2b
commit
7933e34766
41
preserves.md
41
preserves.md
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue