move polymer.dart into dart svn

pkg/polymer/lib/src/analyzer.dart

+// Copyright (c) 2013, 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.
+
+/**
+ * Part of the template compilation that concerns with extracting information
+ * from the HTML parse tree.
+ */
+library analyzer;
+
+import 'package:html5lib/dom.dart';
+import 'package:html5lib/dom_parsing.dart';
+import 'package:source_maps/span.dart' hide SourceFile;
+
+import 'custom_tag_name.dart';
+import 'dart_parser.dart' show parseDartCode;
+import 'files.dart';
+import 'info.dart';
+import 'messages.dart';
+import 'summary.dart';
+
+/**
+ * Finds custom elements in this file and the list of referenced files with
+ * component declarations. This is the first pass of analysis on a file.
+ *
+ * Adds emitted error/warning messages to [messages], if [messages] is
+ * supplied.
+ */
+FileInfo analyzeDefinitions(GlobalInfo global, UrlInfo inputUrl,
+    Document document, String packageRoot,
+    Messages messages, {bool isEntryPoint: false}) {
+  var result = new FileInfo(inputUrl, isEntryPoint);
+  var loader = new _ElementLoader(global, result, packageRoot, messages);
+  loader.visit(document);
+  return result;
+}
+
+/**
+ *  Extract relevant information from all files found from the root document.
+ *
+ *  Adds emitted error/warning messages to [messages], if [messages] is
+ *  supplied.
+ */
+void analyzeFile(SourceFile file, Map<String, FileInfo> info,
+                 Iterator<int> uniqueIds, GlobalInfo global,
+                 Messages messages, emulateScopedCss) {
+  var fileInfo = info[file.path];
+  var analyzer = new _Analyzer(fileInfo, uniqueIds, global, messages,
+      emulateScopedCss);
+  analyzer._normalize(fileInfo, info);
+  analyzer.visit(file.document);
+}
+
+
+/** A visitor that walks the HTML to extract all the relevant information. */
+class _Analyzer extends TreeVisitor {
+  final FileInfo _fileInfo;
+  LibraryInfo _currentInfo;
+  Iterator<int> _uniqueIds;
+  GlobalInfo _global;
+  Messages _messages;
+
+  int _generatedClassNumber = 0;
+
+  /**
+   * Whether to keep indentation spaces. Break lines and indentation spaces
+   * within templates are preserved in HTML. When users specify the attribute
+   * 'indentation="remove"' on a template tag, we'll trim those indentation
+   * spaces that occur within that tag and its decendants. If any decendant
+   * specifies 'indentation="preserve"', then we'll switch back to the normal
+   * behavior.
+   */
+  bool _keepIndentationSpaces = true;
+
+  final bool _emulateScopedCss;
+
+  _Analyzer(this._fileInfo, this._uniqueIds, this._global, this._messages,
+      this._emulateScopedCss) {
+    _currentInfo = _fileInfo;
+  }
+
+  void visitElement(Element node) {
+    if (node.tagName == 'script') {
+      // We already extracted script tags in previous phase.
+      return;
+    }
+
+    if (node.tagName == 'style') {
+      // We've already parsed the CSS.
+      // If this is a component remove the style node.
+      if (_currentInfo is ComponentInfo && _emulateScopedCss) node.remove();
+      return;
+    }
+
+    _bindCustomElement(node);
+
+    var lastInfo = _currentInfo;
+    if (node.tagName == 'polymer-element') {
+      // If element is invalid _ElementLoader already reported an error, but
+      // we skip the body of the element here.
+      var name = node.attributes['name'];
+      if (name == null) return;
+
+      ComponentInfo component = _fileInfo.components[name];
+      if (component == null) return;
+
+      _analyzeComponent(component);
+
+      _currentInfo = component;
+
+      // Remove the <element> tag from the tree
+      node.remove();
+    }
+
+    node.attributes.forEach((name, value) {
+      if (name.startsWith('on')) {
+        _validateEventHandler(node, name, value);
+      } else  if (name == 'pseudo' && _currentInfo is ComponentInfo) {
+        // Any component's custom pseudo-element(s) defined?
+        _processPseudoAttribute(node, value.split(' '));
+      }
+    });
+
+    var keepSpaces = _keepIndentationSpaces;
+    if (node.tagName == 'template' &&
+        node.attributes.containsKey('indentation')) {
+      var value = node.attributes['indentation'];
+      if (value != 'remove' && value != 'preserve') {
+        _messages.warning(
+            "Invalid value for 'indentation' ($value). By default we preserve "
+            "the indentation. Valid values are either 'remove' or 'preserve'.",
+            node.sourceSpan);
+      }
+      _keepIndentationSpaces = value != 'remove';
+    }
+
+    // Invoke super to visit children.
+    super.visitElement(node);
+
+    _keepIndentationSpaces = keepSpaces;
+    _currentInfo = lastInfo;
+
+    if (node.tagName == 'body' || node.parent == null) {
+      _fileInfo.body = node;
+    }
+  }
+
+  void _analyzeComponent(ComponentInfo component) {
+    var baseTag = component.extendsTag;
+    component.extendsComponent = baseTag == null ? null
+        : _fileInfo.components[baseTag];
+    if (component.extendsComponent == null && isCustomTag(baseTag)) {
+      _messages.warning(
+          'custom element with tag name ${component.extendsTag} not found.',
+          component.element.sourceSpan);
+    }
+
+    // Now that the component's code has been loaded, we can validate that the
+    // class exists.
+    component.findClassDeclaration(_messages);
+  }
+
+  void _bindCustomElement(Element node) {
+    // <fancy-button>
+    var component = _fileInfo.components[node.tagName];
+    if (component == null) {
+      // TODO(jmesserly): warn for unknown element tags?
+
+      // <button is="fancy-button">
+      var componentName = node.attributes['is'];
+      if (componentName != null) {
+        component = _fileInfo.components[componentName];
+      } else if (isCustomTag(node.tagName)) {
+        componentName = node.tagName;
+      }
+      if (component == null && componentName != null &&
+          componentName != 'polymer-element') {
+        _messages.warning(
+            'custom element with tag name $componentName not found.',
+            node.sourceSpan);
+      }
+    }
+
+    if (component != null) {
+      if (!component.hasConflict) {
+        _currentInfo.usedComponents[component] = true;
+      }
+
+      var baseTag = component.baseExtendsTag;
+      var nodeTag = node.tagName;
+      var hasIsAttribute = node.attributes.containsKey('is');
+
+      if (baseTag != null && !hasIsAttribute) {
+        _messages.warning(
+            'custom element "${component.tagName}" extends from "$baseTag", but'
+            ' this tag will not include the default properties of "$baseTag". '
+            'To fix this, either write this tag as <$baseTag '
+            'is="${component.tagName}"> or remove the "extends" attribute from '
+            'the custom element declaration.', node.sourceSpan);
+      } else if (hasIsAttribute) {
+        if (baseTag == null) {
+          _messages.warning(
+              'custom element "${component.tagName}" doesn\'t declare any type '
+              'extensions. To fix this, either rewrite this tag as '
+              '<${component.tagName}> or add \'extends="$nodeTag"\' to '
+              'the custom element declaration.', node.sourceSpan);
+        } else if (baseTag != nodeTag) {
+          _messages.warning(
+              'custom element "${component.tagName}" extends from "$baseTag". '
+              'Did you mean to write <$baseTag is="${component.tagName}">?',
+              node.sourceSpan);
+        }
+      }
+    }
+  }
+
+  void _processPseudoAttribute(Node node, List<String> values) {
+    List mangledValues = [];
+    for (var pseudoElement in values) {
+      if (_global.pseudoElements.containsKey(pseudoElement)) continue;
+
+      _uniqueIds.moveNext();
+      var newValue = "${pseudoElement}_${_uniqueIds.current}";
+      _global.pseudoElements[pseudoElement] = newValue;
+      // Mangled name of pseudo-element.
+      mangledValues.add(newValue);
+
+      if (!pseudoElement.startsWith('x-')) {
+        // TODO(terry): The name must start with x- otherwise it's not a custom
+        //              pseudo-element.  May want to relax since components no
+        //              longer need to start with x-.  See isse #509 on
+        //              pseudo-element prefix.
+        _messages.warning("Custom pseudo-element must be prefixed with 'x-'.",
+            node.sourceSpan);
+      }
+    }
+
+    // Update the pseudo attribute with the new mangled names.
+    node.attributes['pseudo'] = mangledValues.join(' ');
+  }
+
+  /**
+   * Support for inline event handlers that take expressions.
+   * For example: `on-double-click=myHandler($event, todo)`.
+   */
+  void _validateEventHandler(Element node, String name, String value) {
+    if (!name.startsWith('on-')) {
+      // TODO(jmesserly): do we need an option to suppress this warning?
+      _messages.warning('Event handler $name will be interpreted as an inline '
+          'JavaScript event handler. Use the form '
+          'on-event-name="handlerName" if you want a Dart handler '
+          'that will automatically update the UI based on model changes.',
+          node.sourceSpan);
+    }
+
+    if (value.contains('.') || value.contains('(')) {
+      // TODO(sigmund): should we allow more if we use fancy-syntax?
+      _messages.warning('Invalid event handler body "$value". Declare a method '
+          'in your custom element "void handlerName(event, detail, target)" '
+          'and use the form on-event-name="handlerName".',
+          node.sourceSpan);
+    }
+  }
+
+  /**
+   * Normalizes references in [info]. On the [analyzeDefinitions] phase, the
+   * analyzer extracted names of files and components. Here we link those names
+   * to actual info classes. In particular:
+   *   * we initialize the [FileInfo.components] map in [info] by importing all
+   *     [declaredComponents],
+   *   * we scan all [info.componentLinks] and import their
+   *     [info.declaredComponents], using [files] to map the href to the file
+   *     info. Names in [info] will shadow names from imported files.
+   *   * we fill [LibraryInfo.externalCode] on each component declared in
+   *     [info].
+   */
+  void _normalize(FileInfo info, Map<String, FileInfo> files) {
+    _attachExtenalScript(info, files);
+
+    for (var component in info.declaredComponents) {
+      _addComponent(info, component);
+      _attachExtenalScript(component, files);
+    }
+
+    for (var link in info.componentLinks) {
+      var file = files[link.resolvedPath];
+      // We already issued an error for missing files.
+      if (file == null) continue;
+      file.declaredComponents.forEach((c) => _addComponent(info, c));
+    }
+  }
+
+  /**
+   * Stores a direct reference in [info] to a dart source file that was loaded
+   * in a script tag with the 'src' attribute.
+   */
+  void _attachExtenalScript(LibraryInfo info, Map<String, FileInfo> files) {
+    var externalFile = info.externalFile;
+    if (externalFile != null) {
+      info.externalCode = files[externalFile.resolvedPath];
+      if (info.externalCode != null) info.externalCode.htmlFile = info;
+    }
+  }
+
+  /** Adds a component's tag name to the names in scope for [fileInfo]. */
+  void _addComponent(FileInfo fileInfo, ComponentSummary component) {
+    var existing = fileInfo.components[component.tagName];
+    if (existing != null) {
+      if (existing == component) {
+        // This is the same exact component as the existing one.
+        return;
+      }
+
+      if (existing is ComponentInfo && component is! ComponentInfo) {
+        // Components declared in [fileInfo] shadow component names declared in
+        // imported files.
+        return;
+      }
+
+      if (existing.hasConflict) {
+        // No need to report a second error for the same name.
+        return;
+      }
+
+      existing.hasConflict = true;
+
+      if (component is ComponentInfo) {
+        _messages.error('duplicate custom element definition for '
+            '"${component.tagName}".', existing.sourceSpan);
+        _messages.error('duplicate custom element definition for '
+            '"${component.tagName}" (second location).', component.sourceSpan);
+      } else {
+        _messages.error('imported duplicate custom element definitions '
+            'for "${component.tagName}".', existing.sourceSpan);
+        _messages.error('imported duplicate custom element definitions '
+            'for "${component.tagName}" (second location).',
+            component.sourceSpan);
+      }
+    } else {
+      fileInfo.components[component.tagName] = component;
+    }
+  }
+}
+
+/** A visitor that finds `<link rel="import">` and `<element>` tags.  */
+class _ElementLoader extends TreeVisitor {
+  final GlobalInfo _global;
+  final FileInfo _fileInfo;
+  LibraryInfo _currentInfo;
+  String _packageRoot;
+  bool _inHead = false;
+  Messages _messages;
+
+  /**
+   * Adds emitted warning/error messages to [_messages]. [_messages]
+   * must not be null.
+   */
+  _ElementLoader(this._global, this._fileInfo, this._packageRoot,
+      this._messages) {
+    _currentInfo = _fileInfo;
+  }
+
+  void visitElement(Element node) {
+    switch (node.tagName) {
+      case 'link': visitLinkElement(node); break;
+      case 'element':
+        _messages.warning('<element> elements are not supported, use'
+            ' <polymer-element> instead', node.sourceSpan);
+        break;
+      case 'polymer-element':
+         visitElementElement(node);
+         break;
+      case 'script': visitScriptElement(node); break;
+      case 'head':
+        var savedInHead = _inHead;
+        _inHead = true;
+        super.visitElement(node);
+        _inHead = savedInHead;
+        break;
+      default: super.visitElement(node); break;
+    }
+  }
+
+  /**
+   * Process `link rel="import"` as specified in:
+   * <https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/components/index.html#link-type-component>
+   */
+  void visitLinkElement(Element node) {
+    var rel = node.attributes['rel'];
+    if (rel != 'component' && rel != 'components' &&
+        rel != 'import' && rel != 'stylesheet') return;
+
+    if (!_inHead) {
+      _messages.warning('link rel="$rel" only valid in '
+          'head.', node.sourceSpan);
+      return;
+    }
+
+    if (rel == 'component' || rel == 'components') {
+      _messages.warning('import syntax is changing, use '
+          'rel="import" instead of rel="$rel".', node.sourceSpan);
+    }
+
+    var href = node.attributes['href'];
+    if (href == null || href == '') {
+      _messages.warning('link rel="$rel" missing href.',
+          node.sourceSpan);
+      return;
+    }
+
+    bool isStyleSheet = rel == 'stylesheet';
+    var urlInfo = UrlInfo.resolve(href, _fileInfo.inputUrl, node.sourceSpan,
+        _packageRoot, _messages, ignoreAbsolute: isStyleSheet);
+    if (urlInfo == null) return;
+    if (isStyleSheet) {
+      _fileInfo.styleSheetHrefs.add(urlInfo);
+    } else {
+      _fileInfo.componentLinks.add(urlInfo);
+    }
+  }
+
+  void visitElementElement(Element node) {
+    // TODO(jmesserly): what do we do in this case? It seems like an <element>
+    // inside a Shadow DOM should be scoped to that <template> tag, and not
+    // visible from the outside.
+    if (_currentInfo is ComponentInfo) {
+      _messages.error('Nested component definitions are not yet supported.',
+          node.sourceSpan);
+      return;
+    }
+
+    var tagName = node.attributes['name'];
+    var extendsTag = node.attributes['extends'];
+
+    if (tagName == null) {
+      _messages.error('Missing tag name of the component. Please include an '
+          'attribute like \'name="your-tag-name"\'.',
+          node.sourceSpan);
+      return;
+    }
+
+    var component = new ComponentInfo(node, _fileInfo, tagName, extendsTag);
+    _fileInfo.declaredComponents.add(component);
+    _addComponent(component);
+
+    var lastInfo = _currentInfo;
+    _currentInfo = component;
+    super.visitElement(node);
+    _currentInfo = lastInfo;
+  }
+
+  /** Adds a component's tag name to the global list. */
+  void _addComponent(ComponentInfo component) {
+    var existing = _global.components[component.tagName];
+    if (existing != null) {
+      if (existing.hasConflict) {
+        // No need to report a second error for the same name.
+        return;
+      }
+
+      existing.hasConflict = true;
+
+      _messages.error('duplicate custom element definition for '
+          '"${component.tagName}".', existing.sourceSpan);
+      _messages.error('duplicate custom element definition for '
+          '"${component.tagName}" (second location).', component.sourceSpan);
+    } else {
+      _global.components[component.tagName] = component;
+    }
+  }
+
+  void visitScriptElement(Element node) {
+    var scriptType = node.attributes['type'];
+    var src = node.attributes["src"];
+
+    if (scriptType == null) {
+      // Note: in html5 leaving off type= is fine, but it defaults to
+      // text/javascript. Because this might be a common error, we warn about it
+      // in two cases:
+      //   * an inline script tag in a web component
+      //   * a script src= if the src file ends in .dart (component or not)
+      //
+      // The hope is that neither of these cases should break existing valid
+      // code, but that they'll help component authors avoid having their Dart
+      // code accidentally interpreted as JavaScript by the browser.
+      if (src == null && _currentInfo is ComponentInfo) {
+        _messages.warning('script tag in component with no type will '
+            'be treated as JavaScript. Did you forget type="application/dart"?',
+            node.sourceSpan);
+      }
+      if (src != null && src.endsWith('.dart')) {
+        _messages.warning('script tag with .dart source file but no type will '
+            'be treated as JavaScript. Did you forget type="application/dart"?',
+            node.sourceSpan);
+      }
+      return;
+    }
+
+    if (scriptType != 'application/dart') {
+      if (_currentInfo is ComponentInfo) {
+        // TODO(jmesserly): this warning should not be here, but our compiler
+        // does the wrong thing and it could cause surprising behavior, so let
+        // the user know! See issue #340 for more info.
+        // What we should be doing: leave JS component untouched by compiler.
+        _messages.warning('our custom element implementation does not support '
+            'JavaScript components yet. If this is affecting you please let us '
+            'know at https://github.com/dart-lang/web-ui/issues/340.',
+            node.sourceSpan);
+      }
+
+      return;
+    }
+
+    if (src != null) {
+      if (!src.endsWith('.dart')) {
+        _messages.warning('"application/dart" scripts should '
+            'use the .dart file extension.',
+            node.sourceSpan);
+      }
+
+      if (node.innerHtml.trim() != '') {
+        _messages.error('script tag has "src" attribute and also has script '
+            'text.', node.sourceSpan);
+      }
+
+      if (_currentInfo.codeAttached) {
+        _tooManyScriptsError(node);
+      } else {
+        _currentInfo.externalFile = UrlInfo.resolve(src, _fileInfo.inputUrl,
+            node.sourceSpan, _packageRoot, _messages);
+      }
+      return;
+    }
+
+    if (node.nodes.length == 0) return;
+
+    // I don't think the html5 parser will emit a tree with more than
+    // one child of <script>
+    assert(node.nodes.length == 1);
+    Text text = node.nodes[0];
+
+    if (_currentInfo.codeAttached) {
+      _tooManyScriptsError(node);
+    } else if (_currentInfo == _fileInfo && !_fileInfo.isEntryPoint) {
+      _messages.warning('top-level dart code is ignored on '
+          ' HTML pages that define components, but are not the entry HTML '
+          'file.', node.sourceSpan);
+    } else {
+      _currentInfo.inlinedCode = parseDartCode(
+          _currentInfo.dartCodeUrl.resolvedPath, text.value,
+          text.sourceSpan.start);
+      if (_currentInfo.userCode.partOf != null) {
+        _messages.error('expected a library, not a part.',
+            node.sourceSpan);
+      }
+    }
+  }
+
+  void _tooManyScriptsError(Node node) {
+    var location = _currentInfo is ComponentInfo ?
+        'a custom element declaration' : 'the top-level HTML page';
+
+    _messages.error('there should be only one dart script tag in $location.',
+        node.sourceSpan);
+  }
+}