|
2 | 2 | // for details. All rights reserved. Use of this source code is governed by a |
3 | 3 | // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
|
| 5 | +/// @docImport 'src/recordings.dart'; |
| 6 | +
|
| 7 | +/// This package provides the data classes for the usage recording feature in |
| 8 | +/// the Dart SDK. |
| 9 | +/// |
| 10 | +/// Dart objects with the `@RecordUse()` annotation are being recorded at |
| 11 | +/// compile time, providing the user with information. The information depends |
| 12 | +/// on the object being recorded. |
| 13 | +/// |
| 14 | +/// The main entrypoint for recorded usages is [Recordings]. |
| 15 | +/// |
| 16 | +/// - If placed on a static method, the annotation means that arguments passed |
| 17 | +/// to the method will be recorded, as far as they can be inferred at compile |
| 18 | +/// time. These can be found in [Recordings.calls]. |
| 19 | +/// - If placed on a class, the annotation means that any constant instance of |
| 20 | +/// the class and any constructor invocation will be recorded. These can be |
| 21 | +/// found in [Recordings.instances]. |
| 22 | +/// |
| 23 | +/// > [!NOTE] |
| 24 | +/// > The `@RecordUse()` annotation is only allowed on definitions within a |
| 25 | +/// > package's `lib/` directory. This includes definitions that are members of |
| 26 | +/// > a class, such as static methods. |
| 27 | +/// |
| 28 | +/// ## Example |
| 29 | +/// |
| 30 | +/// <!-- file://./../example/api/usage.dart#usage --> |
| 31 | +/// ```dart |
| 32 | +/// void main() { |
| 33 | +/// PirateTranslator.speak('Hello'); |
| 34 | +/// print(const PirateShip('Black Pearl', 50)); |
| 35 | +/// } |
| 36 | +/// |
| 37 | +/// abstract class PirateTranslator { |
| 38 | +/// @RecordUse() |
| 39 | +/// static String speak(String english) => 'Ahoy $english'; |
| 40 | +/// } |
| 41 | +/// |
| 42 | +/// @RecordUse() |
| 43 | +/// final class PirateShip { |
| 44 | +/// final String name; |
| 45 | +/// final int cannons; |
| 46 | +/// |
| 47 | +/// const PirateShip(this.name, this.cannons); |
| 48 | +/// } |
| 49 | +/// ``` |
| 50 | +/// This code will generate a data file that contains both the field values of |
| 51 | +/// the `PirateShip` instances, as well as the arguments for the `speak` |
| 52 | +/// method annotated with `@RecordUse()`. |
| 53 | +/// |
| 54 | +/// This information can then be accessed in a link hook as follows: |
| 55 | +/// <!-- file://./../example/api/usage_link.dart#link --> |
| 56 | +/// ```dart |
| 57 | +/// void main(List<String> arguments) { |
| 58 | +/// link(arguments, (input, output) async { |
| 59 | +/// final usesUri = input.recordedUsagesFile; |
| 60 | +/// if (usesUri == null) return; |
| 61 | +/// final usesJson = await File.fromUri(usesUri).readAsString(); |
| 62 | +/// final uses = Recordings.fromJson( |
| 63 | +/// jsonDecode(usesJson) as Map<String, Object?>, |
| 64 | +/// ); |
| 65 | +/// |
| 66 | +/// final calls = uses.calls[methodId] ?? []; |
| 67 | +/// for (final call in calls) { |
| 68 | +/// switch (call) { |
| 69 | +/// case CallWithArguments( |
| 70 | +/// positionalArguments: [StringConstant(value: final english), ...], |
| 71 | +/// ): |
| 72 | +/// // Shrink a translations file based on all the different translation |
| 73 | +/// // keys. |
| 74 | +/// print('Translating to pirate: $english'); |
| 75 | +/// case _: |
| 76 | +/// print('Cannot determine which translations are used.'); |
| 77 | +/// } |
| 78 | +/// } |
| 79 | +/// |
| 80 | +/// final ships = uses.instances[classId] ?? []; |
| 81 | +/// for (final ship in ships) { |
| 82 | +/// switch (ship) { |
| 83 | +/// case InstanceConstantReference( |
| 84 | +/// instanceConstant: InstanceConstant( |
| 85 | +/// fields: {'name': StringConstant(value: final name)}, |
| 86 | +/// ), |
| 87 | +/// ): |
| 88 | +/// // Include the 3d model for this ship in the application but not |
| 89 | +/// // bundle the other ships. |
| 90 | +/// print('Pirate ship found: $name'); |
| 91 | +/// case _: |
| 92 | +/// print('Cannot determine which ships are used.'); |
| 93 | +/// } |
| 94 | +/// } |
| 95 | +/// }); |
| 96 | +/// } |
| 97 | +/// ``` |
| 98 | +library; |
| 99 | + |
5 | 100 | export 'src/constant.dart' |
6 | 101 | show |
7 | 102 | BoolConstant, |
|
0 commit comments