how can I write an annotation for Dart

Question

The question:

• What is the procedure to implement an annotation.
• How can, or indeed when can one activate the annotation you developed?

I can't seem to find an example or tutorial on how to write a class to implement annotations for dart.

For example with Java you might have an annotation that represents a class that is invoked at compile time and let you modify or inject code. Do Dart annotations work like this as well?

background

I have done some (further) digging on understanding this area of the Dart ecosystem. I'm adding some notes because annotation can be a powerful with transparent commentary on how to use it.

After looking at some actual annotation from Dart, Dart annotations record "a notation" (a label or metadata tags). The question is about how to uses annotations within Dart.

gloaming

My current understanding, based on looking at bits of code, is that they are markers on class objects. It looks like annotations are highly-unstructured since while an annotation can be declared simply, there's no structure to use or recognise a label (aka annotation).

steps of annotation

1. Identify the property or action you want to label.
2. Need to write code to use or 'work' your annotation. Look at something like Observe as an example.
3. You can implement and test LOAD-time code to look-for and process your labels. I don't see an infrastructure to register an annotation and provide handlers for example.
   • This is done via the main() method in your library.
4. Implement and test annotation behaviour.

At least I think that's how it works. There's not really a lot of information in the Dart language specification on this area.

Observation and inspection raised a few general questions as well. I've left a reading list of sorts and examples, to assist others in joining the exploration.

readings:

• Dart Language Specification
• type annotations
• metadata
  • extending a class
• I love Dart annotations
• zones
  • zone class
• Dart Annotations are No Longer Structured

examples:

• Observe
  • Observable.dart
• annotations.dart

Answer 1

Any class with a const constructor can be used as annotation.

const FOO = const Foo(37);

@Foo(42)
class Foo {
  @Deprecated("until further notice");
  final int x;
  @FOO
  const Foo(this.x);
}

There is nothing more to it.

See also https://www.dartlang.org/docs/dart-up-and-running/contents/ch02.html#ch02-metadata

Metadata doesn't do anything by itself. If your program wants to read metadata off a class, it needs to use mirrors.

import 'dart:mirrors';
const tag = "TAG"; 

@tag class C {}
void main() {
  print(reflectClass(C).metadata.first.reflectee);  // prints "TAG"
  var c = new C();
  print(reflect(c).type.metadata.first.reflectee);  // prints "TAG" 
}

See: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-mirrors.ClassMirror#id_metadata

Alternatively, you can process the source directly. For example, the dart2js compiler has a "source mirror" library that reflects over the source structure. It is what dart2js and the analyzer do to understand the "proxy" annotation.