platform/packages/mirrors/doc/quick_start.md

# 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.