Add examples and how-to guides for custom type converters, dictionary options, and flag arguments in CLI documentation. Reorganize and update related sections.

Author: phil-scott-78

Spectre.Docs.Cli.Examples/DemoApps/CustomTypeConverters/Main.cs

@@ -0,0 +1,98 @@
+using System.ComponentModel;
+using System.Globalization;
+using Spectre.Console.Cli;
+
+namespace Spectre.Docs.Cli.Examples.DemoApps.CustomTypeConverters;
+
+/// <summary>
+/// Demonstrates how to use custom type converters for complex types.
+/// </summary>
+public class Demo
+{
+    public static async Task<int> RunAsync(string[] args)
+    {
+        var app = new CommandApp<DrawCommand>();
+        return await app.RunAsync(args);
+    }
+}
+
+/// <summary>
+/// Represents a 2D point with X and Y coordinates.
+/// </summary>
+public readonly record struct Point(int X, int Y)
+{
+    public override string ToString() => $"({X}, {Y})";
+}
+
+/// <summary>
+/// Custom TypeConverter that converts strings like "10,20" to Point.
+/// </summary>
+public sealed class PointConverter : TypeConverter
+{
+    public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType)
+        => sourceType == typeof(string) || base.CanConvertFrom(context, sourceType);
+
+    public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
+    {
+        if (value is string str)
+        {
+            var parts = str.Split(',');
+            if (parts.Length == 2 &&
+                int.TryParse(parts[0].Trim(), out var x) &&
+                int.TryParse(parts[1].Trim(), out var y))
+            {
+                return new Point(x, y);
+            }
+
+            throw new FormatException($"Invalid point format: '{str}'. Expected format: X,Y (e.g., 10,20)");
+        }
+
+        return base.ConvertFrom(context, culture, value);
+    }
+}
+
+/// <summary>
+/// A drawing command demonstrating custom type converter usage.
+/// </summary>
+internal class DrawCommand : Command<DrawCommand.Settings>
+{
+    /// <summary>
+    /// Settings demonstrating custom type converters.
+    /// </summary>
+    public class Settings : CommandSettings
+    {
+        // Custom type with TypeConverter attribute
+        [CommandOption("--point <POINT>")]
+        [Description("A point in X,Y format (e.g., 10,20)")]
+        [TypeConverter(typeof(PointConverter))]
+        public required Point Location { get; init; }
+
+        // Optional point with nullable
+        [CommandOption("--offset [OFFSET]")]
+        [Description("Optional offset point")]
+        [TypeConverter(typeof(PointConverter))]
+        public required FlagValue<Point> Offset { get; init; }
+
+        [CommandOption("-c|--color")]
+        [Description("The drawing color")]
+        [DefaultValue("black")]
+        public string Color { get; init; } = "black";
+    }
+
+    protected override int Execute(CommandContext context, Settings settings, CancellationToken cancellation)
+    {
+        System.Console.WriteLine($"Drawing at location: {settings.Location}");
+        System.Console.WriteLine($"Color: {settings.Color}");
+
+        if (settings.Offset.IsSet)
+        {
+            System.Console.WriteLine($"With offset: {settings.Offset.Value}");
+            var adjusted = new Point(
+                settings.Location.X + settings.Offset.Value.X,
+                settings.Location.Y + settings.Offset.Value.Y);
+            System.Console.WriteLine($"Adjusted location: {adjusted}");
+        }
+
+        return 0;
+    }
+}

Spectre.Docs.Cli.Examples/DemoApps/DictionaryOptions/Main.cs

