esDotDev
commented
3 years ago This is really cool, I appreciate the lack of magic, and the highly readable code.
It looks like it would be quite easy to support some special cases in auto-dispose as well, like:
// Usage
@shouldDispose(useCancel: true)
Timer timer = Timer();
...
// Macro
String getDisposeMethodForType(Type type){
if(type is Timer || type is StreamSubscription || useCancel) return "cancel";
return "dispose";
}
...
if (field.annotation is ShouldDispose){
"${field.name}.${getMethodForType(field.type)}();",
}This example could also be made more realworld if it supports null aware operators. It should write out controller?.dispose() if it's nullable, controller.dispose() otherwise.
Another thing to consider is how refactoring will work. If I re-factor MyButton via IDE, would the "MyButton" string be updated somehow?
It might be nicer for maintainability if a prefix-system were used here, like:
@WidgetCreator()
Widget createMyButton(){ // Some error could occur if create is not the prefix here
ElevatedButton(
child: Text(""),
onPressed: () {},
);
}Where MyButton portion is a contract, that updates when either createMyButton or MyButton is renamed.
cedvdb
Levi-Lesches
themisir
Jonas-Sander
renggli
lrhn
ChristianKleineidam
bwilkerson
This is my second draft of a proposal for code generation ("code gen" from now on) through specialized classes called "macros". The issue where this is being discussed is #1482 and my first proposal is #1507.
The key idea for me in code generation is that generated code should function exactly as though it were written by hand. This means that code gen should be strictly an implementation detail -- invisible to others who import your code. This further strengthens the need for code gen to be simple and expressive, so that any code that could be written by hand can be replaced by code gen, and vice-versa.
Another critical point is that code generation should not modify user-written code in any way. For this reason,
partandpart ofare used to separate the human-written code from the generated. Partial classes (#252) help facilitate this, and this proposal heavily relies on them.Definition of a macro
A macro is a class that's responsible for generating code. You can make a macro by extending the built-in
Macrosuperclass. There are two types of macros: those that augment classes, and those that generate top-level code from functions. TheMacroclass consists of thegeneratefunction and some helpful reflection getters. The base definition of a macro is as follows:Here are class-based and function-based macros, with
Variablerepresenting basic reflection.
```dart /// A example of how reflection will be used. /// /// This class applies to both parameters and fields. class VariableVariable
```dart /// A macro that is applied to a class. /// /// Generated code goes in a partial class with the same name as the source. abstract class ClassMacro extends Macro { const ClassMacro(); /// Fields with their respective types. ListClassMacro
```dart /// A macro that is applied to a function. /// /// Generates top-level code since functions can't be augmented. If you want /// to wrap a function, do it using regular Dart. abstract class FunctionMacro { const FunctionMacro(); /// The body of the function. /// /// => can be desugared into a "return" statement String get functionBody => ""; /// The positional parameters of the function. ListFunctionMacroThat being said, I'm not an expert on reflection so this is not really the focus of this proposal. I do know enough to know that `dart:mirrors` cannot be used, since it is exclusively for runtime. We want something more like [the `analyzer` package](https://pub.dev/packages/analyzer), which can statically analyze code without running it. Again, the point is that code gen should work exactly like a human would, and the analyzer can be thought of as a second pair of eyes (as opposed to `dart:mirrors` which is a different idea entirely). Depending on how reflection is implemented, we may need to restrict subclasses of `Macro`, since that's where all the initialization happens. ## Using macros To create a macro, simply extend `ClassMacro` or `FunctionMacro` and override the `generate` function. All macros will output code into a `.g.dart` file. The code generated by a `ClassMacro` will go in a partial class, whereas the code generated by a `FunctionMacro` will be top-level. Because the function outputs a String, `List
JSON serialization
```dart // to_json.dart import "dart:code_gen"; /// Generates a [fromJson] constructor and a [json] getter. class JsonHelper extends ClassMacro { const JsonHelper(); /// Adds a Foo.fromJson constructor. String fromJson() => [ "$sourceName.fromJson(MapDataclass methods
```dart import "dart:code_gen"; /// Generates [==], [hashCode], [toString()], and [copyWith]. class Dataclass extends ClassMacro { const Dataclass(); /// The famous copyWith method String copyWith() => [ "$sourceName copyWith({", for (final Variable field in fields) "${field.type}? ${field.name},", "}) => $sourceName(", for (final String field in fieldNames) "$field: $field ?? this.$field,", ");" ].join("\n"); /// Overrides the == operator to check if each field is equal String equals() => [ "@override", "bool operator ==(Object other) => other is $sourceName", for (final String field in fieldNames) "&& $field == other.$field", ";" ].join("\n"); /// Implements a hash code based on [toString()]. /// /// You can use more complex logic, but this is my simple version. It also /// shows that standard functions can be generated with macros. /// /// Make sure this is interpreted as [Macro.hash], not [Object.hashCode]. String hash() => "@override\n" "int get hashCode => toString().hashCode;"; /// Implements [toString()] by printing each field and the class name. /// /// Don't name it toString() String string() => [ "@override", 'String toString() => "$sourceName("', for (final String field in fieldNames) '"$field = \$$field, "', '")";' ].join("\n"); @override String generate() => [ equals(), hash(), string(), copyWith(), ].join("\n"); } ``` ```dart // person.dart import "dataclass.dart"; part "person.g.dart"; @Dataclass() partial class Person { final String name; final int age; const Person({required this.name, required this.age}); } void main() { Person alice = Person(name: "Alice", age: 42); print(alice.hashCode); print(alice.toString()); final Person alice2 = alice.copyWith(); final Person bob = alice.copyWith(name: "Bob"); if (alice == alice2 && alice != bob) { print("Equals operator works"); } } ``` ```dart // person.g.dart part of "person.dart"; partial class Person { @override bool operator ==(Object other) => other is Person && name == other.name && age == other.age; @override int get hashCode => toString().hashCode; @override String toString() => "Person(" "name = $name, " "age = $age, " ")"; Person copyWith({ String? name, int? age }) => Person( name: name ?? this.name, age: age ?? this.age, ); } ```Auto-dispose
```dart // disposer.dart import "dart:code_gen.dart"; /// An annotation to mark that a class should be disposed. class ShouldDispose { const ShouldDispose(); } const shouldDispose = ShouldDispose(); /// Calls .dispose on all fields with the [ShouldDispose] annotation. class Disposer extends ClassMacro { const Disposer(); @override String generate() => [ "@override", "void dispose() {", for (final Variable field in fields) if (field.annotation is ShouldDispose) "${field.name}.dispose();", "super.dispose();", "}", ].join("\n"); } ``` ```dart // widget.dart import "disposer.dart"; part "widget.g.dart"; // <-- injected by code gen class MyWidget extends StatefulWidget { @override MyState createState() => MyState(); } @Disposer() partial class MyState extends StateFunctional Widgets
```dart // stateless_widget.dart import "dart:code_gen"; /// Creates a StatelessWidget based on a function and its parameters. /// /// This macro will generate the widget with the name [widgetName]. class WidgetCreator extends FunctionMacro { final String widgetName; const WidgetCreator({required this.widgetName}); @override String generate() => [ // because FunctionMacro generates top-level code, we can create a class "class $widgetName extends StatelessWidget {", // The fields: for (final Variable parameter in allParameters) "final ${parameter.type} ${parameter.name};", // The constructor: "const $widgetName({", for (final Variable parameter in allParameters) "required this.${parameter.name}", "});", // The build method: "@override", "Widget build(BuildContext context) {$functionBody}", "}" ].join("\n"); } ``` ```dart // widget.dart import "stateless_widget.dart"; part "widget.g.dart"; @WidgetCreator(widgetName: "MyButton") Widget buildButton() => ElevatedButton( child: Text(""), onPressed: () {}, ); void main() => runApp( MaterialApp( home: Scaffold( body: MyButton(title: "Fancy title") ) ) ); ``` ```dart // widget.g.dart part of "widget.dart"; // Notice how this is not a partial class, but rather a regular class class MyButton extends StatelessWidget { final String title; const MyButton({required this.title}); @override Widget build(BuildContext context) { // Notice how the => was desugared. return ElevatedButton( child: Text(title), onPressed: () {}, ); } } ```