diff --git a/CHANGELOG.md b/CHANGELOG.md index 02ba84819ae..d26be9c3a7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ### Libraries -### `dart:developer` +#### `dart:developer` #### `dart:developer` @@ -19,6 +19,16 @@ - Deprecated `UserTag.MAX_USER_TAGS` in favor of `UserTag.maxUserTags`. +#### `dart:mirrors` + +- **Breaking change** [#34233][]: The APIs [`MirrorsUsed`][] and [`Comment`][] + have been removed. `MirrorsUsed` was experimental and deprecated; `Comment` + was previously used internally in dart2js. Both are no longer functional. + +[#34233]: https://github.com/dart-lang/sdk/issues/34233 +[`MirrorsUsed`]: https://api.dart.dev/stable/dart-mirrors/MirrorsUsed-class.html +[`Comment`]: https://api.dart.dev/stable/dart-mirrors/Comment-class.html + ### Tools #### Linter diff --git a/pkg/compiler/README.md b/pkg/compiler/README.md index a21d663422c..e574f928cbc 100644 --- a/pkg/compiler/README.md +++ b/pkg/compiler/README.md @@ -223,8 +223,7 @@ functionality is publicly exposed. * `lib/src/common/elements.dart`: provides an interface to lookup basic elements like the class of `Object`, `int`, `List`, and their corresponding - interface types, constructors for symbols, annotations such as - `@MirrorsUsed`, the `identical` function, etc. These are normally restricted + interface types, constructors for symbols, annotations such as the `identical` function. These are normally restricted to elements that are understood directly in Dart. * `lib/src/js_backend/backend_helpers.dart`: provides a way to lookup internal @@ -278,10 +277,6 @@ functionality is publicly exposed. import, export, and part directives and keep crawling. It also triggers the patch parser to load patch files. -* `lib/src/mirrors_used.dart`: task that analyzes `@MirrorsUsed` annotations, - which let the compiler continue to do tree-shaking even when code is used via - `dart:mirrors`. - * Input/output: the compiler is designed to avoid all dependencies on dart:io. Most data is consumed and emitted via provider APIs. diff --git a/sdk/lib/_internal/js_runtime/lib/js_helper.dart b/sdk/lib/_internal/js_runtime/lib/js_helper.dart index ec8addd9dae..b4f4f5c8cca 100644 --- a/sdk/lib/_internal/js_runtime/lib/js_helper.dart +++ b/sdk/lib/_internal/js_runtime/lib/js_helper.dart @@ -154,8 +154,7 @@ createUnmangledInvocationMirror( } void throwInvalidReflectionError(String memberName) { - throw new UnsupportedError("Can't use '$memberName' in reflection " - "because it is not included in a @MirrorsUsed annotation."); + throw new UnsupportedError("Can't use '$memberName' in reflection."); } /// Helper used to instrument calls when the compiler is invoked with diff --git a/sdk/lib/mirrors/mirrors.dart b/sdk/lib/mirrors/mirrors.dart index 6e1948759f3..963319fecb6 100644 --- a/sdk/lib/mirrors/mirrors.dart +++ b/sdk/lib/mirrors/mirrors.dart @@ -120,11 +120,6 @@ abstract class MirrorSystem { /** * Returns the name of [symbol]. - * - * The following text is non-normative: - * - * Using this method may result in larger output. If possible, use - * [MirrorsUsed] to specify which symbols must be retained in clear text. */ external static String getName(Symbol symbol); @@ -1196,283 +1191,3 @@ abstract class SourceLocation { */ Uri get sourceUri; } - -/** - * Class used for encoding comments as metadata annotations. - */ -class Comment { - /** - * The comment text as written in the source text. - */ - final String text; - - /** - * The comment text without the start, end, and padding text. - * - * For example, if [text] is [: /** Comment text. */ :] then the [trimmedText] - * is [: Comment text. :]. - */ - final String trimmedText; - - /** - * Is [:true:] if this comment is a documentation comment. - * - * That is, that the comment is either enclosed in [: /** ... */ :] or starts - * with [: /// :]. - */ - final bool isDocComment; - - const Comment(this.text, this.trimmedText, this.isDocComment); -} - -/** - * Annotation describing how "dart:mirrors" is used (EXPERIMENTAL). - * - * When used as metadata on an import of "dart:mirrors" in library *L*, this - * class describes how "dart:mirrors" is used by library *L* unless overridden. - * See [override]. - * - * The following text is non-normative: - * - * In some scenarios, for example, when minifying Dart code, or when generating - * JavaScript code from a Dart program, the size and performance of the output - * can suffer from use of reflection. In those cases, telling the compiler - * what is used, can have a significant impact. - * - * Example usage: - * - * @MirrorsUsed(symbols: 'foo') - * import 'dart:mirrors'; - * - * class Foo { - * noSuchMethod(Invocation invocation) { - * print(MirrorSystem.getName(invocation.memberName)); - * } - * } - * - * main() { - * new Foo().foo(); // Prints "foo". - * new Foo().bar(); // Might print an arbitrary (mangled) name, "bar". - * } - * - * For a detailed description of the parameters to the [MirrorsUsed] constructor - * see the comments for [symbols], [targets], [metaTargets] and [override]. - * - * An import of `dart:mirrors` may have multiple [MirrorsUsed] annotations. This - * is particularly helpful to specify overrides for specific libraries. For - * example: - * - * @MirrorsUsed(targets: 'foo.Bar', override: 'foo') - * @MirrorsUsed(targets: 'Bar') - * import 'dart:mirrors'; - * - * will ensure that the target `Bar` from the current library and from library - * `foo` is available for reflection. See also [override]. - */ -@Deprecated("No longer has any effect. Will be removed in a later release.") -class MirrorsUsed { - // Note: the fields of this class are untyped. This is because the most - // convenient way to specify symbols today is using a single string. In - // some cases, a const list of classes might be convenient. Some - // might prefer to use a const list of symbols. - - /** - * The list of strings passed to new [Symbol], and symbols that might be - * passed to [MirrorSystem.getName]. - * - * Combined with the names of [targets], [metaTargets] and their members, - * this forms the complete list of strings passed to new [Symbol], and - * symbols that might be passed to [MirrorSystem.getName] by the library to - * which this metadata applies. - * - * The following text is non-normative: - * - * Dart2js currently supports the following formats to specify symbols: - * - * * A constant [List] of [String] constants representing symbol names, - * e.g., `const ['foo', 'bar']`. - * * A single [String] constant whose value is a comma-separated list of - * symbol names, e.g., `"foo, bar"`. - * - * Specifying the `symbols` field turns off the following warnings emitted by - * dart2js: - * - * * Using "MirrorSystem.getName" may result in larger output. - * * Using "new Symbol" may result in larger output. - * - * For example, if you're using [noSuchMethod] to interact with a database, - * extract all the possible column names and include them in this list. - * Similarly, if you're using [noSuchMethod] to interact with another - * language (JavaScript, for example) extract all the identifiers from the - * API you use and include them in this list. - * - * Note that specifying a symbol only ensures that the symbol will be - * available under that name at runtime. It does not mark targets with - * that name as available for reflection. See [targets] and [metaTargets] - * for that purpose. - */ - final symbols; - - /** - * A list of reflective targets. - * - * Combined with [metaTargets], this provides the complete list of reflective - * targets used by the library to which this metadata applies. - * - * The following text is non-normative: - * - * For now, there is no formal description of what a reflective target is. - * Informally, a target is a library, a class, a method or a field. - * - * Dart2js currently supports the following formats to specify targets: - * - * * A constant [List] containing [String] constants representing (qualified) - * names of targets and Dart types. - * * A single [String] constant whose value is a comma-separated list of - * (qualified) names. - * * A single Dart type. - * - * A (qualified) name is resolved to a target as follows: - * - * 1. If the qualified name matches a library name, the matching library is - * the target. - * 2. Else, find the longest prefix of the name such that the prefix ends - * just before a `.` and is a library name. - * 3. Use that library as current scope. If no matching prefix was found, use - * the current library, i.e., the library where the [MirrorsUsed] - * annotation was placed. - * 4. Split the remaining suffix (the entire name if no library name was - * found in step 3) into a list of [String] using `.` as a - * separator. - * 5. Select all targets in the current scope whose name matches a [String] - * from the list. - * - * For example: - * - * library my.library.one; - * - * class A { - * var aField; - * } - * - * library main; - * - * @MirrorsUsed(targets: "my.library.one.A.aField") - * import "dart:mirrors"; - * - * The [MirrorsUsed] annotation specifies `A` and `aField` from library - * `my.library.one` as targets. This will mark the class `A` as a reflective - * target. The target specification for `aField` has no effect, as there is - * no target in `my.library.one` with that name. - * - * Note that everything within a target also is available for reflection. - * So, if a library is specified as target, all classes in that library - * become targets for reflection. Likewise, if a class is a target, all - * its methods and fields become targets for reflection. As a consequence, - * `aField` in the above example is also a reflective target. - * - */ - final targets; - - /** - * A list of classes that when used as metadata indicates a reflective - * target. See also [targets]. - * - * The following text is non-normative: - * - * The format for specifying the list of classes is the same as used for - * specifying [targets]. However, as a library cannot be used as a metadata - * annotation in Dart, adding a library to the list of [metaTargets] has no - * effect. In particular, adding a library to [metaTargets] does not make - * the library's classes valid metadata annotations to enable reflection. - * - * If an instance of a class specified in [metaTargets] is used as - * metadata annotation on a library, class, field or method, that library, - * class, field or method is added to the set of targets for reflection. - * - * Example usage: - * - * library example; - * @MirrorsUsed(metaTargets: "example.Reflectable") - * import "dart:mirrors"; - * - * class Reflectable { - * const Reflectable(); - * } - * - * class Foo { - * @Reflectable() - * reflectableMethod() { ... } - * - * nonReflectableMethod() { ... } - * } - * - * In the above example. `reflectableMethod` is marked as reflectable by - * using the `Reflectable` class, which in turn is specified in the - * [metaTargets] annotation. - * - * The method `nonReflectableMethod` lacks a metadata annotation and thus - * will not be reflectable at runtime. - */ - final metaTargets; - - /** - * A list of library names or "*". - * - * When used as metadata on an import of "dart:mirrors", this metadata does - * not apply to the library in which the annotation is used, but instead - * applies to the other libraries (all libraries if "*" is used). - * - * The following text is non-normative: - * - * Dart2js currently supports the following formats to specify libraries: - * - * * A constant [List] containing [String] constants representing names of - * libraries. - * * A single [String] constant whose value is a comma-separated list of - * library names. - * - * Conceptually, a [MirrorsUsed] annotation with [override] has the same - * effect as placing the annotation directly on the import of `dart:mirrors` - * in each of the referenced libraries. Thus, if the library had no - * [MirrorsUsed] annotation before, its unconditional import of - * `dart:mirrors` is overridden by an annotated import. - * - * Note that, like multiple explicit [MirrorsUsed] annotations, using - * override on a library with an existing [MirrorsUsed] annotation is - * additive. That is, the overall set of reflective targets is the union - * of the reflective targets that arise from the original and the - * overriding [MirrorsUsed] annotations. - * - * The use of [override] is only meaningful for libraries that have an - * import of `dart:mirrors` without annotation because otherwise it would - * work exactly the same way without the [override] parameter. - * - * While the annotation will apply to the given target libraries, the - * [symbols], [targets] and [metaTargets] are still evaluated in the - * scope of the annotation. Thus, to select a target from library `foo`, - * a qualified name has to be used or, if the target is visible in the - * current scope, its type may be referenced. - * - * For example, the following code marks all targets in the library `foo` - * as reflectable that have a metadata annotation using the `Reflectable` - * class from the same library. - * - * @MirrorsUsed(metaTargets: "foo.Reflectable", override: "foo") - * - * However, the following code would require the use of the `Reflectable` - * class from the current library, instead. - * - * @MirrorsUsed(metaTargets: "Reflectable", override: "foo") - * - */ - final override; - - /** - * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], - * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation - * of the parameters. - */ - const MirrorsUsed( - {this.symbols, this.targets, this.metaTargets, this.override}); -}