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/base.pkl

@@ -20,12 +20,14 @@
 @ModuleInfo { minPklVersion = "0.31.0" }
 module pkl.base
 
-// math import used for doc comments
+// json, math, and yaml imports used for doc comments
+import "pkl:json"
 import "pkl:jsonnet"
 import "pkl:math"
 import "pkl:pklbinary"
 import "pkl:protobuf"
 import "pkl:xml"
+import "pkl:yaml"
 
 /// The top type of the type hierarchy.
 ///
@@ -351,11 +353,70 @@ abstract class BaseValueRenderer {
   /// both match path spec `server.timeout`, whereas path `server.timeout.millis` does not.
   converters: Mapping<Class | String, (unknown) -> Any>
 
+  /// Customizations for [ConvertProperty] annotation behaviors.
+  ///
+  /// This property is consulted to transform [ConvertProperty] annotation values.
+  /// This can be used to customize or override the conversion behavior for a specific renderer.
+  /// If multiple entries match the annotation's class, the most specific class (according to class
+  /// hierarchy) wins.
+  ///
+  /// See [ConvertProperty] for detailed information.
+  @Since { version = "0.31.0" }
+  convertPropertyTransformers: Mapping<Class, Mixin<ConvertProperty>>
+
   /// The file extension associated with this output format,
   /// or [null] if this format does not have an extension.
   extension: String?
 }
 
+/// Conversion to be applied to properties when rendered through [BaseValueRenderer].
+///
+/// During rendering, the annotation's [render] function is called.
+/// The function must return a [Pair] of the converted property name and value.
+///
+/// Multiple [ConvertProperty] annotations can apply per property, and the output of one
+/// annotation's [render] function is used as input to the next.
+/// Annotations are applied the order as declared on the property.
+/// If the annotated property is overriding a parent property, the parent property's annotations are
+/// applied first.
+///
+/// These conversions can coexist with [BaseValueRenderer.converters], and applies first.
+///
+/// These conversions only affect rendering of class properties.
+/// Applying this to other types of members does not impact rendering.
+///
+/// These conversions can be overriden with [BaseValueRenderer.convertPropertyTransformers].
+///
+/// Example:
+///
+/// ```
+/// // convert duration to the number of seconds
+/// @ConvertProperty {
+///   render = (property, _) -> Pair(property.key, property.value.toUnit("s"))
+/// }
+/// timeout: Duration
+/// ```
+///
+/// [ConvertProperty] can be subclassed to define re-usable property converters.
+/// The conversion defined in the previous example can be rewritten as:
+///
+/// ```
+/// class ConvertDuration extends ConvertProperty {
+///   unit: DurationUnit
+///
+///   render = (property: Pair<String, Duration>, _) -> Pair(property.key, property.value.toUnit(unit))
+/// }
+///
+/// @ConvertDuration { unit = "s" }
+/// timeout: Duration
+/// ```
+@Since { version = "0.31.0" }
+open class ConvertProperty extends Annotation {
+  /// Function called by [BaseValueRenderer] types during rendering to transform property
+  /// names and values.
+  render: (Pair<String, Any>, BaseValueRenderer) -> Pair<String, Any>
+}
+
 /// Base class for rendering Pkl values in some textual output format.
 ///
 /// A renderer's output is guaranteed to be well-formed unless [RenderDirective] is part of the
@@ -466,6 +527,16 @@ class PcfRenderDirective {
 }
 
 /// Renders values as JSON.