@@ -0,0 +1,82 @@
+using System.ComponentModel;
+using Spectre.Console.Cli;
+
+namespace Spectre.Docs.Cli.Examples.DemoApps.DictionaryOptions;
+
+/// <summary>
+/// Demonstrates how to use dictionary and lookup options for key-value pairs.
+/// </summary>
+public class Demo
+{
+    public static async Task<int> RunAsync(string[] args)
+    {
+        var app = new CommandApp<ConfigCommand>();
+        return await app.RunAsync(args);
+    }
+}
+
+/// <summary>
+/// A configuration command demonstrating dictionary option patterns.
+/// </summary>
+internal class ConfigCommand : Command<ConfigCommand.Settings>
+{
+    /// <summary>
+    /// Settings demonstrating IDictionary, ILookup, and IReadOnlyDictionary options.
+    /// </summary>
+    public class Settings : CommandSettings
+    {
+        // IDictionary<string, int> - key=value pairs with typed values
+        // Usage: --value port=8080 --value timeout=30
+        [CommandOption("--value <VALUE>")]
+        [Description("Configuration values in key=value format (e.g., port=8080)")]
+        public IDictionary<string, int>? Values { get; set; }
+
+        // ILookup<string, string> - allows multiple values per key
+        // Usage: --lookup env=dev --lookup env=test --lookup region=us
+        [CommandOption("--lookup <VALUE>")]
+        [Description("Lookup values allowing multiple entries per key")]
+        public ILookup<string, string>? Lookups { get; set; }
+
+        // IReadOnlyDictionary<string, string> - immutable key-value pairs
+        // Usage: --readonly name=myapp --readonly version=1.0
+        [CommandOption("--readonly <VALUE>")]
+        [Description("Read-only configuration values")]
+        public IReadOnlyDictionary<string, string>? ReadOnlyValues { get; set; }
+    }
+
+    protected override int Execute(CommandContext context, Settings settings, CancellationToken cancellation)
+    {
+        // Display IDictionary values
+        if (settings.Values?.Count > 0)
+        {
+            System.Console.WriteLine("Values (IDictionary<string, int>):");
+            foreach (var kvp in settings.Values)
+            {
+                System.Console.WriteLine($"  {kvp.Key} = {kvp.Value}");
+            }
+        }
+
+        // Display ILookup values (note: can have multiple values per key)
+        if (settings.Lookups != null)
+        {
+            System.Console.WriteLine("Lookups (ILookup<string, string>):");
+            foreach (var group in settings.Lookups)
+            {
+                var values = string.Join(", ", group);
+                System.Console.WriteLine($"  {group.Key} = [{values}]");
+            }
+        }
+
+        // Display IReadOnlyDictionary values
+        if (settings.ReadOnlyValues?.Count > 0)
+        {
+            System.Console.WriteLine("ReadOnly Values (IReadOnlyDictionary<string, string>):");
+            foreach (var kvp in settings.ReadOnlyValues)
+            {
+                System.Console.WriteLine($"  {kvp.Key} = {kvp.Value}");
+            }
+        }
+
+        return 0;
+    }
+}

Spectre.Docs.Cli.Examples/DemoApps/FlagArguments/Main.cs

@@ -0,0 +1,80 @@
+using System.ComponentModel;
+using Spectre.Console.Cli;
+
+namespace Spectre.Docs.Cli.Examples.DemoApps.FlagArguments;
+
+/// <summary>
+/// Demonstrates how to use FlagValue for optional flag arguments.
+/// </summary>
+public class Demo
+{
+    public static async Task<int> RunAsync(string[] args)
+    {
+        var app = new CommandApp<ServerCommand>();
+        return await app.RunAsync(args);
+    }
+}
+
+/// <summary>
+/// A server command demonstrating FlagValue patterns.
+/// </summary>
+internal class ServerCommand : Command<ServerCommand.Settings>
+{
+    /// <summary>
+    /// Settings demonstrating FlagValue with optional values.
+    /// </summary>
+    public class Settings : CommandSettings
+    {
+        // FlagValue<int> - can be used as --port (uses default) or --port 8080 (uses specified)
+        [CommandOption("--port [PORT]")]
+        [Description("The port to listen on (default: 3000 if flag present)")]
+        public required FlagValue<int> Port { get; init; }
+
+        // FlagValue<int?> - nullable inner type for truly optional values
+        [CommandOption("--timeout [SECONDS]")]
+        [Description("Connection timeout in seconds")]
+        public required FlagValue<int?> Timeout { get; init; }
+
+        // Regular option for comparison
+        [CommandOption("-h|--host")]
+        [Description("The host to bind to")]
+        [DefaultValue("localhost")]
+        public required string Host { get; init; } = "localhost";
+    }
+
+    protected override int Execute(CommandContext context, Settings settings, CancellationToken cancellation)
+    {
+        System.Console.WriteLine($"Host: {settings.Host}");
+
+        // Check if --port flag was provided
+        if (settings.Port?.IsSet == true)
+        {
+            // Value is the parsed port number (or default if none specified)
+            var port = settings.Port.Value;
+            System.Console.WriteLine($"Port: {port}");
+        }
+        else
+        {
+            System.Console.WriteLine("Port: not specified (will use system default)");
+        }
+
+        // Check if --timeout flag was provided
+        if (settings.Timeout?.IsSet == true)
+        {
+            if (settings.Timeout.Value.HasValue)
+            {
+                System.Console.WriteLine($"Timeout: {settings.Timeout.Value} seconds");
+            }
+            else
+            {
+                System.Console.WriteLine("Timeout: enabled (no specific value)");
+            }
+        }
+        else
+        {
+            System.Console.WriteLine("Timeout: not specified");
+        }
+
+        return 0;
+    }
+}

