capability library

Provides the classes and constants used for configuring the capabilities of a reflector (an instance of a subclass of Reflectable).

The subclasses of ReflectCapability can be used to describe the classes and methods that are covered by a reflector, and what queries are allowed.

The goal is to be able to describe as precisely as possible what the reflector needs to "know", so only the minimal amount of support code has to be generated.

In general the semantics are additive --- meaning that adding a capability will only allow more reflection --- and commutative, so the order of the capabilities does not matter.

Most of the member-specifying capabilities exist in a version using a String denoting a RegExp to match member names, and in a version taking a Type, and matching all members with a metadata annotation of that type or a subtype thereof.

For example InstanceInvokeCapability(r'^foo') will cover all instance members of annotated classes that start with 'foo'. InstanceInvokeMetaCapability(Deprecated) would cover all instance members that are marked as Deprecated.

Hint: It is important to realize that the amount of generated code might not be what will have the biggest impact on the amount of code generated by the compilation to JavaScript, because it is dominated by code that it prevents from being tree-shaken away. And especially the set of instance-methods will generate closures that invoke that method on any target, thus preventing dart2js from removing any method with that name of any instantiated class.

More details can be found in the design document about this library.

Classes

ApiReflectCapability
Abstract superclass of all capabilities concerned with the request for reflective support for a certain part of the mirror class APIs, as opposed to the second order capabilities which are used to associate these API based capabilities with a certain set of potential reflectees.
DeclarationsCapability
Gives support for: declarations, instanceMembers, staticMembers, callMethod, parameters, and defaultValue.
GlobalQuantifyCapability
Gives reflection support in reflector for every class in the program whose qualified name matches the given classNamePattern considered as a regular expression.
GlobalQuantifyMetaCapability
Gives reflection support in reflector for every class in the program whose metadata includes instances of metadataType or a subtype thereof.
ImportAttachedCapability
Abstract superclass for all capabilities which are used to specify that a given reflector must be considered to be applied as metadata to a set of targets. Note that in order to work correctly, this kind of capability can only be used as metadata on an import of 'package:reflectable/reflectable.dart'.
InstanceInvokeCapability
Gives support for reflective invocation of instance members (methods, getters, and setters) matching namePattern interpreted as a regular expression.
InstanceInvokeMetaCapability
Gives support for reflective invocation of instance members (methods, getters, and setters) annotated with instances of metadataType or a subtype thereof.
InvokingCapability
Gives all the capabilities of InstanceInvokeCapability, StaticInvokeCapability, and NewInstanceCapability.
InvokingMetaCapability
Gives the capabilities of all the capabilities requested by InstanceInvokeMetaCapability, StaticInvokeMetaCapability, and NewInstanceMetaCapability.
LibraryCapability
Gives support for library-mirrors.
LibraryDependenciesCapability
Gives support for: sourceLibrary, targetLibrary, prefix, and combinators.
MetadataCapability
Gives support for reflective access to metadata associated with a declaration reflected by a given declaration mirror.
MetadataQuantifiedCapability
Abstract superclass of all capability classes recognizing a particular instance used as metadata as a criterion for providing the annotated declaration with reflection support. Note that there are no constraints on the type of metadata, i.e., it could be metadata which is already used for other purposes related to other packages, but which happens to occur in just the right locations.
NamePatternCapability
Abstract superclass of all capability classes using a regular expression to match names of behaviors (such as methods and constructors).
NewInstanceCapability
Gives support for reflective invocation of constructors (of all kinds) matching namePattern interpreted as a regular expression.
NewInstanceMetaCapability
Gives support for reflective invocation of constructors (of all kinds) annotated by instances of metadataType or a subtype thereof.
ReflectCapability
A ReflectCapability of a reflectable mirror specifies the kinds of reflective operations that are supported for instances of the associated classes.
ReflecteeQuantifyCapability
Abstract superclass for all capability classes supporting quantification over the set of potential reflectees.
StaticInvokeCapability
Gives support for reflective invocation of static members (static methods, getters, and setters) matching namePattern interpreted as a regular expression.
StaticInvokeMetaCapability
Gives support for reflective invocation of static members (static methods, getters, and setters) that are annotated with instances of metadataType or a subtype thereof.
SuperclassQuantifyCapability
Gives support for reflection on all superclasses of covered classes up to upperBound
TopLevelInvokeCapability
Gives support for reflective invocation of top-level members (top-level methods, getters, and setters) matching namePattern interpreted as a regular expression.
TopLevelInvokeMetaCapability
Gives support for reflective invocation of top-level members (top-level methods, getters, and setters) that are annotated with instances of metadataType.
TypeAnnotationQuantifyCapability
Gives support for reflecting on the classes used as type annotations of covered methods, parameters and fields. If transitive is true the support also extends to annotations of their methods, parameters and fields etc.
TypeCapability
Gives support for invocation of the method reflectType on reflectors, and for invocation of the method type on instances of InstanceMirror and ParameterMirror as well as the method returnType on instances of MethodMirror.
TypeRelationsCapability
Gives support for: typeVariables, typeArguments, originalDeclaration, isSubtypeOf, isAssignableTo, superclass, superinterfaces, mixin, isSubclassOf, upperBound, and referent.
TypingCapability
Gives the capabilities of TypeCapability, metadataCapability, typeRelationsCapability, declarationsCapability, uriCapability, and libraryDependenciesCapability.
UriCapability
Gives support for the mirror method uri on LibraryMirrors.

