2

I've seen in polymer.dart they have:

class CustomTag {
  final String tagName;
  const CustomTag(this.tagName);
}

but how does that interact with the rest of the code? from just the code above I can't see how using @CustomTag('my-tag') actually does anything but creates a CustomTag which is then garbage collected since nothing is referencing it.

Günter Zöchbauer
  • 623,577
  • 216
  • 2,003
  • 1,567
Daniel Robinson
  • 13,806
  • 18
  • 64
  • 112

1 Answers1

3

To answer the question in the title; these are called Annotations; they are simply const constructors.

To answer the second question; these are usually used for tooling (eg. @deprecated) or rewriting via a Transformer. You can access them at runtime using mirrors, but that's probably not practical/advisable for a production web app that gets converted to JavaScript.

Here's some sample code taken from this answer

import "dart:mirrors";

void main() {
  var object = new Class1();
  var classMirror = reflectClass(object.runtimeType);
  // Retrieve 'HelloMetadata' for 'object'
  HelloMetadata hello = getAnnotation(classMirror, HelloMetadata);
  print("'HelloMetadata' for object: $hello");

  // Retrieve 'Goodbye' for 'object.method'
  var methodMirror = (reflect(object.method) as ClosureMirror).function;
  Goodbye goodbye = getAnnotation(methodMirror, Goodbye);
  print("'Goodbye' for object: $goodbye");

  // Retrieve all 'Goodbye' for 'object.method'
  List<Goodbye> goodbyes = getAnnotations(methodMirror, Goodbye);
  print("'Goodbye's for object.method': $goodbyes");

  // Retrieve all metadata for 'object.method'
  List all = getAnnotations(methodMirror);
  print("'Metadata for object.method': $all");
}

Object getAnnotation(DeclarationMirror declaration, Type annotation) {
  for (var instance in declaration.metadata) {
    if (instance.hasReflectee) {
      var reflectee = instance.reflectee;
      if (reflectee.runtimeType == annotation) {
        return reflectee;
      }
    }
  }

  return null;
}

List getAnnotations(DeclarationMirror declaration, [Type annotation]) {
  var result = [];
  for (var instance in declaration.metadata) {
    if (instance.hasReflectee) {
      var reflectee = instance.reflectee;
      if (annotation == null) {
        result.add(reflectee);
      } else if (reflectee.runtimeType == annotation) {
        result.add(reflectee);
      }
    }
  }

  return result;
}

@HelloMetadata("Class1")
class Class1 {
  @HelloMetadata("method")
  @Goodbye("method")
  @Goodbye("Class1")
  void method() {
  }
}

class HelloMetadata {
  final String text;
  const HelloMetadata(this.text);
  String toString() => "Hello '$text'";
}

class Goodbye {
  final String text;
  const Goodbye(this.text);
  String toString() => "Goodbye '$text'";
}

Output:

'HelloMetadata' for object: Hello 'Class1'
'Goodbye' for object: Goodbye 'method'
'Goodbye's for object.method': [Goodbye 'method', Goodbye 'Class1']
'Metadata for object.method': [Hello 'method', Goodbye 'method', Goodbye 'Class1']
Community
  • 1
  • 1
Danny Tuppeny
  • 40,147
  • 24
  • 151
  • 275
  • thanks, do you happen to know how polymer.dart reflects across all loaded libraries to search for annotations? I guess it has to do that from somewhere in `initPolymer();` but I don't see how it automatically gets a list of all loaded libraries to register up all the @CustomTag annotations. – Daniel Robinson Oct 28 '14 at 13:10
  • @0xor1 I believe Polymer has a `Transformer`; but I'm afraid I'm not familiar with how it works. – Danny Tuppeny Oct 28 '14 at 13:15
  • I'm not sure about this either but I think Polymer and transformers in general use source mirrors and the analyzer to go through the AST (abstract syntax tree) of the source code and replace and/or add code even before any app code is executed. – Günter Zöchbauer Oct 28 '14 at 14:57