Add a script for determining which DOM methods correspond to which HTML methods.

client/html/scripts/html-diff.dart

+// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * A script to assist in documenting the difference between the dart:html API
+ * and the old DOM API.
+ */
+#library('renames');
+
+#import('../../../frog/lang.dart');
+#import('../../../frog/file_system_node.dart');
+#import('../../../frog/file_system.dart');
+#import('../../../utils/dartdoc/dartdoc.dart');
+
+void main() {
+  HtmlDiff.initWorld('../../frog', new NodeFileSystem());
+  initializeDartDoc();
+  var diff = new HtmlDiff();
+  diff.run();
+
+  diff.domToDart.forEach((domMember, htmlMember) {
+    if (domMember.name != htmlMember.name) {
+      var domTypeName = domMember.declaringType.name;
+      var htmlTypeName = htmlMember.declaringType.name.
+        replaceFirst('WrappingImplementation', '');
+      var htmlName = '$htmlTypeName.${htmlMember.name}';
+      if (htmlMember.isConstructor || htmlMember.isFactory) {
+        htmlName = 'new $htmlTypeName${htmlMember.name == '' ? '' : '.'}' +
+          htmlMember.name;

[Jacob, 2011/11/21 18:51:17]

put the htmlMember.name line in the string template to make the line easier to
read by using a single mechanism to perform string concat.

[nweiz, 2011/11/21 19:34:22]

How do I wrap the line if everything's in a single string literal?

[Jacob, 2011/11/21 19:47:23]

Either use a multi-line string literal or write
          final separator = htmlMember.name == '' ? '' : '.';
          htmlName ='new $htmlTypeName$separator${htmlMember.name}';

[nweiz, 2011/11/21 23:01:32]

Done.

+      }
+      print('$domTypeName.${domMember.name} -> ${htmlName}');
+    }
+  });
+
+  for (var type in world.dom.types.getValues()) {
+    if (type.name == null) continue;
+    if (type.definition is FunctionTypeDefinition) continue;
+    for (var member in type.members.getValues()) {
+      if (member.isPrivate) continue;

[Jacob, 2011/11/21 18:51:17]

I think it is clearer to have multiple clauses anded together than to have a
bunch of separate classes that continue.
For example:

if (!member.isPrivate
   && (member is MethodMember || member is PropertyMember)
   && ...)  {
     print (No dart:html wrapper....

[nweiz, 2011/11/21 19:34:22]

Done.

+      if (member is! MethodMember && member is! PropertyMember) continue;
+      if (member.name == 'typeName') continue;
+      if (diff.domToDart.containsKey(member)) continue;
+      print('No dart:html wrapper for ${type.name}.${member.name}');
+    }
+  }
+}
+
+class HtmlDiff {
+  final Map<Member, Member> domToDart;
+
+  static void initWorld(String frogDir, FileSystem files) {
+    parseOptions(frogDir, [] /* args */, files);
+    initializeWorld(files);
+    world.processScript('dart:html');
+    world.resolveAll();
+  }
+
+  HtmlDiff() : domToDart = <Member, Member>{};
+
+  void run() {
+    var htmlLib = world.libraries['dart:html'];
+    for (var htmlType in htmlLib.types.getValues()) {
+      var domType = htmlToDomType(htmlType);
+      var members = new List.from(htmlType.members.getValues());
+      members.addAll(htmlType.constructors.getValues());
+      htmlType.factories.forEach((f) => members.add(f));
+      for (var member in members) {
+        htmlToDomMembers(member, domType).forEach((m) => domToDart[m] = member);
+      }
+    }
+  }
+
+  Type htmlToDomType(Type htmlType) {
+    if (htmlType.name == null) return;
+    var tags = _getTags(findComment(htmlType.span));
+
+    if (tags.containsKey('domName')) {
+      var domName = tags['domName'];

[Jacob, 2011/11/21 18:51:17]

prefer final to var for local variables that really are final.  it makes it
easier for someone browsing the code to quickly tell that the variable is never
modified in after it is defined which makes it quicker to quickly grock code.

[nweiz, 2011/11/21 19:34:22]

Done, although the fact that "final" is two more characters than "var" makes
doing this pervasively a little annoying.

[Jacob, 2011/11/21 19:47:23]

I agree the extra two characters are annoying but I think the clearer semantics
make it worth it. Time to make your code editor automatically write final after
you type "fin "
of course i'd be even happier if the language was tweaked so that the keyword
for  final took fewer characters.

+      if (domName == 'none') return;
+      var domType = world.dom.types[domName];
+      if (domType == null) print('Warning: no dart:dom type named $domName');
+      return domType;
+    } else {
+      if (!htmlType.name.endsWith('WrappingImplementation')) return;
+      var domName = htmlType.name.replaceFirst('WrappingImplementation', '');
+      var domType = world.dom.types[domName];
+      if (domType == null && domName.endsWith('Element')) {
+        domType = world.dom.types['HTML$domName'];
+      }
+      if (domType == null) domType = world.dom.types['WebKit$domName'];
+      if (domType == null) {
+        print('Warning: no dart:dom type matches dart:html ${htmlType.name}');
+      }
+      return domType;
+    }
+  }
+
+  Set<Member> htmlToDomMembers(Member htmlMember, Type domType) {
+    if (htmlMember.isPrivate) return new Set();
+    if (htmlMember is MethodMember) {
+      var tags = _getTags(findComment(htmlMember.span));
+      if (tags.containsKey('domName')) {
+        var domName = tags['domName'];
+        if (domName == 'none') return new Set();
+        return _membersFromName(domName, domType, world.dom);
+      }
+      if (domType == null) return new Set();
+      if (htmlMember.definition == null) return new Set();
+      if (htmlMember.name == 'get\$on') {
+        var members = _members(domType.members['addEventListener']);
+        members.addAll(_members(domType.members['dispatchEvent']));
+        members.addAll(_members(domType.members['removeEventListener']));
+        return members;
+      }
+      if (htmlMember.isFactory && htmlMember.name == '' &&
+          domType.name.endsWith('Event')) {
+        return _members(domType.members['init${domType.name}']);
+      }
+      return _members(_getDomMember(htmlMember.definition.body, domType));
+    } else if (htmlMember is PropertyMember) {
+      var members = new Set();
+      if (htmlMember.getter != null) {
+        members.addAll(htmlToDomMembers(htmlMember.getter, domType));
+      }
+      if (htmlMember.setter != null) {
+        members.addAll(htmlToDomMembers(htmlMember.setter, domType));
+      }
+      return members;
+    } else {
+      return new Set();
+    }
+  }
+
+  Set<Member> _membersFromName(String name, Type defaultType, Library library) {
+    if (!name.contains('.', 0)) {
+      if (defaultType == null) {
+        print('Warning: no default type for ${name}');
+        return new Set();
+      }
+      var member = defaultType.members[name];
+      if (member == null) {
+        print('Warning: no member ${defaultType.name}.${name}');
+      }
+      return _members(member);
+    }
+
+    var splitName = name.split('.');
+    if (splitName.length != 2) {
+      print('Warning: invalid member name ${name}');
+      return new Set();
+    }
+    var type = library.types[splitName[0]];
+    if (type == null) {
+      print('Warning: no ${library.name} type named ${splitName[0]}');
+      return new Set();
+    }
+    var member = type.members[splitName[1]];
+    if (member == null) {
+      print('Warning: no member named $name');
+    }
+    return _members(member);
+  }
+
+  Set<Member> _members(Member m) => m == null ? new Set() : new Set.from([m]);
+
+  Member _getDomMember(Statement stmt, Type domType) {
+    if (stmt is BlockStatement) {
+      var body = stmt.body.filter((s) => !_ignorableStatement(s));
+      if (body.length != 1) return;
+      return _getDomMember(stmt.body[0], domType);
+    } else if (stmt is ReturnStatement) {
+      return _domMemberFromExpression(stmt.value, domType);
+    } else if (stmt is ExpressionStatement) {
+      return _domMemberFromExpression(stmt.body, domType);
+    } else if (stmt is TryStatement) {
+      return _getDomMember(stmt.body, domType);
+    } else if (stmt is IfStatement) {
+      var trueMember = _getDomMember(stmt.trueBranch, domType);
+      var falseMember = _getDomMember(stmt.falseBranch, domType);
+      if (stmt.falseBranch == null || trueMember == falseMember) {
+        return trueMember;
+      }
+    }
+  }
+
+  /**
+   * Whether a statement can be ignored for the purpose of determining the DOM
+   * name of the enclosing method. The Webkit-to-Dart conversion process leaves
+   * behind various throws and returns that we want to ignore.
+   */
+  bool _ignorableStatement(Statement stmt) {
+    if (stmt is BlockStatement) {
+      return Collections.every(stmt.body, (s) => _ignorableStatement(s));
+    } else if (stmt is TryStatement) {
+      return _ignorableStatement(stmt.body);
+    } else if (stmt is IfStatement) {
+      return _ignorableStatement(stmt.trueBranch) &&
+        _ignorableStatement(stmt.falseBranch);
+    } else if (stmt is ReturnStatement) {
+      return stmt.value == null || stmt.value is ThisExpression;
+    } else {
+      return stmt is ThrowStatement;
+    }
+  }
+
+  Member _domMemberFromExpression(Expression expr, Type domType) {
+    if (expr is BinaryExpression && expr.op.kind == TokenKind.ASSIGN) {
+      return _domMemberFromExpression(expr.x, domType);
+    } else if (expr is CallExpression) {
+      if (expr.target is DotExpression && expr.target.self is VarExpression &&
+          expr.target.self.name.name == 'LevelDom' &&
+          (expr.target.name.name.startsWith('wrap') ||
+           expr.target.name.name == 'unwrap')) {
+        return _domMemberFromExpression(expr.arguments[0].value, domType);
+      }
+      return _domMemberFromExpression(expr.target, domType);
+    } else if (expr is DotExpression) {
+      if (expr.self is NewExpression && expr.name.name == '_wrap' &&
+          expr.self.arguments.length == 1) {
+        return _domMemberFromExpression(expr.self.arguments[0].value, domType);
+      } else if (expr.self is VarExpression && expr.self.name.name == '_ptr') {
+        return domType.members[expr.name.name];
+      }
+      var base = _domMemberFromExpression(expr.self, domType);
+      if (base != null && base.returnType != null) {
+        return base.returnType.members[expr.name.name];
+      }
+    } else if (expr is NewExpression && expr.arguments.length == 1) {
+      return _domMemberFromExpression(expr.arguments[0].value, domType);
+    }
+  }

[Jacob, 2011/11/21 18:51:17]

provide explicit return of null or throw an exception if nothing matched

[nweiz, 2011/11/21 19:34:22]

Done.

+
+  Map<String, String> _getTags(String comment) {
+    if (comment == null) return const <String, String>{};
+    var re = new RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)");
+    var tags = <String, String>{};
+    for (var m in re.allMatches(comment.trim())) {
+      tags[m[1]] = m[2];
+    }
+    return tags;
+  }
+}