Chickensoft.Introspection
1.5.0
See the version list below for details.
dotnet add package Chickensoft.Introspection --version 1.5.0
NuGet\Install-Package Chickensoft.Introspection -Version 1.5.0
<PackageReference Include="Chickensoft.Introspection" Version="1.5.0" />
paket add Chickensoft.Introspection --version 1.5.0
#r "nuget: Chickensoft.Introspection, 1.5.0"
// Install Chickensoft.Introspection as a Cake Addin #addin nuget:?package=Chickensoft.Introspection&version=1.5.0 // Install Chickensoft.Introspection as a Cake Tool #tool nuget:?package=Chickensoft.Introspection&version=1.5.0
๐ฎ Introspection
Create mixins and generate metadata about types at build time to enable reflection in ahead-of-time (AOT) environments.
<p align="center"> <img alt="Chickensoft.Introspection" src="Chickensoft.Introspection/icon.png" width="200"> </p>
๐ฅ Installation
Find the latest version of the Introspection and Introspection Generator packages from nuget and add them to your C# project.
<PackageReference Include="Chickensoft.Introspection" Version=... />
<PackageReference Include="Chickensoft.Introspection.Generator" Version=... PrivateAssets="all" OutputItemType="analyzer" />
๐ Background
This package powers several other Chickensoft tools and directly supersedes SuperNodes. It is designed to be leveraged by simple metaprogramming tools like PowerUps, as well as provide the foundation for other systems, such as Serialization.
The introspection package provides the following features:
- Create a registry of all types visible from the global scope.
- Generate metadata about visible types.
- Track types by id and version.
- Allow types to implement and look up mixins.
- Compute and cache type hierarchies, attributes, and properties.
- Track generic types of properties in a way that enables convenient serialization in AOT environments.
The introspection generator is designed to be performant as a project grows. The generator only uses syntax information to generate metadata, rather than relying on the C# analyzer's symbol data, which can be very slow.
๐ Usage
๐งโโ๏ธ Introspective Types
Simply add the [Meta]
attribute to a partial class or record that is visible from the global scope.
using Chickensoft.Introspection;
[Meta]
public partial class MyType;
public partial class Container {
// Nested types are supported, too.
[Meta]
public partial class MyType;
}
The generator will generate a type registry for your assembly that lists every type it can discover in the codebase, along with their generated metadata. Introspective types have much additional metadata compared to types without the [Meta]
attribute.
The generated registry automatically registers types with the Introspection library's type graph using a module initializer, so no action is needed on the developer's part. The module initializer registration process also performs some logic at runtime to resolve the type graph and cache the type hierarchy in a way that makes it performant to lookup. This preprocessing runs in roughly linear time and is negligible.
All introspective types must be a class or record, partial, visible from the global scope. Introspective types cannot be generic.
๐ชช Identifiable Types
An introspective type can also be an identifiable type if it is given the [Id]
attribute. Identifiable types get additional metadata generated about them, allowing them to be looked up by their identifier.
[Meta, Id("my_type")]
public partial class MyType;
โคต๏ธ The Type Graph
The type graph can be used to query information about types at runtime. If the type graph has to compute a query, the results are cached for all future queries. Most api's are simple O(1) lookups.
// Get every type that is a valid subtype of Ancestor.
var allSubtypes = Types.Graph.GetDescendantSubtypes(typeof(Ancestor));
// Only get the types that directly inherit from Parent.
var subtypes = Types.Graph.GetSubtypes(typeof(Parent));
// Get generated metadata associated with a type.
if (Types.Graph.GetMetadata(typeof(Model)) is { } metadata) {
// ...
}
// Get properties, including those from parent introspective types.
var properties = Types.Graph.GetProperties(typeof(Model));
// ...see the source for all possible type graph operations.
๐ฏโโ๏ธ Versioning
All concrete introspective types have a simple integer version associated with them. By default, the version is 1
. You can use the [Version]
attribute to denote the version of an introspective type.
[Meta, Version(2)]
public partial class MyType;
// Or, multiple versions of the same identifiable type.
[Meta, Id("my_type")]
public abstract class MyType;
[Meta, Version(1)]
public class MyType1 : MyType;
[Meta, Version(2)]
public class MyType2 : MyType;
[Meta, Version(3)]
public class MyType3 : MyType;
During type registration, the type graph will "promote" introspective types which inherit from an identifiable type to an identifiable type themselves, sharing the same identifier as their parent or ancestor identifiable type. Promoted identifiable types must, however, have uniquely specified versions.
๐ Metadata Types
The introspection generator differentiates between the following categories of types and constructs the appropriate metadata for the type, depending on which category it belongs to.
Category | Metadata |
---|---|
๐ซฅ Abstract or generic types | TypeMetadata |
๐ชจ Non-generic, concrete types | ConcreteTypeMetadata |
๐ป Abstract introspective types | AbstractIntrospectiveTypeMetadata |
๐ฟ Concrete introspective types | IntrospectiveTypeMetadata |
๐ Abstract identifiable types | AbstractIdentifiableTypeMetadata |
๐ชช Concrete identifiable types | IdentifiableTypeMetadata |
You can check the type of metadata that a type has to understand what its capabilities are. Each type of metadata has different fields associated with it.
In addition to the metadata classes, each metadata class implements the appropriate interfaces:
Metadata | Conforms To |
---|---|
TypeMetadata |
ITypeMetadata |
ConcreteTypeMetadata |
..., IClosedTypeMetadata , IConcreteMetadata |
IntrospectiveTypeMetadata |
..., IConcreteIntrospectiveTypeMetadata |
IdentifiableTypeMetadata |
..., IIdentifiableTypeMetadata |
... etc. |
public class MyTypeReceiver : ITypeReceiver {
public void Receive<T>() {
// Do whatever you want with the type as a generic parameter.
}
}
var metadata = Types.Graph.GetMetadata(typeof(Model));
if (metadata is IClosedTypeMetadata closedMetadata) {
// Closed types allow you to receive the type as a generic argument in
// a TypeReceiver's Receive<T>() method.
closedMetadata.GenericTypeGetter(new MyTypeReceiver())
}
if (metadata is IConcreteTypeMetadata concreteMetadata) {
// Concrete types allow you to create a new instance of the type, if
// it has a parameterless constructor.
var instance = concreteMetadata.Factory();
}
if (metadata is IIntrospectiveTypeMetadata introMetadata) {
// Introspective types provide a metatype instance which allows you to access
// more information about that type, such as its properties and attributes.
var metatype = introMetadata.Metatype;
}
if (metadata is IConcreteIntrospectiveTypeMetadata concreteIntroMetadata) {
// Concrete introspective types have a version number.
var version = concreteIntroMetadata.Version;
}
if (metadata is IIdentifiableTypeMetadata idMetadata) {
// Identifiable types have an id.
var id = idMetadata.Id;
}
ฮ Metatypes
The introspection generator generates additional metadata for introspective and identifiable types known as a "metatype." A type's metatype information can be accessed from its metadata.
var metadata = Types.Graph.GetMetadata(typeof(Model));
if (metadata is IIntrospectiveTypeMetadata introMetadata) {
var metatype = introMetadata.Metatype;
foreach (var attribute in metatype.Attributes) {
// Iterate the attributes on an introspective type.
}
foreach (var property in metatype.Properties) {
// Iterate the properties of an introspective type.
if (property.Setter is { } setter) {
// We can set the value of the property.
setter(obj, value);
}
// etc.
}
}
Metatype data provides information about a specific type, its properties, and attributes. The type graph combines metatype information with its understanding of the type hierarchy to enable you to fetch all properties of an introspective type, including those it inherited from other introspective types. Metatypes will only contain information about the type itself, not anything it inherits from.
To see all of the information that a metatype exposes, please see the Metatype interface definition.
๐๏ธ Mixins
The introspection generator allows you to create mixins to add additional functionality to the type they are applied to. Unlike default interface method implementations, mixins are able to add instance state via a blackboard. Every introspective type has a MixinState
blackboard which allows mixins to add instance data to the type they are applied to.
Additionally, mixins must implement a single handler method. An introspective type's Metatype
has a Mixins
property containing a list of mixin types that were applied to it. Additionally, a MixinHandler
table is provided which maps the mixin type to a closure which invokes the mixin's handler.
Introspective type instances can also cast themselves to IIntrospective
to invoke a given mixin easily.
// Declare a mixin
[Mixin]
public interface IMyMixin : IMixin<IMyMixin> {
void IMixin<IMyMixin>.Handler() { }
}
// Use a mixin
[Meta(typeof(Mixin))]
public partial class MyModel {
// Use mixins
public void MyMethod() {
// Call all applied mixin handlers
(this as IIntrospective).InvokeMixins();
// Call a specific mixin handler
(this as IIntrospective).InvokeMixin(typeof(IMyMixin));
}
}
๐ฃ Package generated from a ๐ค Chickensoft Template โ https://chickensoft.games
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- Chickensoft.Collections (>= 1.6.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Chickensoft.Introspection:
Package | Downloads |
---|---|
Chickensoft.LogicBlocks
Human-friendly, hierarchical state machines for games and apps in C#. |
|
Chickensoft.Serialization
Easy to use serializable models with AOT compilation support and System.Text.Json compatibility. |
GitHub repositories (3)
Showing the top 3 popular GitHub repositories that depend on Chickensoft.Introspection:
Repository | Stars |
---|---|
chickensoft-games/GameDemo
The Chickensoft Game Demo โ a fully tested, third-person 3D game built with Godot and C#. Now with saving and loading!
|
|
chickensoft-games/LogicBlocks
Human-friendly, hierarchical and serializable state machines for games and apps in C#.
|
|
chickensoft-games/AutoInject
Node-based dependency injection for C# Godot scripts at build-time, including utilities for automatic node-binding, additional lifecycle hooks, and .net-inspired notification callbacks.
|
Chickensoft.Introspection release.