initialize 0.3.1+1 initialize: ^0.3.1+1 copied to clipboard
Generic building blocks for doing static initialization.
Initialize #
This package provides a common interface for initialization annotations on top level methods, classes, and libraries. The interface looks like this:
abstract class Initializer<T> {
dynamic initialize(T target);
}
The initialize
method will be called once for each annotation. The type T
is
determined by what was annotated. For libraries it will be the Symbol
representing that library, for a class it will be the Type representing that
class, and for a top level method it will be the Function object representing
that method.
If a future is returned from the initialize method, it will wait until the future completes before running the next initializer.
Usage #
@initMethod #
Ther is one initializer which comes with this package, @initMethod
. Annotate
any top level function with this and it will be invoked automatically. For
example, the program below will print hello
:
import 'package:initialize/initialize.dart';
@initMethod
printHello() => print('hello');
main() => run();
Running the initializers #
In order to run all the initializers, you need to import
package:initialize/initialize.dart
and invoke the run
method. This should
typically be the first thing to happen in your main. That method returns a Future,
so you should put the remainder of your program inside the chained then call.
import 'package:initialize/initialize.dart';
main() {
run().then((_) {
print('hello world!');
});
}
Transformer #
During development a mirror based system is used to find and run the initializers, but for deployment there is a transformer which can replace that with a static list of initializers to be ran.
This will create a new entry point which bootstraps your existing app. If you
supply an html_entry_point
then any script tags whose src is the same as
entry_point
will be rewritten to the bootstrapped file new_entry_point
.
Below is an example pubspec with the transformer:
name: my_app
dependencies:
initialize: any
transformers:
- initialize:
entry_point: web/index.dart
new_entry_point: web/index.bootstrap.dart
html_entry_point: web/index.html
Creating your own initializer #
Lets look at a slightly simplified version of the @initMethod
class:
class InitMethod implements Initializer<Function> {
const InitMethod();
@override
initialize(Function method) => method();
}
You would now be able to add @InitMethod()
in front of any function and it
will be automatically invoked when the user calls run()
.
For classes which are stateless, you can usually just have a single const instance, and that is how the actual InitMethod implementation works. Simply add something like the following:
const initMethod = const InitMethod();
Now when people use the annotation, it just looks like @initMethod
without any
parenthesis, and its a bit more efficient since there is a single instance. You
can also make your class private to force users into using the static instance.