forked from syndicate-lang/preserves
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
|
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 / 2HEXDIG) ws "}"
|
ByteString =/ %s"#hex{" *(ws / hexchunk) 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
|
||||||
|
@ -392,20 +393,25 @@ prefixing a `ByteString` containing the binary representation of the
|
||||||
|
|
||||||
### Annotations.
|
### Annotations.
|
||||||
|
|
||||||
When written down, a `Value` may have an associated sequence of
|
**Syntax.** When written down, a `Value` may have an associated
|
||||||
*annotations* carrying “out-of-band” contextual metadata about the
|
sequence of *annotations* carrying “out-of-band” contextual metadata
|
||||||
value. Each annotation is, in turn, a `Value`, and may itself have
|
about the value. Each annotation is, in turn, a `Value`, and may
|
||||||
annotations.
|
itself have annotations.
|
||||||
|
|
||||||
Value =/ ws "@" Value Value
|
Value =/ ws "@" Value Value
|
||||||
|
|
||||||
Each annotation is preceded by `@`; the underlying annotated value
|
Each annotation is preceded by `@`; the underlying annotated value
|
||||||
follows its annotations.
|
follows its annotations.
|
||||||
|
|
||||||
Annotations appear within syntax denoting a `Value`; however, the
|
Any chunk of hexadecimal digits in a `#hex{`...`}` `ByteString` may
|
||||||
annotations are not part of the denoted value. They are only part of
|
similarly be annotated.
|
||||||
the syntax. Annotations do not play a part in equivalences and
|
|
||||||
orderings of `Value`s.
|
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
|
Reflective tools such as debuggers, user interfaces, and message
|
||||||
routers and relays---tools which process `Value`s generically---may
|
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,
|
and one which enforces validity (i.e. side-conditions) when reading,
|
||||||
writing, or constructing `Value`s.
|
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.
|
### MIME-type tagged binary data.
|
||||||
|
|
||||||
Many internet protocols use
|
Many internet protocols use
|
||||||
|
|
Loading…
Reference in New Issue