From 783327145af3121bfb29d9bd14a889de877a3407 Mon Sep 17 00:00:00 2001 From: James Hughes Date: Sat, 4 Jan 2025 03:29:21 +0000 Subject: [PATCH] Updated documentation --- README.md | 266 ++++++++++++++++-- .../Definitions/FluidApiArgumentDefinition.cs | 9 +- .../Definitions/FluidApiDefinition.cs | 10 +- .../FluidGenericArgumentDefinition.cs | 2 +- src/SuperFluid/SuperFluid.csproj | 3 +- 5 files changed, 256 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 8d5c40c..03ea36d 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,250 @@ -# Dotnet 7 Template with CI/CD - -[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hughesjs/SuperFluid/dotnet-ci.yml?label=BUILD%20CI&style=for-the-badge&branch=master)](https://github.com/hughesjs/SuperFluid/actions) -[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hughesjs/SuperFluid/dotnet-cd.yml?label=BUILD%20CD&style=for-the-badge&branch=master)](https://github.com/hughesjs/SuperFluid/actions) +[![GitHub Workflow Status CI](https://img.shields.io/github/actions/workflow/status/hughesjs/SuperFluid/dotnet-ci.yml?label=BUILD%20CI&style=for-the-badge&branch=master)](https://github.com/hughesjs/SuperFluid/actions) +[![GitHub Workflow Status CD](https://img.shields.io/github/actions/workflow/status/hughesjs/SuperFluid/dotnet-cd.yml?label=BUILD%20CD&style=for-the-badge&branch=master)](https://github.com/hughesjs/SuperFluid/actions) ![GitHub top language](https://img.shields.io/github/languages/top/hughesjs/SuperFluid?style=for-the-badge) [![GitHub](https://img.shields.io/github/license/hughesjs/SuperFluid?style=for-the-badge)](LICENSE) +[![Nuget (with prereleases)](https://img.shields.io/nuget/vpre/SuperFluid?style=for-the-badge)](https://nuget.org/packages/SuperFluid/) +[![Nuget](https://img.shields.io/nuget/dt/SuperFluid?style=for-the-badge)](https://nuget.org/packages/SuperFluid/) ![FTB](https://raw.githubusercontent.com/hughesjs/custom-badges/master/made-in/made-in-scotland.svg) -This template repository contains: - -- A .NET 7 Solution - - SuperFluent Class Library - - SuperFluent Unit Test Project (XUnit) - -- Various Workflows - - CodeQL - - Dependabot - - CI Pipeline - - CD Pipeline (to Nuget and Github Package Repo) - - Uses Conventional Commits to Semver Package +--- + +# SuperFluid + +A C# library for generating fluent APIs with grammar. + +# Introduction + +It is often desirable to define an API that allows us to express our intentions as an easily readable method chain. + +The most common example of this in C# would probably be LINQ: + +```cs +var result = myCollection + .Where(item => item.IsActive) + .OrderBy(item => item.Name) + .Select(item => new { item.Id, item.Name }); +``` + +The simple case of this is actually quite simple to implement, you just have each of your methods return the type of the declaring object and `this`. + +```cs +public class Car +{ + public Car Unlock() + { + // Do something + return this; + } + + public Car Enter() + { + // Do something + return this; + } + + public Car Start() + { + // Do something + return this; + } +} + +// Which then lets us do +var car = new Car().Unlock().Enter().Start(); +``` + +However, in this instance, there's nothing stopping us from starting the car before we've unlocked and entered it. + +Clearly, in cases where we want to enforce a valid state, we have to define a grammar for our API. + +Typically, we accomplish this by designing a state machine for our API and then working out the set of all unique combinations of transitions, and creating interfaces for each of these states. +We can then make the return type for each method be the interface that represents the set of transitions that it allows. + +```csharp +public class Car: ICanEnter, ICanStart +{ + public ICanEnter Unlock() + { + // Do something + return this; + } + + public ICanStart Enter() + { + // Do something + return this; + } -- Standard Documents - - Readme - - Code of Conduct (Lunduke) - - Issue Templates - - Contributing + public void Start() + { + // Do something + return this; + } +} + +// Which then lets us do +var car = new Car().Unlock().Enter().Start(); + +// But we can't do +var car = new Car().Unlock().Start(); // Haven't entered yet +var otherCar = new Car().Enter().Start(); // Haven't unlocked yet +``` + +[This write up explains how tricky this can be to do by hand.](https://mitesh1612.github.io/blog/2021/08/11/how-to-design-fluent-api) + +This is where SuperFluid comes in. It lets us define the grammar for your API in a YAML file and then generates the interfaces for you. + +All you then need to do is implement the interfaces and you're good to go. + +# How to Use + +## Installation + +You can install SuperFluid from Nuget: + +``` +Install-Package SuperFluid +``` + +## Defining Your Grammar + +> [!WARNING] +> Your grammar file needs to end with `.fluid.yml` to be picked up by SuperFluid. + +Your grammar is defined in a YAML file following this data structure. + +```cs +record FluidApiDefinition +{ + public required string Name { get; init; } + public required string Namespace { get; init; } + public required FluidApiMethodDefinition InitialState { get; init; } + public required List Methods { get; init; } +} + +record FluidApiMethodDefinition +{ + public required string Name { get; init; } + public string? ReturnType { get; init; } + public List CanTransitionTo { get; init; }; + public List Arguments { get; init; }; + public List GenericArguments { get; init; }; +} + +record FluidApiArgumentDefinition +{ + public required string Type { get; init; } + public required string Name { get; init; } + public string? DefaultValue { get; init; } +} + +record FluidGenericArgumentDefinition +{ + public required List Constraints { get; init; } + public required string Name { get; init; } +} +``` + +Essentially, you do the following: + +- Define the initial state of your API, the namespaces you want your interfaces to be in, and what you want the main interface to be called. +- Define each of the methods that you want to be able to call on your API. +- Define the arguments that each method takes. +- Define the return type of each method. +- Define the states that each method can transition to. + +Then Roslyn will generate the interfaces for you. + +A simple example of this would be: + +```yaml +Name: "ICarActor" +Namespace: "SuperFluid.Tests.Cars" +InitialState: + Name: "Initialize" + CanTransitionTo: + - "Unlock" +Methods: + - Name: "Unlock" + CanTransitionTo: + - "Lock" + - "Enter" + - Name: "Lock" + CanTransitionTo: + - "Unlock" + - Name: "Enter" + CanTransitionTo: + - "Start" + - "Exit" + - Name: "Exit" + CanTransitionTo: + - "Lock" + - "Enter" + - Name: "Start" + Arguments: + # These are deliberately out of order to test that the parser sticks the defaults to the end of the argument list + - Name: "direction" + Type: "string" + DefaultValue: "\"Forward\"" # Note that we need the quotes here + - Name: "speed" + Type: "int" + - Name: "hotwire" + Type: "bool" + DefaultValue: "false" + + # These constraints are pointless but are here to test the parser + GenericArguments: + - Name: "T" + Constraints: + - "class" + - "INumber" + - Name: "X" + Constraints: + - "notnull" + + CanTransitionTo: + - "Stop" + - "Build" + - Name: "Stop" + CanTransitionTo: + - "Start" + - "Exit" + - Name: "Build" + Arguments: + - Name: "color" + Type: "string" + CanTransitionTo: [] + ReturnType: "string" +``` + +Unfortunately, Roslyn isn't great at giving you feedback for source generation errors. In Rider, you can find them under `Problems > Toolset, Environment` if it's actually run. + +I plan to add an analyzer to the project that can give actual feedback to you but this might take a while. + +## Registering Your Grammar File with SuperFluid + +You need to add your grammar file(s) as `AdditionalFiles` in your csproj file. + +```xml + + + +``` + +You can have as many files as you want and they don't have to be in the root of your project. + +## Implementing Your API + +Actually implementing the API is pretty simple. You just implement the root interface that has been generated. In the above example, that would be `ICarActor`. + +You then just implement the methods on that interface, and you're good to go. + +One note, if you use your IDE's feature to generate your method stubs, you might end up with multiple declarations of each method for each explicit interface that has it as a component. In this case, just delete the explicit implementations and implement the method once using the standard `public type name(args)` syntax. This is simply an artefact of the fact that you can arrive at the same method through multiple transitions. + +# Reference Project + +Another one of my projects [PgfPlotsSdk](https://github.com/hughesjs/PgfPlotsSdk) uses SuperFluid to generate a complicated fluent API for working with LaTex PgfPlots. + +The yaml file for this is [here](https://github.com/hughesjs/PgfPlotsSdk/blob/master/src/PgfPlotsSdk/SuperFluidDefinitions/PgfPlotsBuilder.fluid.yml). -Run `./runme.sh` after cloning to rename directories, project files and root namespace to your desired project name. +The relevant class is [here](https://github.com/hughesjs/PgfPlotsSdk/blob/master/src/PgfPlotsSdk/Public/Builders/PgfPlotBuilder.cs). \ No newline at end of file diff --git a/src/SuperFluid/Internal/Definitions/FluidApiArgumentDefinition.cs b/src/SuperFluid/Internal/Definitions/FluidApiArgumentDefinition.cs index e1062cd..3015ecc 100644 --- a/src/SuperFluid/Internal/Definitions/FluidApiArgumentDefinition.cs +++ b/src/SuperFluid/Internal/Definitions/FluidApiArgumentDefinition.cs @@ -5,8 +5,7 @@ namespace SuperFluid.Internal.Definitions; [DebuggerDisplay("{Type} {Name}")] internal record FluidApiArgumentDefinition { - public required string Type { get; init; } - public required string Name { get; init; } - - public string? DefaultValue { get; init; } -} + public required string Type { get; init; } + public required string Name { get; init; } + public string? DefaultValue { get; init; } +} \ No newline at end of file diff --git a/src/SuperFluid/Internal/Definitions/FluidApiDefinition.cs b/src/SuperFluid/Internal/Definitions/FluidApiDefinition.cs index 3382dae..bfd1c35 100644 --- a/src/SuperFluid/Internal/Definitions/FluidApiDefinition.cs +++ b/src/SuperFluid/Internal/Definitions/FluidApiDefinition.cs @@ -5,8 +5,8 @@ namespace SuperFluid.Internal.Definitions; [DebuggerDisplay("{Name}")] internal record FluidApiDefinition { - public required string Name { get; init; } - public required string Namespace { get; init; } - public required FluidApiMethodDefinition InitialState { get; init; } - public required List Methods { get; init; } -} + public required string Name { get; init; } + public required string Namespace { get; init; } + public required FluidApiMethodDefinition InitialState { get; init; } + public required List Methods { get; init; } +} \ No newline at end of file diff --git a/src/SuperFluid/Internal/Definitions/FluidGenericArgumentDefinition.cs b/src/SuperFluid/Internal/Definitions/FluidGenericArgumentDefinition.cs index 3e6c2ff..66cc906 100644 --- a/src/SuperFluid/Internal/Definitions/FluidGenericArgumentDefinition.cs +++ b/src/SuperFluid/Internal/Definitions/FluidGenericArgumentDefinition.cs @@ -7,4 +7,4 @@ internal record FluidGenericArgumentDefinition { public required List Constraints { get; init; } public required string Name { get; init; } -} +} \ No newline at end of file diff --git a/src/SuperFluid/SuperFluid.csproj b/src/SuperFluid/SuperFluid.csproj index 863e302..601de01 100644 --- a/src/SuperFluid/SuperFluid.csproj +++ b/src/SuperFluid/SuperFluid.csproj @@ -11,7 +11,8 @@ James Hughes An incremental source generator for fluent APIs with grammar https://github.com/hughesjs/SuperFluid - https://github.com/hughesjs/SuperFluid/blob/master/LICENSE + MIT + README.md https://github.com/hughesjs/SuperFluid.git git ./README.md