From 4a70364eda7724bba0a7e6bfcfa862a881d06587 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Thu, 4 Jul 2019 00:33:37 +0100 Subject: [PATCH] Initial draft text re annotations --- preserves.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/preserves.md b/preserves.md index 064b147..83d3bc0 100644 --- a/preserves.md +++ b/preserves.md @@ -25,7 +25,8 @@ programming languages. Preserves also supports the usual suite of atomic and compound data types, in particular including *binary* data as a distinct type from -text strings. +text strings. Its *annotations* allow separation of data from metadata +such as comments, trace information, and provenance information. Finally, Preserves defines precisely how to *compare* two values. Comparison is based on the data model, not on syntax or on data @@ -389,6 +390,34 @@ prefixing a `ByteString` containing the binary representation of the structure at all. It would be incoherent to expect to be able to access the representation of the text from within the text itself. +### 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. + + 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. + +Reflective tools such as debuggers, user interfaces, and message +routers and relays---tools which process `Value`s generically---may +use annotated inputs to tailor their operation, or may insert +annotations in their outputs. By contrast, in ordinary programs, as a +rule of thumb, the presence, absence or specific value of an +annotation should not change the control flow or output of the +program. Annotations are data *describing* `Value`s, and are not in +the domain of any specific application of `Value`s. That is, an +annotation will almost never cause a non-reflective program to do +anything observably different. + ## Compact Binary Syntax A `Repr` is an encoding, or representation, of a specific `Value`.