update: updating files with detailed comments
This commit is contained in:
parent
5fd57e1ebd
commit
ea26e024ce
12 changed files with 448 additions and 40 deletions
|
@ -7,10 +7,15 @@
|
||||||
* file that was distributed with this source code.
|
* file that was distributed with this source code.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/// The main library for the Protevus runtime package.
|
||||||
|
///
|
||||||
|
/// This library provides core functionality for the Protevus Platform,
|
||||||
|
/// including compilation, analysis, and runtime management.
|
||||||
library runtime;
|
library runtime;
|
||||||
|
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
|
|
||||||
|
// Export statements for various components of the runtime package
|
||||||
export 'package:protevus_runtime/src/analyzer.dart';
|
export 'package:protevus_runtime/src/analyzer.dart';
|
||||||
export 'package:protevus_runtime/src/build.dart';
|
export 'package:protevus_runtime/src/build.dart';
|
||||||
export 'package:protevus_runtime/src/build_context.dart';
|
export 'package:protevus_runtime/src/build_context.dart';
|
||||||
|
@ -21,19 +26,36 @@ export 'package:protevus_runtime/src/exceptions.dart';
|
||||||
export 'package:protevus_runtime/src/generator.dart';
|
export 'package:protevus_runtime/src/generator.dart';
|
||||||
export 'package:protevus_runtime/src/mirror_coerce.dart';
|
export 'package:protevus_runtime/src/mirror_coerce.dart';
|
||||||
export 'package:protevus_runtime/src/mirror_context.dart';
|
export 'package:protevus_runtime/src/mirror_context.dart';
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
/// Compiler for the runtime package itself.
|
/// A specialized compiler for the runtime package itself.
|
||||||
///
|
///
|
||||||
/// Removes dart:mirror from a replica of this package, and adds
|
/// This compiler is responsible for creating a mirror-free version of the
|
||||||
/// a generated runtime to the replica's pubspec.
|
/// runtime package. It removes dart:mirror dependencies and adds a generated
|
||||||
|
/// runtime to the package's pubspec.
|
||||||
class RuntimePackageCompiler extends Compiler {
|
class RuntimePackageCompiler extends Compiler {
|
||||||
|
/// Compiles the runtime package.
|
||||||
|
///
|
||||||
|
/// This method is currently a no-op, returning an empty map. It may be
|
||||||
|
/// extended in the future to perform actual compilation tasks.
|
||||||
|
///
|
||||||
|
/// [context] - The mirror context for compilation (unused in this implementation).
|
||||||
|
///
|
||||||
|
/// Returns an empty map, as no compilation is currently performed.
|
||||||
@override
|
@override
|
||||||
Map<String, Object> compile(MirrorContext context) => {};
|
Map<String, Object> compile(MirrorContext context) => {};
|
||||||
|
|
||||||
|
/// Modifies the package structure to remove mirror dependencies.
|
||||||
|
///
|
||||||
|
/// This method performs the following tasks:
|
||||||
|
/// 1. Rewrites the main library file to remove mirror-related exports.
|
||||||
|
/// 2. Updates the context file to use the generated runtime instead of mirror context.
|
||||||
|
/// 3. Modifies the pubspec.yaml to include the generated runtime as a dependency.
|
||||||
|
///
|
||||||
|
/// [destinationDirectory] - The directory where the modified package will be created.
|
||||||
@override
|
@override
|
||||||
void deflectPackage(Directory destinationDirectory) {
|
void deflectPackage(Directory destinationDirectory) {
|
||||||
|
// Rewrite the main library file
|
||||||
final libraryFile = File.fromUri(
|
final libraryFile = File.fromUri(
|
||||||
destinationDirectory.uri.resolve("lib/").resolve("runtime.dart"),
|
destinationDirectory.uri.resolve("lib/").resolve("runtime.dart"),
|
||||||
);
|
);
|
||||||
|
@ -41,6 +63,7 @@ class RuntimePackageCompiler extends Compiler {
|
||||||
"library runtime;\nexport 'src/context.dart';\nexport 'src/exceptions.dart';",
|
"library runtime;\nexport 'src/context.dart';\nexport 'src/exceptions.dart';",
|
||||||
);
|
);
|
||||||
|
|
||||||
|
// Update the context file
|
||||||
final contextFile = File.fromUri(
|
final contextFile = File.fromUri(
|
||||||
destinationDirectory.uri
|
destinationDirectory.uri
|
||||||
.resolve("lib/")
|
.resolve("lib/")
|
||||||
|
@ -53,6 +76,7 @@ class RuntimePackageCompiler extends Compiler {
|
||||||
);
|
);
|
||||||
contextFile.writeAsStringSync(contextFileContents);
|
contextFile.writeAsStringSync(contextFileContents);
|
||||||
|
|
||||||
|
// Modify the pubspec.yaml
|
||||||
final pubspecFile =
|
final pubspecFile =
|
||||||
File.fromUri(destinationDirectory.uri.resolve("pubspec.yaml"));
|
File.fromUri(destinationDirectory.uri.resolve("pubspec.yaml"));
|
||||||
final pubspecContents = pubspecFile.readAsStringSync().replaceFirst(
|
final pubspecContents = pubspecFile.readAsStringSync().replaceFirst(
|
||||||
|
|
|
@ -9,12 +9,30 @@
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
|
/// Prefix string for List types in type checking.
|
||||||
const String _listPrefix = "List<";
|
const String _listPrefix = "List<";
|
||||||
|
|
||||||
|
/// Prefix string for Map types in type checking.
|
||||||
const String _mapPrefix = "Map<String,";
|
const String _mapPrefix = "Map<String,";
|
||||||
|
|
||||||
|
/// Casts a dynamic input to a specified type T.
|
||||||
|
///
|
||||||
|
/// This function attempts to cast the input to the specified type T.
|
||||||
|
/// It handles nullable types, Lists, and Maps with various element types.
|
||||||
|
///
|
||||||
|
/// Parameters:
|
||||||
|
/// - input: The dynamic value to be cast.
|
||||||
|
///
|
||||||
|
/// Returns:
|
||||||
|
/// The input cast to type T.
|
||||||
|
///
|
||||||
|
/// Throws:
|
||||||
|
/// - [TypeCoercionException] if the casting fails.
|
||||||
T cast<T>(dynamic input) {
|
T cast<T>(dynamic input) {
|
||||||
try {
|
try {
|
||||||
var typeString = T.toString();
|
var typeString = T.toString();
|
||||||
|
|
||||||
|
// Handle nullable types
|
||||||
if (typeString.endsWith('?')) {
|
if (typeString.endsWith('?')) {
|
||||||
if (input == null) {
|
if (input == null) {
|
||||||
return null as T;
|
return null as T;
|
||||||
|
@ -22,11 +40,14 @@ T cast<T>(dynamic input) {
|
||||||
typeString = typeString.substring(0, typeString.length - 1);
|
typeString = typeString.substring(0, typeString.length - 1);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Handle List types
|
||||||
if (typeString.startsWith(_listPrefix)) {
|
if (typeString.startsWith(_listPrefix)) {
|
||||||
if (input is! List) {
|
if (input is! List) {
|
||||||
throw TypeError();
|
throw TypeError();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Cast List to various element types
|
||||||
if (typeString.startsWith("List<int>")) {
|
if (typeString.startsWith("List<int>")) {
|
||||||
return List<int>.from(input) as T;
|
return List<int>.from(input) as T;
|
||||||
} else if (typeString.startsWith("List<num>")) {
|
} else if (typeString.startsWith("List<num>")) {
|
||||||
|
@ -50,12 +71,16 @@ T cast<T>(dynamic input) {
|
||||||
} else if (typeString.startsWith("List<Map<String, dynamic>>")) {
|
} else if (typeString.startsWith("List<Map<String, dynamic>>")) {
|
||||||
return List<Map<String, dynamic>>.from(input) as T;
|
return List<Map<String, dynamic>>.from(input) as T;
|
||||||
}
|
}
|
||||||
} else if (typeString.startsWith(_mapPrefix)) {
|
}
|
||||||
|
// Handle Map types
|
||||||
|
else if (typeString.startsWith(_mapPrefix)) {
|
||||||
if (input is! Map) {
|
if (input is! Map) {
|
||||||
throw TypeError();
|
throw TypeError();
|
||||||
}
|
}
|
||||||
|
|
||||||
final inputMap = input as Map<String, dynamic>;
|
final inputMap = input as Map<String, dynamic>;
|
||||||
|
|
||||||
|
// Cast Map to various value types
|
||||||
if (typeString.startsWith("Map<String, int>")) {
|
if (typeString.startsWith("Map<String, int>")) {
|
||||||
return Map<String, int>.from(inputMap) as T;
|
return Map<String, int>.from(inputMap) as T;
|
||||||
} else if (typeString.startsWith("Map<String, num>")) {
|
} else if (typeString.startsWith("Map<String, num>")) {
|
||||||
|
@ -79,8 +104,10 @@ T cast<T>(dynamic input) {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// If no specific casting is needed, return the input as T
|
||||||
return input as T;
|
return input as T;
|
||||||
} on TypeError {
|
} on TypeError {
|
||||||
|
// If a TypeError occurs during casting, throw a TypeCoercionException
|
||||||
throw TypeCoercionException(T, input.runtimeType);
|
throw TypeCoercionException(T, input.runtimeType);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -14,7 +14,11 @@ import 'package:analyzer/dart/ast/ast.dart';
|
||||||
import 'package:analyzer/file_system/physical_file_system.dart';
|
import 'package:analyzer/file_system/physical_file_system.dart';
|
||||||
import 'package:path/path.dart';
|
import 'package:path/path.dart';
|
||||||
|
|
||||||
|
/// A class for analyzing Dart code.
|
||||||
class CodeAnalyzer {
|
class CodeAnalyzer {
|
||||||
|
/// Constructs a CodeAnalyzer with the given URI.
|
||||||
|
///
|
||||||
|
/// Throws an [ArgumentError] if the URI is not absolute or if no analysis context is found.
|
||||||
CodeAnalyzer(this.uri) {
|
CodeAnalyzer(this.uri) {
|
||||||
if (!uri.isAbsolute) {
|
if (!uri.isAbsolute) {
|
||||||
throw ArgumentError("'uri' must be absolute for CodeAnalyzer");
|
throw ArgumentError("'uri' must be absolute for CodeAnalyzer");
|
||||||
|
@ -27,16 +31,23 @@ class CodeAnalyzer {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Gets the path from the URI.
|
||||||
String get path {
|
String get path {
|
||||||
return getPath(uri);
|
return getPath(uri);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The URI of the code to analyze.
|
||||||
late final Uri uri;
|
late final Uri uri;
|
||||||
|
|
||||||
|
/// The collection of analysis contexts.
|
||||||
late AnalysisContextCollection contexts;
|
late AnalysisContextCollection contexts;
|
||||||
|
|
||||||
|
/// A cache of resolved ASTs.
|
||||||
final _resolvedAsts = <String, AnalysisResult>{};
|
final _resolvedAsts = <String, AnalysisResult>{};
|
||||||
|
|
||||||
|
/// Resolves the unit or library at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns a [Future] that completes with an [AnalysisResult].
|
||||||
Future<AnalysisResult> resolveUnitOrLibraryAt(Uri uri) async {
|
Future<AnalysisResult> resolveUnitOrLibraryAt(Uri uri) async {
|
||||||
if (FileSystemEntity.isFileSync(
|
if (FileSystemEntity.isFileSync(
|
||||||
uri.toFilePath(windows: Platform.isWindows),
|
uri.toFilePath(windows: Platform.isWindows),
|
||||||
|
@ -47,6 +58,10 @@ class CodeAnalyzer {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Resolves the library at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns a [Future] that completes with a [ResolvedLibraryResult].
|
||||||
|
/// Throws an [ArgumentError] if the URI could not be resolved.
|
||||||
Future<ResolvedLibraryResult> resolveLibraryAt(Uri uri) async {
|
Future<ResolvedLibraryResult> resolveLibraryAt(Uri uri) async {
|
||||||
assert(
|
assert(
|
||||||
FileSystemEntity.isDirectorySync(
|
FileSystemEntity.isDirectorySync(
|
||||||
|
@ -68,6 +83,10 @@ class CodeAnalyzer {
|
||||||
"${contexts.contexts.map((c) => c.contextRoot.root.toUri()).join(", ")})");
|
"${contexts.contexts.map((c) => c.contextRoot.root.toUri()).join(", ")})");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Resolves the unit at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns a [Future] that completes with a [ResolvedUnitResult].
|
||||||
|
/// Throws an [ArgumentError] if the URI could not be resolved.
|
||||||
Future<ResolvedUnitResult> resolveUnitAt(Uri uri) async {
|
Future<ResolvedUnitResult> resolveUnitAt(Uri uri) async {
|
||||||
assert(
|
assert(
|
||||||
FileSystemEntity.isFileSync(
|
FileSystemEntity.isFileSync(
|
||||||
|
@ -89,6 +108,9 @@ class CodeAnalyzer {
|
||||||
"${contexts.contexts.map((c) => c.contextRoot.root.toUri()).join(", ")})");
|
"${contexts.contexts.map((c) => c.contextRoot.root.toUri()).join(", ")})");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Gets the class declaration from the file at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns null if the class is not found or if there's an error.
|
||||||
ClassDeclaration? getClassFromFile(String className, Uri fileUri) {
|
ClassDeclaration? getClassFromFile(String className, Uri fileUri) {
|
||||||
try {
|
try {
|
||||||
return _getFileAstRoot(fileUri)
|
return _getFileAstRoot(fileUri)
|
||||||
|
@ -103,6 +125,9 @@ class CodeAnalyzer {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Gets all subclasses of the given superclass from the file at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns a list of [ClassDeclaration]s.
|
||||||
List<ClassDeclaration> getSubclassesFromFile(
|
List<ClassDeclaration> getSubclassesFromFile(
|
||||||
String superclassName,
|
String superclassName,
|
||||||
Uri fileUri,
|
Uri fileUri,
|
||||||
|
@ -115,6 +140,9 @@ class CodeAnalyzer {
|
||||||
.toList();
|
.toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Gets the AST root of the file at the given URI.
|
||||||
|
///
|
||||||
|
/// Returns a [CompilationUnit].
|
||||||
CompilationUnit _getFileAstRoot(Uri fileUri) {
|
CompilationUnit _getFileAstRoot(Uri fileUri) {
|
||||||
assert(
|
assert(
|
||||||
FileSystemEntity.isFileSync(
|
FileSystemEntity.isFileSync(
|
||||||
|
@ -135,6 +163,9 @@ class CodeAnalyzer {
|
||||||
return unit.unit;
|
return unit.unit;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Converts the input URI to a normalized path string.
|
||||||
|
///
|
||||||
|
/// This is a static utility method.
|
||||||
static String getPath(dynamic inputUri) {
|
static String getPath(dynamic inputUri) {
|
||||||
return PhysicalResourceProvider.INSTANCE.pathContext.normalize(
|
return PhysicalResourceProvider.INSTANCE.pathContext.normalize(
|
||||||
PhysicalResourceProvider.INSTANCE.pathContext.fromUri(inputUri),
|
PhysicalResourceProvider.INSTANCE.pathContext.fromUri(inputUri),
|
||||||
|
|
|
@ -11,16 +11,34 @@
|
||||||
import 'dart:convert';
|
import 'dart:convert';
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
import 'dart:mirrors';
|
import 'dart:mirrors';
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
import 'package:io/io.dart';
|
import 'package:io/io.dart';
|
||||||
import 'package:package_config/package_config.dart';
|
import 'package:package_config/package_config.dart';
|
||||||
|
|
||||||
|
/// A class responsible for building and compiling the application.
|
||||||
|
///
|
||||||
|
/// This class handles the entire build process, including resolving ASTs,
|
||||||
|
/// generating runtime, compiling packages, and creating the final executable.
|
||||||
class Build {
|
class Build {
|
||||||
|
/// Creates a new [Build] instance with the given [BuildContext].
|
||||||
|
///
|
||||||
|
/// [context] is the build context containing necessary information for the build process.
|
||||||
Build(this.context);
|
Build(this.context);
|
||||||
|
|
||||||
|
/// The build context for this build operation.
|
||||||
final BuildContext context;
|
final BuildContext context;
|
||||||
|
|
||||||
|
/// Executes the build process.
|
||||||
|
///
|
||||||
|
/// This method performs the following steps:
|
||||||
|
/// 1. Resolves ASTs
|
||||||
|
/// 2. Generates runtime
|
||||||
|
/// 3. Compiles packages
|
||||||
|
/// 4. Prepares the build directory
|
||||||
|
/// 5. Fetches dependencies
|
||||||
|
/// 6. Compiles the final executable (if not for tests)
|
||||||
|
///
|
||||||
|
/// Throws a [StateError] if any step fails.
|
||||||
Future execute() async {
|
Future execute() async {
|
||||||
final compilers = context.context.compilers;
|
final compilers = context.context.compilers;
|
||||||
|
|
||||||
|
@ -129,6 +147,10 @@ class Build {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Fetches dependencies for the project.
|
||||||
|
///
|
||||||
|
/// This method runs 'dart pub get' with the '--offline' and '--no-precompile' flags.
|
||||||
|
/// It throws a [StateError] if the command fails.
|
||||||
Future getDependencies() async {
|
Future getDependencies() async {
|
||||||
const String cmd = "dart";
|
const String cmd = "dart";
|
||||||
|
|
||||||
|
@ -147,6 +169,13 @@ class Build {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Compiles the source file to an executable.
|
||||||
|
///
|
||||||
|
/// [srcUri] is the URI of the source file to compile.
|
||||||
|
/// [dstUri] is the URI where the compiled executable will be saved.
|
||||||
|
///
|
||||||
|
/// This method runs 'dart compile exe' with verbose output.
|
||||||
|
/// It throws a [StateError] if the compilation fails.
|
||||||
Future compile(Uri srcUri, Uri dstUri) async {
|
Future compile(Uri srcUri, Uri dstUri) async {
|
||||||
final res = await Process.run(
|
final res = await Process.run(
|
||||||
"dart",
|
"dart",
|
||||||
|
@ -173,6 +202,13 @@ class Build {
|
||||||
print("${res.stdout}");
|
print("${res.stdout}");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Copies a package from source to destination.
|
||||||
|
///
|
||||||
|
/// [srcUri] is the URI of the source package.
|
||||||
|
/// [dstUri] is the URI where the package will be copied.
|
||||||
|
///
|
||||||
|
/// This method creates the destination directory if it doesn't exist,
|
||||||
|
/// copies the package contents, and handles Windows-specific file system issues.
|
||||||
Future copyPackage(Uri srcUri, Uri dstUri) async {
|
Future copyPackage(Uri srcUri, Uri dstUri) async {
|
||||||
final dstDir = Directory.fromUri(dstUri);
|
final dstDir = Directory.fromUri(dstUri);
|
||||||
if (!dstDir.existsSync()) {
|
if (!dstDir.existsSync()) {
|
||||||
|
@ -206,6 +242,12 @@ class Build {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves package information for a given compiler.
|
||||||
|
///
|
||||||
|
/// [compiler] is the compiler instance to get package information for.
|
||||||
|
///
|
||||||
|
/// This method uses reflection to find the source URI of the compiler
|
||||||
|
/// and then retrieves the corresponding package information.
|
||||||
Future<Package> _getPackageInfoForCompiler(Compiler compiler) async {
|
Future<Package> _getPackageInfoForCompiler(Compiler compiler) async {
|
||||||
final compilerUri = reflect(compiler).type.location!.sourceUri;
|
final compilerUri = reflect(compiler).type.location!.sourceUri;
|
||||||
|
|
||||||
|
|
|
@ -9,7 +9,6 @@
|
||||||
|
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
import 'dart:mirrors';
|
import 'dart:mirrors';
|
||||||
|
|
||||||
import 'package:analyzer/dart/ast/ast.dart';
|
import 'package:analyzer/dart/ast/ast.dart';
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
import 'package:package_config/package_config.dart';
|
import 'package:package_config/package_config.dart';
|
||||||
|
@ -17,8 +16,18 @@ import 'package:path/path.dart';
|
||||||
import 'package:pubspec_parse/pubspec_parse.dart';
|
import 'package:pubspec_parse/pubspec_parse.dart';
|
||||||
import 'package:yaml/yaml.dart';
|
import 'package:yaml/yaml.dart';
|
||||||
|
|
||||||
/// Configuration and context values used during [Build.execute].
|
/// BuildContext provides configuration and context values used during the build process.
|
||||||
|
/// It encapsulates information about the application being compiled, build artifacts,
|
||||||
|
/// and provides utility methods for file and package management.
|
||||||
class BuildContext {
|
class BuildContext {
|
||||||
|
/// Constructs a new BuildContext instance.
|
||||||
|
///
|
||||||
|
/// [rootLibraryFileUri]: The URI of the root library file of the application being compiled.
|
||||||
|
/// [buildDirectoryUri]: The URI of the directory where build artifacts will be stored.
|
||||||
|
/// [executableUri]: The URI of the executable build product file.
|
||||||
|
/// [source]: The source script for the executable.
|
||||||
|
/// [environment]: Optional map of environment variables.
|
||||||
|
/// [forTests]: Boolean flag indicating whether this context is for tests (includes dev dependencies).
|
||||||
BuildContext(
|
BuildContext(
|
||||||
this.rootLibraryFileUri,
|
this.rootLibraryFileUri,
|
||||||
this.buildDirectoryUri,
|
this.buildDirectoryUri,
|
||||||
|
@ -30,6 +39,12 @@ class BuildContext {
|
||||||
analyzer = CodeAnalyzer(sourceApplicationDirectory.uri);
|
analyzer = CodeAnalyzer(sourceApplicationDirectory.uri);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Creates a BuildContext instance from a map of values.
|
||||||
|
///
|
||||||
|
/// This factory constructor allows for easy serialization and deserialization of BuildContext objects.
|
||||||
|
///
|
||||||
|
/// [map]: A map containing the necessary values to construct a BuildContext.
|
||||||
|
/// Returns: A new BuildContext instance.
|
||||||
factory BuildContext.fromMap(Map<String, dynamic> map) {
|
factory BuildContext.fromMap(Map<String, dynamic> map) {
|
||||||
return BuildContext(
|
return BuildContext(
|
||||||
Uri.parse(map['rootLibraryFileUri']),
|
Uri.parse(map['rootLibraryFileUri']),
|
||||||
|
@ -41,6 +56,10 @@ class BuildContext {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Returns a map representation of the BuildContext with safe-to-serialize values.
|
||||||
|
///
|
||||||
|
/// This getter is useful for serialization purposes, ensuring that all values are
|
||||||
|
/// in a format that can be easily serialized (e.g., converting URIs to strings).
|
||||||
Map<String, dynamic> get safeMap => {
|
Map<String, dynamic> get safeMap => {
|
||||||
'rootLibraryFileUri': sourceLibraryFile.uri.toString(),
|
'rootLibraryFileUri': sourceLibraryFile.uri.toString(),
|
||||||
'buildDirectoryUri': buildDirectoryUri.toString(),
|
'buildDirectoryUri': buildDirectoryUri.toString(),
|
||||||
|
@ -50,41 +69,56 @@ class BuildContext {
|
||||||
'forTests': forTests
|
'forTests': forTests
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// The CodeAnalyzer instance used for analyzing Dart code.
|
||||||
late final CodeAnalyzer analyzer;
|
late final CodeAnalyzer analyzer;
|
||||||
|
|
||||||
/// A [Uri] to the library file of the application to be compiled.
|
/// The URI of the root library file of the application being compiled.
|
||||||
final Uri rootLibraryFileUri;
|
final Uri rootLibraryFileUri;
|
||||||
|
|
||||||
/// A [Uri] to the executable build product file.
|
/// The URI of the executable build product file.
|
||||||
final Uri executableUri;
|
final Uri executableUri;
|
||||||
|
|
||||||
/// A [Uri] to directory where build artifacts are stored during the build process.
|
/// The URI of the directory where build artifacts are stored during the build process.
|
||||||
final Uri buildDirectoryUri;
|
final Uri buildDirectoryUri;
|
||||||
|
|
||||||
/// The source script for the executable.
|
/// The source script for the executable.
|
||||||
final String source;
|
final String source;
|
||||||
|
|
||||||
/// Whether dev dependencies of the application package are included in the dependencies of the compiled executable.
|
/// Indicates whether dev dependencies of the application package should be included
|
||||||
|
/// in the dependencies of the compiled executable.
|
||||||
final bool forTests;
|
final bool forTests;
|
||||||
|
|
||||||
|
/// Cached PackageConfig instance.
|
||||||
PackageConfig? _packageConfig;
|
PackageConfig? _packageConfig;
|
||||||
|
|
||||||
|
/// Optional map of environment variables.
|
||||||
final Map<String, String>? environment;
|
final Map<String, String>? environment;
|
||||||
|
|
||||||
/// The [RuntimeContext] available during the build process.
|
/// The current RuntimeContext, cast as a MirrorContext.
|
||||||
|
///
|
||||||
|
/// This getter provides access to the runtime context available during the build process.
|
||||||
MirrorContext get context => RuntimeContext.current as MirrorContext;
|
MirrorContext get context => RuntimeContext.current as MirrorContext;
|
||||||
|
|
||||||
|
/// The URI of the target script file.
|
||||||
|
///
|
||||||
|
/// If [forTests] is true, this will be a test file, otherwise it will be the main application file.
|
||||||
Uri get targetScriptFileUri => forTests
|
Uri get targetScriptFileUri => forTests
|
||||||
? getDirectory(buildDirectoryUri.resolve("test/"))
|
? getDirectory(buildDirectoryUri.resolve("test/"))
|
||||||
.uri
|
.uri
|
||||||
.resolve("main_test.dart")
|
.resolve("main_test.dart")
|
||||||
: buildDirectoryUri.resolve("main.dart");
|
: buildDirectoryUri.resolve("main.dart");
|
||||||
|
|
||||||
|
/// The Pubspec of the source application.
|
||||||
|
///
|
||||||
|
/// This getter parses and returns the pubspec.yaml file of the application being compiled.
|
||||||
Pubspec get sourceApplicationPubspec => Pubspec.parse(
|
Pubspec get sourceApplicationPubspec => Pubspec.parse(
|
||||||
File.fromUri(sourceApplicationDirectory.uri.resolve("pubspec.yaml"))
|
File.fromUri(sourceApplicationDirectory.uri.resolve("pubspec.yaml"))
|
||||||
.readAsStringSync(),
|
.readAsStringSync(),
|
||||||
);
|
);
|
||||||
|
|
||||||
|
/// The pubspec of the source application as a map.
|
||||||
|
///
|
||||||
|
/// This getter loads and returns the pubspec.yaml file as a YAML map.
|
||||||
Map<dynamic, dynamic> get sourceApplicationPubspecMap => loadYaml(
|
Map<dynamic, dynamic> get sourceApplicationPubspecMap => loadYaml(
|
||||||
File.fromUri(
|
File.fromUri(
|
||||||
sourceApplicationDirectory.uri.resolve("pubspec.yaml"),
|
sourceApplicationDirectory.uri.resolve("pubspec.yaml"),
|
||||||
|
@ -101,26 +135,32 @@ class BuildContext {
|
||||||
/// The directory where build artifacts are stored.
|
/// The directory where build artifacts are stored.
|
||||||
Directory get buildDirectory => getDirectory(buildDirectoryUri);
|
Directory get buildDirectory => getDirectory(buildDirectoryUri);
|
||||||
|
|
||||||
/// The generated runtime directory
|
/// The generated runtime directory.
|
||||||
Directory get buildRuntimeDirectory =>
|
Directory get buildRuntimeDirectory =>
|
||||||
getDirectory(buildDirectoryUri.resolve("generated_runtime/"));
|
getDirectory(buildDirectoryUri.resolve("generated_runtime/"));
|
||||||
|
|
||||||
/// Directory for compiled packages
|
/// Directory for compiled packages.
|
||||||
Directory get buildPackagesDirectory =>
|
Directory get buildPackagesDirectory =>
|
||||||
getDirectory(buildDirectoryUri.resolve("packages/"));
|
getDirectory(buildDirectoryUri.resolve("packages/"));
|
||||||
|
|
||||||
/// Directory for compiled application
|
/// Directory for the compiled application.
|
||||||
Directory get buildApplicationDirectory => getDirectory(
|
Directory get buildApplicationDirectory => getDirectory(
|
||||||
buildPackagesDirectory.uri.resolve("${sourceApplicationPubspec.name}/"),
|
buildPackagesDirectory.uri.resolve("${sourceApplicationPubspec.name}/"),
|
||||||
);
|
);
|
||||||
|
|
||||||
/// Gets dependency package location relative to [sourceApplicationDirectory].
|
/// Gets the dependency package configuration relative to [sourceApplicationDirectory].
|
||||||
|
///
|
||||||
|
/// This getter lazily loads and caches the package configuration.
|
||||||
|
/// Returns: A Future that resolves to a PackageConfig instance.
|
||||||
Future<PackageConfig> get packageConfig async {
|
Future<PackageConfig> get packageConfig async {
|
||||||
return _packageConfig ??=
|
return _packageConfig ??=
|
||||||
(await findPackageConfig(sourceApplicationDirectory))!;
|
(await findPackageConfig(sourceApplicationDirectory))!;
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Returns a [Directory] at [uri], creates it recursively if it doesn't exist.
|
/// Returns a [Directory] at the specified [uri], creating it recursively if it doesn't exist.
|
||||||
|
///
|
||||||
|
/// [uri]: The URI of the directory.
|
||||||
|
/// Returns: A Directory instance.
|
||||||
Directory getDirectory(Uri uri) {
|
Directory getDirectory(Uri uri) {
|
||||||
final dir = Directory.fromUri(uri);
|
final dir = Directory.fromUri(uri);
|
||||||
if (!dir.existsSync()) {
|
if (!dir.existsSync()) {
|
||||||
|
@ -129,7 +169,10 @@ class BuildContext {
|
||||||
return dir;
|
return dir;
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Returns a [File] at [uri], creates all parent directories recursively if necessary.
|
/// Returns a [File] at the specified [uri], creating all parent directories recursively if necessary.
|
||||||
|
///
|
||||||
|
/// [uri]: The URI of the file.
|
||||||
|
/// Returns: A File instance.
|
||||||
File getFile(Uri uri) {
|
File getFile(Uri uri) {
|
||||||
final file = File.fromUri(uri);
|
final file = File.fromUri(uri);
|
||||||
if (!file.parent.existsSync()) {
|
if (!file.parent.existsSync()) {
|
||||||
|
@ -139,6 +182,11 @@ class BuildContext {
|
||||||
return file;
|
return file;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves a Package instance from a given URI.
|
||||||
|
///
|
||||||
|
/// [uri]: The URI to resolve to a package.
|
||||||
|
/// Returns: A Future that resolves to a Package instance, or null if not found.
|
||||||
|
/// Throws: ArgumentError if the URI is not absolute or a package URI.
|
||||||
Future<Package?> getPackageFromUri(Uri? uri) async {
|
Future<Package?> getPackageFromUri(Uri? uri) async {
|
||||||
if (uri == null) {
|
if (uri == null) {
|
||||||
return null;
|
return null;
|
||||||
|
@ -152,6 +200,13 @@ class BuildContext {
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves import directives from a URI or source code.
|
||||||
|
///
|
||||||
|
/// [uri]: The URI of the file to analyze.
|
||||||
|
/// [source]: The source code to analyze.
|
||||||
|
/// [alsoImportOriginalFile]: Whether to include an import for the original file.
|
||||||
|
/// Returns: A Future that resolves to a list of import directive strings.
|
||||||
|
/// Throws: ArgumentError for invalid combinations of parameters.
|
||||||
Future<List<String>> getImportDirectives({
|
Future<List<String>> getImportDirectives({
|
||||||
Uri? uri,
|
Uri? uri,
|
||||||
String? source,
|
String? source,
|
||||||
|
@ -201,6 +256,10 @@ class BuildContext {
|
||||||
return imports;
|
return imports;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves a ClassDeclaration from a given Type.
|
||||||
|
///
|
||||||
|
/// [type]: The Type to analyze.
|
||||||
|
/// Returns: A Future that resolves to a ClassDeclaration, or null if not found.
|
||||||
Future<ClassDeclaration?> getClassDeclarationFromType(Type type) async {
|
Future<ClassDeclaration?> getClassDeclarationFromType(Type type) async {
|
||||||
final classMirror = reflectType(type);
|
final classMirror = reflectType(type);
|
||||||
Uri uri = classMirror.location!.sourceUri;
|
Uri uri = classMirror.location!.sourceUri;
|
||||||
|
@ -214,6 +273,11 @@ class BuildContext {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves a FieldDeclaration from a ClassMirror and property name.
|
||||||
|
///
|
||||||
|
/// [type]: The ClassMirror to analyze.
|
||||||
|
/// [propertyName]: The name of the property to find.
|
||||||
|
/// Returns: A Future that resolves to a FieldDeclaration, or null if not found.
|
||||||
Future<FieldDeclaration?> _getField(ClassMirror type, String propertyName) {
|
Future<FieldDeclaration?> _getField(ClassMirror type, String propertyName) {
|
||||||
return getClassDeclarationFromType(type.reflectedType).then((cd) {
|
return getClassDeclarationFromType(type.reflectedType).then((cd) {
|
||||||
try {
|
try {
|
||||||
|
@ -229,6 +293,13 @@ class BuildContext {
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves annotations from a field of a given Type.
|
||||||
|
///
|
||||||
|
/// This method searches for the field in the given type and its superclasses.
|
||||||
|
///
|
||||||
|
/// [type1]: The Type to analyze.
|
||||||
|
/// [propertyName]: The name of the property to find.
|
||||||
|
/// Returns: A Future that resolves to a list of Annotations.
|
||||||
Future<List<Annotation>> getAnnotationsFromField(
|
Future<List<Annotation>> getAnnotationsFromField(
|
||||||
Type type1,
|
Type type1,
|
||||||
String propertyName,
|
String propertyName,
|
||||||
|
|
|
@ -8,20 +8,31 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
|
|
||||||
import 'package:analyzer/dart/analysis/results.dart';
|
import 'package:analyzer/dart/analysis/results.dart';
|
||||||
import 'package:analyzer/dart/ast/ast.dart';
|
import 'package:analyzer/dart/ast/ast.dart';
|
||||||
import 'package:protevus_isolate/isolate.dart';
|
import 'package:protevus_isolate/isolate.dart';
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
import 'package:io/io.dart';
|
import 'package:io/io.dart';
|
||||||
|
|
||||||
|
/// A class that represents an executable build process.
|
||||||
|
///
|
||||||
|
/// This class extends the [Executable] class and is responsible for
|
||||||
|
/// executing a build process based on the provided build context.
|
||||||
class BuildExecutable extends Executable {
|
class BuildExecutable extends Executable {
|
||||||
|
/// Constructs a new [BuildExecutable] instance.
|
||||||
|
///
|
||||||
|
/// [message] is a map containing the build context information.
|
||||||
BuildExecutable(Map<String, dynamic> message) : super(message) {
|
BuildExecutable(Map<String, dynamic> message) : super(message) {
|
||||||
context = BuildContext.fromMap(message);
|
context = BuildContext.fromMap(message);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The build context for this executable.
|
||||||
late final BuildContext context;
|
late final BuildContext context;
|
||||||
|
|
||||||
|
/// Executes the build process.
|
||||||
|
///
|
||||||
|
/// This method creates a new [Build] instance with the current context
|
||||||
|
/// and calls its execute method.
|
||||||
@override
|
@override
|
||||||
Future execute() async {
|
Future execute() async {
|
||||||
final build = Build(context);
|
final build = Build(context);
|
||||||
|
@ -29,21 +40,33 @@ class BuildExecutable extends Executable {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// A class that manages the build process for non-mirrored builds.
|
||||||
class BuildManager {
|
class BuildManager {
|
||||||
/// Creates a new build manager to compile a non-mirrored build.
|
/// Creates a new [BuildManager] instance.
|
||||||
|
///
|
||||||
|
/// [context] is the [BuildContext] for this build manager.
|
||||||
BuildManager(this.context);
|
BuildManager(this.context);
|
||||||
|
|
||||||
|
/// The build context for this manager.
|
||||||
final BuildContext context;
|
final BuildContext context;
|
||||||
|
|
||||||
|
/// Gets the URI of the source directory.
|
||||||
Uri get sourceDirectoryUri => context.sourceApplicationDirectory.uri;
|
Uri get sourceDirectoryUri => context.sourceApplicationDirectory.uri;
|
||||||
|
|
||||||
|
/// Performs the build process.
|
||||||
|
///
|
||||||
|
/// This method handles the following steps:
|
||||||
|
/// 1. Creates the build directory if it doesn't exist.
|
||||||
|
/// 2. Creates a temporary copy of the script file with the main function stripped.
|
||||||
|
/// 3. Analyzes the script file and removes all main functions.
|
||||||
|
/// 4. Copies the 'not_tests' directory if it exists.
|
||||||
|
/// 5. Runs the build executable in an isolate.
|
||||||
Future build() async {
|
Future build() async {
|
||||||
if (!context.buildDirectory.existsSync()) {
|
if (!context.buildDirectory.existsSync()) {
|
||||||
context.buildDirectory.createSync();
|
context.buildDirectory.createSync();
|
||||||
}
|
}
|
||||||
|
|
||||||
// Here is where we need to provide a temporary copy of the script file with the main function stripped;
|
// Create a temporary copy of the script file with the main function stripped
|
||||||
// this is because when the RuntimeGenerator loads, it needs Mirror access to any declarations in this file
|
|
||||||
var scriptSource = context.source;
|
var scriptSource = context.source;
|
||||||
final strippedScriptFile = File.fromUri(context.targetScriptFileUri)
|
final strippedScriptFile = File.fromUri(context.targetScriptFileUri)
|
||||||
..writeAsStringSync(scriptSource);
|
..writeAsStringSync(scriptSource);
|
||||||
|
@ -52,6 +75,7 @@ class BuildManager {
|
||||||
final parsedUnit = analyzerContext.currentSession
|
final parsedUnit = analyzerContext.currentSession
|
||||||
.getParsedUnit(analyzer.path) as ParsedUnitResult;
|
.getParsedUnit(analyzer.path) as ParsedUnitResult;
|
||||||
|
|
||||||
|
// Find and remove all main functions
|
||||||
final mainFunctions = parsedUnit.unit.declarations
|
final mainFunctions = parsedUnit.unit.declarations
|
||||||
.whereType<FunctionDeclaration>()
|
.whereType<FunctionDeclaration>()
|
||||||
.where((f) => f.name.value() == "main")
|
.where((f) => f.name.value() == "main")
|
||||||
|
@ -63,12 +87,14 @@ class BuildManager {
|
||||||
|
|
||||||
strippedScriptFile.writeAsStringSync(scriptSource);
|
strippedScriptFile.writeAsStringSync(scriptSource);
|
||||||
|
|
||||||
|
// Copy the 'not_tests' directory if it exists
|
||||||
try {
|
try {
|
||||||
await copyPath(
|
await copyPath(
|
||||||
context.sourceApplicationDirectory.uri.resolve('test/not_tests').path,
|
context.sourceApplicationDirectory.uri.resolve('test/not_tests').path,
|
||||||
context.buildDirectoryUri.resolve('not_tests').path);
|
context.buildDirectoryUri.resolve('not_tests').path);
|
||||||
} catch (_) {}
|
} catch (_) {}
|
||||||
|
|
||||||
|
// Run the build executable in an isolate
|
||||||
await IsolateExecutor.run(
|
await IsolateExecutor.run(
|
||||||
BuildExecutable(context.safeMap),
|
BuildExecutable(context.safeMap),
|
||||||
packageConfigURI:
|
packageConfigURI:
|
||||||
|
@ -81,6 +107,9 @@ class BuildManager {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Cleans up the build directory.
|
||||||
|
///
|
||||||
|
/// This method deletes the build directory and its contents if it exists.
|
||||||
Future clean() async {
|
Future clean() async {
|
||||||
if (context.buildDirectory.existsSync()) {
|
if (context.buildDirectory.existsSync()) {
|
||||||
context.buildDirectory.deleteSync(recursive: true);
|
context.buildDirectory.deleteSync(recursive: true);
|
||||||
|
|
|
@ -8,32 +8,70 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
|
/// An abstract class that defines the interface for compilers in the Protevus Platform.
|
||||||
|
///
|
||||||
|
/// This class provides methods for modifying packages, compiling runtime objects,
|
||||||
|
/// and handling post-generation tasks. Implementations of this class are used to
|
||||||
|
/// remove dart:mirrors usage from packages and prepare them for runtime execution.
|
||||||
abstract class Compiler {
|
abstract class Compiler {
|
||||||
/// Modifies a package on the filesystem in order to remove dart:mirrors from the package.
|
/// Modifies a package on the filesystem to remove dart:mirrors usage.
|
||||||
///
|
///
|
||||||
/// A copy of this compiler's package will be written to [destinationDirectory].
|
/// This method creates a copy of the compiler's package in the [destinationDirectory]
|
||||||
/// This method is overridden to modify the contents of that directory
|
/// and modifies its contents to remove all uses of dart:mirrors. This is crucial for
|
||||||
/// to remove all uses of dart:mirrors.
|
/// preparing packages for environments where reflection is not available or desired.
|
||||||
///
|
///
|
||||||
/// Packages should export their [Compiler] in their main library file and only
|
/// Packages should export their [Compiler] in their main library file and only
|
||||||
/// import mirrors in files directly or transitively imported by the Compiler file.
|
/// import mirrors in files directly or transitively imported by the Compiler file.
|
||||||
/// This method should remove that export statement and therefore remove all transitive mirror imports.
|
/// This method should remove that export statement and therefore remove all transitive mirror imports.
|
||||||
|
///
|
||||||
|
/// [destinationDirectory] The directory where the modified package will be written.
|
||||||
void deflectPackage(Directory destinationDirectory);
|
void deflectPackage(Directory destinationDirectory);
|
||||||
|
|
||||||
/// Returns a map of runtime objects that can be used at runtime while running in mirrored mode.
|
/// Compiles and returns a map of runtime objects for use in mirrored mode.
|
||||||
|
///
|
||||||
|
/// This method is responsible for creating runtime representations of objects
|
||||||
|
/// that can be used when the application is running in mirrored mode.
|
||||||
|
///
|
||||||
|
/// [context] The [MirrorContext] providing reflection capabilities for compilation.
|
||||||
|
///
|
||||||
|
/// Returns a [Map] where keys are String identifiers and values are compiled Objects.
|
||||||
Map<String, Object> compile(MirrorContext context);
|
Map<String, Object> compile(MirrorContext context);
|
||||||
|
|
||||||
|
/// A hook method called after package generation is complete.
|
||||||
|
///
|
||||||
|
/// This method can be overridden to perform any necessary cleanup or additional
|
||||||
|
/// tasks after the package has been generated.
|
||||||
|
///
|
||||||
|
/// [context] The [BuildContext] containing information about the build process.
|
||||||
void didFinishPackageGeneration(BuildContext context) {}
|
void didFinishPackageGeneration(BuildContext context) {}
|
||||||
|
|
||||||
|
/// Returns a list of URIs that need to be resolved during the build process.
|
||||||
|
///
|
||||||
|
/// This method can be overridden to specify additional URIs that should be
|
||||||
|
/// resolved as part of the compilation process.
|
||||||
|
///
|
||||||
|
/// [context] The [BuildContext] containing information about the build process.
|
||||||
|
///
|
||||||
|
/// Returns a [List] of [Uri] objects to be resolved.
|
||||||
List<Uri> getUrisToResolve(BuildContext context) => [];
|
List<Uri> getUrisToResolve(BuildContext context) => [];
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Runtimes that generate source code implement this method.
|
/// An abstract class for compilers that generate source code.
|
||||||
|
///
|
||||||
|
/// This class extends the functionality of [Compiler] to include
|
||||||
|
/// the ability to generate source code that represents the runtime behavior.
|
||||||
abstract class SourceCompiler {
|
abstract class SourceCompiler {
|
||||||
/// The source code, including directives, that declare a class that is equivalent in behavior to this runtime.
|
/// Generates source code that declares a class equivalent in behavior to this runtime.
|
||||||
|
///
|
||||||
|
/// This method should be implemented to produce a string of Dart source code
|
||||||
|
/// that includes all necessary directives and class declarations to replicate
|
||||||
|
/// the behavior of the runtime in a static context.
|
||||||
|
///
|
||||||
|
/// [ctx] The [BuildContext] containing information about the build process.
|
||||||
|
///
|
||||||
|
/// Returns a [Future] that resolves to a [String] containing the generated source code.
|
||||||
Future<String> compile(BuildContext ctx) async {
|
Future<String> compile(BuildContext ctx) async {
|
||||||
throw UnimplementedError();
|
throw UnimplementedError();
|
||||||
}
|
}
|
||||||
|
|
|
@ -10,20 +10,26 @@
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
/// Contextual values used during runtime.
|
/// Contextual values used during runtime.
|
||||||
|
///
|
||||||
|
/// This abstract class defines the structure for runtime contexts in the Protevus Platform.
|
||||||
|
/// It provides access to runtime objects and coercion functionality.
|
||||||
abstract class RuntimeContext {
|
abstract class RuntimeContext {
|
||||||
/// The current [RuntimeContext] available to the executing application.
|
/// The current [RuntimeContext] available to the executing application.
|
||||||
///
|
///
|
||||||
/// Is either a `MirrorContext` or a `GeneratedContext`,
|
/// This static property holds either a `MirrorContext` or a `GeneratedContext`,
|
||||||
/// depending on the execution type.
|
/// depending on the execution type.
|
||||||
static final RuntimeContext current = instance;
|
static final RuntimeContext current = instance;
|
||||||
|
|
||||||
/// The runtimes available to the executing application.
|
/// The runtimes available to the executing application.
|
||||||
|
///
|
||||||
|
/// This property stores a collection of runtime objects that can be accessed
|
||||||
|
/// during the application's execution.
|
||||||
late RuntimeCollection runtimes;
|
late RuntimeCollection runtimes;
|
||||||
|
|
||||||
/// Gets a runtime object for [type].
|
/// Gets a runtime object for the specified [type].
|
||||||
///
|
///
|
||||||
/// Callers typically invoke this method, passing their [runtimeType]
|
/// Callers typically invoke this operator, passing their [runtimeType]
|
||||||
/// in order to retrieve their runtime object.
|
/// to retrieve their runtime object.
|
||||||
///
|
///
|
||||||
/// It is important to note that a runtime object must exist for every
|
/// It is important to note that a runtime object must exist for every
|
||||||
/// class that extends a class that has a runtime. Use `MirrorContext.getSubclassesOf` when compiling.
|
/// class that extends a class that has a runtime. Use `MirrorContext.getSubclassesOf` when compiling.
|
||||||
|
@ -31,18 +37,44 @@ abstract class RuntimeContext {
|
||||||
/// In other words, if the type `Base` has a runtime and the type `Subclass` extends `Base`,
|
/// In other words, if the type `Base` has a runtime and the type `Subclass` extends `Base`,
|
||||||
/// `Subclass` must also have a runtime. The runtime objects for both `Subclass` and `Base`
|
/// `Subclass` must also have a runtime. The runtime objects for both `Subclass` and `Base`
|
||||||
/// must be the same type.
|
/// must be the same type.
|
||||||
|
///
|
||||||
|
/// @param type The Type to retrieve the runtime object for.
|
||||||
|
/// @return The runtime object associated with the specified type.
|
||||||
dynamic operator [](Type type) => runtimes[type];
|
dynamic operator [](Type type) => runtimes[type];
|
||||||
|
|
||||||
|
/// Coerces the given [input] to the specified type [T].
|
||||||
|
///
|
||||||
|
/// This method is used to convert or cast the input to the desired type.
|
||||||
|
///
|
||||||
|
/// @param input The input value to be coerced.
|
||||||
|
/// @return The coerced value of type [T].
|
||||||
T coerce<T>(dynamic input);
|
T coerce<T>(dynamic input);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// A collection of runtime objects indexed by type names.
|
||||||
|
///
|
||||||
|
/// This class provides a way to store and retrieve runtime objects
|
||||||
|
/// associated with specific types.
|
||||||
class RuntimeCollection {
|
class RuntimeCollection {
|
||||||
|
/// Creates a new [RuntimeCollection] with the given [map].
|
||||||
|
///
|
||||||
|
/// @param map A map where keys are type names and values are runtime objects.
|
||||||
RuntimeCollection(this.map);
|
RuntimeCollection(this.map);
|
||||||
|
|
||||||
|
/// The underlying map storing runtime objects.
|
||||||
final Map<String, Object> map;
|
final Map<String, Object> map;
|
||||||
|
|
||||||
|
/// Returns an iterable of all runtime objects in the collection.
|
||||||
Iterable<Object> get iterable => map.values;
|
Iterable<Object> get iterable => map.values;
|
||||||
|
|
||||||
|
/// Retrieves the runtime object for the specified type [t].
|
||||||
|
///
|
||||||
|
/// This operator first attempts to find an exact match for the type name.
|
||||||
|
/// If not found, it tries to match a generic type by removing type parameters.
|
||||||
|
///
|
||||||
|
/// @param t The Type to retrieve the runtime object for.
|
||||||
|
/// @return The runtime object associated with the specified type.
|
||||||
|
/// @throws ArgumentError if no runtime object is found for the given type.
|
||||||
Object operator [](Type t) {
|
Object operator [](Type t) {
|
||||||
//todo: optimize by keeping a cache where keys are of type [Type] to avoid the
|
//todo: optimize by keeping a cache where keys are of type [Type] to avoid the
|
||||||
// expensive indexOf and substring calls in this method
|
// expensive indexOf and substring calls in this method
|
||||||
|
@ -67,10 +99,10 @@ class RuntimeCollection {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Prevents a type from being compiled when it otherwise would be.
|
/// An annotation to prevent a type from being compiled when it otherwise would be.
|
||||||
///
|
///
|
||||||
/// Annotate a type with the const instance of this type to prevent its
|
/// Use this annotation on a type to exclude it from compilation.
|
||||||
/// compilation.
|
|
||||||
class PreventCompilation {
|
class PreventCompilation {
|
||||||
|
/// Creates a constant instance of [PreventCompilation].
|
||||||
const PreventCompilation();
|
const PreventCompilation();
|
||||||
}
|
}
|
||||||
|
|
|
@ -7,13 +7,38 @@
|
||||||
* file that was distributed with this source code.
|
* file that was distributed with this source code.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/// Exception thrown when type coercion fails.
|
||||||
|
///
|
||||||
|
/// This exception is used to indicate that an attempt to convert a value
|
||||||
|
/// from one type to another has failed. It provides information about
|
||||||
|
/// the expected type and the actual type of the value.
|
||||||
class TypeCoercionException implements Exception {
|
class TypeCoercionException implements Exception {
|
||||||
|
/// Creates a new [TypeCoercionException].
|
||||||
|
///
|
||||||
|
/// [expectedType] is the type that was expected for the conversion.
|
||||||
|
/// [actualType] is the actual type of the value that couldn't be converted.
|
||||||
|
///
|
||||||
|
/// Example:
|
||||||
|
/// ```dart
|
||||||
|
/// throw TypeCoercionException(String, int);
|
||||||
|
/// ```
|
||||||
TypeCoercionException(this.expectedType, this.actualType);
|
TypeCoercionException(this.expectedType, this.actualType);
|
||||||
|
|
||||||
|
/// The type that was expected for the conversion.
|
||||||
final Type expectedType;
|
final Type expectedType;
|
||||||
|
|
||||||
|
/// The actual type of the value that couldn't be converted.
|
||||||
final Type actualType;
|
final Type actualType;
|
||||||
|
|
||||||
@override
|
@override
|
||||||
|
|
||||||
|
/// Returns a string representation of the exception.
|
||||||
|
///
|
||||||
|
/// The returned string includes both the expected type and the actual type
|
||||||
|
/// to provide clear information about the nature of the coercion failure.
|
||||||
|
///
|
||||||
|
/// Returns:
|
||||||
|
/// A string describing the type coercion exception.
|
||||||
String toString() {
|
String toString() {
|
||||||
return "input is not expected type '$expectedType' (input is '$actualType')";
|
return "input is not expected type '$expectedType' (input is '$actualType')";
|
||||||
}
|
}
|
||||||
|
|
|
@ -10,16 +10,32 @@
|
||||||
import 'dart:async';
|
import 'dart:async';
|
||||||
import 'dart:io';
|
import 'dart:io';
|
||||||
|
|
||||||
|
/// Token used to replace directives in the loader shell.
|
||||||
const String _directiveToken = "___DIRECTIVES___";
|
const String _directiveToken = "___DIRECTIVES___";
|
||||||
|
|
||||||
|
/// Token used to replace assignments in the loader shell.
|
||||||
const String _assignmentToken = "___ASSIGNMENTS___";
|
const String _assignmentToken = "___ASSIGNMENTS___";
|
||||||
|
|
||||||
|
/// A class responsible for generating runtime code.
|
||||||
|
///
|
||||||
|
/// This class allows adding runtime elements and writing them to a specified directory.
|
||||||
class RuntimeGenerator {
|
class RuntimeGenerator {
|
||||||
|
/// List of runtime elements to be generated.
|
||||||
final _elements = <_RuntimeElement>[];
|
final _elements = <_RuntimeElement>[];
|
||||||
|
|
||||||
|
/// Adds a new runtime element to the generator.
|
||||||
|
///
|
||||||
|
/// [name] is the name of the runtime element.
|
||||||
|
/// [source] is the source code of the runtime element.
|
||||||
void addRuntime({required String name, required String source}) {
|
void addRuntime({required String name, required String source}) {
|
||||||
_elements.add(_RuntimeElement(name, source));
|
_elements.add(_RuntimeElement(name, source));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Writes the generated runtime code to the specified directory.
|
||||||
|
///
|
||||||
|
/// [directoryUri] is the URI of the directory where the code will be written.
|
||||||
|
/// This method creates necessary directories, writes the library file,
|
||||||
|
/// pubspec file, and individual runtime element files.
|
||||||
Future<void> writeTo(Uri directoryUri) async {
|
Future<void> writeTo(Uri directoryUri) async {
|
||||||
final dir = Directory.fromUri(directoryUri);
|
final dir = Directory.fromUri(directoryUri);
|
||||||
final libDir = Directory.fromUri(dir.uri.resolve("lib/"));
|
final libDir = Directory.fromUri(dir.uri.resolve("lib/"));
|
||||||
|
@ -48,6 +64,7 @@ class RuntimeGenerator {
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Returns the content of the pubspec.yaml file as a string.
|
||||||
String get pubspecSource => """
|
String get pubspecSource => """
|
||||||
name: generated_runtime
|
name: generated_runtime
|
||||||
description: A runtime generated by package:conduit_runtime
|
description: A runtime generated by package:conduit_runtime
|
||||||
|
@ -57,6 +74,9 @@ environment:
|
||||||
sdk: '>=3.4.0 <4.0.0'
|
sdk: '>=3.4.0 <4.0.0'
|
||||||
""";
|
""";
|
||||||
|
|
||||||
|
/// Returns the shell of the loader file as a string.
|
||||||
|
///
|
||||||
|
/// This shell contains placeholders for directives and assignments.
|
||||||
String get _loaderShell => """
|
String get _loaderShell => """
|
||||||
import 'package:conduit_runtime/runtime.dart';
|
import 'package:conduit_runtime/runtime.dart';
|
||||||
import 'package:conduit_runtime/slow_coerce.dart' as runtime_cast;
|
import 'package:conduit_runtime/slow_coerce.dart' as runtime_cast;
|
||||||
|
@ -80,12 +100,17 @@ class GeneratedContext extends RuntimeContext {
|
||||||
}
|
}
|
||||||
""";
|
""";
|
||||||
|
|
||||||
|
/// Returns the complete source of the loader file.
|
||||||
|
///
|
||||||
|
/// This method replaces the directive and assignment tokens in the loader shell
|
||||||
|
/// with the actual directives and assignments.
|
||||||
String get loaderSource {
|
String get loaderSource {
|
||||||
return _loaderShell
|
return _loaderShell
|
||||||
.replaceFirst(_directiveToken, _directives)
|
.replaceFirst(_directiveToken, _directives)
|
||||||
.replaceFirst(_assignmentToken, _assignments);
|
.replaceFirst(_assignmentToken, _assignments);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Generates the import directives for all runtime elements.
|
||||||
String get _directives {
|
String get _directives {
|
||||||
final buf = StringBuffer();
|
final buf = StringBuffer();
|
||||||
|
|
||||||
|
@ -98,6 +123,7 @@ class GeneratedContext extends RuntimeContext {
|
||||||
return buf.toString();
|
return buf.toString();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Generates the assignments for all runtime elements.
|
||||||
String get _assignments {
|
String get _assignments {
|
||||||
final buf = StringBuffer();
|
final buf = StringBuffer();
|
||||||
|
|
||||||
|
@ -109,14 +135,24 @@ class GeneratedContext extends RuntimeContext {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// A class representing a single runtime element.
|
||||||
class _RuntimeElement {
|
class _RuntimeElement {
|
||||||
|
/// Creates a new runtime element.
|
||||||
|
///
|
||||||
|
/// [typeName] is the name of the type for this runtime element.
|
||||||
|
/// [source] is the source code of this runtime element.
|
||||||
_RuntimeElement(this.typeName, this.source);
|
_RuntimeElement(this.typeName, this.source);
|
||||||
|
|
||||||
|
/// The name of the type for this runtime element.
|
||||||
final String typeName;
|
final String typeName;
|
||||||
|
|
||||||
|
/// The source code of this runtime element.
|
||||||
final String source;
|
final String source;
|
||||||
|
|
||||||
|
/// Returns the relative URI for this runtime element's file.
|
||||||
Uri get relativeUri => Uri.file("${typeName.toLowerCase()}.dart");
|
Uri get relativeUri => Uri.file("${typeName.toLowerCase()}.dart");
|
||||||
|
|
||||||
|
/// Returns the import alias for this runtime element.
|
||||||
String get importAlias {
|
String get importAlias {
|
||||||
return "g_${typeName.toLowerCase()}";
|
return "g_${typeName.toLowerCase()}";
|
||||||
}
|
}
|
||||||
|
|
|
@ -8,9 +8,23 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import 'dart:mirrors';
|
import 'dart:mirrors';
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
|
/// Attempts to cast an object to a specified type at runtime.
|
||||||
|
///
|
||||||
|
/// This function uses Dart's mirror system to perform runtime type checking
|
||||||
|
/// and casting. It handles casting to List and Map types, including their
|
||||||
|
/// generic type arguments.
|
||||||
|
///
|
||||||
|
/// Parameters:
|
||||||
|
/// - [object]: The object to be cast.
|
||||||
|
/// - [intoType]: A [TypeMirror] representing the type to cast into.
|
||||||
|
///
|
||||||
|
/// Returns:
|
||||||
|
/// The object cast to the specified type.
|
||||||
|
///
|
||||||
|
/// Throws:
|
||||||
|
/// - [TypeCoercionException] if the casting fails.
|
||||||
Object runtimeCast(Object object, TypeMirror intoType) {
|
Object runtimeCast(Object object, TypeMirror intoType) {
|
||||||
final exceptionToThrow =
|
final exceptionToThrow =
|
||||||
TypeCoercionException(intoType.reflectedType, object.runtimeType);
|
TypeCoercionException(intoType.reflectedType, object.runtimeType);
|
||||||
|
@ -51,6 +65,16 @@ Object runtimeCast(Object object, TypeMirror intoType) {
|
||||||
throw exceptionToThrow;
|
throw exceptionToThrow;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Determines if a given type is fully primitive.
|
||||||
|
///
|
||||||
|
/// A type is considered fully primitive if it's a basic type (num, String, bool),
|
||||||
|
/// dynamic, or a collection (List, Map) where all nested types are also primitive.
|
||||||
|
///
|
||||||
|
/// Parameters:
|
||||||
|
/// - [type]: A [TypeMirror] representing the type to check.
|
||||||
|
///
|
||||||
|
/// Returns:
|
||||||
|
/// true if the type is fully primitive, false otherwise.
|
||||||
bool isTypeFullyPrimitive(TypeMirror type) {
|
bool isTypeFullyPrimitive(TypeMirror type) {
|
||||||
if (type == reflectType(dynamic)) {
|
if (type == reflectType(dynamic)) {
|
||||||
return true;
|
return true;
|
||||||
|
|
|
@ -8,12 +8,19 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import 'dart:mirrors';
|
import 'dart:mirrors';
|
||||||
|
|
||||||
import 'package:protevus_runtime/runtime.dart';
|
import 'package:protevus_runtime/runtime.dart';
|
||||||
|
|
||||||
|
/// Global instance of the MirrorContext.
|
||||||
RuntimeContext instance = MirrorContext._();
|
RuntimeContext instance = MirrorContext._();
|
||||||
|
|
||||||
|
/// A runtime context implementation using Dart's mirror system.
|
||||||
|
///
|
||||||
|
/// This class provides runtime type information and compilation capabilities
|
||||||
|
/// using reflection.
|
||||||
class MirrorContext extends RuntimeContext {
|
class MirrorContext extends RuntimeContext {
|
||||||
|
/// Private constructor to ensure singleton instance.
|
||||||
|
///
|
||||||
|
/// Initializes the context by compiling all available runtimes.
|
||||||
MirrorContext._() {
|
MirrorContext._() {
|
||||||
final m = <String, Object>{};
|
final m = <String, Object>{};
|
||||||
|
|
||||||
|
@ -31,6 +38,9 @@ class MirrorContext extends RuntimeContext {
|
||||||
runtimes = RuntimeCollection(m);
|
runtimes = RuntimeCollection(m);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// List of all class mirrors in the current mirror system.
|
||||||
|
///
|
||||||
|
/// Excludes classes marked with @PreventCompilation.
|
||||||
final List<ClassMirror> types = currentMirrorSystem()
|
final List<ClassMirror> types = currentMirrorSystem()
|
||||||
.libraries
|
.libraries
|
||||||
.values
|
.values
|
||||||
|
@ -40,6 +50,9 @@ class MirrorContext extends RuntimeContext {
|
||||||
.where((cm) => firstMetadataOfType<PreventCompilation>(cm) == null)
|
.where((cm) => firstMetadataOfType<PreventCompilation>(cm) == null)
|
||||||
.toList();
|
.toList();
|
||||||
|
|
||||||
|
/// List of all available compilers.
|
||||||
|
///
|
||||||
|
/// Returns instances of non-abstract classes that are subclasses of Compiler.
|
||||||
List<Compiler> get compilers {
|
List<Compiler> get compilers {
|
||||||
return types
|
return types
|
||||||
.where((b) => b.isSubclassOf(reflectClass(Compiler)) && !b.isAbstract)
|
.where((b) => b.isSubclassOf(reflectClass(Compiler)) && !b.isAbstract)
|
||||||
|
@ -47,6 +60,10 @@ class MirrorContext extends RuntimeContext {
|
||||||
.toList();
|
.toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves all non-abstract subclasses of a given type.
|
||||||
|
///
|
||||||
|
/// [type] The base type to find subclasses of.
|
||||||
|
/// Returns a list of ClassMirror objects representing the subclasses.
|
||||||
List<ClassMirror> getSubclassesOf(Type type) {
|
List<ClassMirror> getSubclassesOf(Type type) {
|
||||||
final mirror = reflectClass(type);
|
final mirror = reflectClass(type);
|
||||||
return types.where((decl) {
|
return types.where((decl) {
|
||||||
|
@ -68,6 +85,13 @@ class MirrorContext extends RuntimeContext {
|
||||||
}).toList();
|
}).toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Coerces an input to a specified type T.
|
||||||
|
///
|
||||||
|
/// Attempts to cast the input directly, and if that fails,
|
||||||
|
/// uses runtime casting.
|
||||||
|
///
|
||||||
|
/// [input] The object to be coerced.
|
||||||
|
/// Returns the coerced object of type T.
|
||||||
@override
|
@override
|
||||||
T coerce<T>(dynamic input) {
|
T coerce<T>(dynamic input) {
|
||||||
try {
|
try {
|
||||||
|
@ -78,6 +102,11 @@ class MirrorContext extends RuntimeContext {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Retrieves the first metadata annotation of a specific type from a declaration.
|
||||||
|
///
|
||||||
|
/// [dm] The DeclarationMirror to search for metadata.
|
||||||
|
/// [dynamicType] Optional TypeMirror to use instead of T.
|
||||||
|
/// Returns the first metadata of type T, or null if not found.
|
||||||
T? firstMetadataOfType<T>(DeclarationMirror dm, {TypeMirror? dynamicType}) {
|
T? firstMetadataOfType<T>(DeclarationMirror dm, {TypeMirror? dynamicType}) {
|
||||||
final tMirror = dynamicType ?? reflectType(T);
|
final tMirror = dynamicType ?? reflectType(T);
|
||||||
try {
|
try {
|
||||||
|
|
Loading…
Reference in a new issue