Skip to content

Commit c24bcc5

Browse files
lindexilindexi
authored
Merge pull request #42 from dotnet-campus/t/walterlv/source-generator
重构命令行解析库：采用源生成器技术，全面支持五种命令行风格，并增强类型系统
2 parents 558a94c + 549cf4c commit c24bcc5

File tree

195 files changed

+12138
-6788
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

195 files changed

+12138
-6788
lines changed

‎.gitignore

Lines changed: 71 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
## Ignore Visual Studio temporary files, build results, and
1+
## Ignore Visual Studio temporary files, build results, and
22
## files generated by popular Visual Studio add-ons.
33
##
4-
## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
4+
## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore
55

66
# User-specific files
77
*.rsuser
@@ -13,19 +13,24 @@
1313
# User-specific files (MonoDevelop/Xamarin Studio)
1414
*.userprefs
1515

16+
# Mono auto generated files
17+
mono_crash.*
18+
1619
# Build results
1720
[Dd]ebug/
1821
[Dd]ebugPublic/
1922
[Rr]elease/
2023
[Rr]eleases/
2124
x64/
2225
x86/
26+
[Ww][Ii][Nn]32/
2327
[Aa][Rr][Mm]/
2428
[Aa][Rr][Mm]64/
2529
bld/
2630
[Bb]in/
2731
[Oo]bj/
2832
[Ll]og/
33+
[Ll]ogs/
2934

3035
# Visual Studio 2015/2017 cache/options directory
3136
.vs/
@@ -39,9 +44,10 @@ Generated\ Files/
3944
[Tt]est[Rr]esult*/
4045
[Bb]uild[Ll]og.*
4146

42-
# NUNIT
47+
# NUnit
4348
*.VisualState.xml
4449
TestResult.xml
50+
nunit-*.xml
4551

4652
# Build Results of an ATL Project
4753
[Dd]ebugPS/
@@ -56,6 +62,9 @@ project.lock.json
5662
project.fragment.lock.json
5763
artifacts/
5864

65+
# ASP.NET Scaffolding
66+
ScaffoldingReadMe.txt
67+
5968
# StyleCop
6069
StyleCopReport.xml
6170

@@ -81,6 +90,7 @@ StyleCopReport.xml
8190
*.tmp_proj
8291
*_wpftmp.csproj
8392
*.log
93+
*.tlog
8494
*.vspscc
8595
*.vssscc
8696
.builds
@@ -122,9 +132,6 @@ _ReSharper*/
122132
*.[Rr]e[Ss]harper
123133
*.DotSettings.user
124134

125-
# JustCode is a .NET coding add-in
126-
.JustCode
127-
128135
# TeamCity is a build add-in
129136
_TeamCity*
130137

