[html5lib] api updates: localName

pkg/third_party/html5lib/lib/dom.dart

 /// A simple tree API that results from parsing html. Intended to be compatible
 /// with dart:html, but right now it resembles the classic JS DOM.
 library dom;
 
 import 'dart:collection';
 import 'package:source_maps/span.dart' show FileSpan;
 
 import 'src/constants.dart';
 import 'src/list_proxy.dart';
 import 'src/token.dart';
@@ skipping 57 matching lines @@
   static const int DOCUMENT_FRAGMENT_NODE = 11;
   static const int DOCUMENT_NODE = 9;
   static const int DOCUMENT_TYPE_NODE = 10;
   static const int ELEMENT_NODE = 1;
   static const int ENTITY_NODE = 6;
   static const int ENTITY_REFERENCE_NODE = 5;
   static const int NOTATION_NODE = 12;
   static const int PROCESSING_INSTRUCTION_NODE = 7;
   static const int TEXT_NODE = 3;
 
-  // TODO(jmesserly): this should be on Element
-  /// The tag name associated with the node.
-  final String tagName;
+  /// Note: For now we use it to implement the deprecated tagName property.
+  final String _tagName;
+
+  /// *Deprecated* use [Element.localName] instead.
+  /// Note: after removal, this will be replaced by a correct version that
+  /// returns uppercase [as specified](http://dom.spec.whatwg.org/#dom-element-tagname).
+  @deprecated String get tagName => _tagName;
 
   /// The parent of the current node (or null for the document node).
   Node parent;
 
   // TODO(jmesserly): should move to Element.
   /// A map holding name, value pairs for attributes of the node.
   ///
   /// Note that attribute order needs to be stable for serialization, so we use
   /// a LinkedHashMap. Each key is a [String] or [AttributeName].
   LinkedHashMap<dynamic, String> attributes = new LinkedHashMap();
 
   /// A list of child nodes of the current node. This must
   /// include all elements but not necessarily other node types.
   final NodeList nodes = new NodeList._();
 
   List<Element> _elements;
 
   // TODO(jmesserly): consider using an Expando for this, and put it in
   // dom_parsing. Need to check the performance affect.
   /// The source span of this node, if it was created by the [HtmlParser].
   FileSpan sourceSpan;
 
   /// The attribute spans if requested. Otherwise null.
   LinkedHashMap<dynamic, FileSpan> _attributeSpans;
   LinkedHashMap<dynamic, FileSpan> _attributeValueSpans;
 
-  Node(this.tagName) {
+  /// *Deprecated* use [new Element.tag] instead.
+  @deprecated Node(String tagName) : this._(tagName);
+
+  Node._([this._tagName]) {
     nodes._parent = this;
   }
 
   /// If [sourceSpan] is available, this contains the spans of each attribute.
   /// The span of an attribute is the entire attribute, including the name and
   /// quotes (if any). For example, the span of "attr" in `<a attr="value">`
   /// would be the text `attr="value"`.
   LinkedHashMap<dynamic, FileSpan> get attributeSpans {
     _ensureAttributeSpans();
     return _attributeSpans;
@@ skipping 13 matching lines @@
       _elements = new FilteredElementList(this);
     }
     return _elements;
   }
 
   // TODO(jmesserly): needs to support deep clone.
   /// Return a shallow copy of the current node i.e. a node with the same
   /// name and attributes but with no parent or child nodes.
   Node clone();
 
-  String get namespace => null;
+  /// *Deprecated* use [Element.namespaceUri] instead.
+  @deprecated String get namespace => null;
 
   int get nodeType;
 
   /// *Deprecated* use [text], [Text.data] or [Comment.data].
   @deprecated String get value => null;
 
   /// *Deprecated* use [nodeType].
   @deprecated int get $dom_nodeType => nodeType;
 
