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:

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

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

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 ReflectionExceptions 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 for detailed information.
• Explore the examples directory for more complex scenarios.
• If migrating from dart:mirrors, check the Migration Guide 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.