dotnet 用 SourceGenerator 源代碼生成技術實現中文編程語言

相信有很多伙伴都很喜歡自己造編程語言，在有現代的很多工具鏈的幫助下，實現一門編程語言，似乎已不是一件十分困難的事情。我利用 SourceGenerator 源代碼生成技術實現了一個簡易的中文編程語言，核心原理是將中文編程語言翻譯為 C# 語言，從而完成後續的所有對接，完成了最簡單的構建和運行。本文將告訴大家這個有趣的方式是如何實現

開始之前，先給大家看看效果

這是我設計的 csg 格式（Chinese programming language by SourceGenerator）的中文編程語言，設計上完全參考（抄襲）了中文巨集的實現方式。原本我是考慮抄襲 易語言 的，但是 易語言 更貼近是 VB 系的方式（？ 似乎也不能這麼說）感覺不是我隨便就能寫出來的。我只是想著學習源代碼生成技術，順帶測試一下自己能否很隨意的就寫出一個新的編程語言。當然，測試結果是我不能很隨意就寫出一個新的編程語言

本文所設計的 csg 格式的中文編程語言，僅僅只能用來做演示使用，絲毫不能用在實際項目里。本文僅僅只是用來告訴大家一個簡易的方法來完成自己創建一門編程語言

本文所設計的 csg 格式的中文編程語言，能夠和 C# 完美的結合，畢竟實際參與構建的就是 C# 代碼。我在本文的最後給出了所有的代碼的下載方式，要求在 VS 2022 較新版本上才能成功運行

以下是 csg 的代碼，也是本文效果里所使用的代碼

引用命名空間 系統;

定義命名空間 這是一個命名空間;

類型 這是測試類型
{
    公開的 靜態的 無返回值類型的 測試輸出()
    {
        控制台.輸出一行文本("你好");
    }
}

可以看到，這是全部採用中文編寫的一段代碼。相信大家看到上面的代碼，在熟悉 C# 的前提下，能反應過來這段代碼的作用

儘管這是採用中文編寫的，但不代表著任何人都能讀懂這段代碼的作用。因為這僅僅只是使用中文對 C# 的關鍵詞進行翻譯而已。同理的，也不是任何會英文的人都能讀懂代碼

那以上代碼可以被如何調用呢？可以完全和 C# 交互，被 C# 直接調用，如以下代碼，在 C# 代碼的主函數裡面調用 測試輸出() 方法。這是利用了 C# 裡面允許標識符支持 Utf-8 編寫，而不僅僅是 ASCII 編碼的字元。換句話說是使用中文作用方法名、類名、屬性名等，在 C# 里都是合法的

// Program.cs

using 這是一個命名空間;

這是測試類型.測試輸出();

以上是採用 C# 9.0 新特性——頂級語句，無須加上類型和主函數定義，直接編寫代碼體即主函數執行代碼體的。如此可以極大簡化代碼量

執行代碼，可以看到控制台輸出了 你好 字元串，證明瞭代碼的構建執行正常

接下來將告訴大家實現的原理和實現的細節方法，在開始之前，期望大家已對 C# dotnet 的基礎知識熟悉，對 dotnet 整個構建過程熟悉，瞭解源代碼生成技術，本文將略過基礎知識

先新建兩個項目，分別是 JelallnalukebaqeLairjaybearjair 和 JelallnalukebaqeLairjaybearjair.Analyzers 兩個控制台項目。其中 JelallnalukebaqeLairjaybearjair 項目就是用來編寫中文編程的項目。而 JelallnalukebaqeLairjaybearjair.Analyzers 是一個分析器項目，將在此項目里編寫源代碼生成邏輯，用來支持將編寫的中文代碼轉換為 C# 代碼，從而參與後續的構建和執行

在 JelallnalukebaqeLairjaybearjair 項目里，將對 JelallnalukebaqeLairjaybearjair.Analyzers 項目進行引用，從而用來啟動此分析器的內容。添加引用時設置 OutputItemType 為 Analyzer 類型，且設置不使用不引用 JelallnalukebaqeLairjaybearjair.Analyzers 程式集。引用之後的 JelallnalukebaqeLairjaybearjair 項目的 csproj 項目文件的引用代碼如下

  <ItemGroup>
    <ProjectReference Include="..\JelallnalukebaqeLairjaybearjair.Analyzers\JelallnalukebaqeLairjaybearjair.Analyzers.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>

