Specs: fix typos in style2.md, checkin forgotten builtins.md, add guard...

Specs: fix typos in style2.md, checkin forgotten builtins.md, add guard feature to runloop.md, rename WeakMap to MapOfWeakReferences, factor out Pair<>

Review URL: https://codereview.chromium.org/974313003

specs/builtins.md

+Built-In Elements
+=================
+
+```dart
+SKY MODULE
+
+<script>
+import 'dart:sky';
+
+class ImportElement extends Element {
+  ImportElement = Element;
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class TemplateElement extends Element {
+  TemplateElement = Element;
+
+  // TODO(ianh): convert <template> to using a token stream instead of a Fragment
+
+  external Fragment get content; // O(1)
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class ScriptElement extends Element {
+  ScriptElement = Element;
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class StyleElement extends Element {
+  StyleElement = Element;
+
+  external List<Rule> getRules(); // O(N) in rules
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class ContentElement extends Element {
+  ContentElement = Element;
+
+  external List<Node> getDistributedNodes(); // O(N) in distributed nodes
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class ImgElement extends Element {
+  ImgElement = Element;
+
+  @override
+  Type getLayoutManager() => ImgElementLayoutManager; // O(1)
+}
+
+class DivElement extends Element {
+  DivElement = Element;
+}
+
+class SpanElement extends Element {
+  SpanElement = Element;
+}
+
+class IframeElement extends Element {
+  IframeElement = Element;
+
+  @override
+  Type getLayoutManager() => IframeElementLayoutManager; // O(1)
+}
+
+class TElement extends Element {
+  TElement = Element;
+}
+
+class AElement extends Element {
+  AElement = Element;
+}
+
+class TitleElement extends Element {
+  TitleElement = Element;
+
+  @override
+  Type getLayoutManager() => null; // O(1)
+}
+
+class _ErrorElement extends Element {
+  _ErrorElement._create();
+
+  @override
+  Type getLayoutManager() => _ErrorElementLayoutManager; // O(1)
+}
+
+void _init(script) {
+  module.registerElement('import', ImportElement);
+  module.registerElement('template', TemplateElement);
+  module.registerElement('script', ScriptElement);
+  module.registerElement('style', StyleElement);
+  module.registerElement('content', ContentElement);
+  module.registerElement('img', ImgElement);
+  module.registerElement('div', DivElement);
+  module.registerElement('span', SpanElement);
+  module.registerElement('iframe', IframeElement);
+  module.registerElement('t', TElement);
+  module.registerElement('a', AElement);
+  module.registerElement('title', TitleElement);
+}
+</script>
+```

specs/events.md

@@ -31,12 +31,6 @@ class DispatcherController<T> {
   void add(T data) => dispatcher._add(data);
 }
 
-class Pair<A, B> {
-  const Pair(this.a, this.b);
-  final A a;
-  final B b;
-}
-
 class Dispatcher<T> {
   List<Pair<Handler, ZoneUnaryCallback>> _listeners;
   void listen(Handler<T> handler) {

specs/runloop.md

@@ -11,6 +11,18 @@ fired.
 class DeadlineExceededException implements Exception { }
 ```
 
+There is a method you can use that guards your code against these
+exceptions:
+
+```dart
+typedef void Callback();
+external guardAgainstDeadlineExceptions(Callback callback);
+// runs callback.
+// if the time budget for the _task_ expires while the callback is
+// running, the callback isn't interrupted, but the method will throw
+// an exception once the callback returns.
+```
+
 When Sky is to *process a task queue until a particular time*, with a
 queue *relevant task queue*, bits *filter bits*, a time
 *particular time*, and an *idle rule* which is either "sleep" or

specs/style2.md

 Sky Style Language
 ==================
 
-Note: This is a work in progress that will eventually replace
-(style.md)[style.md].
+This is a trimmed down version of the API in (style.md)[style.md]
+that is intended to be a stepping stone to the long-term world where
+there are no hard-coded properties in the engine.
 
 The Sky style API looks like the following:
 
@@ -57,17 +58,6 @@ The dart:sky library contains the following to define this API:
 import 'dart:mirrors';
 import 'dart:math';
 
-class WeakMap<Key, Value> {
-  // This is not actually a weak map right now, because Dart doesn't let us have weak references.
-  // We should fix that, or else we're going to keep alive every object you ever tear off through
-  // the StyleDeclaration API, even if you never use it again, until the StyleDeclaration object
-  // itself is GC'ed, which is likely when the element is GC'ed, which is likely never.
-  Map<Key, Value> _map = new Map<Key, Value>();
-  operator[](Key key) => _map[key];
-  operator[]=(Key key, Value value) => _map[key] = value;
-  bool containsKey(Key key) => _map.containsKey(key);
-}
-
 typedef void StringSetter(Symbol propertySymbol, StyleDeclaration declaration, String value);
 typedef String StringGetter(Symbol propertySymbol, StyleDeclaration declaration);
 typedef Property ObjectConstructor(Symbol propertySymbol, StyleDeclaration declaration);
@@ -119,7 +109,7 @@ class StyleDeclaration {
   }
 
   // some properties expose dedicated APIs so you don't have to use string manipulation
-  WeakMap<Symbol, Property> _properties = new WeakMap<Symbol, Property>();
+  MapOfWeakReferences<Symbol, Property> _properties = new MapOfWeakReferences<Symbol, Property>();
   noSuchMethod(Invocation invocation) {
     Symbol propertySymbol;
     if (invocation.isSetter) {
@@ -178,14 +168,17 @@ abstract class Property {
     throw new ArgumentError(value);
   }
 
-  void setter(dynamic value) {
-    if (value == initial)
-      return _setInitial();
-    if (value == inherit)
-      return _setInitial();
-    if (value == null)
-      return _unset();
-    throw new ArgumentError(value);
+  void setter(dynamic newValue) {
+    switch (newValue) {
+      case initial:
+        _setInitial();
+      case inherit:
+        _setInherit();
+      case null:
+        _unset();
+      default:
+        throw new ArgumentError(value);
+    }
   }
 
   external bool _isInitial();

specs/utils.md

+Dart Utilities Used By dart:sky
+===============================
+
+The classes defined here are used internally by dart:sky but are
+pretty generic.
+
+```dart
+class Pair<A, B> {
+  const Pair(this.a, this.b);
+  final A a;
+  final B b;
+  int get hashCode => a.hashCode ^ b.hashCode;
+  bool operator==(other) => other is Pair<A, B> && a == other.a && b == other.b;
+}
+
+// MapOfWeakReferences can be implemented in C, using the C Dart API, apparently
+class MapOfWeakReferences<Key, Value> {
+  external operator[](Key key);
+  external operator[]=(Key key, Value value);
+  external bool containsKey(Key key);
+}
+```