508 lines
12 KiB
Markdown
508 lines
12 KiB
Markdown
# Platform Reflection
|
|
|
|
A powerful cross-platform reflection system for Dart that provides runtime type introspection and manipulation. This implementation offers a carefully balanced approach between functionality and performance, providing reflection capabilities without the limitations of `dart:mirrors`.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Architecture](#architecture)
|
|
- [Installation](#installation)
|
|
- [Core Components](#core-components)
|
|
- [Usage Guide](#usage-guide)
|
|
- [Advanced Usage](#advanced-usage)
|
|
- [Performance Considerations](#performance-considerations)
|
|
- [Migration Guide](#migration-guide)
|
|
- [API Reference](#api-reference)
|
|
- [Limitations](#limitations)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Features
|
|
|
|
### Core Features
|
|
- ✅ Platform independent reflection system
|
|
- ✅ No dependency on `dart:mirrors`
|
|
- ✅ Pure runtime reflection
|
|
- ✅ Explicit registration for performance
|
|
- ✅ Type-safe operations
|
|
- ✅ Comprehensive error handling
|
|
|
|
### Reflection Capabilities
|
|
- ✅ Class reflection
|
|
- ✅ Method invocation
|
|
- ✅ Property access/mutation
|
|
- ✅ Constructor invocation
|
|
- ✅ Type introspection
|
|
- ✅ Basic metadata support
|
|
- ✅ Parameter inspection
|
|
- ✅ Type relationship checking
|
|
|
|
### Performance Features
|
|
- ✅ Optimized metadata storage
|
|
- ✅ Efficient lookup mechanisms
|
|
- ✅ Minimal runtime overhead
|
|
- ✅ Memory-efficient design
|
|
- ✅ Lazy initialization support
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
```
|
|
platform_reflection/
|
|
├── core/
|
|
│ ├── reflector.dart # Central reflection management
|
|
│ ├── scanner.dart # Type scanning and analysis
|
|
│ └── runtime_reflector.dart # Runtime reflection implementation
|
|
├── metadata/
|
|
│ ├── type_metadata.dart # Type information storage
|
|
│ ├── method_metadata.dart # Method metadata handling
|
|
│ └── property_metadata.dart # Property metadata handling
|
|
├── mirrors/
|
|
│ ├── class_mirror.dart # Class reflection implementation
|
|
│ ├── instance_mirror.dart # Instance reflection handling
|
|
│ └── method_mirror.dart # Method reflection support
|
|
└── exceptions/
|
|
└── reflection_exceptions.dart # Error handling
|
|
```
|
|
|
|
### Design Principles
|
|
|
|
1. **Explicit Registration**
|
|
- Clear registration of reflectable types
|
|
- Controlled reflection surface
|
|
- Optimized runtime performance
|
|
|
|
2. **Type Safety**
|
|
- Strong type checking
|
|
- Compile-time validations
|
|
- Runtime type verification
|
|
|
|
3. **Performance First**
|
|
- Minimal runtime overhead
|
|
- Efficient metadata storage
|
|
- Optimized lookup mechanisms
|
|
|
|
4. **Platform Independence**
|
|
- Cross-platform compatibility
|
|
- No platform-specific dependencies
|
|
- Consistent behavior
|
|
|
|
## Installation
|
|
|
|
```yaml
|
|
dependencies:
|
|
platform_reflection: ^0.1.0
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### Reflector
|
|
|
|
Central management class for reflection operations:
|
|
|
|
```dart
|
|
class Reflector {
|
|
// Type registration
|
|
static void register(Type type);
|
|
static void registerProperty(Type type, String name, Type propertyType);
|
|
static void registerMethod(Type type, String name, List<Type> parameterTypes);
|
|
static void registerConstructor(Type type, String name, {Function? creator});
|
|
|
|
// Metadata access
|
|
static TypeMetadata? getTypeMetadata(Type type);
|
|
static Map<String, PropertyMetadata>? getPropertyMetadata(Type type);
|
|
static Map<String, MethodMetadata>? getMethodMetadata(Type type);
|
|
|
|
// Utility methods
|
|
static void reset();
|
|
static bool isReflectable(Type type);
|
|
}
|
|
```
|
|
|
|
### Scanner
|
|
|
|
Automatic metadata extraction and analysis:
|
|
|
|
```dart
|
|
class Scanner {
|
|
// Scanning operations
|
|
static void scanType(Type type);
|
|
static TypeMetadata getTypeMetadata(Type type);
|
|
|
|
// Analysis methods
|
|
static TypeInfo analyze(Type type);
|
|
static List<PropertyInfo> analyzeProperties(Type type);
|
|
static List<MethodInfo> analyzeMethods(Type type);
|
|
}
|
|
```
|
|
|
|
### RuntimeReflector
|
|
|
|
Runtime reflection implementation:
|
|
|
|
```dart
|
|
class RuntimeReflector {
|
|
// Instance creation
|
|
InstanceMirror createInstance(Type type, {
|
|
List<dynamic>? positionalArgs,
|
|
Map<Symbol, dynamic>? namedArgs,
|
|
String? constructorName,
|
|
});
|
|
|
|
// Reflection operations
|
|
InstanceMirror reflect(Object object);
|
|
ClassMirror reflectClass(Type type);
|
|
TypeMirror reflectType(Type type);
|
|
}
|
|
```
|
|
|
|
## Usage Guide
|
|
|
|
### Basic Registration
|
|
|
|
```dart
|
|
@reflectable
|
|
class User {
|
|
String name;
|
|
int age;
|
|
final String id;
|
|
|
|
User(this.name, this.age, {required this.id});
|
|
|
|
void birthday() {
|
|
age++;
|
|
}
|
|
|
|
String greet(String greeting) {
|
|
return '$greeting $name!';
|
|
}
|
|
}
|
|
|
|
// Register class and members
|
|
void registerUser() {
|
|
Reflector.register(User);
|
|
|
|
// Register properties
|
|
Reflector.registerProperty(User, 'name', String);
|
|
Reflector.registerProperty(User, 'age', int);
|
|
Reflector.registerProperty(User, 'id', String, isWritable: false);
|
|
|
|
// Register methods
|
|
Reflector.registerMethod(
|
|
User,
|
|
'birthday',
|
|
[],
|
|
true,
|
|
parameterNames: [],
|
|
isRequired: [],
|
|
);
|
|
|
|
Reflector.registerMethod(
|
|
User,
|
|
'greet',
|
|
[String],
|
|
false,
|
|
parameterNames: ['greeting'],
|
|
isRequired: [true],
|
|
);
|
|
|
|
// Register constructor
|
|
Reflector.registerConstructor(
|
|
User,
|
|
'',
|
|
parameterTypes: [String, int, String],
|
|
parameterNames: ['name', 'age', 'id'],
|
|
isRequired: [true, true, true],
|
|
isNamed: [false, false, true],
|
|
creator: (String name, int age, {required String id}) =>
|
|
User(name, age, id: id),
|
|
);
|
|
}
|
|
```
|
|
|
|
### Instance Manipulation
|
|
|
|
```dart
|
|
void manipulateInstance() {
|
|
final reflector = RuntimeReflector.instance;
|
|
|
|
// Create instance
|
|
final user = reflector.createInstance(
|
|
User,
|
|
positionalArgs: ['John', 30],
|
|
namedArgs: {const Symbol('id'): '123'},
|
|
) as User;
|
|
|
|
// Get mirror
|
|
final mirror = reflector.reflect(user);
|
|
|
|
// Property access
|
|
final name = mirror.getField(const Symbol('name')).reflectee as String;
|
|
final age = mirror.getField(const Symbol('age')).reflectee as int;
|
|
|
|
// Property modification
|
|
mirror.setField(const Symbol('name'), 'Jane');
|
|
mirror.setField(const Symbol('age'), 31);
|
|
|
|
// Method invocation
|
|
mirror.invoke(const Symbol('birthday'), []);
|
|
final greeting = mirror.invoke(
|
|
const Symbol('greet'),
|
|
['Hello'],
|
|
).reflectee as String;
|
|
}
|
|
```
|
|
|
|
### Type Introspection
|
|
|
|
```dart
|
|
void inspectType() {
|
|
final metadata = Reflector.getTypeMetadata(User);
|
|
|
|
// Property inspection
|
|
for (var property in metadata.properties.values) {
|
|
print('Property: ${property.name}');
|
|
print(' Type: ${property.type}');
|
|
print(' Writable: ${property.isWritable}');
|
|
print(' Static: ${property.isStatic}');
|
|
}
|
|
|
|
// Method inspection
|
|
for (var method in metadata.methods.values) {
|
|
print('Method: ${method.name}');
|
|
print(' Return type: ${method.returnType}');
|
|
print(' Parameters:');
|
|
for (var param in method.parameters) {
|
|
print(' ${param.name}: ${param.type}');
|
|
print(' Required: ${param.isRequired}');
|
|
print(' Named: ${param.isNamed}');
|
|
}
|
|
}
|
|
|
|
// Constructor inspection
|
|
for (var ctor in metadata.constructors) {
|
|
print('Constructor: ${ctor.name}');
|
|
print(' Parameters:');
|
|
for (var param in ctor.parameters) {
|
|
print(' ${param.name}: ${param.type}');
|
|
print(' Required: ${param.isRequired}');
|
|
print(' Named: ${param.isNamed}');
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Scanner Usage
|
|
|
|
```dart
|
|
void useScannerFeatures() {
|
|
// Scan type
|
|
Scanner.scanType(User);
|
|
|
|
// Get scanned metadata
|
|
final metadata = Scanner.getTypeMetadata(User);
|
|
|
|
// Analyze type structure
|
|
final typeInfo = Scanner.analyze(User);
|
|
|
|
// Property analysis
|
|
final properties = typeInfo.properties;
|
|
for (var prop in properties) {
|
|
print('Property: ${prop.name}');
|
|
print(' Type: ${prop.type}');
|
|
print(' Final: ${prop.isFinal}');
|
|
}
|
|
|
|
// Method analysis
|
|
final methods = typeInfo.methods;
|
|
for (var method in methods) {
|
|
print('Method: ${method.name}');
|
|
print(' Return type: ${method.returnType}');
|
|
print(' Static: ${method.isStatic}');
|
|
print(' Parameters: ${method.parameters}');
|
|
}
|
|
}
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Generic Type Handling
|
|
|
|
```dart
|
|
@reflectable
|
|
class Container<T> {
|
|
T value;
|
|
Container(this.value);
|
|
}
|
|
|
|
void handleGenericType() {
|
|
Reflector.register(Container);
|
|
|
|
// Register with specific type
|
|
final stringContainer = reflector.createInstance(
|
|
Container,
|
|
positionalArgs: ['Hello'],
|
|
) as Container<String>;
|
|
|
|
final mirror = reflector.reflect(stringContainer);
|
|
final value = mirror.getField(const Symbol('value')).reflectee as String;
|
|
}
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
```dart
|
|
void demonstrateErrorHandling() {
|
|
try {
|
|
// Attempt to reflect unregistered type
|
|
reflector.reflect(UnregisteredClass());
|
|
} on NotReflectableException catch (e) {
|
|
print('Type not registered: $e');
|
|
}
|
|
|
|
try {
|
|
// Attempt to access non-existent member
|
|
final mirror = reflector.reflect(user);
|
|
mirror.getField(const Symbol('nonexistent'));
|
|
} on MemberNotFoundException catch (e) {
|
|
print('Member not found: $e');
|
|
}
|
|
|
|
try {
|
|
// Attempt invalid method invocation
|
|
final mirror = reflector.reflect(user);
|
|
mirror.invoke(const Symbol('greet'), [42]); // Wrong argument type
|
|
} on InvalidArgumentsException catch (e) {
|
|
print('Invalid arguments: $e');
|
|
}
|
|
}
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
### Registration Impact
|
|
|
|
- Explicit registration adds startup cost
|
|
- Improved runtime performance
|
|
- Reduced memory usage
|
|
- Controlled reflection surface
|
|
|
|
### Optimization Techniques
|
|
|
|
1. **Lazy Loading**
|
|
```dart
|
|
// Only register when needed
|
|
if (Reflector.getTypeMetadata(User) == null) {
|
|
registerUser();
|
|
}
|
|
```
|
|
|
|
2. **Metadata Caching**
|
|
```dart
|
|
// Cache metadata access
|
|
final metadata = Reflector.getTypeMetadata(User);
|
|
final properties = metadata.properties;
|
|
final methods = metadata.methods;
|
|
```
|
|
|
|
3. **Instance Reuse**
|
|
```dart
|
|
// Reuse instance mirrors
|
|
final mirror = reflector.reflect(user);
|
|
// Store mirror for repeated use
|
|
```
|
|
|
|
### Memory Management
|
|
|
|
- Metadata storage optimization
|
|
- Instance mirror lifecycle management
|
|
- Cache invalidation strategies
|
|
|
|
## Migration Guide
|
|
|
|
### From dart:mirrors
|
|
|
|
```dart
|
|
// Old dart:mirrors code
|
|
import 'dart:mirrors';
|
|
|
|
final mirror = reflect(instance);
|
|
final value = mirror.getField(#propertyName).reflectee;
|
|
|
|
// New platform_reflection code
|
|
import 'package:platform_reflection/reflection.dart';
|
|
|
|
final mirror = reflector.reflect(instance);
|
|
final value = mirror.getField(const Symbol('propertyName')).reflectee;
|
|
```
|
|
|
|
### Registration Requirements
|
|
|
|
```dart
|
|
// Add registration code
|
|
void registerTypes() {
|
|
Reflector.register(MyClass);
|
|
Reflector.registerProperty(MyClass, 'property', String);
|
|
Reflector.registerMethod(MyClass, 'method', [int]);
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Core Classes
|
|
|
|
- `Reflector`: Central reflection management
|
|
- `Scanner`: Metadata extraction
|
|
- `RuntimeReflector`: Runtime reflection operations
|
|
|
|
### Mirrors
|
|
|
|
- `InstanceMirror`: Instance reflection
|
|
- `ClassMirror`: Class reflection
|
|
- `MethodMirror`: Method reflection
|
|
|
|
### Metadata
|
|
|
|
- `TypeMetadata`: Type information
|
|
- `PropertyMetadata`: Property information
|
|
- `MethodMetadata`: Method information
|
|
|
|
### Exceptions
|
|
|
|
- `NotReflectableException`
|
|
- `ReflectionException`
|
|
- `InvalidArgumentsException`
|
|
- `MemberNotFoundException`
|
|
|
|
## Limitations
|
|
|
|
Current Implementation Gaps:
|
|
|
|
1. **Type System**
|
|
- Limited generic support
|
|
- No variance handling
|
|
- Basic type relationship checking
|
|
|
|
2. **Reflection Features**
|
|
- No cross-isolate reflection
|
|
- No source location tracking
|
|
- Limited metadata capabilities
|
|
|
|
3. **Language Features**
|
|
- No extension method support
|
|
- No mixin composition
|
|
- No operator overloading reflection
|
|
|
|
4. **Advanced Features**
|
|
- No dynamic proxy generation
|
|
- No attribute-based reflection
|
|
- Limited annotation processing
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|