+///
+/// The [json.Property] annotation can be used to change how a property name renders into JSON.
+///
+/// Example:
+/// ```
+/// import "pkl:json"
+///
+/// @json.Property { name = "wing_span" }
+/// wingSpan: Int
+/// ```
 class JsonRenderer extends ValueRenderer {
   extension = "json"
 
@@ -486,6 +557,16 @@ class JsonRenderer extends ValueRenderer {
 /// Renders values as YAML.
 ///
 /// To render a YAML stream, set [isStream] to [true].
+///
+/// The [yaml.Property] annotation can be used to change how a property name renders into YAML.
+///
+/// Example:
+/// ```
+/// import "pkl:yaml"
+///
+/// @yaml.Property { name = "wing_span" }
+/// wingSpan: Int
+/// ```
 class YamlRenderer extends ValueRenderer {
   extension = "yaml"
 

stdlib/json.pkl

@@ -18,6 +18,16 @@
 @ModuleInfo { minPklVersion = "0.31.0" }
 module pkl.json
 
+/// Annotate properties of classes and modules with this class to override how a [JsonRenderer]
+/// 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 [JsonRenderer].
+  name: String
+
+  render = (prop, renderer) -> if (renderer is JsonRenderer) Pair(name, prop.value) else prop
+}
+
 /// A JSON parser.
 ///
 /// JSON values are mapped to Pkl values as follows:

stdlib/jsonnet.pkl

@@ -68,6 +68,16 @@ function ExtVar(_name: String): ExtVar = new { name = _name }
 ///   }
 /// }
 /// ```
+///
+/// The [Property] annotation can be used to change how a property name renders into Jsonnet.
+///
+/// Example:
+/// ```
+/// import "pkl:jsonnet"
+///
+/// @jsonnet.Property { name = "wing_span" }
+/// wingSpan: Int
+/// ```
 class Renderer extends ValueRenderer {
   extension = "jsonnet"
 
@@ -91,6 +101,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
+}
+
 /// An `importstr` construct that, when evaluated by Jsonnet, returns the content of a UTF-8 text file.
 ///
 /// To construct an [ImportStr], use method [ImportStr()].

stdlib/pklbinary.pkl

@@ -32,6 +32,11 @@
 module pkl.pklbinary
 
 /// Render values as `pkl-binary`.
+///
+/// The `pkl-binary` renderer disables all [ConvertProperty] annotation converters by default
+/// because `pkl-binary` data is intended to closely represent native Pkl types and data.
+/// This behavior may be overridden for [ConvertProperty] or its subclasses by adding an entry to
+/// [Renderer.convertPropertyTransformers].
 class Renderer extends BytesRenderer {
   /// Renders [value] as `pkl-binary`.
   external function renderValue(value: Any): Bytes
@@ -40,4 +45,11 @@ class Renderer extends BytesRenderer {
   ///
   /// Every `pkl-binary` value is also a valid document.
   external function renderDocument(value: Any): Bytes
+
+  convertPropertyTransformers {
+    // disable all property conversions by default
+    [ConvertProperty] {
+      render = (property, _) -> property
+    }
+  }
 }

stdlib/protobuf.pkl

@@ -25,6 +25,16 @@ import "pkl:reflect"
 /// Note: This class is _experimental_ and not ready for production use.
 ///
 /// As of this release, only Protocol Buffers' text format is supported.
+///
+/// The [Property] annotation can be used to change how a property name renders into Protobuf.
+///
+/// Example:
+/// ```
+/// import "pkl:protobuf"
+///
+/// @protobuf.Property { name = "wing_span" }
+/// wingSpan: Int
+/// ```
 class Renderer extends ValueRenderer {
   /// The characters to use for indenting output.
   ///
@@ -38,3 +48,13 @@ class Renderer extends ValueRenderer {
   /// Returns the canonical name for [type].
   external function renderType(type: reflect.Type): 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
+}

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
 ///   }
 /// }
 /// ```

stdlib/yaml.pkl

@@ -18,6 +18,16 @@
 @ModuleInfo { minPklVersion = "0.31.0" }
 module pkl.yaml
 
+/// Annotate properties of classes and modules with this class to override how a [YamlRenderer]
+/// 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 [YamlRenderer].
+  name: String
+
+  render = (prop, renderer) -> if (renderer is YamlRenderer) Pair(name, prop.value) else prop
+}
+
 /// A YAML parser.
 ///
 /// YAML values are mapped to Pkl values as follows: