110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# Platform Reflection Quick Start Guide
|
|
|
|
This guide covers the essential steps to get started with Platform Reflection, a drop-in replacement for dart:mirrors with AOT compilation support.
|
|
|
|
## Installation
|
|
|
|
Add this to your package's `pubspec.yaml` file:
|
|
|
|
```yaml
|
|
dependencies:
|
|
platform_reflection: ^0.1.0
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
1. **Explicit Registration**: Unlike dart:mirrors, Platform Reflection requires explicit registration of classes and their members.
|
|
2. **AOT Compilation Support**: The registration process enables AOT compilation, which dart:mirrors doesn't support.
|
|
3. **API Similarity**: The reflection API is similar to dart:mirrors, easing the transition.
|
|
|
|
## Basic Usage
|
|
|
|
### 1. Define and Register a Class
|
|
|
|
```dart
|
|
import 'package:platform_mirrors/mirrors.dart';
|
|
|
|
@reflectable
|
|
class User {
|
|
String name;
|
|
int age;
|
|
|
|
User(this.name, this.age);
|
|
|
|
String greet() => "Hello, $name!";
|
|
}
|
|
|
|
void registerUser() {
|
|
Reflector.register(User);
|
|
Reflector.registerProperty(User, 'name', String);
|
|
Reflector.registerProperty(User, 'age', int);
|
|
Reflector.registerMethod(User, 'greet', [], false);
|
|
Reflector.registerConstructor(
|
|
User,
|
|
'',
|
|
parameterTypes: [String, int],
|
|
parameterNames: ['name', 'age'],
|
|
);
|
|
}
|
|
|
|
void main() {
|
|
registerUser();
|
|
// Your application code here
|
|
}
|
|
```
|
|
|
|
### 2. Use Reflection
|
|
|
|
```dart
|
|
void demonstrateReflection() {
|
|
final reflector = RuntimeReflector.instance;
|
|
|
|
// Create instance
|
|
final user = reflector.createInstance(
|
|
User,
|
|
positionalArgs: ['John Doe', 30],
|
|
) as User;
|
|
|
|
// Get mirror
|
|
final mirror = reflector.reflect(user);
|
|
|
|
// Property access and modification
|
|
print('Name: ${mirror.getField(const Symbol('name')).reflectee}');
|
|
mirror.setField(const Symbol('age'), 31);
|
|
|
|
// Method invocation
|
|
final greeting = mirror.invoke(const Symbol('greet'), []).reflectee as String;
|
|
print(greeting);
|
|
|
|
// Type information
|
|
final classMirror = reflector.reflectClass(User);
|
|
print('Type name: ${classMirror.name}');
|
|
}
|
|
```
|
|
|
|
## Key Differences from dart:mirrors
|
|
|
|
1. **Registration**: You must register classes, properties, methods, and constructors explicitly.
|
|
2. **Reflector Class**: Use the `Reflector` class for registration and the `RuntimeReflector` for reflection operations.
|
|
3. **Limited Automatic Discovery**: There's no automatic discovery of classes or members; everything must be registered.
|
|
|
|
## Best Practices
|
|
|
|
1. Register all reflectable types at application startup.
|
|
2. Cache instance mirrors for repeated operations on the same object.
|
|
3. Always handle potential `ReflectionException`s in your code.
|
|
4. Use reflection judiciously, as it can impact performance.
|
|
|
|
## Common Pitfalls
|
|
|
|
1. Forgetting to register a class or its members before reflection.
|
|
2. Attempting to reflect on private members (not supported).
|
|
3. Not handling potential exceptions during reflection operations.
|
|
|
|
## Next Steps
|
|
|
|
- Review the [API Reference](../README.md#api-reference) for detailed information.
|
|
- Explore the [examples](../example) directory for more complex scenarios.
|
|
- If migrating from dart:mirrors, check the [Migration Guide](mirrors_comparison.md) for a detailed comparison and transition tips.
|
|
|
|
Remember, Platform Reflection aims to provide the power of reflection with the benefits of AOT compilation. The trade-off is the need for explicit registration, which gives you more control over what can be reflected upon in your application.
|