SPICE-0024: Annotation converters

[HT154]

This has been banging around in my head for a while and I finally needed to get it out.

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: apple/pkl-evolution#26

This also fixes a silly wart in the API for getting class property mirrors added in #1106.

Resolves #576

[stackoverflow]

Look good. One question:
As annotation converters run subclass -> superclass, you may get into cases where you can't override a superclass converter right?

// some parent module
open class Super {
  @SnakeCase
  myProperty: String
}

// my rendered file
class Sub extends Super {
  @CamelCase
  myProperty: String
}

Will render to my_property if I understood it correctly.

[HT154]

Look good. One question: As annotation converters run subclass -> superclass, you may get into cases where you can't override a superclass converter right?

Yeah, that's true. I wonder if this approach is worth revising. There are two main alternatives I see here:

• Reversing the order, so annotations are walked from parent to child class.
• Continue walking child->parent, but only allow each annotationConverters entry to be matched once per property. Example:

abstract class RenameConverter extends Annotation {
  abstract function rename(name: String): String
}

class SnakeCase extends RenameConverter {
  // ...
}

class CamelCase extends RenameConverter {
  // ...
}

output {
  renderer {
    annotationConverters {
      [RenameConverter] = (name, annotation, value) -> Pair(annotation.rename(name), value)
    }
  }
}

Here, only the CamelCase converter would run because it would be checked first and match against RenameConverter. Subsequently, SnakeCase would be checked and not match any unused converter entries so it would be ignored.

This approach is more complex in that it's more rules to keep in mind when working with annotation converters, but it's also simpler: the user does not have to keep track of how each annotation's implementation might interact.

Thoughts on which route might be preferable here?

[bioball]

Hmm.. I feel that it's fine that you can't override the annotations set on the superclass. I'm not actually sure if this is a problem.

[bioball]

Overall, looks pretty good!

[bioball]

Getting pretty close!

[bioball]

Approving to unblock!

But, some more suggestions (see below)

Also, we still need @Since annotations added to the new classes (like class Property in pkl:yaml).

[stackoverflow]

Looks good.