RhoMicro.CodeAnalysis.UtilityGenerators 20.0.0

What is this?

This project contains generators and analyzers that help writing generators and analyzers:

Installation

<PackageReference Include="RhoMicro.CodeAnalysis.UtilityGenerators" Version="*">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Attribute Factory

TODO

File Inclusion

Annotate with the IncludeFileAttribute any type or assembly in order to generate code that includes the file containing the target in a generator context via RegisterPostInitializationOutput.

Example:

namespace MyNamespace;

using System;
using RhoMicro.CodeAnalysis;

[IncludeFile]
internal class Foo
{
    public static Int32 Bar() => 42;
}

Foo.cs

// <auto-generated>
// This file was generated by the RhoMicro.CodeAnalysis.FileInclusionGenerator.
// </auto-generated>
using Microsoft.CodeAnalysis;
using System;

namespace RhoMicro.CodeAnalysis.Generated
{
    internal static class IncludedFileSources
    {
        public static void RegisterToContext(IncrementalGeneratorInitializationContext context)
        {
            context.RegisterPostInitializationOutput(c =>
            {c.AddSource(
    "RhoMicro_CodeAnalysis_Foo.g.cs",
$$"""
// <auto-generated>
// This file was generated by RhoMicro.CodeAnalysis.FileInclusionGenerator.
// </auto-generated>
#pragma warning disable
namespace RhoMicro.CodeAnalysis;

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

[IncludeFile]
internal class Foo
{
    public static Int32 Bar() => 42;
}

""");
            });        }
    }
}

IncludedFiles.g.cs

NonEquatable

Annotate types with the NonEquatableAttribute to generate throwing implementations for Equals and GetHashCode. This generator helps detect illegal objects in incremental generator pipelines.

Example:

namespace MyNamespace;

using System;

using RhoMicro.CodeAnalysis;

[NonEquatable]
internal partial class Foo
{
    public static Int32 Bar() => 42;
}

Foo.cs

// <auto-generated>
// This file was generated by RhoMicro.CodeAnalysis.NonEquatableGenerator
// The tool used to generate this code may be subject to license terms;
// this generated code is however not subject to those terms, instead it is
// subject to the license (if any) applied to the containing project.
// </auto-generated>
#pragma warning disable
#nullable enable
namespace MyNamespace;
partial class Foo
{
	/// <inheritdoc/>
	public sealed override bool Equals(object obj) => throw new global::System.NotSupportedException("global::MyNamespace.Foo.Equals(object) is not supported.");
	/// <inheritdoc/>
	public bool Equals(global::MyNamespace.Foo obj) => throw new global::System.NotSupportedException("global::MyNamespace.Foo.Equals(global::MyNamespace.Foo) is not supported.");
	/// <inheritdoc/>
	public sealed override int GetHashCode() => throw new global::System.NotSupportedException("global::MyNamespace.Foo.GetHashCode() is not supported.");
}

MyNamespace_Foo.g.cs

Type Symbol Pattern

Annotate static partial methods with the TypeSymbolPattern attribute to generate an implementation matching a pattern of the attributes type parameter against the method symbol paremeter.

Example:

namespace MyNamespace;

using System;

using Microsoft.CodeAnalysis;

using RhoMicro.CodeAnalysis;

internal static partial class Foo
{
    [TypeSymbolPattern(typeof(List<String>))]
    public static partial Boolean IsStream(ITypeSymbol symbol);
}

Foo.cs

// <auto-generated>
// This file was generated by RhoMicro.CodeAnalysis.TypeSymbolPatternGenerator
// The tool used to generate this code may be subject to license terms;
// this generated code is however not subject to those terms, instead it is
// subject to the license (if any) applied to the containing project.
// </auto-generated>
#pragma warning disable
#nullable enable
namespace MyNamespace;
partial class Foo
{
	public static partial bool IsStringList(global::Microsoft.CodeAnalysis.ITypeSymbol? type)
	{
		var result = type is global::Microsoft.CodeAnalysis.INamedTypeSymbol
		{
			Name: "List",
			TypeArguments:[global::Microsoft.CodeAnalysis.INamedTypeSymbol
			{
				Name: "String",
				TypeArguments:[],
				ContainingNamespace: 
				{
					Name: "System",
					ContainingNamespace:
					{
						IsGlobalNamespace: true
					}
				}
			}
			],
			ContainingNamespace: 
			{
				Name: "Generic",
				ContainingNamespace:
				{
					Name: "Collections",
					ContainingNamespace:
					{
						Name: "System",
						ContainingNamespace:
						{
							IsGlobalNamespace: true
						}
					}
				}
			}
		}
		;
		return result;
	}
	public static bool IsStringList(global::Microsoft.CodeAnalysis.ITypeSymbol? type, [global::System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out global::Microsoft.CodeAnalysis.INamedTypeSymbol? outType)
	{
		var result = IsStringList(type);
		outType = result ? (global::Microsoft.CodeAnalysis.INamedTypeSymbol) type : null;
		return result;
	}
}

MyNamespace_Foo.g.cs_

Note that containing types are not currently supported.

Templating

A string templating engine is provided via the Template attribute.

The templating syntax uses the following delimiters:

• Code blocks:
  • enclosed in {: and :}
  • for C# code
• Render blocks:
  • enclosed in (: and :)
  • for embedding (rendering) expressions or instantiating child templates.
• Template blocks:
  • enclosed in <: and :>
  • to pass child content to child templates.

Examples

Simple Text-Only template

namespace MyNamespace;

using RhoMicro.CodeAnalysis;

[Template(
"""
Hello, world!
Welcome to our templating engine demo.
""")]
internal partial class Foo;

Foo.cs

// <auto-generated>
// This file was generated by RhoMicro.CodeAnalysis.TemplatingGenerator
// The tool used to generate this code may be subject to license terms;
// this generated code is however not subject to those terms, instead it is
// subject to the license (if any) applied to the containing project.
// </auto-generated>
#pragma warning disable
#nullable enable
using static global::RhoMicro.CodeAnalysis.Library.Text.Templating.Indentations;
namespace MyNamespace;
partial class Foo :
	global::RhoMicro.CodeAnalysis.Library.Text.Templating.ITemplate
{
	public override string ToString() => global::RhoMicro.CodeAnalysis.Library.Text.Templating.TemplateRenderer.Render(this);
	public string ToString(global::System.Threading.CancellationToken cancellationToken) => global::RhoMicro.CodeAnalysis.Library.Text.Templating.TemplateRenderer.Render(this, cancellationToken);
	public void Render<__TBody>(ref global::RhoMicro.CodeAnalysis.Library.Text.Templating.TemplateRenderer __renderer, __TBody __body)
	where __TBody : global::RhoMicro.CodeAnalysis.Library.Text.Templating.ITemplate
	{
		__renderer.ThrowIfCancellationRequested();

		// This template was taken from: F:\dev\git\RhoMicro.CodeAnalysis\UtilityGenerators.Tests.E2E\Templating\Foo.cs(6,0)
		const string __template =
"""
Hello, world!
Welcome to our templating engine demo.
""";

		__renderer.Render(__template.AsSpan(0, 52));
	}
}

MyNamespace_Foo.g.cs

Building The Project

This project is running the generators contained against itself. To do this, run the bootstrap.ps1 script.