SPICE-0024: Annotation converters (#1333)

This enables defining declarative key and/or value transformations in
cases where neither `Class`- nor path-based converters can be applied
gracefully. It is also the only way to express transforming the
resulting property names in `Typed` objects without applying a converter
to the entire containing type, which is cumbersome at best.

SPICE: https://github.com/apple/pkl-evolution/pull/26

stdlib/xml.pkl

@@ -32,6 +32,16 @@ module pkl.xml
 ///
 /// To set the name and attributes of the XML document's root element,
 /// use [rootElementName] and [rootElementAttributes].
+///
+/// The [Property] annotation can be used to change how a property name renders into XML.
+///
+/// Example:
+/// ```
+/// import "pkl:xml"
+///
+/// @xml.Property { name = "wing_span" }
+/// wingSpan: Int
+/// ```
 class Renderer extends ValueRenderer {
   extension = "xml"
 
@@ -52,6 +62,16 @@ class Renderer extends ValueRenderer {
   external function renderValue(value: Any): String
 }
 
+/// Annotate properties of classes and modules with this class to override how a [Renderer]
+/// interprets a property's name.
+@Since { version = "0.31.0" }
+class Property extends ConvertProperty {
+  /// The new name to use for the annotated property when rendered by [Renderer].
+  name: String
+
+  render = (prop, renderer) -> if (renderer is Renderer) Pair(name, prop.value) else prop
+}
+
 /// Creates an XML element with the given name.
 ///
 /// Use this method to directly define an XML element
@@ -68,10 +88,10 @@ class Renderer extends ValueRenderer {
 ///
 /// To define the XML element's content, add child values (normally also called "elements") to the `Element` object:
 /// ```
-/// order = xml.Element("order") {       // element with one child
-///   xml.Element("item") {              // element with two children
-///     xml.Element("name") { "banana" } // element with one child
-///     xml.Element("quantity") { 42 }   // element with one child
+/// order = (xml.Element("order")) {       // element with one child
+///   (xml.Element("item")) {              // element with two children
+///     (xml.Element("name")) { "banana" } // element with one child
+///     (xml.Element("quantity")) { 42 }   // element with one child
 ///   }
 /// }
 /// ```