@@ -12,8 +12,7 @@ being recorded.
1212- If placed on a static method, the annotation means that arguments passed to
1313the method will be recorded, as far as they can be inferred at compile time.
1414- If placed on a class with a constant constructor, the annotation means that
15- any constant instance of the class will be recorded. This is particularly useful
16- when using the class as an annotation.
15+ any constant instance of the class will be recorded.
1716
1817> [ !NOTE]
1918> The ` @RecordUse ` annotation is only allowed on definitions within a package's
@@ -22,102 +21,62 @@ when using the class as an annotation.
2221
2322## Example
2423
24+ <!-- file://./example/api/usage.dart#usage -->
2525``` dart
26- import 'package:meta/meta.dart' show RecordUse;
27-
2826void main() {
29- print(SomeClass.stringMetadata(42));
30- print(SomeClass.doubleMetadata(42));
31- print(SomeClass.intMetadata(42));
32- print(SomeClass.boolMetadata(42));
27+ PirateTranslator.speak('Hello');
28+ print(const PirateShip('Black Pearl', 50));
3329}
3430
35- class SomeClass {
36- @RecordMetadata('leroyjenkins')
37- @RecordUse()
38- static stringMetadata(int i) {
39- return i + 1;
40- }
41-
42- @RecordMetadata(3.14)
43- @RecordUse()
44- static doubleMetadata(int i) {
45- return i + 1;
46- }
47-
48- @RecordMetadata(42)
49- @RecordUse()
50- static intMetadata(int i) {
51- return i + 1;
52- }
53-
54- @RecordMetadata(true)
31+ abstract class PirateTranslator {
5532 @RecordUse()
56- static boolMetadata(int i) {
57- return i + 1;
58- }
33+ static String speak(String english) => 'Ahoy $english';
5934}
6035
6136@RecordUse()
62- class RecordMetadata {
63- final Object metadata;
37+ class PirateShip {
38+ final String name;
39+ final int cannons;
6440
65- const RecordMetadata (this.metadata );
41+ const PirateShip (this.name, this.cannons );
6642}
67-
6843```
69- This code will generate a data file that contains both the ` metadata ` values of
70- the ` RecordMetadata ` instances, as well as the arguments for the different
71- methods annotated with ` @RecordUse() ` .
44+ This code will generate a data file that contains both the field values of
45+ the ` PirateShip ` instances, as well as the arguments for the ` speak `
46+ method annotated with ` @RecordUse() ` .
7247
7348This information can then be accessed in a link hook as follows:
49+ <!-- file://./example/api/usage_link.dart#link -->
7450``` dart
75- import 'dart:convert';
76-
77- import 'package:hooks/hooks.dart';
78- import 'package:record_use/record_use_internal.dart';
79-
80- final methodId = Definition(
81- 'package:mypackage/myfile.dart',
82- [Name('myMethod')],
83- );
84-
85- final classId = Definition(
86- 'package:mypackage/myfile.dart',
87- [Name('myClass')],
88- );
89-
90- void main(List<String> arguments){
51+ void main(List<String> arguments) {
9152 link(arguments, (input, output) async {
9253 final usesUri = input.recordedUsagesFile;
9354 if (usesUri == null) return;
9455 final usesJson = await File.fromUri(usesUri).readAsString();
95- final uses = RecordedUsages.fromJson(jsonDecode(usesJson));
56+ final uses = RecordedUsages.fromJson(
57+ jsonDecode(usesJson) as Map<String, Object?>,
58+ );
9659
9760 final args = uses.constArgumentsFor(methodId);
98- //[args] is an iterable of arguments, in this case containing "42"
99-
100- final fields = uses.constantsOf(classId);
101- //[fields] is an iterable of the constants of the class, in this case
102- //containing
103- // {"metadata": "leroyjenkins"}
104- // {"metadata": 3.14}
105- // {"metadata": 42}
106- // {"metadata": true}
107-
108- ... // Do something with the information, such as tree-shaking native assets
61+ for (final arg in args) {
62+ if (arg.positional[0] case StringConstant(value: final english)) {
63+ print('Translating to pirate: $english');
64+ // Shrink a translations file based on all the different translation
65+ // keys.
66+ }
67+ }
68+
69+ final ships = uses.constantsOf(classId);
70+ for (final ship in ships) {
71+ if (ship.fields['name'] case StringConstant(value: final name)) {
72+ print('Pirate ship found: $name');
73+ // Include the 3d model for this ship in the application but not
74+ // bundle the other ships.
75+ }
76+ }
10977 });
11078}
11179```
11280
113- ## Limitations
114- As this is designed to work on both web and native platforms, we have to adapt
115- to the platform pecularities. One of them is that javascript does not support
116- named arguments, so the dart2js compiler rewrites functions to only accept named
117- parameters.
118- While you can use named parameters to record functions, we advise caution as the
119- retrieval behavior might change once we work around this dart2js limitation and
120- implement separate positional and named parameters.
121-
12281## Contributing
12382Contributions are welcome! Please open an issue or submit a pull request.
0 commit comments