在本文的例子里，在 JelallnalukebaqeLairjaybearjair 項目里只有兩個文件，一個是 Program.cs 文件，一個是 這是測試類型.csg 文件。其中 Program.cs 文件就是傳統的 C# 項目，採用 C# 9.0 的頂層語句，編寫的代碼如下

using 這是一個命名空間;

這是測試類型.測試輸出();

而 這是測試類型.csg 文件里的內容就是本文開頭的中文代碼內容

接著，為了讓分析器能瞭解到 這是測試類型.csg 文件是需要參與構建的，額外在 JelallnalukebaqeLairjaybearjair 的 csproj 項目文件裡面添加 AdditionalFiles 列表。通過 AdditionalFiles 列表，可以在後續的分析器裡面，在增量構建里，通過 AdditionalTextsProvider 監聽獲取到這部分文件內容。編輯 JelallnalukebaqeLairjaybearjair 的 csproj 項目文件，添加如下代碼

  <ItemGroup>
      <AdditionalFiles Include="這是測試類型.csg" />
  </ItemGroup>

以上就是 JelallnalukebaqeLairjaybearjair 項目的所有文件和核心邏輯了。完成了準備工作之後，開始編寫 JelallnalukebaqeLairjaybearjair.Analyzers 分析器項目。為了能夠在 Visual Studio 裡面載入上分析器，以及同時在 dotnet 命令行裡加載分析器，設置 TargetFramework 為 .NET Standard 2.0 版本。因為 Visual Studio 採用的是 .NET Framework 運行時，而 dotnet 命令行工具採用的是 .NET Core 運行時，於是分析器採用 .NET Standard 2.0 版本就能剛好在這兩個運行時載入

為了編寫分析器項目，按照慣例，還需要引用必要的 NuGet 包。這裡需要引用 Microsoft.CodeAnalysis.Analyzers 和 Microsoft.CodeAnalysis.CSharp 程式集

編輯 JelallnalukebaqeLairjaybearjair.Analyzers 的 csproj 項目文件為如下代碼

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.3" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.2.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

完成了安裝庫之後，即可開始編寫核心代碼。需求是將 csg 格式的中文編程語言，轉換為 C# 代碼，從而參與後續的構建和執行

新建一個叫 CsgIncrementalGenerator 類型，繼承 IIncrementalGenerator 介面，順帶加上 GeneratorAttribute 特性標識這是生成 C# 代碼的。類型名可以自己發揮，只是本文作為例子叫成 CsgIncrementalGenerator 而已

    [Generator(LanguageNames.CSharp)]
    public class CsgIncrementalGenerator : IIncrementalGenerator
    {
        // 忽略代碼
    }

繼承 IIncrementalGenerator 介面，需要實現 public void Initialize(IncrementalGeneratorInitializationContext context) 方法。如 嘗試 IIncrementalGenerator 進行增量 Source Generator 生成代碼 博客所述，在進行增量構建時，只有 Initialize 方法。在 Initialize 方法裡面，加上分析器感興趣的文件以及對這些文件的處理方法即可

咱這裡的中文編程語言採用尾碼名為 .csg 的文件，在 JelallnalukebaqeLairjaybearjair 項目里也將 csg 文件在 csproj 項目文件里添加到 AdditionalFiles 列表裡面。在 Initialize 方法裡面，先告訴分析器感興趣的文件就是 csg 文件，只有有 csg 文件的變更，那將自動觸發更新邏輯，在更新邏輯里執行實際的轉換代碼

        public void Initialize(IncrementalGeneratorInitializationContext context)
        {
            var csgFileIncrementalValuesProvider =
            context.AdditionalTextsProvider.Where(t =>
                string.Equals(Path.GetExtension(t.Path), ".csg", StringComparison.OrdinalIgnoreCase));
            // 忽略文件
        }

以上代碼的 AdditionalTextsProvider 不是實際立刻提供了文件，而是用來編寫文件變更時的過濾命令，這也是增量代碼生成的核心邏輯。通過編寫過濾命令的方式，可以減少代碼生成實際轉換邏輯的執行次數，只有在遇到感興趣的文件的變更的時候才會觸發實際的執行邏輯，從而極大的提升性能

接下來將此過濾條件加入註冊，在過濾條件 csgFileIncrementalValuesProvider 能過濾出有文件變更時，將執行轉換代碼。轉換代碼的輸入是 csg 中文編程語言的代碼文件，輸出是加入到構建的 C# 的代碼字元串

通過 RegisterSourceOutput 方法進行註冊，註冊在滿足 csgFileIncrementalValuesProvider 過濾條件時，支持添加額外的參與構建代碼

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                // 忽略代碼
            });