@@ -135,6 +142,11 @@ _TeamCity*
135142
.axoCover/*
136143
!.axoCover/settings.json
137144

145+
# Coverlet is a free, cross platform Code Coverage Tool
146+
coverage*.json
147+
coverage*.xml
148+
coverage*.info
149+
138150
# Visual Studio code coverage results
139151
*.coverage
140152
*.coveragexml
@@ -182,6 +194,8 @@ PublishScripts/
182194

183195
# NuGet Packages
184196
*.nupkg
197+
# NuGet Symbol Packages
198+
*.snupkg
185199
# The packages folder can be ignored because of Package Restore
186200
**/[Pp]ackages/*
187201
# except build/, which is used as an MSBuild target.
@@ -206,6 +220,8 @@ BundleArtifacts/
206220
Package.StoreAssociation.xml
207221
_pkginfo.txt
208222
*.appx
223+
*.appxbundle
224+
*.appxupload
209225

210226
# Visual Studio cache files
211227
# files ending in .cache can be ignored
@@ -255,7 +271,9 @@ ServiceFabricBackup/
255271
*.bim.layout
256272
*.bim_*.settings
257273
*.rptproj.rsuser
258-
*- Backup*.rdl
274+
*- [Bb]ackup.rdl
275+
*- [Bb]ackup ([0-9]).rdl
276+
*- [Bb]ackup ([0-9][0-9]).rdl
259277

260278
# Microsoft Fakes
261279
FakesAssemblies/
@@ -276,6 +294,17 @@ node_modules/
276294
# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
277295
*.vbw
278296

297+
# Visual Studio 6 auto-generated project file (contains which files were open etc.)
298+
*.vbp
299+
300+
# Visual Studio 6 workspace and project file (working project files containing files to include in project)
301+
*.dsw
302+
*.dsp
303+
304+
# Visual Studio 6 technical files
305+
*.ncb
306+
*.aps
307+
279308
# Visual Studio LightSwitch build output
280309
**/*.HTMLClient/GeneratedArtifacts
281310
**/*.DesktopClient/GeneratedArtifacts
@@ -291,10 +320,6 @@ paket-files/
291320
# FAKE - F# Make
292321
.fake/
293322

294-
# JetBrains Rider
295-
.idea/
296-
*.sln.iml
297-
298323
# CodeRush personal settings
299324
.cr/personal
300325

@@ -336,5 +361,39 @@ ASALocalRun/
336361
# Local History for Visual Studio
337362
.localhistory/
338363

364+
# Visual Studio History (VSHistory) files
365+
.vshistory/
366+
339367
# BeatPulse healthcheck temp database
340-
healthchecksdb
368+
healthchecksdb
369+
370+
# Backup folder for Package Reference Convert tool in Visual Studio 2017
371+
MigrationBackup/
372+
373+
# Ionide (cross platform F# VS Code tools) working folder
374+
.ionide/
375+
376+
# Fody - auto-generated XML schema
377+
FodyWeavers.xsd
378+
379+
# VS Code files for those working on multiple tools
380+
.vscode/*
381+
!.vscode/settings.json
382+
!.vscode/tasks.json
383+
!.vscode/launch.json
384+
!.vscode/extensions.json
385+
*.code-workspace
386+
387+
# Local History for Visual Studio Code
388+
.history/
389+
390+
# Windows Installer files from build outputs
391+
*.cab
392+
*.msi
393+
*.msix
394+
*.msm
395+
*.msp
396+
397+
# JetBrains Rider
398+
.idea/
399+
*.sln.iml

‎ApiChanges.3.x-4.0.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# 重大更新
2+
3+
## 3.x -> 4.0
4+
5+
DotNetCampus.CommandLine 4.0版本带来了全面的架构升级和功能增强，使命令行参数解析更加高效、灵活且易于使用。
6+
7+
### 主要更新内容
8+
9+
#### 1. 全面采用源代码生成器
10+
11+
- 完全使用源生成器技术，替代以前的手写解析器（`XxxParser`）和反射解析器（`RuntimeParser`）
12+
- 相比上个版本，性能出现了轻微下降（换来了各种命令行风格的完全支持），好在保持在同一个数量级内，仍然比同类库快得多
13+
- 充分支持 AOT 编译，更适合现代 .NET 应用场景
14+
15+
#### 2. 全面增强的命令行风格支持
16+
17+
- 从原来支持 Linux/GNU、CMD、PowerShell 三种风格的有限子集，升级为全面支持五种完整命令行风格：
18+
- `CommandLineStyle.Flexible`（默认）：智能识别多种风格
19+
- `CommandLineStyle.GNU`：符合 GNU 规范的风格
20+
- `CommandLineStyle.POSIX`：符合 POSIX 规范的风格
21+
- `CommandLineStyle.DotNet`：.NET CLI 风格
22+
- `CommandLineStyle.PowerShell`：PowerShell 风格
23+
- 全面支持各种命令行选项格式：
24+
- 长选项：`--option value`、`--option=value`、`--option:value`
25+
- 短选项：`-o value`、`-o=value`、`-o:value`
26+
- Windows风格：`/option value`、`/option:value`
27+
- 布尔选项：`--flag`（无值时自动设为true）、`--flag:true/false`
28+
- URL协议风格：`protocol://command/subcommand?param1=value&param2=value`
29+
30+
#### 3. 增强的类型系统支持
31+
32+
- 支持 C# 8.0+ 的 `init` 和 C# 11.0 的 `required` 关键字，支持不可变对象
33+
- 全面支持更多复杂数据类型：
34+
- 集合类型：数组、列表、只读集合、不可变集合
35+
- 字典类型：支持多种传入方式和分隔符
36+
- 枚举类型：支持枚举名称和数值
37+
- 增强类型转换能力，提供更友好的类型错误提示
38+
39+
#### 4. 改进的命令处理器模式
40+
41+
- `AddHandler<T>` 现在支持实现 `ICommandHandler` 接口的类型，可以在类型内部编写处理逻辑
42+
- 保留了通过委托方式传入处理逻辑的经典用法
43+
44+
### 破坏性变更和升级指南
45+
46+
1. **命名空间变更**：`OptionAttribute`、`ValueAttribute`、`VerbAttribute` 的命名空间发生了变化。升级库后，您可能需要借助IDE来修正相关引用。
47+
48+
2. **参数解析选项变更**：`CommandLine.Parse(args, xxx)` 的第二个参数已从简单的URL scheme字符串升级为完整的 `CommandLineParsingOptions` 对象：
49+
```csharp
50+
// 旧版本
51+
var commandLine = CommandLine.Parse(args, "myapp");
52+
53+
// 新版本
54+
var commandLine = CommandLine.Parse(args, new CommandLineParsingOptions { SchemeNames = ["myapp"] });
55+
// 或者使用预定义样式
56+
var commandLine = CommandLine.Parse(args, CommandLineParsingOptions.DotNet);
57+
```
58+
59+
3. **命名约定变更**：选项命名规则从 `PascalCase` 改为推荐使用 `kebab-case`：
60+
```csharp
61+
// 旧版本（依然支持，但不再推荐）
62+
[Option("OutputFile")]
63+
64+
// 新版本（推荐）
65+
[Option("output-file")]
66+
```
67+
原因请见：[DCL101.md](/docs/analyzers/DCL101.md)
68+
69+
4. **标准处理器移除**：删除了 `AddStandardHandlers` 方法（用于自动处理 `--help` 和 `--version`）。这个功能在未来版本可能会以新形式回归，如有需要请暂时自行实现。
70+
71+
5. **过滤器机制移除**：删除了很少使用的 `CommandLineFilter` 机制，该机制主要为 `AddStandardHandlers` 提供支持。
72+
73+
### 保留的功能
74+
75+
本次升级范围很大，不过仍然尽量在更规范更强大的设计中保持了跟上个版本 API 的一致性。你原来的项目通常只进行命名空间的修改即可正常工作；调整选项的命名规则后可消除新引入的警告（我们提供了代码修改器辅助你自动采用新的命名规则）。
76+
77+
1. **多种命令行风格解析**：保留并增强了对多种命令行参数风格的支持
78+
2. **URL协议支持**：完整保留并改进了对URL协议格式命令行的解析
79+
3. **位置参数支持**：保留了对位置参数的支持，并增强了位置参数的处理能力
80+
4. **谓词（命令）支持**：保留并增强了对命令谓词的支持（如 `git commit`、`git push` 等形式）

‎Directory.Build.props

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,35 @@
22

33
<Import Project="build\Version.props" />
44

5+
<!-- 框架和语言信息 -->
56
<PropertyGroup>
6-
<PackageOutputPath>$(MSBuildThisFileDirectory)bin\$(Configuration)</PackageOutputPath>
77
<LangVersion>latest</LangVersion>
88
<Nullable>enable</Nullable>
9+
<Deterministic>true</Deterministic>
10+
<RepositoryRoot>$(MSBuildThisFileDirectory)</RepositoryRoot>
11+
<ArtifactsPath>$(MSBuildThisFileDirectory)artifacts\</ArtifactsPath>
12+
</PropertyGroup>
13+
14+
<PropertyGroup>
15+
<!--
16+
DCL101: 命令行库自己的警告，是为了给库的用户报告的；而本仓库要测这些，所以不能放一堆警告破窗。
17+
-->
18+
<NoWarn>$(NoWarn);DCL101</NoWarn>
19+
<!--
20+
CA1416: 平台兼容性警告
21+
-->
22+
<WarningsAsErrors>$(WarningAsErrors);CA1416</WarningsAsErrors>
23+
</PropertyGroup>
24+
25+
<!-- 库和项目信息 -->
26+
<PropertyGroup>
27+
<Description>使用源生成器高性能地辅助你的应用程序解析几种主流风格的命令行。</Description>
928
<Authors>walterlv</Authors>
1029
<Company>dotnet-campus</Company>
1130
<PackageLicenseExpression>MIT</PackageLicenseExpression>
12-
<PackageProjectUrl>https://github.com/dotnet-campus/dotnetCampus.CommandLine</PackageProjectUrl>
13-
<RepositoryUrl>https://github.com/dotnet-campus/dotnetCampus.CommandLine.git</RepositoryUrl>
31+
<PackageProjectUrl>https://github.com/dotnet-campus/DotNetCampus.CommandLine</PackageProjectUrl>
32+
<RepositoryUrl>https://github.com/dotnet-campus/DotNetCampus.CommandLine.git</RepositoryUrl>
1433
<RepositoryType>git</RepositoryType>
1534
</PropertyGroup>
1635

17-
</Project>
36+
</Project>

‎dotnetCampus.CommandLine.sln renamed to ‎DotNetCampus.CommandLine.sln

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00
33
# Visual Studio Version 17
44
VisualStudioVersion = 17.0.31606.5
55
MinimumVisualStudioVersion = 10.0.40219.1
6-
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{2AC77BF2-2FBB-4DE2-9444-38EC30003867}"
6+
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{2AC77BF2-2FBB-4DE2-9444-38EC30003867}"
77
ProjectSection(SolutionItems) = preProject
88
.gitattributes = .gitattributes
99
.gitignore = .gitignore
@@ -13,19 +13,19 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
1313
build\Version.props = build\Version.props
1414
EndProjectSection
1515
EndProject
16-
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnetCampus.CommandLine", "src\dotnetCampus.CommandLine\dotnetCampus.CommandLine.csproj", "{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}"
16+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DotNetCampus.CommandLine.Analyzer", "src\DotNetCampus.CommandLine.Analyzer\DotNetCampus.CommandLine.Analyzer.csproj", "{8AD0FEAB-2E36-4EBB-9E32-C4394FC6DC86}"
1717
EndProject
18-
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnetCampus.CommandLine.Analyzer", "src\dotnetCampus.CommandLine.Analyzer\dotnetCampus.CommandLine.Analyzer.csproj", "{8AD0FEAB-2E36-4EBB-9E32-C4394FC6DC86}"
18+
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{7DDA8183-3606-4B08-86E3-A4537860448F}"
1919
EndProject
20-
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{7DDA8183-3606-4B08-86E3-A4537860448F}"
20+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DotNetCampus.CommandLine.Tests", "tests\DotNetCampus.CommandLine.Tests\DotNetCampus.CommandLine.Tests.csproj", "{470A596C-D8C4-4506-A71A-4BEEA08BCC62}"
2121
EndProject
22-
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnetCampus.CommandLine.Tests", "tests\dotnetCampus.CommandLine.Tests\dotnetCampus.CommandLine.Tests.csproj", "{470A596C-D8C4-4506-A71A-4BEEA08BCC62}"
23-
EndProject
24-
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnetCampus.CommandLine.Performance", "tests\dotnetCampus.CommandLine.Performance\dotnetCampus.CommandLine.Performance.csproj", "{7B664373-31A0-47AB-9076-15153EF4722A}"
22+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DotNetCampus.CommandLine.Performance", "tests\DotNetCampus.CommandLine.Performance\DotNetCampus.CommandLine.Performance.csproj", "{7B664373-31A0-47AB-9076-15153EF4722A}"
2523
EndProject
2624
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{F26EAA27-AA79-4B28-890C-D759F1D1A374}"
2725
EndProject
28-
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "dotnetCampus.CommandLine.Sample", "samples\dotnetCampus.CommandLine.Sample\dotnetCampus.CommandLine.Sample.csproj", "{B44D0273-A584-4845-899A-597D52387DC7}"
26+
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DotNetCampus.CommandLine.Sample", "samples\DotNetCampus.CommandLine.Sample\DotNetCampus.CommandLine.Sample.csproj", "{B44D0273-A584-4845-899A-597D52387DC7}"
27+
EndProject
28+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DotNetCampus.CommandLine", "src\DotNetCampus.CommandLine\DotNetCampus.CommandLine.csproj", "{B61424A0-02C5-4C24-819B-8153D52BC0B8}"
2929
EndProject
3030
Global
3131
GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -35,14 +35,6 @@ Global
3535
Release|x86 = Release|x86
3636
EndGlobalSection
3737
GlobalSection(ProjectConfigurationPlatforms) = postSolution
38-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
39-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Debug|Any CPU.Build.0 = Debug|Any CPU
40-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Debug|x86.ActiveCfg = Debug|Any CPU
41-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Debug|x86.Build.0 = Debug|Any CPU
42-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Release|Any CPU.ActiveCfg = Release|Any CPU
43-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Release|Any CPU.Build.0 = Release|Any CPU
44-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Release|x86.ActiveCfg = Release|Any CPU
45-
{EE3640D1-C870-4C4E-869E-AE3DCC6CB3C4}.Release|x86.Build.0 = Release|Any CPU
4638
{8AD0FEAB-2E36-4EBB-9E32-C4394FC6DC86}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
4739
{8AD0FEAB-2E36-4EBB-9E32-C4394FC6DC86}.Debug|Any CPU.Build.0 = Debug|Any CPU
4840
{8AD0FEAB-2E36-4EBB-9E32-C4394FC6DC86}.Debug|x86.ActiveCfg = Debug|Any CPU
@@ -75,6 +67,14 @@ Global
7567
{B44D0273-A584-4845-899A-597D52387DC7}.Release|Any CPU.Build.0 = Release|Any CPU
7668
{B44D0273-A584-4845-899A-597D52387DC7}.Release|x86.ActiveCfg = Release|Any CPU
7769
{B44D0273-A584-4845-899A-597D52387DC7}.Release|x86.Build.0 = Release|Any CPU
70+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
71+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Debug|Any CPU.Build.0 = Debug|Any CPU
72+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Debug|x86.ActiveCfg = Debug|Any CPU
73+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Debug|x86.Build.0 = Debug|Any CPU
74+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Release|Any CPU.ActiveCfg = Release|Any CPU
75+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Release|Any CPU.Build.0 = Release|Any CPU
76+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Release|x86.ActiveCfg = Release|Any CPU
77+
{B61424A0-02C5-4C24-819B-8153D52BC0B8}.Release|x86.Build.0 = Release|Any CPU
7878
EndGlobalSection
7979
GlobalSection(SolutionProperties) = preSolution
8080
HideSolutionNode = FALSE

0 commit comments

Comments
 (0)