reflectable 4.0.12

Reflection support based on code generation, using 'capabilities' to specify which operations to support, on which objects.

Reflectable

A listing of known limitations is given at the end of this page.

Introduction

This package provides support for reflection which may be tailored to cover certain reflective features and omit others, thus reducing the resource requirements at run time.

The core idea is that the desired level of support for reflection is specified explicitly and statically, and any usage of reflection at run time must stay within the boundaries thus specified; otherwise a NoSuchCapabilityError is thrown. In return for statically confining the required reflection support, programs can be smaller. Other than that, using this package and using dart:mirrors is very similar.

The core concept in the reflection support specification is that of a reflectable capability. For a more detailed discussion about capabilities, please consult the reflectable capability design document. On this page we just use a couple of simple special cases.

This package uses code generation to provide support for reflection at the level which is specified using capabilities. The build package is used to manage the code generation, and a major part of this package is concerned with generating that code. It is specified which programs to transform, and certain elements in the program itself are used to decide how to transform it. As a result, the transformed program will contain generated code providing the requested level of support for reflection.

The use of dynamic reflection is supported if and only if the usage is covered by the set of capabilities specified.

In general, reflection is provided via a subclass of the class Reflectable (we use the term reflector to designate an instance of such a subclass).

class Reflector extends Reflectable {
  const Reflector() : super(capability1, capability2, ...);
}

Reflection is disabled by default, and it is enabled by specifying reflectable capabilities. With Reflector we have specified that capability1, capability2, and so on must be supported. The main case for using this is annotating a given class A with a reflector. This implies that the specified level of reflection support for that reflector should be provided for the class A and its instances.

@Reflector()
class A {
  ...
}

Only classes covered by a reflector R and their instances can be accessed reflectively using R, and that access is constrained by the capabilities passed as the superinitializer in the class of R. The basic case is when R is used as an annotation of a given class (as is the case with A above), but a class C can also be covered by a reflector R because a supertype A of C is annotated by a reflector which specifies that subtypes of A are covered. There are several other indirect mechanisms in addition to subtype based coverage, as described in the capability design document.

As a result, the available universe of reflection related operations is so well-known at compile time that it is possible to specialize the support for reflection to a purely static form that satisfies the requirements of the given annotations and capabilities.

Usage

Here is a simple usage example. Assume that we have the following code in the file web/main.dart:

import 'package:reflectable/reflectable.dart';
import 'main.reflectable.dart'; // Import generated code.

// Annotate with this class to enable reflection.
class Reflector extends Reflectable {
  const Reflector()
      : super(invokingCapability); // Request the capability to invoke methods.
}

const reflector = const Reflector();

@reflector // This annotation enables reflection on A.
class A {
  final int a;
  A(this.a);
  greater(int x) => x > a;
  lessEqual(int x) => x <= a;
}

main() {
  initializeReflectable(); // Set up reflection support.
  A x = new A(10);
  // Reflect upon [x] using the const instance of the reflector:
  InstanceMirror instanceMirror = reflector.reflect(x);
  int weekday = new DateTime.now().weekday;
  // On Fridays we test if 3 is greater than 10, on other days if it is less
  // than or equal.
  String methodName = weekday == DateTime.FRIDAY ? "greater" : "lessEqual";
  // Reflectable invocation:
  print(instanceMirror.invoke(methodName, [3]));
}

It is necessary to import the generated code, which is stored in a library whose file name is obtained by taking the file name of the main library of the program and adding .reflectable. In the example, this amounts to import 'main.reflectable.dart'.

Note that it is not recommended to publish generated code, i.e., published packages on pub.dev should not include files whose name is of the form *.reflectable.dart. The reason for this is that the generated code may change because some direct or indirect dependency changes (say, your package indirectly imports package path and then path changes), and this could make some generated code invalid.

It is also necessary to initialize the reflection support by calling initializeReflectable(), as shown at the beginning of main in the example.

You also need to add the following dependency to your 'pubspec.yaml':

dependencies:
  reflectable: any

You may also wish to specify constraints on the version, depending on the approach to version management that your software otherwise employs.

The root of your library may need to contain a file build.yaml which will specify how to run the code generation step. For an example of how to write this file, please consult test_reflectable/build.yaml and the general documentation about package build.

In order to generate code you will need to run the following command from the root directory of your package:

> pub run build_runner build DIR

where DIR should be replaced by a relative path that specifies the directory where the entry point(s) are located, that is, the main file(s) for the program(s) that you wish to generate code for. In the example where we have an entry point at web/myProgram.dart the command would be as follows:

> pub run build_runner build web

You may appreciate the following shortcut command which will work when you wish to generate code for entry points in the test subdirectory and also run the tests (given that the tests are written using package test):

> pub run build_runner test

This approach (using pub run build_runner ...) includes support for incremental code generation, that is, it offers shorter execution times for the code generation step because strives to only generate code that relies on something that changed. This is the recommended approach.

However, if you have a complex setup then you may wish to study the packages build, build_runner, etc. in order to learn more about how to control the build process in more detail.

To give a hint about a more low-level approach, you may choose to write a tiny Dart program which imports the actual builder, and run the build process from there, rather than using pub run build_runner .... This will give you more control, but also more ways to shoot yourself in the foot.

Here's an example which shows how to get started. The code of such a builder program can be as concise as the following:

