languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-10-01 17:41:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove unsupported APIs in dart:mirrors

Browse source 
Contributes to bug: https://github.com/dart-lang/sdk/issues/34233
Fixes https://github.com/dart-lang/sdk/issues/32507

Change-Id: Iee72e9f91fc1fc49761e6f5e6e9dba412493c8ef
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/248003
Reviewed-by: Siva Annamalai <asiva@google.com>
Commit-Queue: Michael Thomsen <mit@google.com>
Reviewed-by: Ryan Macnak <rmacnak@google.com>
This commit is contained in:
Michael Thomsen 2022-07-20 18:28:35 +00:00 committed by Commit Bot
parent 54d3d7e459
commit e84412af45
4 changed files with 13 additions and 294 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
CHANGELOG.md
View file

@ -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

7
pkg/compiler/README.md
View file

@ -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.

3
sdk/lib/_internal/js_runtime/lib/js_helper.dart
View file

@ -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

285
sdk/lib/mirrors/mirrors.dart
View file

@ -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});
}