doc/ref: added field attributes
Field attributes are like Go struct tags.
Attributes are needed for maintaining meta data for mapping
CUE to other languages like protobuf, Go, XML, and even JSON,
as well as preserving information when converting such languages
to CUE.
This proposal does not use back quotes for tags, like Go,
as this would be ambiguous if back quotes are used as
identifier literals.
The use of @ has a precedence in other languages, like Swift.
Change-Id: I618caad6b43d598a7462872c484509be9b00047f
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/1662
Reviewed-by: Marcel van Lohuizen <mpvl@google.com>
diff --git a/doc/ref/spec.md b/doc/ref/spec.md
index be367c3..b204d45 100644
--- a/doc/ref/spec.md
+++ b/doc/ref/spec.md
@@ -987,14 +987,18 @@
field and is visible within the template value.
```
-StructLit = "{" [ { Declaration "," } Declaration ] "}" .
+StructLit = "{" [ Declaration { "," Declaration } [ "," ] ] "}" .
Declaration = FieldDecl | AliasDecl | ComprehensionDecl .
-FieldDecl = Label { Label } ":" Expression .
+FieldDecl = Label { Label } ":" Expression { attribute } .
AliasDecl = Label "=" Expression .
Label = identifier | simple_string_lit | TemplateLabel .
TemplateLabel = "<" identifier ">" .
-Tag = "#" identifier [ ":" json_string ] .
+
+attribute = "@" identifier "(" attr_elem { "," attr_elem } ")" .
+attr_elem = attr_string | identifier "=" attr_string .
+attr_string = { attr_char } | string_lit .
+attr_char = /* an arbitrary Unicode code point except newline, ',', '"', `'`, '#', '=', '(', and ')' */ .
```
```
@@ -1021,6 +1025,44 @@
{a: 1} & {a: 2} _|_
```
+Fields may be associated with attributes.
+Attributes define additional information about a field,
+such as a mapping to a protobuf tag or alternative
+name of the field when mapping to a different language.
+
+If a field has multiple attributes their identifiers must be unique.
+Attributes accumulate when unifying two fields, removing duplicate entries.
+It is an error for the resulting field to have two different attributes
+with the same identifier.
+
+Attributes are not directly part of the data model, but may be
+accessed through the API or other means of reflection.
+The interpretation of the attribute value
+(a comma-separated list of attribute elements) depends on the attribute.
+Interpolations are not allowed in attribute strings.
+
+The recommended convention, however, is to interpret the first
+`n` arguments as positional arguments,
+where duplicate conflicting entries are an error,
+and the remaining arguments as a combination of flags
+(an identifier) and key value pairs, separated by a `=`.
+
+```
+MyStruct1: {
+ field: string @go(Field)
+ attr: int @xml(,attr) @go(Attr)
+}
+
+MyStruct2: {
+ field: string @go(Field)
+ attr: int @xml(a1,attr) @go(Attr)
+}
+
+Combined: MyStruct1 & MyStruct2
+// field: string @go(Field)
+// attr: int @xml(,attr) @xml(a1,attr) @go(Attr)
+```
+
In addition to fields, a struct literal may also define aliases.
Aliases name values that can be referred to
within the [scope](#declarations-and-scopes) of their
@@ -1927,8 +1969,14 @@
in the clauses.
Values of iterations that map to the same label unify into a single field.
+<!--
+TODO: consider allowing multiple labels for comprehensions
+(current implementation). Generally it is better to define comprehensions
+in the current scope, though, as it may prevent surprises given the
+restrictions on comprehensions.
+-->
```
-ComprehensionDecl = Field [ "<-" ] Clauses .
+ComprehensionDecl = Label ":" Expression [ "<-" ] Clauses .
ListComprehension = "[" Expression [ "<-" ] Clauses "]" .
Clauses = Clause { Clause } .