import 'package:reflectable/reflectable_builder.dart' as builder;

main(List<String> arguments) async {
  await builder.reflectableBuild(arguments);
}

You may now run the code generation step with the root of your package as the current directory:

> dart tool/builder.dart web/myProgram.dart

where web/myProgram.dart should be replaced by a path that specifies the entry point(s) for which you wish to generate code. For a set of test files in test, this would typically be tool/builder.dart test/*_test.dart.

It should be noted that you need to generate code for the same set of entry points every time you run builder.dart. This is because the build framework stores data about the code generation in a single database in the directory .dart_tool, so you will get complaints about inconsistencies if you switch from generating code for web/myProgram.dart to generating code for web/myOtherProgram.dart. If and when you need to generate code for another set of programs, delete all files named *.reflectable.dart, and delete the whole directory .dart_tool.

Again, the approach where you are using your own builder.dart to generate the code is more flexible, but the recommended standard approach is to use pub run build_runner ....

Note that it is necessary to perform the code generation step if you use reflectable directly or indirectly by depending on a package that uses reflectable. Even in the indirect case there may (typically will!) be a need to generate code based on files in your package.

Conversely, if you are writing a package which uses reflectable and is expected to be used by clients, please make it explicit that such clients must run this step in order to obtain the generated code for each root library.

The generated file contains the data needed for reflection, and a declaration of the top-level function initializeReflectable, which will initialize the reflection framework and which must be called before any reflective features are used.

For a more advanced example, you could look at serialize_test.dart and its library, where the base of a serialization framework is implemented; or you could look at meta_reflectors_test.dart and the libraries it imports, which illustrates how reflectable can be used to dynamically make a choice among several kinds of reflection, and how to eliminate several kinds of static dependencies among libraries.

Known limitations

Several parts of the library have not yet been implemented. In particular, the following parts are still incomplete:

• Reflection on functions/closures. We do not have the required primitives to support this feature, so it is expected to remain unsupported for a while. There is support for one case: When a function type is given a name with typedef it is possible to use that name as a type annotation, say, on a method parameter or as a return type, and then reflectedTypeCapability will make it possible to get a corresponding reflectedType and dynamicReflectedType. For non-generic function types this will also work with anonymous (inline) function types like void Function(int).

• Private declarations. There is currently almost no support for reflection on private declarations, as this would require special support from the runtime for accessing private names from other libraries. As an example of a case where there is some support, library mirrors can deliver class mirrors for private classes, and instanceMembers includes public members inherited from private superclasses. But in the vast majority of situations, private declarations are not supported.

• uri's of libraries. The transformer framework does not give us access to good uri's of libraries, so these are currently only partially supported: A unique uri containing the name given in the library directive (if any) is generated for each library; this means that equality tests will work, and the toString() of a uri will be somewhat human readable. But this kind of uri does not give any information about the location of a corresponding file on disk.

• Type arguments of generic types are only supported in some statically resolved cases, because we do not have the primitives required for a general implementation. E.g., when it is known statically that a given list of actual type arguments is empty then the empty list is returned. Moreover, if a type annotation contains only types which are fully resolved statically, it is possible to get these type arguments, as mirrors or as instances of Type using various reflected type features. An example is shown below.

• The mirror method libraryDependencies has not yet been implemented.

Here is an example illustrating the partial support for type arguments:

class Reflector extends Reflectable {
  const Reflector()
      : super(invokingCapability, typingCapability, reflectedTypeCapability);
}

const reflector = Reflector();

@reflector
class A<X> {
  A<B> ab;
  A<X> ax;
}

@reflector
class B {}

main() {
  initializeReflectable();
  ClassMirror aMirror = reflector.reflectType(A);
  final declarations = aMirror.declarations;
  VariableMirror abMirror = declarations['ab'];
  VariableMirror axMirror = declarations['ax'];
  print(abMirror.type.typeArguments[0].reflectedType); // Prints 'B'.
  print(abMirror.type.reflectedTypeArguments[0] == B); // Prints 'true'.
  try {
    print(axMirror.type.typeArguments[0]); // Throws 'UnimplementedError'.
    print("Not reached");
  } on UnimplementedError catch (_) {
    print("As expected: Could not get type mirror for type argument.");
  }
  try {
    axMirror.type.reflectedTypeArguments[0]; // Throws 'UnimplementedError'.
    print("Not reached");
  } on UnimplementedError catch (_) {
    print("As expected: Could not get reflected type argument.");
  }
}

// Output:
//   B
//   true
//   As expected: Could not get type mirror for type argument.
//   As expected: Could not get reflected type argument.

As the example above illustrates, we can invoke reflectedTypeArguments on the mirror of the type annotation of ai and get <Type>[int], because that type argument list is statically resolved, but we cannot do it with ax because X will have different values at different occasions at run time (that is, it is not fully resolved statically).

Similarly, it is not supported to obtain the actual type arguments for an existing instance; e.g., if we have an expression of type Iterable then we may evaluate it and get an instance x of List<int>. We can test x is List<num> and get true, and we can get false for x is List<double>, but we cannot directly extract the type argument (int) using reflection. That is because it can only be done with support for some primitives (that is, built-in operations with special powers) that do not exist today.

Feature requests and bug reports

Please file feature requests and bugs using the github issue tracker for this repository.