SourceGeneratorUtils 1.2.0

SourceGeneratorUtils

<p align="center">An essential library equipped with utility functions and helpers to aid in writing source files for source generators or for general purposes.</p>

Context and goals

In my journey of implementing source generators, I noticed recurrent similarities in each project. Handling source generation on nested types, for example, appeared frequently. Rewriting this logic on every source generator felt redundant and time-consuming, prompting me to abstract and manage most of these routine writing tasks. Hence, SourceGeneratorUtils was created.

The main objective is to enable developers to dive straight into writing the code necessary for their source generators, instead of handling the boilerplate writing logic for namespaces, containing types etc.. With SourceGeneratorUtils, users can supply an instance of ITypeSpec that could be mapped from Roslyn's ISymbol (for source generators) or some parsed files with type definitions (for general purpose). Users can then focus on implementing CSharpSourceBlockWriter<TDescriptor> with logic specific to the target code to generate.

Installation

NuGet Releases

This package can be found on nuget.org:

> dotnet add package SourceGeneratorUtils

CI Builds

For those who want to utilize builds from this repository's main branch, install them from the NuGet Github Package Registry using this repo's package feed. You'll need your own Github Personal Access Token (PAT) in order to access the registry. For information on obtaining your PAT, see the Working with the NuGet registry article.

1. At the command line, navigate to your user profile directory and run the following command to add the package feed to your NuGet configuration, replacing the <GITHUB_USER_NAME> and <PERSONAL_ACCESS_TOKEN> placeholders with the relevant values:

   > dotnet nuget add source -n GitHub -u <GITHUB_USER_NAME> -p <PERSONAL_ACCESS_TOKEN> https://nuget.pkg.github.com/thenameless314159/index.json
   

2. You should now be able to add a reference to the package specifying a version from the repository packages feed

What's Included?

This library provides a variety of types that help the conception of source generation logic :

• SourceWriter - A minimal wrapper over StringBuilder, it handles indentation in a straightforward manner.
• SourceBuilder - Another thin wrapper, this time over a dictionary, to store generated source files and export them to disk. The following type can populate it:
• SourceFileEmitterBase<TSpec> - Encapsulates all the necessary logic to write a C# source file ready for compilation. This is the main abstraction that users should implement to write their own source generation logic.
• SourceCodeEmitter<TSpec> - An abstraction that allows developers to break down their source generation logic into smaller components. It is used by SourceFileEmitter<TSpec> to write the source file.
• SourceFileEmitterOptions - A simple class that holds options for source file generation within a SourceFileEmitterBase<TSpec>.

Usage

Usage documentation and samples are in progress and will be available soon. My apologies for any inconvenience.

Acknowledgements

• I would like to thank Damian Edwards for the inspiration I drew from his CI workflows.
• Gratitude is also extended to the individual who wrote SourceWriter at Microsoft.