Skip to content

Commit 3eb90d7

Browse files
natemcmasternatemcmaster
authored
Update README and helloworld samples (#419)
1 parent ad9a1c7 commit 3eb90d7

File tree

8 files changed

+116
-84
lines changed

8 files changed

+116
-84
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,5 @@ jobs:
4545
path: artifacts/
4646
- uses: codecov/codecov-action@v1
4747
with:
48+
name: unittests-${{ matrix.os }}
4849
fail_ci_if_error: true

‎README.md‎

Lines changed: 43 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,48 @@
11
CommandLineUtils
22
================
33

4-
[![Build Status](https://dev.azure.com/natemcmaster/github/_apis/build/status/CommandLineUtils?branchName=main)](https://dev.azure.com/natemcmaster/github/_build/?definitionId=3)
5-
4+
[![Build Status][ci-badge]][ci] [![Code Coverage][codecov-badge]][codecov]
65
[![NuGet][nuget-badge] ![NuGet Downloads][nuget-download-badge]][nuget]
76

7+
[ci]: https://github.com/natemcmaster/CommandLineUtils/actions?query=workflow%3ACI+branch%3Amain
8+
[ci-badge]: https://github.com/natemcmaster/CommandLineUtils/workflows/CI/badge.svg
9+
[codecov]: https://codecov.io/gh/natemcmaster/CommandLineUtils
10+
[codecov-badge]: https://codecov.io/gh/natemcmaster/CommandLineUtils/branch/main/graph/badge.svg?token=l6uSsHZ8nA
811
[nuget]: https://www.nuget.org/packages/McMaster.Extensions.CommandLineUtils/
912
[nuget-badge]: https://img.shields.io/nuget/v/McMaster.Extensions.CommandLineUtils.svg?style=flat-square
1013
[nuget-download-badge]: https://img.shields.io/nuget/dt/McMaster.Extensions.CommandLineUtils?style=flat-square
1114

15+
This project helps you create command line applications using .NET.
16+
It simplifies parsing arguments provided on the command line, validating
17+
user inputs, and generating help text.
1218

13-
This is a fork of [Microsoft.Extensions.CommandLineUtils](https://github.com/aspnet/Common), which is no longer under [active development](https://github.com/aspnet/Common/issues/257). This fork, on the other hand, will continue to make improvements, release updates, and accept contributions.
14-
15-
The roadmap for this project is [pinned to the top of the issue list](https://github.com/natemcmaster/CommandLineUtils/issues/).
16-
17-
## Install
18-
19-
Install the [NuGet package][nuget] into your project.
20-
21-
```
22-
PM> Install-Package McMaster.Extensions.CommandLineUtils
23-
```
24-
```
25-
$ dotnet add package McMaster.Extensions.CommandLineUtils
26-
```
19+
The **roadmap** for this project is [pinned to the top of the issue list](https://github.com/natemcmaster/CommandLineUtils/issues/).
2720

2821
## Usage
2922

3023
See [documentation](https://natemcmaster.github.io/CommandLineUtils/) for API reference, samples, and tutorials.
31-
See [docs/samples/](./docs/samples/) for more examples, such as:
24+
See also [docs/samples/](./docs/samples/) for more examples, such as:
3225

26+
- [Hello world](./docs/samples/hello-world/)
3327
- [Async console apps](./docs/samples/helloworld-async/)
3428
- [Structuring an app with subcommands](./docs/samples/subcommands/)
3529
- [Defining options with attributes](./docs/samples/attributes/)
3630
- [Interactive console prompts](./docs/samples/interactive-prompts/)
3731
- [Required options and arguments](./docs/samples/validation/)
3832

33+
34+
### Installing the library
35+
36+
This project is available as a [NuGet package][nuget].
37+
38+
```
39+
$ dotnet add package McMaster.Extensions.CommandLineUtils
40+
```
41+
42+
### Code
3943
`CommandLineApplication` is the main entry point for most console apps parsing. There are two primary ways to use this API, using the builder pattern and attributes.
4044

45+
4146
### Attribute API
4247

4348
```c#
@@ -73,34 +78,27 @@ public class Program
7378
using System;
7479
using McMaster.Extensions.CommandLineUtils;
7580

76-
public class Program
77-
{
78-
public static int Main(string[] args)
79-
{
80-
var app = new CommandLineApplication();
81+
var app = new CommandLineApplication();
8182

82-
app.HelpOption();
83-
var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
84-
var optionRepeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
83+
app.HelpOption();
84+
var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
85+
var optionRepeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
8586

86-
app.OnExecute(() =>
87-
{
88-
var subject = optionSubject.HasValue()
89-
? optionSubject.Value()
90-
: "world";
91-
92-
var count = optionRepeat.HasValue() ? optionRepeat.ParsedValue : 1;
93-
for (var i = 0; i < count; i++)
94-
{
95-
Console.WriteLine($"Hello {subject}!");
96-
}
97-
return 0;
98-
});
99-
100-
return app.Execute(args);
87+
app.OnExecute(() =>
88+
{
89+
var subject = optionSubject.HasValue()
90+
? optionSubject.Value()
91+
: "world";
92+
93+
var count = optionRepeat.HasValue() ? optionRepeat.ParsedValue : 1;
94+
for (var i = 0; i < count; i++)
95+
{
96+
Console.WriteLine($"Hello {subject}!");
10197
}
102-
}
98+
return 0;
99+
});
103100

101+
return app.Execute(args);
104102
```
105103

106104
### Utilities
@@ -129,3 +127,7 @@ The library also includes other utilities for interaction with the console. Thes
129127
```
130128

131129
And more! See the [documentation](https://natemcmaster.github.io/CommandLineUtils/) for more API, such as `IConsole`, `IReporter`, and others.
130+
131+
## Project origin and status
132+
133+
This is a fork of [Microsoft.Extensions.CommandLineUtils](https://github.com/aspnet/Common), which is no longer under [active development](https://github.com/aspnet/Common/issues/257). This fork, on the other hand, will continue to make improvements, release updates, and accept contributions. It is currently maintained by [@natemcmaster](https://github.com/natemcmaster).

‎azure-pipelines.yml‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,4 @@
1-
trigger:
2-
branches:
3-
include:
4-
- 'main'
5-
- 'release/*'
6-
exclude:
7-
- gh-pages
8-
9-
pr:
10-
- '*'
1+
trigger: none
112

123
variables:
134
- name: BUILD_NUMBER

‎docs/samples/helloworld-async/AsyncBuilderApi.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<PropertyGroup>
44
<OutputType>Exe</OutputType>
5-
<TargetFramework>netcoreapp3.1</TargetFramework>
5+
<TargetFramework>net5.0</TargetFramework>
66
</PropertyGroup>
77

88
<ItemGroup>

‎docs/samples/helloworld-async/Program.cs‎

Lines changed: 20 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,29 @@
1-
// Copyright (c) Nate McMaster.
2-
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
3-
4-
using System;
1+
using System;
52
using System.Threading.Tasks;
63
using McMaster.Extensions.CommandLineUtils;
74

8-
/// <summary>
9-
/// You can call <see cref="CommandLineApplication.OnExecute(Func{Task{int}})" />
10-
/// with an async lambda to have your application execute asynchronously.
11-
/// </summary>
12-
public class AsyncWithBuilderApi
13-
{
14-
public static int Main(string[] args)
15-
{
16-
var app = new CommandLineApplication();
5+
var app = new CommandLineApplication();
176

18-
app.HelpOption("-h|--help");
19-
var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
20-
var optionRepeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
7+
app.HelpOption();
8+
var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
9+
var optionRepeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
2110

22-
app.OnExecuteAsync(async cancellationToken =>
23-
{
24-
var subject = optionSubject.HasValue()
25-
? optionSubject.Value()
26-
: "world";
11+
app.OnExecuteAsync(async cancellationToken =>
12+
{
13+
var subject = optionSubject.HasValue()
14+
? optionSubject.Value()
15+
: "world";
2716

28-
var count = optionRepeat.HasValue() ? optionRepeat.ParsedValue : 1;
29-
for (var i = 0; i < count; i++)
30-
{
31-
Console.Write($"Hello");
17+
var count = optionRepeat.HasValue() ? optionRepeat.ParsedValue : 1;
18+
for (var i = 0; i < count; i++)
19+
{
20+
Console.Write($"Hello");
3221

33-
// This pause here is just for indication that some awaitable operation could happens here.
34-
await Task.Delay(5000, cancellationToken);
35-
Console.WriteLine($" {subject}!");
36-
}
37-
});
22+
// Pause for dramatic effect
23+
await Task.Delay(2000, cancellationToken);
3824

39-
return app.Execute(args);
25+
Console.WriteLine($" {subject}!");
4026
}
41-
}
27+
});
28+
29+
return app.Execute(args);

‎docs/samples/helloworld/HelloWorld.csproj‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net5.0</TargetFramework>
6+
</PropertyGroup>
7+
8+
<ItemGroup>
9+
<PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="3.1.0" />
10+
</ItemGroup>
11+
12+
</Project>

‎docs/samples/helloworld/Program.cs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
using System;
2+
using McMaster.Extensions.CommandLineUtils;
3+
4+
var app = new CommandLineApplication();
5+
6+
app.HelpOption();
7+
var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);
8+
var optionRepeat = app.Option<int>("-n|--count <N>", "Repeat", CommandOptionType.SingleValue);
9+
10+
app.OnExecute(() =>
11+
{
12+
var subject = optionSubject.HasValue()
13+
? optionSubject.Value()
14+
: "world";
15+
16+
var count = optionRepeat.HasValue() ? optionRepeat.ParsedValue : 1;
17+
for (var i = 0; i < count; i++)
18+
{
19+
Console.WriteLine($"Hello {subject}!");
20+
}
21+
return 0;
22+
});
23+
24+
return app.Execute(args);

‎docs/samples/samples.sln‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AttributeApi", "generic-hos
6161
EndProject
6262
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "BuilderApi", "generic-host\BuilderApi\BuilderApi.csproj", "{B38FF032-9AFB-481F-A432-DFA7A5100C3A}"
6363
EndProject
64+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HelloWorld", "helloworld\HelloWorld.csproj", "{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}"
65+
EndProject
6466
Global
6567
GlobalSection(SolutionConfigurationPlatforms) = preSolution
6668
Debug|Any CPU = Debug|Any CPU
@@ -347,6 +349,18 @@ Global
347349
{B38FF032-9AFB-481F-A432-DFA7A5100C3A}.Release|x64.Build.0 = Release|Any CPU
348350
{B38FF032-9AFB-481F-A432-DFA7A5100C3A}.Release|x86.ActiveCfg = Release|Any CPU
349351
{B38FF032-9AFB-481F-A432-DFA7A5100C3A}.Release|x86.Build.0 = Release|Any CPU
352+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
353+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|Any CPU.Build.0 = Debug|Any CPU
354+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|x64.ActiveCfg = Debug|Any CPU
355+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|x64.Build.0 = Debug|Any CPU
356+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|x86.ActiveCfg = Debug|Any CPU
357+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Debug|x86.Build.0 = Debug|Any CPU
358+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|Any CPU.ActiveCfg = Release|Any CPU
359+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|Any CPU.Build.0 = Release|Any CPU
360+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|x64.ActiveCfg = Release|Any CPU
361+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|x64.Build.0 = Release|Any CPU
362+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|x86.ActiveCfg = Release|Any CPU
363+
{D444D44D-76BB-4FDB-9C06-1D8D30729F4A}.Release|x86.Build.0 = Release|Any CPU
350364
EndGlobalSection
351365
GlobalSection(SolutionProperties) = preSolution
352366
HideSolutionNode = FALSE

0 commit comments

Comments
 (0)