Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@drewburlingame
drewburlingame committed Dec 12, 2024
1 parent 08f0dd0 commit 6f7cbdd
Show file tree
Hide file tree
Showing 29 changed files with 113 additions and 116 deletions.
4 changes: 2 additions & 2 deletions docs/ArgumentValidation/data-annotations-validation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Enable with `appRunner.UseDataAnnotationValidations()`, or `appRunner.UseDataAnn

<!-- snippet: data_annotations_validation -->
<a id='snippet-data_annotations_validation'></a>
```c#
```cs
public class Program
{
static int Main(string[] args) => AppRunner.Run(args);
Expand Down Expand Up @@ -61,7 +61,7 @@ public class Verbosity : IArgumentModel, IValidatableObject
}
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Data_Annotations_Validation.cs#L13-L51' title='Snippet source file'>snippet source</a> | <a href='#snippet-data_annotations_validation' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Data_Annotations_Validation.cs#L14-L52' title='Snippet source file'>snippet source</a> | <a href='#snippet-data_annotations_validation' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

DataAnnotations can be defined on the method parameters and model properties. Notice
Expand Down
8 changes: 4 additions & 4 deletions docs/ArgumentValidation/fluent-validation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Enable with `appRunner.UseFluentValidation()`, or `appRunner.UseFluentValidation

<!-- snippet: fluent_validation -->
<a id='snippet-fluent_validation'></a>
```c#
```cs
public class Program
{
static int Main(string[] args) => AppRunner.Run(args);
Expand Down Expand Up @@ -92,7 +92,7 @@ public class VerbosityValidator : AbstractValidator<Verbosity>
}
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Fluent_Validation.cs#L15-L84' title='Snippet source file'>snippet source</a> | <a href='#snippet-fluent_validation' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Fluent_Validation.cs#L16-L85' title='Snippet source file'>snippet source</a> | <a href='#snippet-fluent_validation' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: fluent_validation_create_invalid -->
Expand Down Expand Up @@ -121,7 +121,7 @@ Register your validators with a container or provide a factory method.

<!-- snippet: fluent_validation_factory -->
<a id='snippet-fluent_validation_factory'></a>
```c#
```cs
public static AppRunner AppRunner =>
new AppRunner<Program>()
.UseNameCasing(Case.LowerCase)
Expand All @@ -136,7 +136,7 @@ public static AppRunner AppRunner =>
}
});
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Fluent_Validation.cs#L90-L104' title='Snippet source file'>snippet source</a> | <a href='#snippet-fluent_validation_factory' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Validation/Fluent_Validation.cs#L91-L105' title='Snippet source file'>snippet source</a> | <a href='#snippet-fluent_validation_factory' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

## vs. DataAnnotations
Expand Down
8 changes: 4 additions & 4 deletions docs/ArgumentValues/argument-separator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Let's look at an example.

