blob: d61053e24a9cfd679fed4a90e06a774639214593 [file] [log] [blame]
// Copyright (c) 2014, 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.
library stub_core_library;
import 'package:analyzer/analyzer.dart';
import 'package:analyzer/src/generated/java_core.dart';
import 'package:analyzer/src/generated/scanner.dart';
import 'package:path/path.dart' as p;
/// Returns the contents of a stub version of the library at [path].
/// A stub library has the same API as the original library, but none of the
/// implementation. Specifically, this guarantees that any code that worked with
/// the original library will be statically valid with the stubbed library, and
/// its only runtime errors will be [UnsupportedError]s. This means that
/// constants and const constructors are preserved.
/// [importReplacements] is a map from import URIs to their replacements. It's
/// used so that mutliple interrelated libraries can refer to their stubbed
/// versions rather than the originals.
String stubFile(String path, [Map<String, String> importReplacements]) {
var visitor = new _StubVisitor(path, importReplacements);
return visitor.toString();
/// Returns the contents of a stub version of the library parsed from [code].
/// If [code] contains `part` directives, they will be resolved relative to
/// [path]. The contents of the parted files will be stubbed and inlined.
String stubCode(String code, String path,
[Map<String, String> importReplacements]) {
var visitor = new _StubVisitor(path, importReplacements);
parseCompilationUnit(code, name: path).accept(visitor);
return visitor.toString();
/// An AST visitor that traverses the tree of the original library and writes
/// the stubbed version.
/// In order to avoid complex tree-shaking logic, this takes a conservative
/// approach to removing private code. Private classes may still be extended by
/// public classes; private constants may be referenced by public constants; and
/// private static and top-level methods may be referenced by public constants
/// or by superclass constructor calls. All of these are preserved even though
/// most could theoretically be eliminated.
class _StubVisitor extends ToSourceVisitor {
/// The directory containing the library being visited.
final String _root;
/// Which imports to replace.
final Map<String, String> _importReplacements;
final PrintStringWriter _writer;
// TODO(nweiz): Get rid of this when issue 19897 is fixed.
/// The current class declaration being visited.
/// This is `null` if there is no current class declaration.
ClassDeclaration _class;
_StubVisitor(String path, Map<String, String> importReplacements)
: this._(path, importReplacements, new PrintStringWriter());
_StubVisitor._(String path, Map<String, String> importReplacements,
PrintStringWriter writer)
: _root = p.dirname(path),
_importReplacements = importReplacements == null ? const {} :
_writer = writer,
String toString() => _writer.toString();
visitImportDirective(ImportDirective node) {
node = _modifyDirective(node);
if (node != null) super.visitImportDirective(node);
visitExportDirective(ExportDirective node) {
node = _modifyDirective(node);
if (node != null) super.visitExportDirective(node);
visitPartDirective(PartDirective node) {
// Inline parts directly in the output file.
var path = p.url.join(_root, p.fromUri(node.uri.stringValue));
parseDartFile(path).accept(new _StubVisitor._(path, const {}, _writer));
visitPartOfDirective(PartOfDirective node) {
// Remove "part of", since parts are inlined.
visitClassDeclaration(ClassDeclaration node) {
_class = _clone(node);
_class.nativeClause = null;
_class = null;
visitConstructorDeclaration(ConstructorDeclaration node) {
node = _withoutExternal(node);
// Remove field initializers and redirecting initializers but not superclass
// initializers. The code is ugly because NodeList doesn't support
// removeWhere.
var superclassInitializers = node.initializers.where((initializer) =>
initializer is SuperConstructorInvocation).toList();
// Add a space because ToSourceVisitor doesn't and it makes testing easier.
_writer.print(" ");
visitSuperConstructorInvocation(SuperConstructorInvocation node) {
// If this is a const constructor, it should actually work, so don't screw
// with the superclass constructor.
if ((node.parent as ConstructorDeclaration).constKeyword != null) {
return super.visitSuperConstructorInvocation(node);
_visitNodeWithPrefix(".", node.constructorName);
// If one stubbed class extends another, we don't want to run the original
// code for the superclass constructor call, and we do want an
// UnsupportedException that points to the subclass rather than the
// superclass. To do this, we null out all but the first superclass
// constructor parameter and replace the first parameter with a throw.
var positionalArguments = node.argumentList.arguments
.where((argument) => argument is! NamedExpression);
if (positionalArguments.isNotEmpty) {
for (var i = 0; i < positionalArguments.length - 1; i++) {
_writer.print(", null");
visitMethodDeclaration(MethodDeclaration node) {
// Private non-static methods aren't public and aren't accessible from
// constant expressions, so can be safely removed.
if (Identifier.isPrivateName( && !node.isStatic) return;
_writer.print(" ");
visitFunctionDeclaration(FunctionDeclaration node) {
visitBlockFunctionBody(BlockFunctionBody node) => _emitFunctionBody(node);
visitExpressionFunctionBody(ExpressionFunctionBody node) =>
visitNativeFunctionBody(NativeFunctionBody node) => _emitFunctionBody(node);
visitEmptyFunctionBody(FunctionBody node) {
// Preserve empty function bodies for abstract methods, since there's no
// reason not to. Note that "empty" here means "foo();" not "foo() {}".
var isAbstractMethod = node.parent is MethodDeclaration &&
!(node.parent as MethodDeclaration).isStatic && _class != null &&
// Preserve empty function bodies for const constructors because we want
// them to continue to work.
var isConstConstructor = node.parent is ConstructorDeclaration &&
(node.parent as ConstructorDeclaration).constKeyword != null;
if (isAbstractMethod || isConstConstructor) {
_writer.print(" ");
} else {
_writer.print(" ");
visitFieldFormalParameter(FieldFormalParameter node) {
// Remove "this." because instance variables are replaced with getters and
// setters or just set to null.
_emitTokenWithSuffix(node.keyword, " ");
// Make sure the parameter is still typed by grabbing the type from the
// associated instance variable.
var type = node.type;
if (type == null) {
var variable = _class.members
.where((member) => member is FieldDeclaration)
.expand((member) => member.fields.variables)
.firstWhere((variable) => ==,
orElse: () => null);
if (variable != null) type = variable.parent.type;
_visitNodeWithSuffix(type, " ");
visitTopLevelVariableDeclaration(TopLevelVariableDeclaration node) {
visitFieldDeclaration(FieldDeclaration node) {
_writer.print(" ");
/// Modifies a directive to respect [importReplacements] and ignore hidden
/// core libraries.
/// This can return `null`, indicating that the directive should not be
/// emitted.
UriBasedDirective _modifyDirective(UriBasedDirective node) {
// Ignore internal "dart:" libraries.
if (node.uri.stringValue.startsWith('dart:_')) return null;
// Replace libraries in [importReplacements].
if (_importReplacements.containsKey(node.uri.stringValue)) {
node = _clone(node);
var token = new StringToken(TokenType.STRING,
'"${_importReplacements[node.uri.stringValue]}"', 0);
node.uri = new SimpleStringLiteral(token, null);
return node;
/// Emits a variable declaration, either as a literal variable or as a getter
/// and maybe a setter that throw [UnsupportedError]s.
_emitVariableDeclaration(VariableDeclaration node) {
VariableDeclarationList parent = node.parent;
var isStatic = node.parent.parent is FieldDeclaration &&
(node.parent.parent as FieldDeclaration).isStatic;
// Preserve constants as-is.
if (node.isConst) {
if (isStatic) _writer.print("static ");
_writer.print("const ");
_writer.print("; ");
// Ignore non-const private variables.
if (Identifier.isPrivateName( return;
// There's no need to throw errors for instance fields of classes that can't
// be constructed.
if (!isStatic && _class != null && !_inConstructableClass) {
_emitTokenWithSuffix(parent.keyword, " ");
_visitNodeWithSuffix(parent.type, " ");
// Add an initializer to make sure that final variables are initialized.
if (node.isFinal) _writer.print(" = null; ");
var name =;
if (_class != null) name = "${}.$name";
// Convert public variables into getters and setters that throw
// UnsupportedErrors.
if (isStatic) _writer.print("static ");
_visitNodeWithSuffix(parent.type, " ");
_writer.print("get ");
_writer.print(" => ${_unsupported(name)}; ");
if (node.isFinal) return;
if (isStatic) _writer.print("static ");
_writer.print("set ");
_visitNodeWithSuffix(parent.type, " ");
_writer.print("_) { ${_unsupported("$name=")}; } ");
/// Emits a function body.
/// This usually emits a body that throws an [UnsupportedError], but it can
/// emit an empty body as well.
void _emitFunctionBody(FunctionBody node) {
// There's no need to throw errors for instance methods of classes that
// can't be constructed.
var parent = node.parent;
if (parent is MethodDeclaration && !parent.isStatic &&
!_inConstructableClass) {
_writer.print('{} ');
_writer.print('{ ${_unsupported(_functionName(node))}; } ');
// Returns a human-readable name for the function containing [node].
String _functionName(AstNode node) {
// Come up with a nice name for the error message so users can tell exactly
// what unsupported method they're calling.
var function = node.getAncestor((ancestor) =>
ancestor is FunctionDeclaration || ancestor is MethodDeclaration);
if (function != null) {
var name =;
if (function.isSetter) {
name = "$name=";
} else if (!function.isGetter &&
!(function is MethodDeclaration && function.isOperator)) {
name = "$name()";
if (_class != null) name = "${}.$name";
return name;
var constructor = node.getAncestor((ancestor) =>
ancestor is ConstructorDeclaration);
if (constructor == null) return "This function";
var name = "new ${}";
if ( != null) name = "$name.${}";
return "$name()";
/// Returns a deep copy of [node].
AstNode _clone(AstNode node) => node.accept(new AstCloner());
/// Returns a deep copy of [node] without the "external" keyword.
AstNode _withoutExternal(node) {
var clone = node.accept(new AstCloner());
clone.externalKeyword = null;
return clone;
/// Visits [node] if it's non-`null`.
void _visitNode(AstNode node) {
if (node != null) node.accept(this);
/// Visits [node] then emits [suffix] if [node] isn't `null`.
void _visitNodeWithSuffix(AstNode node, String suffix) {
if (node == null) return;
/// Emits [prefix] then visits [node] if [node] isn't `null`.
void _visitNodeWithPrefix(String prefix, AstNode node) {
if (node == null) return;
/// Emits [token] followed by [suffix] if [token] isn't `null`.
void _emitTokenWithSuffix(Token token, String suffix) {
if (token == null) return;
/// Returns an expression that throws an [UnsupportedError] explaining that
/// [name] isn't supported.
String _unsupported(String name) => 'throw new UnsupportedError("$name is '
'unsupported on this platform.")';
/// Returns whether or not the visitor is currently visiting a class that can
/// be constructed without error after it's stubbed.
/// There are two cases where a class will be constructable once it's been
/// stubbed. First, a class with a const constructor will be preserved, since
/// making the const constructor fail would statically break code. Second, a
/// class with a default constructor is preserved since adding a constructor
/// that throws an error could statically break uses of the class as a mixin.
bool get _inConstructableClass {
if (_class == null) return false;
var constructors = _class.members.where((member) =>
member is ConstructorDeclaration);
if (constructors.isEmpty) return true;
return constructors.any((constructor) => constructor.constKeyword != null);