|
2 | 2 |
|
3 | 3 |   [](https://www.nuget.org/packages/dotnetCampus.CommandLine/) [](https://www.nuget.org/packages/dotnetCampus.CommandLine.Source/)
|
4 | 4 |
|
5 |
| -[English][en]|[简体中文][zh-chs]|[繁體中文][zh-cht] |
6 |
| --|-|- |
| 5 | +| [English][en] | [简体中文][zh-hans] | [繁體中文][zh-hant] | |
| 6 | +| ------------- | ------------------- | ------------------- | |
7 | 7 |
|
8 |
| -[en]: /README.md |
9 |
| -[zh-chs]: /docs/zh-chs/README.md |
10 |
| -[zh-cht]: /docs/zh-cht/README.md |
| 8 | +[en]: /docs/en/README.md |
| 9 | +[zh-hans]: /docs/zh-hans/README.md |
| 10 | +[zh-hant]: /docs/zh-hant/README.md |
11 | 11 |
|
12 |
| -dotnetCampus.CommandLine is probably the fastest command line parser in all .NET open-source projects. |
| 12 | +dotnetCampus.CommandLine is a simple yet high-performance command line parsing library for .NET. Thanks to the power of source code generators, it provides efficient parsing capabilities with a developer-friendly experience. |
13 | 13 |
|
14 |
| -Parsing a classical command line only takes 1091ns, thus 10 ticks. |
| 14 | +Parsing a typical command line takes only about 5000ns (0.005ms), making it one of the fastest command line parsers available in .NET. |
15 | 15 |
|
16 | 16 | ## Get Started
|
17 | 17 |
|
18 |
| -For your program `Main` method, write this code below: |
| 18 | +For your program `Main` method, write this code: |
19 | 19 |
|
20 | 20 | ```csharp
|
21 | 21 | class Program
|
22 | 22 | {
|
23 | 23 | static void Main(string[] args)
|
24 | 24 | {
|
| 25 | + // Create a new instance of CommandLine type from command line arguments |
25 | 26 | var commandLine = CommandLine.Parse(args);
|
26 |
| - var options = commandLine.As<Options>(new OptionsParser()); |
27 | 27 |
|
28 |
| - // Then, use your Options instance here. |
| 28 | + // Parse the command line into an instance of Options type |
| 29 | + // The source generator will automatically handle the parsing for you |
| 30 | + var options = commandLine.As<Options>(); |
| 31 | + |
| 32 | + // Now use your options object to implement your functionality |
29 | 33 | }
|
30 | 34 | }
|
31 | 35 | ```
|
32 | 36 |
|
33 |
| -You need to define the `Options` class as followed below: |
| 37 | +Define a class that maps command line arguments: |
34 | 38 |
|
35 | 39 | ```csharp
|
36 | 40 | class Options
|
37 | 41 | {
|
38 | 42 | [Value(0)]
|
39 |
| - public string FilePath { get; } |
40 |
| - |
41 |
| - [Option('s', "Silence")] |
42 |
| - public bool IsSilence { get; } |
| 43 | + public string FilePath { get; init; } |
43 | 44 |
|
44 |
| - [Option('m', "Mode")] |
45 |
| - public string StartMode { get; } |
| 45 | + [Option('s', "silence")] |
| 46 | + public bool IsSilence { get; init; } |
46 | 47 |
|
47 |
| - [Option("StartupSessions")] |
48 |
| - public IReadonlyList<string> StartupSessions { get; } |
| 48 | + [Option('m', "mode")] |
| 49 | + public string StartMode { get; init; } |
49 | 50 |
|
50 |
| - public Options( |
51 |
| - string filePath, |
52 |
| - bool isSilence, |
53 |
| - string startMode, |
54 |
| - IReadonlyList<string> startupSessions) |
55 |
| - { |
56 |
| - FilePath = filePath; |
57 |
| - IsSilence = isSilence; |
58 |
| - StartMode = startMode; |
59 |
| - StartupSessions = startupSessions; |
60 |
| - } |
| 51 | + [Option("startup-sessions")] |
| 52 | + public IReadOnlyList<string> StartupSessions { get; init; } = []; |
61 | 53 | }
|
62 | 54 | ```
|
63 | 55 |
|
64 |
| -Then you can run your program by passing these kind of command line args: |
| 56 | +Then use different command line styles to populate instances of this type: |
65 | 57 |
|
66 |
| -Windows style: |
| 58 | +### Windows PowerShell Style |
67 | 59 |
|
68 | 60 | ```powershell
|
69 | 61 | > demo.exe "C:\Users\lvyi\Desktop\demo.txt" -s -Mode Edit -StartupSessions A B C
|
70 | 62 | ```
|
71 | 63 |
|
| 64 | +### Windows CMD Style |
| 65 | + |
72 | 66 | ```cmd
|
73 | 67 | > demo.exe "C:\Users\lvyi\Desktop\demo.txt" /s /Mode Edit /StartupSessions A B C
|
74 | 68 | ```
|
75 | 69 |
|
76 |
| -Linux style: |
| 70 | +### Linux/GNU Style |
77 | 71 |
|
78 | 72 | ```bash
|
79 | 73 | $ demo.exe "C:/Users/lvyi/Desktop/demo.txt" -s --mode Edit --startup-sessions A B C
|
80 | 74 | ```
|
81 | 75 |
|
82 |
| -Notice that you cannot use different styles in a single command line. |
83 |
| - |
84 |
| -For `bool`: |
85 |
| - |
86 |
| -- You can pass `true` / `True` / `false` / `False` to specify a boolean value; |
87 |
| -- You can pass nothing but only a switch. |
88 |
| - |
89 |
| -It means that `-s true`, `-s True`, `-s` are the same. |
90 |
| - |
91 |
| -For `ValueAttribute` and `OptionAttribute`: |
92 |
| - |
93 |
| -- You can specify both on a single property. |
94 |
| -- If there is a value without option the property got the value, but if another value with the specified option exists, the new value will override the old one. |
95 |
| - |
96 |
| -```csharp |
97 |
| -[Value(0), Option('f', "File")] |
98 |
| -public string FilePath { get; } |
| 76 | +### .NET CLI Style |
| 77 | +``` |
| 78 | +> demo.exe "C:\Users\lvyi\Desktop\demo.txt" -s:true --mode:Edit --startup-sessions:A;B;C |
99 | 79 | ```
|
100 | 80 |
|
| 81 | +## Command Styles and Features |
| 82 | + |
| 83 | +The library supports multiple command line styles through `CommandLineStyle` enum: |
| 84 | +- Flexible (default): Intelligently recognizes multiple styles |
| 85 | +- GNU: GNU standard compliant |
| 86 | +- POSIX: POSIX standard compliant |
| 87 | +- DotNet: .NET CLI style |
| 88 | +- PowerShell: PowerShell style |
| 89 | + |
| 90 | +Advanced features include: |
| 91 | +- Support for various data types including collections and dictionaries |
| 92 | +- Positional arguments with `ValueAttribute` |
| 93 | +- Required properties with C# `required` modifier |
| 94 | +- Command handling with verb support |
| 95 | +- URL protocol parsing |
| 96 | +- High performance thanks to source generators |
| 97 | + |
101 | 98 | ## Engage, Contribute and Provide Feedback
|
102 | 99 |
|
103 | 100 | Thank you very much for firing a new issue and providing new pull requests.
|
|
0 commit comments