Add ConsoleAppFramework.CliSchema

Author: neuecc

ConsoleAppFramework.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.0.31903.59
+# Visual Studio Version 18
+VisualStudioVersion = 18.0.11205.157 d18.0
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{1F399F98-7439-4F05-847B-CC1267B4B7F2}"
 EndProject
@@ -18,8 +18,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		.editorconfig = .editorconfig
 		.gitignore = .gitignore
 		Directory.Build.props = Directory.Build.props
-		ReadMe.md = ReadMe.md
 		exclusion.dic = exclusion.dic
+		ReadMe.md = ReadMe.md
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ConsoleAppFramework", "src\ConsoleAppFramework\ConsoleAppFramework.csproj", "{09BEEA7B-B6D3-4011-BCAB-6DF976713695}"
@@ -38,6 +38,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FilterShareProject", "sandb
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NativeAotTrimming", "tests\NativeAotTrimming\NativeAotTrimming.csproj", "{B14EB164-AC1E-4B0C-9CEB-312B233195E5}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ConsoleAppFramework.CliSchema", "src\ConsoleAppFramework.CliSchema\ConsoleAppFramework.CliSchema.csproj", "{52BC6A88-9699-420A-AAC3-A3C129EC7219}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -144,6 +146,18 @@ Global
 		{B14EB164-AC1E-4B0C-9CEB-312B233195E5}.Release|x64.Build.0 = Release|Any CPU
 		{B14EB164-AC1E-4B0C-9CEB-312B233195E5}.Release|x86.ActiveCfg = Release|Any CPU
 		{B14EB164-AC1E-4B0C-9CEB-312B233195E5}.Release|x86.Build.0 = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|x64.Build.0 = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Debug|x86.Build.0 = Debug|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|Any CPU.Build.0 = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|x64.ActiveCfg = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|x64.Build.0 = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|x86.ActiveCfg = Release|Any CPU
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -157,6 +171,7 @@ Global
 		{855B0D28-DC69-470B-B3D9-481EE52737AA} = {1F399F98-7439-4F05-847B-CC1267B4B7F2}
 		{2A1E8ED1-CEB9-47CB-8497-A0C4F5A8F025} = {A2CF2984-E8E2-48FC-B5A1-58D74A2467E6}
 		{B14EB164-AC1E-4B0C-9CEB-312B233195E5} = {AAD2D900-C305-4449-A9FC-6C7696FFEDFA}
+		{52BC6A88-9699-420A-AAC3-A3C129EC7219} = {1F399F98-7439-4F05-847B-CC1267B4B7F2}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {7F3E353A-C125-4020-8481-11DC6496358C}

ReadMe.md

@@ -155,9 +155,11 @@ As you can see from the generated output, the help display is also fast. In typi
 
 Getting Started
 --