在 RegisterSourceOutput 的開始，是先註冊框架部分的代碼，如上面的中文代碼，可以看到用到了一些需要預設的框架代碼，例如 控制台.輸出一行文本("你好"); 這句代碼就需要先有預設的名為 控制台 的類型。先添加框架代碼如下

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                AddFrameworkCode(sourceProductionContext);
                // 忽略代碼
            });

這裡拿到的 sourceProductionContext 參數，可以用來設置構建的生成代碼。在 AddFrameworkCode 裡面，添加框架需要的預設代碼，代碼如下

        /// <summary>
        /// 添加框架代碼
        /// </summary>
        /// <param name="sourceProductionContext"></param>
        private static void AddFrameworkCode(SourceProductionContext sourceProductionContext)
        {
            string consoleText = @"
using System;

namespace 系統;

static class 控制台
{
    public static void 輸出一行文本(string 文本)
    {
        Console.WriteLine(文本);
    }
}";
            sourceProductionContext.AddSource("DefaultConsole", consoleText);
        }

本文這裡只添加了用來演示的名為 控制台 的類型，添加方法如上代碼。以上代碼將會在項目里，添加一個叫做 DefaultConsole 的生成代碼，如此即可讓中文編程代碼里有可以使用的控制台輔助類型

接下來是獲取到發生變更的 csg 中文編程語言的文件的內容，用來轉換為 C# 代碼

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                AddFrameworkCode(sourceProductionContext);

                var csgSource = csg.GetText();
                if (csgSource == null) return;
                // 忽略代碼
            });

通過 GetText 即可獲取到其文本內容

獲取到內容之後，需要將 csg 中文編程語言的內容轉換為 C# 代碼字元串內容。我這裡抄襲了中文巨集的方法，使用關鍵詞替換。本文這裡只是替換了演示所需要的關鍵詞，沒有對其他的關鍵詞進行替換

                var keyDictionary = new Dictionary<string, string>()
                {
                    {"引用命名空間 ","using "},
                    {"定義命名空間 ","namespace "},
                    {"類型 ","class "},
                    {"公開的 ","public "},
                    {"靜態的 ","static "},
                    {"無返回值類型的 ","void "},
                };

                var stringBuilder = new StringBuilder();
                foreach (var textLine in csgSource.Lines)
                {
                    var text = textLine.ToString();
                    if (!string.IsNullOrEmpty(text))
                    {
                        foreach (var keyValuePair in keyDictionary)
                        {
                            text = text.Replace(keyValuePair.Key, keyValuePair.Value);
                        }
                    }

                    stringBuilder.AppendLine(text);
                }

如此一行行進行替換，即可拿到一段 C# 代碼

將 stringBuilder 里的 C# 代碼作為生成代碼，添加到 sourceProductionContext 用於參與構建

                sourceProductionContext.AddSource(Path.GetFileNameWithoutExtension(csg.Path) + ".g.cs", stringBuilder.ToString());

添加的時候，設置了 hintName 參數為 Path.GetFileNameWithoutExtension(csg.Path) + ".g.cs" 如此即可在相同的一個 csg 文件變更的時候，生成的代碼可以替換舊的生成代碼。生成代碼之間的替換就是採用 hintName 參數作為判斷條件

如此即可完成將 csg 中文編程語言轉換為 C# 代碼，且加入到構建里

本文只是作為一個演示，告訴大家可以利用 Source Generator 技術，將中文編程語言轉換為 C# 代碼，方便的加入到構建里，從而復用整個 dotnet 的機制

本文的代碼放在github 和 gitee 歡迎訪問

可以通過如下方式獲取本文的源代碼，先創建一個空文件夾，接著使用命令行 cd 命令進入此空文件夾，在命令行裡面輸入以下代碼，即可獲取到本文的代碼

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin bba0c728bbc1d850f6f1929ab14a42e995e23e3b

以上使用的是 gitee 的源，如果 gitee 不能訪問，請替換為 github 的源。請在命令行繼續輸入以下代碼

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin bba0c728bbc1d850f6f1929ab14a42e995e23e3b

獲取代碼之後，進入 JelallnalukebaqeLairjaybearjair 文件夾

更多增量構建請看 嘗試 IIncrementalGenerator 進行增量 Source Generator 生成代碼

更多編譯器、代碼分析、代碼生成相關博客，請參閱我的 博客導航

博客園博客只做備份，博客發佈就不再更新，如果想看最新博客，請到 https://blog.lindexi.com/