-  String get outerHtml {
+  /// *Deprecated* use [Element.outerHtml]
+  @deprecated String get outerHtml => _outerHtml;
+
+  /// *Deprecated* use [Element.innerHtml]
+  @deprecated String get innerHtml => _innerHtml;
+  @deprecated set innerHtml(String value) { _innerHtml = value; }
+
+  // http://domparsing.spec.whatwg.org/#extensions-to-the-element-interface
+  String get _outerHtml {
     var str = new StringBuffer();
     _addOuterHtml(str);
     return str.toString();
   }
 
-  String get innerHtml {
+  String get _innerHtml {
     var str = new StringBuffer();
     _addInnerHtml(str);
     return str.toString();
   }
 
-  set innerHtml(String value) {
+  set _innerHtml(String value) {
     nodes.clear();
     // TODO(jmesserly): should be able to get the same effect by adding the
     // fragment directly.
-    nodes.addAll(parseFragment(value, container: tagName).nodes);
+    nodes.addAll(parseFragment(value, container: _tagName).nodes);
   }
 
   // Implemented per: http://dom.spec.whatwg.org/#dom-node-textcontent
   String get text => null;
   set text(String value) {}
 
   void append(Node node) => nodes.add(node);
 
   Node get firstChild => nodes.isNotEmpty ? nodes[0] : null;
 
   void _addOuterHtml(StringBuffer str);
 
   void _addInnerHtml(StringBuffer str) {
     for (Node child in nodes) child._addOuterHtml(str);
   }
 
-  String toString() => tagName;
-
   Node remove() {
     // TODO(jmesserly): is parent == null an error?
     if (parent != null) {
       parent.nodes.remove(this);
     }
     return this;
   }
 
   /// Insert [node] as a child of the current node, before [refNode] in the
   /// list of child nodes. Raises [UnsupportedOperationException] if [refNode]
@@ skipping 13 matching lines @@
       throw new UnsupportedError('Node must have a parent to replace it.');
     }
     parent.nodes[parent.nodes.indexOf(this)] = otherNode;
     return this;
   }
 
   // TODO(jmesserly): should this be a property or remove?
   /// Return true if the node has children or text.
   bool hasContent() => nodes.length > 0;
 
-  Pair<String, String> get nameTuple {
-    var ns = namespace != null ? namespace : Namespaces.html;
-    return new Pair(ns, tagName);
-  }
+  /// *Deprecated* construct a pair using the namespaceUri and the name.
+  @deprecated Pair<String, String> get nameTuple =>
+      this is Element ? getElementNameTuple(this) : null;
 
   /// Move all the children of the current node to [newParent].
   /// This is needed so that trees that don't store text as nodes move the
   /// text in the correct way.
   void reparentChildren(Node newParent) {
     newParent.nodes.addAll(nodes);
     nodes.clear();
   }
 
   /// *Deprecated* use [querySelector] instead.
@@ skipping 68 matching lines @@
         return false;
       }
     }
 
     return true;
   }
 
   Element _queryType(String tag) {
     for (var node in nodes) {
       if (node is! Element) continue;
-      if (node.tagName == tag) return node;
+      if (node.localName == tag) return node;
       var result = node._queryType(tag);
       if (result != null) return result;
     }
     return null;
   }
 
   void _queryAllType(String tag, List<Element> results) {
     for (var node in nodes) {
       if (node is! Element) continue;
-      if (node.tagName == tag) results.add(node);
+      if (node.localName == tag) results.add(node);
       node._queryAllType(tag, results);
     }
   }
 
   /// Initialize [attributeSpans] using [sourceSpan].
   void _ensureAttributeSpans() {
     if (_attributeSpans != null) return;
 
     _attributeSpans = new LinkedHashMap<dynamic, FileSpan>();
     _attributeValueSpans = new LinkedHashMap<dynamic, FileSpan>();
@@ skipping 14 matching lines @@
           offset + attr.start, offset + attr.end);
       if (attr.startValue != null) {
         _attributeValueSpans[attr.name] = sourceSpan.file.span(
             offset + attr.startValue, offset + attr.endValue);
       }
     }
   }
 }
 
 class Document extends Node {
-  Document() : super(null);
+  Document() : super._();
   factory Document.html(String html) => parse(html);
 
   int get nodeType => Node.DOCUMENT_NODE;
 
   // TODO(jmesserly): optmize this if needed
   Element get documentElement => querySelector('html');
   Element get head => documentElement.querySelector('head');
   Element get body => documentElement.querySelector('body');
 
+  /// Returns a fragment of HTML or XML that represents the element and its
+  /// contents.
+  // TODO(jmesserly): this API is not specified in:
+  // <http://domparsing.spec.whatwg.org/> nor is it in dart:html, instead
+  // only Element has outerHtml. However it is quite useful. Should we move it
+  // to dom_parsing, where we keep other custom APIs?
+  String get outerHtml => _outerHtml;
+
   String toString() => "#document";
 
   void _addOuterHtml(StringBuffer str) => _addInnerHtml(str);
 
   Document clone() => new Document();
 }
 
 class DocumentFragment extends Document {
   DocumentFragment();
   factory DocumentFragment.html(String html) => parseFragment(html);
 
   int get nodeType => Node.DOCUMENT_FRAGMENT_NODE;
 
   String toString() => "#document-fragment";
 
   DocumentFragment clone() => new DocumentFragment();
 
   String get text => _getText(this);
   set text(String value) => _setText(this, value);
 }
 
 class DocumentType extends Node {
+  final String name;
   final String publicId;
   final String systemId;
 
-  DocumentType(String name, this.publicId, this.systemId) : super(name);
+  DocumentType(String name, this.publicId, this.systemId)
+      // Note: once Node.tagName is removed, don't pass "name" to super
+      : name = name, super._(name);
 
   int get nodeType => Node.DOCUMENT_TYPE_NODE;
 
   String toString() {
     if (publicId != null || systemId != null) {
       // TODO(jmesserly): the html5 serialization spec does not add these. But
       // it seems useful, and the parser can handle it, so for now keeping it.
       var pid = publicId != null ? publicId : '';
       var sid = systemId != null ? systemId : '';
-      return '<!DOCTYPE $tagName "$pid" "$sid">';
+      return '<!DOCTYPE $name "$pid" "$sid">';
     } else {
-      return '<!DOCTYPE $tagName>';
+      return '<!DOCTYPE $name>';
     }
   }
 
 
   void _addOuterHtml(StringBuffer str) {
     str.write(toString());
   }
 
-  DocumentType clone() => new DocumentType(tagName, publicId, systemId);
+  DocumentType clone() => new DocumentType(name, publicId, systemId);
 }
 
 class Text extends Node {
   String data;
 
-  Text(this.data) : super(null);
+  Text(this.data) : super._();
 
   /// *Deprecated* use [data].
   @deprecated String get value => data;
   @deprecated set value(String x) { data = x; }
 
   int get nodeType => Node.TEXT_NODE;
 
   String toString() => '"$data"';
 
-  void _addOuterHtml(StringBuffer str) {
-    // Don't escape text for certain elements, notably <script>.
-    if (rcdataElements.contains(parent.tagName) ||
-        parent.tagName == 'plaintext') {
-      str.write(data);
-    } else {
-      str.write(htmlSerializeEscape(data));
-    }
-  }
+  void _addOuterHtml(StringBuffer str) => writeTextNodeAsHtml(str, this);
 
   Text clone() => new Text(data);
 
   String get text => data;
   set text(String value) { data = value; }
 }
 
 class Element extends Node {
-  final String namespace;
+  final String namespaceUri;
 
-  // TODO(jmesserly): deprecate in favor of Element.tag? Or rename?
-  Element(String name, [this.namespace]) : super(name);
+  @deprecated String get namespace => namespaceUri;
 
-  Element.tag(String name) : namespace = null, super(name);
+  /// The [local name](http://dom.spec.whatwg.org/#concept-element-local-name)
+  /// of this element.
+  String get localName => _tagName;
+
+  // TODO(jmesserly): deprecate in favor of [Document.createElementNS].
+  // However we need every element to have a Document before this can work.
+  Element(String name, [this.namespaceUri]) : super._(name);
+
+  Element.tag(String name) : namespaceUri = null, super._(name);
 
   static final _START_TAG_REGEXP = new RegExp('<(\\w+)');
 
   static final _CUSTOM_PARENT_TAG_MAP = const {
     'body': 'html',
     'head': 'html',
     'caption': 'table',
     'td': 'tr',
     'colgroup': 'table',
     'col': 'colgroup',
@@ skipping 38 matching lines @@
       throw new ArgumentError('HTML had ${fragment.children.length} '
           'top level elements but 1 expected');
     }
     element.remove();
     return element;
   }
 
   int get nodeType => Node.ELEMENT_NODE;
 
   String toString() {
-    if (namespace == null) return "<$tagName>";
-    return "<${Namespaces.getPrefix(namespace)} $tagName>";
+    if (namespaceUri == null) return "<$localName>";
+    return "<${Namespaces.getPrefix(namespaceUri)} $localName>";
   }
 
   String get text => _getText(this);
   set text(String value) => _setText(this, value);
 