-This library is distributed via NuGet, minimal requirement is .NET 8 and C# 13.
+This library is distributed via [NuGet](https://www.nuget.org/packages/ConsoleAppFramework), minimal requirement is .NET 8 and C# 13.
 
-> dotnet add package [ConsoleAppFramework](https://www.nuget.org/packages/ConsoleAppFramework)
+```bash
+dotnet add package ConsoleAppFramework
+```
 
 ConsoleAppFramework is an analyzer (Source Generator) and does not have any dll references. When referenced, the entry point class `ConsoleAppFramework.ConsoleApp` is generated internally.
 
@@ -423,6 +425,33 @@ app.Run(args);
 
 You can also combine this with `Add` or `Add<T>` to add more commands.
 
+### Alias command 
+
+Similar to option aliases, commands also support aliases. In the `Add` method, separating `commandName` or `[Command]` with `|` defines them as aliases.
+
+```csharp
+using ConsoleAppFramework;
+
+var app = ConsoleApp.Create();
+
+app.Add("build|b", () => { });
+app.Add("keyvault|kv", () => { });
+app.Add<Commands>();
+
+app.Run(args);
+
+public class Commands
+{
+    /// <summary>Executes the check command using the specified coordinates.</summary>
+    [Command("check|c")]
+    public void Check() { }
+
+    /// <summary>Build this packages's and its dependencies' documenation.</summary>
+    [Command("doc|d")]
+    public void Doc() { }
+}
+```
+
 ### Performance of Commands
 
 In `ConsoleAppFramework`, the number and types of registered commands are statically determined at compile time. For example, let's register the following four commands:
@@ -571,7 +600,15 @@ When using `ConsoleApp.Run`, you can check the syntax of the command line in the
 
 For the rules on converting parameter names to option names, aliases, and how to set documentation, refer to the [Option aliases](#option-aliases-and-help-version) section.
 
-Parameters marked with the `[Argument]` attribute receive values in order without parameter names. This attribute can only be set on sequential parameters from the beginning.
+Parameters marked with the `[Argument]` attribute receive values in order without parameter names. This attribute allows from first or last.
+
+```csharp
+// cmd.exe "input.txt" "output.txt"
+ConsoleApp.Run(args, ([Argument]string input, [Argument]string output, bool dryRun) => { });
+
+// cmd.exe --message "foo bar baz" "output1.txt" "output2.txt" "output3.txt"
+ConsoleApp.Run(args, (string message, [Argument]params string[] outputs) => { });
+```
 
 To convert from string arguments to various types, basic primitive types (`string`, `char`, `sbyte`, `byte`, `short`, `int`, `long`, `uint`, `ushort`, `ulong`, `decimal`, `float`, `double`) use `TryParse`. For types that implement `ISpanParsable<T>` (`DateTime`, `DateTimeOffset`, `Guid`, `BigInteger`, `Complex`, `Half`, `Int128`, etc.), [IParsable<TSelf>.TryParse](https://learn.microsoft.com/en-us/dotnet/api/system.iparsable-1.tryparse?view=net-8.0#system-ispanparsable-1-tryparse(system-readonlyspan((system-char))-system-iformatprovider-0@)) or [ISpanParsable<TSelf>.TryParse](https://learn.microsoft.com/en-us/dotnet/api/system.ispanparsable-1.tryparse?view=net-8.0#system-ispanparsable-1-tryparse(system-readonlyspan((system-char))-system-iformatprovider-0@)) is used.
 
@@ -1428,6 +1465,55 @@ The framework doesn't support colorization directly; however, utilities like [Cy
 
 For more powerful Console UI support, you can also use it in combination with [Spectre.Console](https://spectreconsole.net/).
 
+Cli Schema
+---
+The dotnet command can output command and option information in JSON format using the `--cli-schema` option. In ConsoleAppFramework, by importing the `ConsoleAppFramework.CliSchema` package, you can call the `ConsoleAppBuilder.GetCliSchema()` method.
+
+```bash
+dotnet add package ConsoleAppFramework.CliSchema
+```
+
+```csharp
+var app = ConsoleApp.Create();
+app.Add("foo", (int x, int y) => { });
+
+// get cli-schema as objects
+CommandHelpDefinition[] schema = app.GetCliSchema();
+```
+
+`CommandHelpDefinition` is the same one used internally for help output.
+
+```csharp
+public record CommandHelpDefinition
+{
+    public string CommandName { get; }
+    public CommandOptionHelpDefinition[] Options { get; }
+    public string Description { get; }
+}
+
+public record CommandOptionHelpDefinition
+{
+    public string[] Options { get; }
+    public string Description { get; }
+    public string? DefaultValue { get; }
+    public string ValueTypeName { get; }
+    public int? Index { get; }
+    public bool IsRequired => DefaultValue == null && !IsParams;
+    public bool IsFlag { get; }
+    public bool IsParams { get; }
+    public bool IsHidden { get; }
+    public bool IsDefaultValueHidden { get; }
+    public string FormattedValueTypeName => "<" + ValueTypeName + ">";
+}
+```
+
+You can also convert it to JSON. Since `CliSchemaJsonSerializerContext` is provided, by passing it as a Serialize/Deserialize argument, you can perform Native AOT-compatible conversion.
+
+```csharp
+var json = JsonSerializer.Serialize(schema, CliSchemaJsonSerializerContext.Default.CommandHelpDefinitionArray);
+var schema2 = JsonSerializer.Deserialize(json, CliSchemaJsonSerializerContext.Default.CommandHelpDefinitionArray);
+```
+
 Publish to executable file
 ---
 There are multiple ways to run a CLI application in .NET:
@@ -1440,6 +1526,8 @@ There are multiple ways to run a CLI application in .NET:
 
 Also, to run with Native AOT, please refer to the [Native AOT deployment overview](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/). In any case, ConsoleAppFramework thoroughly implements a dependency-free and reflection-free approach, so it shouldn't be an obstacle to execution.
 
+There is a method of distributing CLI tools by packaging them as [.NET tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools). Also, starting from .NET 10, it is possible to execute them directly from the package manager using [dotnet tool exec(dnx)](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-exec).
+
 v4 -> v5 Migration Guide
 ---
 v4 was running on top of `Microsoft.Extensions.Hosting`, so build a Host in the same way and need to convert ConsoleAppBuilder.

sandbox/GeneratorSandbox/GeneratorSandbox.csproj

@@ -32,6 +32,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\src\ConsoleAppFramework.Abstractions\ConsoleAppFramework.Abstractions.csproj" />
+    <ProjectReference Include="..\..\src\ConsoleAppFramework.CliSchema\ConsoleAppFramework.CliSchema.csproj" />
     <ProjectReference Include="..\..\src\ConsoleAppFramework\ConsoleAppFramework.csproj">
       <OutputItemType>Analyzer</OutputItemType>
       <ReferenceOutputAssembly>false</ReferenceOutputAssembly>

sandbox/GeneratorSandbox/Program.cs

@@ -1,19 +1,18 @@
 using ConsoleAppFramework;
 
-// args = ["foo", "--help"];
-
 var app = ConsoleApp.Create();
 
 app.Add("build|b", () => { });
-app.Add("test|t", () => { });
 app.Add("keyvault|kv", () => { });
 app.Add<Commands>();
 
 app.Run(args);
 
 public class Commands
 {
-    /// <summary>Analyze the current package and report errors, but don't build object files.</summary>
+    /// <summary>
+    /// Executes the check command using the specified coordinates.
+    /// </summary>
     [Command("check|c")]
     public void Check() { }
 

src/ConsoleAppFramework.Abstractions/ConsoleAppFramework.Abstractions.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 

src/ConsoleAppFramework.CliSchema/CommandHelpDefinition.cs

@@ -0,0 +1,55 @@
+using System.Text.Json.Serialization;
+
+namespace ConsoleAppFramework;
+
+public record CommandHelpDefinition
+{
+    public string CommandName { get; }
+    public CommandOptionHelpDefinition[] Options { get; }
+    public string Description { get; }
+
+    public CommandHelpDefinition(string commandName, CommandOptionHelpDefinition[] options, string description)
+    {
+        CommandName = commandName;
+        Options = options;
+        Description = description;
+    }
+}
+
+public record CommandOptionHelpDefinition
+{
+    public string[] Options { get; }
+    public string Description { get; }
+    public string? DefaultValue { get; }
+    public string ValueTypeName { get; }
+    public int? Index { get; }
+    public bool IsRequired => DefaultValue == null && !IsParams;
+    public bool IsFlag { get; }
+    public bool IsParams { get; }
+    public bool IsHidden { get; }
+    public bool IsDefaultValueHidden { get; }
+    public string FormattedValueTypeName => "<" + ValueTypeName + ">";
+
+    public CommandOptionHelpDefinition(string[] options, string description, string valueTypeName, string? defaultValue, int? index, bool isFlag, bool isParams, bool isHidden, bool isDefaultValueHidden)
+    {
+        Options = options;
+        Description = description;
+        ValueTypeName = valueTypeName;
+        DefaultValue = defaultValue;
+        Index = index;
+        IsFlag = isFlag;
+        IsParams = isParams;
+        IsHidden = isHidden;
+        IsDefaultValueHidden = isDefaultValueHidden;
+    }
+}
+
+[JsonSerializable(typeof(CommandHelpDefinition))]
+[JsonSerializable(typeof(CommandOptionHelpDefinition))]
+[JsonSerializable(typeof(CommandHelpDefinition[]))]
+[JsonSerializable(typeof(CommandOptionHelpDefinition[]))]
+[JsonSerializable(typeof(string[]))]
+[JsonSerializable(typeof(string))]
+[JsonSerializable(typeof(int))]
+[JsonSerializable(typeof(bool))]
+public partial class CliSchemaJsonSerializerContext : JsonSerializerContext { }

src/ConsoleAppFramework.CliSchema/ConsoleAppFramework.CliSchema.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>latest</LangVersion>
+
+    <!-- NuGet -->
+    <IsPackable>true</IsPackable>
+    <PackageId>ConsoleAppFramework.CliSchema</PackageId>
+    <Description>ConsoleAppFramework cli-schema metadata library.</Description>
+    <Configurations>Debug;Release</Configurations>
+  </PropertyGroup>
+
+</Project>

src/ConsoleAppFramework/CommandHelpBuilder.cs

@@ -1,4 +1,4 @@
-using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis;
 using System.Text;
 
 namespace ConsoleAppFramework;
@@ -47,6 +47,13 @@ public static string BuildCommandHelpMessage(Command command)
         return BuildHelpMessageCore(command, showCommandName: command.Name != "", showCommand: false);
     }
 
+    public static string BuildCliSchema(IEnumerable<Command> commands)
+    {
+        return "return new[] {\n"
+            + string.Join(", \n", commands.Select(x => CreateCommandHelpDefinition(x).ToCliSchema()))
+            + "\n};";
+    }
+
     static string BuildHelpMessageCore(Command command, bool showCommandName, bool showCommand)
     {
         var definition = CreateCommandHelpDefinition(command);
@@ -333,6 +340,44 @@ public CommandHelpDefinition(string command, CommandOptionHelpDefinition[] optio
             Options = options;
             Description = description;
         }
+
+        public string ToCliSchema()
+        {
+            var sb = new StringBuilder();
+            sb.AppendLine($"new CommandHelpDefinition(");
+            sb.AppendLine($"    \"{EscapeString(CommandName)}\",");
+            sb.AppendLine($"    new CommandOptionHelpDefinition[]");
+            sb.AppendLine($"    {{");
+
+            for (int i = 0; i < Options.Length; i++)
+            {
+                sb.Append("        ");
+                sb.Append(Options[i].ToCliSchema());
+                if (i < Options.Length - 1)
+                {
+                    sb.AppendLine(",");
+                }
+                else
+                {
+                    sb.AppendLine();
+                }
+            }
+
+            sb.AppendLine($"    }},");
+            sb.AppendLine($"    \"{EscapeString(Description)}\"");
+            sb.Append($")");
+
+            return sb.ToString();
+        }
+
+        private static string EscapeString(string str)
+        {
+            return str.Replace("\\", "\\\\")
+                      .Replace("\"", "\\\"")
+                      .Replace("\n", "\\n")
+                      .Replace("\r", "\\r")
+                      .Replace("\t", "\\t");
+        }
     }
 
     class CommandOptionHelpDefinition
@@ -361,5 +406,23 @@ public CommandOptionHelpDefinition(string[] options, string description, string
             IsHidden = isHidden;
             IsDefaultValueHidden = isDefaultValueHidden;
         }
+
+        public string ToCliSchema()
+        {
+            var optionsArray = string.Join(", ", Options.Select(o => $"\"{EscapeString(o)}\""));
+            var defaultValueStr = DefaultValue == null ? "null" : $"\"{EscapeString(DefaultValue)}\"";
+            var indexStr = Index.HasValue ? Index.Value.ToString() : "null";
+
+            return $"new CommandOptionHelpDefinition(new[] {{ {optionsArray} }}, \"{EscapeString(Description)}\", \"{EscapeString(ValueTypeName)}\", {defaultValueStr}, {indexStr}, {IsFlag.ToString().ToLower()}, {IsParams.ToString().ToLower()}, {IsHidden.ToString().ToLower()}, {IsDefaultValueHidden.ToString().ToLower()})";
+        }
+
+        private static string EscapeString(string str)
+        {
+            return str.Replace("\\", "\\\\")
+                      .Replace("\"", "\\\"")
+                      .Replace("\n", "\\n")
+                      .Replace("\r", "\\r")
+                      .Replace("\t", "\\t");
+        }
     }
 }