Constants

admitSubtypeCapability → const _AdmitSubtypeCapability
Gives support for calling .reflect on subtypes of covered instances.
correspondingSetterQuantifyCapability → const _CorrespondingSetterQuantifyCapability
Quantifying capability instance specifying that the reflection support for any given explicitly declared getter must also be given to its corresponding explicitly declared setter, if any.
declarationsCapability → const DeclarationsCapability
Shorthand for const DeclarationsCapability().
delegateCapability → const _DelegateCapability
Capability instance giving support for the delegate method on instance mirrors when it leads to invocation of a method where instance invocation is supported. Also implies support for translation of Symbols of covered members to their corresponding Strings.
instanceInvokeCapability → const InstanceInvokeCapability
Short hand for InstanceInvokeCapability(''), meaning the capability to reflect over all instance members.
invokingCapability → const InvokingCapability
Short hand for InvokingCapability('').
libraryCapability → const LibraryCapability
Shorthand for const LibraryCapability().
libraryDependenciesCapability → const LibraryDependenciesCapability
Shorthand for const LibraryDependenciesCapability().
metadataCapability → const MetadataCapability
Shorthand for const MetadataCapability().
newInstanceCapability → const NewInstanceCapability
Short hand for const NewInstanceCapability(''), meaning the capability to reflect over all constructors.
reflectedTypeCapability → const _ReflectedTypeCapability
Gives support for the method reflectedType on VariableMirror and ParameterMirror, and for the method reflectedReturnType on MethodMirror.
staticInvokeCapability → const StaticInvokeCapability
Short hand for StaticInvokeCapability(''), meaning the capability to reflect over all static members.
subtypeQuantifyCapability → const _SubtypeQuantifyCapability
Quantifying capability instance specifying that the reflection support covers all subclasses of annotated classes and classes matching global quantifiers.
superclassQuantifyCapability → const SuperclassQuantifyCapability
Gives support for reflection on all superclasses of covered classes.
topLevelInvokeCapability → const TopLevelInvokeCapability
Short hand for TopLevelInvokeCapability(''), meaning the capability to reflect over all top-level members.
typeAnnotationDeepQuantifyCapability → const TypeAnnotationQuantifyCapability
Gives support for reflecting on the full closure of type annotations of covered methods/parameters.
typeAnnotationQuantifyCapability → const TypeAnnotationQuantifyCapability
Gives support for reflecting on the classes used as type annotations of covered methods, parameters and fields.
typeCapability → const TypeCapability
Shorthand for const TypeCapability().
typeRelationsCapability → const TypeRelationsCapability
Shorthand for const TypeRelationsCapability().
typingCapability → const TypingCapability
Shorthand for const TypingCapability().
uriCapability → const UriCapability
Shorthand for const UriCapability().

Functions

reflectableNoSuchConstructorError(Object? receiver, String constructorName, List positionalArguments, Map<Symbol, dynamic>? namedArguments) → dynamic
reflectableNoSuchGetterError(Object? receiver, String memberName, List positionalArguments, Map<Symbol, dynamic>? namedArguments) → dynamic
reflectableNoSuchInvokableError(Object? receiver, String memberName, List positionalArguments, Map<Symbol, dynamic>? namedArguments, StringInvocationKind kind) → dynamic
reflectableNoSuchMethodError(Object? receiver, String memberName, List positionalArguments, Map<Symbol, dynamic>? namedArguments) → dynamic
reflectableNoSuchSetterError(Object? receiver, String memberName, List positionalArguments, Map<Symbol, dynamic>? namedArguments) → dynamic

Exceptions / Errors

NoSuchCapabilityError
Thrown when reflection is invoked without sufficient capabilities.
ReflectableNoSuchMethodError
Thrown when a method is invoked via a reflectable, but the reflectable doesn't have the capabilities to invoke it.