RhoMicro.CodeAnalysis.UnionsGenerator 14.0.0-alpha.25

Unions

Read about union types here: https://en.wikipedia.org/wiki/Union_type

Licensing

This source code generator is licensed to you under the GplV3 (see the license). The code generated by the tool, is however not subject to this license, but rather the license of whatever project it is being used in.

Features

• generate rich examination and conversion api
• automatic relation type detection (congruency, superset, subset, intersection)
• generate conversion operators
• generate meaningful api names like myUnion.IsResult or MyUnion.CreateFromResult(result)
• generate the most efficient impementation for your usecase and optimize against boxing or size constraints
• group representable types and use members like myUnion.IsNumber
• use System.Text.Json serialization

Installation

Package Reference:

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

CLI:

dotnet add package RhoMicro.CodeAnalysis.UnionsGenerator

Note: The source code generator will generate netstandard2.0 compliant code that potentially uses newer language features. It is expected that consumers enable the <LangVersion>11.0</LangVersion> flag. This could change in the future to support a wider number of language versions, however the netstandard2.0 constraint will remain. The generator generates members (e.g.: NotNullWhenAttribute ) that rely on special types not required by netstandard2.0, therefore under some circumstances (i.e. in analyzers) a polyfill (see PolySharp) is required.

How To Use

Annotate your union type with the UnionType attribute:

[UnionType<String, Double>]
readonly partial struct Union;

Use your union type:

Union u = "Hello, World!"; //implicitly converted
u = 32; //implicitly converted
u = false; //CS0029	Cannot implicitly convert type 'bool' to 'Union'

Available Attributes and Instructions

UnionTypeAttribute<T0> and UnionTypeAttribute

General Usage

Use UnionTypeAttribute<T0> to add T0 to the list of representable types:

[UnionType<Int32>]
[UnionType<String>]
partial struct IntOrString;

Usage:

IntOrString u = "Hello, World!"; //implicitly converted
u = 32; //implicitly converted

Use UnionTypeAttribute on type parameters to add the targeted type parameter to the list of representable types:

partial struct GenericUnion<[UnionType] T0, [UnionType] T1>;

Usage:

var u = GenericUnion<Int32, String>.CreateFromT1("Hello, World!");
u = GenericUnion<Int32, String>.CreateFromT0(32);

Note: due to compiler restrictions no conversions from or to generic type parameters are generated. Using factory methods is an alternative way of creating union instances.

Alias

Define aliae for generated members using Alias , e.g.:

[UnionType<List<String>>(Alias = "MultipleNames")]
[UnionType<String>(Alias = "SingleName")]
partial struct Names;

Usage:

Names n = "John";
if(n.IsSingleName)
{
    var singleName = n.AsSingleName;
} else if(n.IsMultipleNames)
{
    var multipleNames = n.AsMultipleNames;
}

Options

Define miscellaneous behaviour for the represented type using Options.

ImplicitConversionIfSolitary

Instructs the generator to emit an implicit conversion to the representable type if it is the only one. In effect, this option will enable the union type to act as an alias wrapper for the representable type.

This option is enabled by default.

[UnionType<Int32>(Options = UnionTypeOptions.ImplicitConversionIfSolitary)]
partial struct Int32Alias;

Usage:

var i = 32;
Int32Alias u = i;
i = u;

Nullable

Instructs the generator to treat the representable reference type as nullable, allowing for null arguments in factories, conversions etc.

[UnionType<String>(Options = UnionTypeOptions.Nullable)]
[UnionType<List<String>>]
partial struct NullableStringUnion;

Usage:

NullableStringUnion u = (String?)null;
u = new List<String>();
u = "Nonnull String";
u = (List<String>?)null; //CS8604 - Possible null reference argument for parameter.

Storage

Optimize the generated storage implementation for the representable type against boxing or size constraints using Storage.

Auto

The generator will automatically decide on a storage strategy.

If the representable type is known to be a value type, this will store values of that type inside a shared value type container. Boxing will not occur.

If the representable type is known to be a reference type, this will store values of that type inside a shared reference type container.

If the representable type is neither known to be a reference type nor a value type, this option will cause values of that type to be stored inside a shared reference type container. If the representable type is a generic type parameter, boxing will occur for value type arguments to that parameter.

Reference

The generator will always store values of the representable type inside a shared reference type container.

If the representable type is known to be a value type, boxing will occur.

If the representable type is a generic type parameter, boxing will occur for value type arguments to that parameter.

Value

The generator will attempt to store values of the representable type inside a value type container.