<!-- snippet: argument_separator_end_of_options -->
<a id='snippet-argument_separator_end_of_options'></a>
```c#
```cs
public void EndOfOptions(IConsole console, CommandContext ctx, string? arg1)
{
var parserSettings = ctx.AppConfig.AppSettings.Parser;
Expand All @@ -38,7 +38,7 @@ public void EndOfOptions(IConsole console, CommandContext ctx, string? arg1)
console.WriteLine($"remaining: {string.Join(',', ctx.ParseResult!.RemainingOperands)}");
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Argument_Separator.cs#L20-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_separator_end_of_options' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Argument_Separator.cs#L21-L34' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_separator_end_of_options' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

This command expects a single operand, but if the operand value looks like an option, the parser will throw an exception
Expand Down Expand Up @@ -127,7 +127,7 @@ Let's modify the EndOfOptions example using the `[Command]` attribute to set the

<!-- snippet: argument_separator_pass_thru -->
<a id='snippet-argument_separator_pass_thru'></a>
```c#
```cs
[Command(ArgumentSeparatorStrategy = ArgumentSeparatorStrategy.PassThru)]
public void PassThru(IConsole console, CommandContext ctx, string? arg1)
{
Expand All @@ -142,7 +142,7 @@ public void PassThru(IConsole console, CommandContext ctx, string? arg1)
console.WriteLine($"remaining: {string.Join(',', ctx.ParseResult!.RemainingOperands)}");
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Argument_Separator.cs#L35-L49' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_separator_pass_thru' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Argument_Separator.cs#L36-L50' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_separator_pass_thru' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

Help will append ` [[--] <arg>...]` to the usage example when `ArgumentSeparatorStrategy.PassThru` is used.
Expand Down
8 changes: 4 additions & 4 deletions docs/ArgumentValues/piped-arguments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Every command is allowed a single operand collection. If one is defined and if p

<!-- snippet: piped_arguments -->
<a id='snippet-piped_arguments'></a>
```c#
```cs
public void List(IConsole console,
[Option('i')] bool idsOnly)
{
Expand All @@ -46,7 +46,7 @@ public void Disable(IConsole console, IEnumerable<string> ids)
}
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Piped_Arguments.cs#L14-L32' title='Snippet source file'>snippet source</a> | <a href='#snippet-piped_arguments' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Piped_Arguments.cs#L15-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-piped_arguments' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

This app has two commands, one to list users and the other to disable them. The list command works like this...
Expand Down Expand Up @@ -100,7 +100,7 @@ Let's add a Welcome command to our example app.

<!-- snippet: piped_arguments_options -->
<a id='snippet-piped_arguments_options'></a>
```c#
```cs
public void Welcome(IConsole console, string userId, [Option] ICollection<string> notify)
{
console.Out.WriteLine($"welcome {userSvc.Get(userId)?.Name}");
Expand All @@ -112,7 +112,7 @@ public void Welcome(IConsole console, string userId, [Option] ICollection<string
}
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Piped_Arguments.cs#L45-L56' title='Snippet source file'>snippet source</a> | <a href='#snippet-piped_arguments_options' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Values/Piped_Arguments.cs#L46-L57' title='Snippet source file'>snippet source</a> | <a href='#snippet-piped_arguments_options' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

And let's welcome Cris and send a notification to the other users
Expand Down
12 changes: 6 additions & 6 deletions docs/Arguments/argument-arity.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ CommandDotNet will check if the minimum or maximum arity has been exceeded and r

<!-- snippet: arguments_arity -->
<a id='snippet-arguments_arity'></a>
```c#
```cs
public void DefaultCommand(Model model,
bool requiredBool, Uri requiredRefType,
bool? nullableBool, Uri? nullableRefType,
Expand All @@ -66,7 +66,7 @@ public class Model : IArgumentModel
[Operand] public Uri DefaultRefType { get; set; } = new ("http://apple.com");
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Arity.cs#L17-L31' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_arity' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Arity.cs#L18-L32' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_arity' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: arguments_arity_help -->
Expand Down Expand Up @@ -128,13 +128,13 @@ We'll use options for these because we can have only one collection operand per

<!-- snippet: arguments_arity_collection -->
<a id='snippet-arguments_arity_collection'></a>
```c#
```cs
public void DefaultCommand(
[Option('b')] bool[] requiredBool, [Option('u')] Uri[] requiredRefType,
[Option] bool[]? nullableBool, [Option] Uri[]? nullableRefType,
[Option] bool[] optionalBool = null, [Option] Uri[] optionalRefType = null)
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Arity.cs#L93-L98' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_arity_collection' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Arity.cs#L94-L99' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_arity_collection' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: arguments_arity_collection_help -->
Expand Down Expand Up @@ -181,7 +181,7 @@ requiredRefType is required

<!-- snippet: known-arities -->
<a id='snippet-known-arities'></a>
```c#
```cs
public static IArgumentArity Zero => new ArgumentArity(0, 0);
public static IArgumentArity ZeroOrOne => new ArgumentArity(0, 1);
public static IArgumentArity ExactlyOne => new ArgumentArity(1, 1);
Expand All @@ -197,7 +197,7 @@ There are several extension methods that make it easier check conditions of a gi

<!-- snippet: arity-extensions -->
<a id='snippet-arity-extensions'></a>
```c#
```cs
/// <summary><see cref="IArgumentArity.Maximum"/> &gt; 1</summary>
public static bool AllowsMany(this IArgumentArity arity) => arity.Maximum > 1;

Expand Down
4 changes: 2 additions & 2 deletions docs/Arguments/argument-collections.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ Let's enhance our rocket launcher to visit multiple planets and specify a crew.

<!-- snippet: arguments_collections -->
<a id='snippet-arguments_collections'></a>
```c#
```cs
public void LaunchRocket(IConsole console,
IEnumerable<string> planets,
[Option('c', "crew")] string[] crew)
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Collections.cs#L11-L15' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_collections' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Arguments_Collections.cs#L12-L16' title='Snippet source file'>snippet source</a> | <a href='#snippet-arguments_collections' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

Help looks like...
Expand Down
28 changes: 14 additions & 14 deletions docs/Arguments/argument-models.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ Let's consider this notify command.

<!-- snippet: argument_models_notify_without_model -->
<a id='snippet-argument_models_notify_without_model'></a>
```c#
```cs
public void Notify(string message, List<string> recipients,
[Option] bool dryrun, [Option('v')] bool verbose, [Option('q')] bool quiet)
{
// send notification
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L16-L22' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_without_model' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L17-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_without_model' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: argument_models_notify_without_model_help -->
Expand Down Expand Up @@ -53,7 +53,7 @@ Here's how they're configured

<!-- snippet: argument_models_notify_with_model -->
<a id='snippet-argument_models_notify_with_model'></a>
```c#
```cs
public void Notify(
NotificationArgs notificationArgs,
DryRunOptions dryRunOptions,
Expand All @@ -71,12 +71,12 @@ public class NotificationArgs : IArgumentModel
public List<string> Recipients { get; set; } = null!;
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L27-L44' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_model' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L28-L45' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_model' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: argument_models_dry_run_and_verbosity -->
<a id='snippet-argument_models_dry_run_and_verbosity'></a>
```c#
```cs
public class DryRunOptions : IArgumentModel
{
[Option("dryrun")]
Expand All @@ -99,7 +99,7 @@ public class VerbosityOptions : IArgumentModel, IValidatableObject
}
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L167-L189' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_dry_run_and_verbosity' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L168-L190' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_dry_run_and_verbosity' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: argument_models_notify_with_model_help -->
Expand Down Expand Up @@ -138,7 +138,7 @@ Using same example from above, we configure the arguments into a single model li

<!-- snippet: argument_models_notify_with_model_composed -->
<a id='snippet-argument_models_notify_with_model_composed'></a>
```c#
```cs
public void Notify(NotificationArgs notificationArgs)
{
// send notification
Expand All @@ -157,7 +157,7 @@ public class NotificationArgs : IArgumentModel
public VerbosityOptions VerbosityOptions { get; set; } = null!;
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L49-L67' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_model_composed' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L50-L68' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_model_composed' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->


Expand All @@ -167,7 +167,7 @@ Instead of defining the model in each command method, the model could be defined

<!-- snippet: argument_models_notify_with_interceptor -->
<a id='snippet-argument_models_notify_with_interceptor'></a>
```c#
```cs
public Task<int> Interceptor(InterceptorExecutionDelegate next, CommandContext ctx,
DryRunOptions dryRunOptions, VerbosityOptions verbosityOptions)
{
Expand Down Expand Up @@ -205,7 +205,7 @@ public class VerbosityOptions : IArgumentModel
public bool Quite { get; set; }
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L72-L111' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_interceptor' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L73-L112' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_interceptor' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

<!-- snippet: argument_models_notify_with_interceptor_help -->
Expand Down Expand Up @@ -262,15 +262,15 @@ An example of invalidly nesting an IArgumentModel that contains operands

<!-- snippet: argument_models_notify_with_invalid_nested_operands_model -->
<a id='snippet-argument_models_notify_with_invalid_nested_operands_model'></a>
```c#
```cs
public class NotifyModel : IArgumentModel
{
public NotificationArgs NotificationArgs { get; set; }
public DryRunOptions DryRunOptions { get; set; }
public VerbosityOptions VerbosityOptions { get; set; }
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L148-L155' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_invalid_nested_operands_model' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L149-L156' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_invalid_nested_operands_model' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

And the error received because NotificationArgs contains operands
Expand All @@ -289,7 +289,7 @@ This is the correct way to nest a model with operands

<!-- snippet: argument_models_notify_with_nested_operands_model -->
<a id='snippet-argument_models_notify_with_nested_operands_model'></a>
```c#
```cs
public class NotifyModel : IArgumentModel
{
[OrderByPositionInClass]
Expand All @@ -298,7 +298,7 @@ public class NotifyModel : IArgumentModel
public VerbosityOptions VerbosityOptions { get; set; }
}
```
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L121-L129' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_nested_operands_model' title='Start of snippet'>anchor</a></sup>
<sup><a href='https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.DocExamples/Arguments/Arguments/Argument_Models.cs#L122-L130' title='Snippet source file'>snippet source</a> | <a href='#snippet-argument_models_notify_with_nested_operands_model' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

### Recommendation
Expand Down
Loading

0 comments on commit 6f7cbdd

Please sign in to comment.