Spectre.Docs/Content/cli/how-to/async-commands-and-cancellation.md

@@ -2,7 +2,7 @@
 title: "Async Commands and Cancellation"
 description: "How to create asynchronous commands and handle cancellation in Spectre.Console.Cli"
 uid: "cli-async-commands"
-order: 2080
+order: 2040
 ---
 
 When your command performs I/O-bound operations like HTTP requests, database queries, or file operations, use `AsyncCommand<TSettings>` instead of `Command<TSettings>`. This lets you use `async/await` and enables graceful shutdown when users press Ctrl+C.

Spectre.Docs/Content/cli/how-to/configuring-commandapp-and-commands.md

@@ -2,7 +2,7 @@
 title: "Configuring CommandApp and Commands"
 description: "How to register commands with the CommandApp and configure global settings"
 uid: "cli-app-configuration"
-order: 2090
+order: 2050
 ---
 
 When building a CLI with multiple commands, use `CommandApp.Configure` to register commands, set up aliases, and customize how your application appears in help output.

Spectre.Docs/Content/cli/how-to/customizing-help-text-and-usage.md

@@ -2,7 +2,7 @@
 title: "Customizing Help Text and Usage"
 description: "How to tailor the automatically generated help output of Spectre.Console.Cli"
 uid: "cli-help-customization"
-order: 2100
+order: 2060
 ---
 
 Spectre.Console.Cli generates help text automatically from your commands and settings. When the defaults don't match your needs—whether for branding, accessibility, or clarity—you can customize the application name, add usage examples, adjust styling, or disable styling entirely for plain text output.

Spectre.Docs/Content/cli/how-to/defining-commands-and-arguments.md

@@ -2,7 +2,7 @@
 title: "Defining Commands and Arguments"
 description: "How to declare command-line parameters (arguments and options) using Spectre.Console.Cli's attributes and settings classes"
 uid: "cli-commands-arguments"
-order: 2050
+order: 2010
 ---
 
 Every command in Spectre.Console.Cli receives its input through a `CommandSettings` class. Decorate properties with `[CommandArgument]` for positional parameters and `[CommandOption]` for named flags and options. The framework handles parsing, validation, and help generation automatically.
@@ -56,5 +56,8 @@ Invalid values produce a clear error message listing the allowed options.
 
 ## See Also
 
+- <xref:cli-flag-arguments> - Optional flag values with FlagValue
+- <xref:cli-dictionary-options> - Key-value pair options with dictionaries
+- <xref:cli-custom-type-converters> - Custom type conversion for complex types
 - <xref:cli-required-options> - Force users to provide specific options
 - <xref:cli-attributes-parameters> - Complete attribute documentation

Spectre.Docs/Content/cli/how-to/handling-errors-and-exit-codes.md

@@ -2,7 +2,7 @@
 title: "Handling Errors and Exit Codes"
 description: "How Spectre.Console.Cli deals with exceptions and how to customize error handling"
 uid: "cli-error-handling"
-order: 2070
+order: 2030
 ---
 
 By default, Spectre.Console.Cli catches exceptions, displays a user-friendly message, and returns exit code `-1`. When you need more control—different exit codes for different error types, custom formatting, or integration with logging—you have two options: `SetExceptionHandler` for centralized handling within the framework, or `PropagateExceptions` for full manual control with try-catch blocks.

Spectre.Docs/Content/cli/how-to/hiding-commands-and-options.md

@@ -2,7 +2,7 @@
 title: "Hiding Commands and Options"
 description: "How to hide commands and options from help output while keeping them functional"
 uid: "cli-hidden-commands"
-order: 2130
+order: 2120
 ---
 
 Sometimes you need commands or options that work but shouldn't appear in help output—internal debugging tools, deprecated features you're phasing out, or advanced options that would overwhelm typical users. Hidden items remain fully functional; users who know about them can still use them.

Spectre.Docs/Content/cli/how-to/intercepting-command-execution.md

@@ -2,7 +2,7 @@
 title: "Intercepting Command Execution"
 description: "How to use command interceptors to run logic before or after any command executes"
 uid: "cli-command-interception"
-order: 2140
+order: 2130
 ---
 
 When you need cross-cutting concerns like logging, timing, or authentication across all commands without duplicating code, implement a command interceptor. The interceptor runs before and after every command, keeping individual commands focused on their core logic.