+  /// Returns a fragment of HTML or XML that represents the element and its
+  /// contents.
+  String get outerHtml => _outerHtml;
+
+  /// Returns a fragment of HTML or XML that represents the element's contents.
+  /// Can be set, to replace the contents of the element with nodes parsed from
+  /// the given string.
+  String get innerHtml => _innerHtml;
+  // TODO(jmesserly): deprecate in favor of:
+  // <https://api.dartlang.org/apidocs/channels/stable/#dart-dom-html.Element@id_setInnerHtml>
+  set innerHtml(String value) { _innerHtml = value; }
+
   void _addOuterHtml(StringBuffer str) {
     // http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#serializing-html-fragments
     // Element is the most complicated one.
-    if (namespace == null ||
-        namespace == Namespaces.html ||
-        namespace == Namespaces.mathml ||
-        namespace == Namespaces.svg) {
-      str.write('<$tagName');
+    if (namespaceUri == null ||
+        namespaceUri == Namespaces.html ||
+        namespaceUri == Namespaces.mathml ||
+        namespaceUri == Namespaces.svg) {
+      str.write('<$localName');
     } else {
       // TODO(jmesserly): the spec doesn't define "qualified name".
       // I'm not sure if this is correct, but it should parse reasonably.
-      str.write('<${Namespaces.getPrefix(namespace)}:$tagName');
+      str.write('<${Namespaces.getPrefix(namespaceUri)}:$localName');
     }
 
     if (attributes.length > 0) {
       attributes.forEach((key, v) {
         // Note: AttributeName.toString handles serialization of attribute
         // namespace, if needed.
         str.write(' $key="${htmlSerializeEscape(v, attributeMode: true)}"');
       });
     }
 
     str.write('>');
 
     if (nodes.length > 0) {
-      if (tagName == 'pre' || tagName == 'textarea' || tagName == 'listing') {
+      if (localName == 'pre' || localName == 'textarea' ||
+          localName == 'listing') {
         final first = nodes[0];
         if (first is Text && first.data.startsWith('\n')) {
           // These nodes will remove a leading \n at parse time, so if we still
           // have one, it means we started with two. Add it back.
           str.write('\n');
         }
       }
 
       _addInnerHtml(str);
     }
 
     // void elements must not have an end tag
     // http://dev.w3.org/html5/markup/syntax.html#void-elements
-    if (!isVoidElement(tagName)) str.write('</$tagName>');
+    if (!isVoidElement(localName)) str.write('</$localName>');
   }
 
-  Element clone() => new Element(tagName, namespace)
+  Element clone() => new Element(localName, namespaceUri)
       ..attributes = new LinkedHashMap.from(attributes);
 
   String get id {
     var result = attributes['id'];
     return result != null ? result : '';
   }
 
   set id(String value) {
     if (value == null) {
       attributes.remove('id');
     } else {
       attributes['id'] = value;
     }
   }
 }
 
 class Comment extends Node {
   String data;
 
-  Comment(this.data) : super(null);
+  Comment(this.data) : super._();
 
   int get nodeType => Node.COMMENT_NODE;
 
   String toString() => "<!-- $data -->";
 
   void _addOuterHtml(StringBuffer str) {
     str.write("<!--$data-->");
   }
 
   Comment clone() => new Comment(data);
@@ skipping 302 matching lines @@
 
 class _ConcatTextVisitor extends TreeVisitor {
   final _str = new StringBuffer();
 
   String toString() => _str.toString();
 
   visitText(Text node) {
     _str.write(node.data);
   }
 }