If the representable type is known to be a value type, this will store values of that type inside a shared value type container. Boxing will not occur.

If the representable type is known to be a reference type, this will store values of that type inside a shared reference type container. Boxing will not occur.

If the representable type is neither known to be a reference type nor a value type, this option will cause values of that type to be stored inside a shared value type container. If the representable type is a generic type parameter, an exception of type TypeLoadException will occur for reference type arguments to that parameter.

Field

The generator will attempt to store values of the representable type inside a dedicated container for that type.

If the representable type is known to be a value type, this will store values of that type inside a dedicated value type container. Boxing will not occur.

If the representable type is known to be a reference type, this will store values of that type inside a dedicated reference type container.

If the representable type is neither known to be a reference type nor a value type, this option will cause values of that type to be stored inside a dedicated strongly typed container. Boxing will not occur.

Groups

Group representable types into categories by assigning Groups:

[UnionType<Int32, Single>(Groups = ["Number"])]
[UnionType<String, Char>(Groups = ["Text"])]
partial struct GroupedUnion;

Usage:

GroupedUnion u = "Hello, World!";
if(u.IsNumberGroup)
{
    Assert.Fail("Expected union to be text.");
}
if(!u.IsTextGroup)
{
    Assert.Fail("Expected union to be text.");
}

u = 32f;
if(!u.IsNumberGroup)
{
    Assert.Fail("Expected union to be number.");
}
if(u.IsTextGroup)
{
    Assert.Fail("Expected union to be number.");
}

UnionTypeAttribute<T0..Tn>

The generic UnionTypeAttribute types allow to define multiple representable types inline. Except for Alias, they support all of the features that UnionTypeAttribute<T0> and UnionTypeAttribute provide. Any such features will be applied to all representable types listed in the type arguments list.

For sample usage, see Groups.

UnionTypeSettingsAttribute

TODO: update to current changes

This attribute may target either a union type or an assembly. When targeting a union type, it defines settings specific to that type. If, however, the attribute is annotating an assembly, it supplies the default settings for every union type in that assembly.

• ConstructorAccessibility: define the accessibility of generated constructors:

public enum ConstructorAccessibilitySetting
{
    // Generated constructors should always be private, unless
    // no conversion operators are generated for the type they
    // accept. This would be the case for interface types or
    // supertypes of the target union.
    PublicIfInconvertible,
    // Generated constructors should always be private.
    Private,
    // Generated constructors should always be public
    Public
}

• DiagnosticsLevel: define the reporting of diagnostics:

[Flags]
public enum DiagnosticsLevelSettings
{
    // Instructs the analyzer to report info diagnostics.
    Info = 0x01,
    // Instructs the analyzer to report warning diagnostics.
    Warning = 0x02,
    // Instructs the analyzer to report error diagnostics.
    Error = 0x04,
    // Instructs the analyzer to report all diagnostics.
    All = Info + Warning + Error
}

• ToStringSetting: define how implementations of ToString should be generated:

public enum ToStringSetting
{
    // The generator will emit an implementation that returns detailed information, including:
    // - the name of the union type
    // - a list of types representable by the union type
    // - an indication of which type is being represented by the instance
    // - the value currently being represented by the instance
    Detailed,
    // The generator will not generate an implementation of ToString.
    None,
    // The generator will generate an implementation that returns the result of
    // calling ToString on the currently represented value.
    Simple
}

• Layout: generate a layout attribute for size optimization

public enum LayoutSetting
{
    // Generate an annotation optimized for size.
    Small,
    // Do not generate any annotations.
    Auto
}

• Generic Names: define how generic type parameter names should be generated:

// Gets or sets the name of the generic parameter for generic Is, As and factory methods. 
// Set this property in order to avoid name collisions with generic union type parameters
public String GenericTValueName { get; set; }
// Gets or sets the name of the generic parameter for the Match method. 
// Set this property in order to avoid name collisions with generic union type parameters
public String MatchTypeName { get; set; }

RelationAttribute

This attribute defines a relation between the targeted union type the supplied type. The following relations are available:

• None
• Congruent
• Superset
• Subset
• Intersection

The generator will automatically detect the relation between two union types. The only requirement is for one of the two types to be annotated with the RelationAttribute:

