From 01bec1736f9e88f22ce2270607cd4e8fae281b48 Mon Sep 17 00:00:00 2001
From: Hixie <github.com@spam.hixie.ch>
Date: Fri, 20 Feb 2015 13:55:52 -0800
Subject: [PATCH] Specs: pass the current <script> to the module library init()
 function, rename it _init(), plumb that through AutomaticMetadata, and move
 @tagname and Element.tagname to a new frameworks.md file that has stuff that
 wouldn't actually be part of core Sky

Review URL: https://codereview.chromium.org/946513006
---
 specs/elements.md   | 19 -------------------
 specs/frameworks.md | 31 +++++++++++++++++++++++++++++++
 specs/modules.md    | 12 +++++++-----
 specs/script.md     | 13 +++++++------
 4 files changed, 45 insertions(+), 30 deletions(-)
 create mode 100644 specs/frameworks.md

diff --git a/specs/elements.md b/specs/elements.md
index 07b3633a16c..f219ad0d4c7 100644
--- a/specs/elements.md
+++ b/specs/elements.md
@@ -184,19 +184,6 @@ class Attr {
   final String value; // O(1)
 }
 
-// @tagname annotation for registering elements
-// only useful when placed on classes that inherit from Element
-class tagname extends AutomaticMetadata {
-  const tagname(this.name);
-  final String name;
-  void init(DeclarationMirror target, Module module) {
-    assert(target is ClassMirror);
-    if (!(target as ClassMirror).isSubclassOf(reflectClass(Element)))
-      throw new UnsupportedError('@tagname can only be used on descendants of Element');
-    module.registerElement(name, (target as ClassMirror).reflectedType);
-  }
-}
-
 // @hasShadow annotation for registering elements
 class _HasShadow {
   const _HasShadow();
@@ -222,12 +209,6 @@ abstract class Element extends ParentNode {
   // children must be Text or Element
   // if needsShadow is true, creates a shadow tree
 
-  String get tagName { // O(N) in number of annotations on the class
-    // throws a StateError if the class doesn't have an @tagname annotation
-    var tagnameClass = reflectClass(tagname);
-    return (reflectClass(this.runtimeType).metadata.singleWhere((mirror) => mirror.type == tagnameClass).reflectee as tagname).name;
-  }
-
   external bool hasAttribute(String name); // O(N) in number of attributes
   external String getAttribute(String name); // O(N) in number of attributes
   external void setAttribute(String name, [String value = '']); // O(N) in number of attributes
diff --git a/specs/frameworks.md b/specs/frameworks.md
new file mode 100644
index 00000000000..f7d91a517f6
--- /dev/null
+++ b/specs/frameworks.md
@@ -0,0 +1,31 @@
+Frameworks
+----------
+
+Sky is intended to support multiple frameworks. Here is one way you
+could register a custom element using Dart annotations:
+
+```dart
+// @tagname annotation for registering elements
+// only useful when placed on classes that inherit from Element
+class tagname extends AutomaticMetadata {
+  const tagname(this.name);
+  final String name;
+  void init(DeclarationMirror target, Module module, ScriptElement script) {
+    assert(target is ClassMirror);
+    if (!(target as ClassMirror).isSubclassOf(reflectClass(Element)))
+      throw new UnsupportedError('@tagname can only be used on descendants of Element');
+    module.registerElement(name, (target as ClassMirror).reflectedType);
+  }
+}
+```
+
+A framework that used the above code could use the following code to
+get the tag name of an element:
+
+```dart
+String getTagName(Element element) { // O(N) in number of annotations on the class
+  // throws a StateError if the class doesn't have an @tagname annotation
+  var tagnameClass = reflectClass(tagname);
+  return (reflectClass(element.runtimeType).metadata.singleWhere((mirror) => mirror.type == tagnameClass).reflectee as tagname).name;
+}
+```
diff --git a/specs/modules.md b/specs/modules.md
index 25f8e62d034..475ef9461a6 100644
--- a/specs/modules.md
+++ b/specs/modules.md
@@ -71,15 +71,17 @@ the library itself):
 
 ```dart
 class _ { }
-void main() {
+void main(ScriptElement script) {
   LibraryMirror library = reflectClass(_).owner as LibraryMirror;
-  if (library.declarations.containsKey(#init) && library.declarations[#init] is MethodMirror)
-    init();
-  AutomaticMetadata.runLibrary(library, module);
+  if (library.declarations.containsKey(#_init) && library.declarations[#_init] is MethodMirror)
+    _init(script);
+  AutomaticMetadata.runLibrary(library, module, script);
 }
 ```
 
-Then, that ``main()`` function is called.
+Then, that ``main(script)`` function is called, with ``script`` set to
+the ``ScriptElement`` object representing the relevant ``<script>``
+element.
 
 TODO(ianh): decide what URL and name we should give the libraries, as
 exposed in MirrorSystem.getName(libraryMirror.qualifiedName) etc
diff --git a/specs/script.md b/specs/script.md
index 857f2c00f1c..4004283159e 100644
--- a/specs/script.md
+++ b/specs/script.md
@@ -26,9 +26,9 @@ import 'dart:mirrors';
 
 abstract class AutomaticMetadata {
   const AutomaticMetadata();
-  void init(DeclarationMirror target, Module module);
+  void init(DeclarationMirror target, Module module, ScriptElement script);
 
-  static void runLibrary(LibraryMirror library, Module module) {
+  static void runLibrary(LibraryMirror library, Module module, ScriptElement script) {
     library.declarations.values.toList() /* ..sort((DeclarationMirror a, DeclarationMirror b) {
       bool aHasLocation;
       try {
@@ -55,7 +55,7 @@ abstract class AutomaticMetadata {
     ..forEach((DeclarationMirror d) {
       d.metadata.forEach((InstanceMirror i) {
         if (i.reflectee is AutomaticMetadata)
-          i.reflectee.run(d, module);
+          i.reflectee.run(d, module, script);
       });
     });
   }
@@ -63,16 +63,17 @@ abstract class AutomaticMetadata {
 
 class AutomaticFunction extends AutomaticMetadata {
   const AutomaticFunction();
-  void init(DeclarationMirror target, Module module) {
+  void init(DeclarationMirror target, Module module, ScriptElement script) {
     assert(target is MethodMirror);
     MethodMirror f = target as MethodMirror;
     assert(!f.isAbstract);
     assert(f.isRegularMethod);
     assert(f.isTopLevel);
     assert(f.isStatic);
-    assert(f.parameters.length == 0);
+    assert(f.parameters.length == 1);
+    assert(f.parameters[0].type == ScriptElement);
     assert(f.returnType == currentMirrorSystem().voidType);
-    (f.owner as LibraryMirror).invoke(f.simpleName, []);
+    (f.owner as LibraryMirror).invoke(f.simpleName, [script]);
   }
 }
 const autorun = const AutomaticFunction();