[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[Relation(typeof(CongruentUnion))]
[Relation(typeof(SubsetUnion))]
[Relation(typeof(SupersetUnion))]
[Relation(typeof(IntersectionUnion))]
readonly partial struct Union;

[UnionType(typeof(Double))]
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
sealed partial class CongruentUnion;

[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
partial class SubsetUnion;

[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[UnionType(typeof(Int32))]
partial struct SupersetUnion;

[UnionType(typeof(Int16))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[UnionType(typeof(List<Byte>))]
partial class IntersectionUnion;

Contrived Example

In our imaginary usecase, a user shall be retrieved from the infrastructure via a name query. The following types will be found throughout the example:

sealed record User(String Name);

enum ErrorCode
{
    NotFound,
    Unauthorized
}

readonly record struct MultipleUsersError(Int32 Count);

The User type represents a user. The ErrorCode represents an error that does not contain additional information, like MultipleUsersError does. It represents multiple users having been found while only one was requested.

We define a union type to represent our imaginary query:

[UnionType(typeof(ErrorCode))]
[UnionType(typeof(MultipleUsersError))]
[UnionType(typeof(User))]
readonly partial struct GetUserResult;

Instances of GetUserResult can represent either an instance of ErrorCode, MultipleUsersError or User.

It will be used in a service façade like so:

interface IUserService
{
    GetUserResult GetUserByName(String name);
}

A repository abstracts over the underlying infrastructure:

interface IUserRepository
{
    IQueryable<User> UsersByName(String name);
}

Access violations would be communicated through the repository using the following exception type:

sealed class UnauthorizedDatabaseAccessException : Exception;

An implementation of the IUserService is provided as follows:

sealed class UserService : IUserService
{
    public UserService(IUserRepository repository) => _repository = repository;

    private readonly IUserRepository _repository;

    public GetUserResult GetUserByName(String name)
    {
        IQueryable<User> users;
        try
        {
            users = _repository.UsersByName(name);
        } catch(UnauthorizedDatabaseAccessException)
        {
            return ErrorCode.Unauthorized;
        }

        var reifiedUsers = users.ToArray();
        if(reifiedUsers.Length == 0)
        {
            return ErrorCode.NotFound;
        } else if(reifiedUsers.Length > 1)
        {
            return new MultipleUsersError(reifiedUsers.Length);
        }

        return reifiedUsers[0];
    }
}

As you can see, possible representations of GetUserResult are implicitly converted and returned by the service. Users of OneOf will be familiar with this.

On the consumer side of this api, a generated Match function helps with transforming the union instance to another type:

sealed class UserModel
{
    public UserModel(IUserService service) => _service = service;

    private readonly IUserService _service;

    public String ErrorMessage { get; private set; } = String.Empty;
    public User? User { get; private set; }
    public void SetUser(String name)
    {
        var getUserResult = _service.GetUserByName(name);
        User = getUserResult.Match(
            HandleErrorCode,
            HandleMultipleResult,
            user => user);
    }
    private User? HandleErrorCode(ErrorCode code)
    {
        ErrorMessage = code switch
        {
            ErrorCode.NotFound => "The user could not be located.",
            ErrorCode.Unauthorized => "You are not authorized to access users.",
            _ => throw new NotImplementedException()
        };
        return null;
    }
    private User? HandleMultipleResult(MultipleUsersError result)
    {
        ErrorMessage = $"{result.Count} users have been located. The name was not precise enough.";
        return null;
    }
}

Here is a list of some generated members on the GetUserResult union type (implementations have been elided):

/*Factories*/
public static GetUserResult Create(ErrorCode value);
public static GetUserResult Create(MultipleUsersResult value);
public static GetUserResult Create(User value);
public static Boolean TryCreate<TValue>(TValue value, out GetUserResult instance);
public static GetUserResult Create<TValue>(TValue value);

/*Handling Methods*/
public void Switch(
    Action<ErrorCode> onErrorCode, 
    Action<MultipleUsersResult> onMultipleUsersResult,
    Action<User> onUser);

public TResult Match<TResult>(
    Func<ErrorCode, TResult> onErrorCode,
    Func<MultipleUsersResult, TResult> onMultipleUsersResult,
    Func<User, TResult> onUser);

/*Casting & Conversion*/
public Boolean Is<TValue>();

public Boolean Is(Type type);

public TValue As<TValue>();

public Boolean IsErrorCode;
public ErrorCode AsErrorCode;

public Boolean IsMultipleUsersResult;
public MultipleUsersResult AsMultipleUsersResult;

public Boolean IsUser;
public User AsUser;

public Type GetRepresentedType();

public static implicit operator GetUserResult(ErrorCode value);
public static explicit operator ErrorCode(GetUserResult union);

public static implicit operator GetUserResult(MultipleUsersResult value);
public static explicit operator MultipleUsersResult(GetUserResult union);

public static implicit operator GetUserResult(User value);
public static explicit operator User(GetUserResult union);