Alias for command branches (#411)

ilyahryapko · web-flow · commit 04610cf49229 · 2023-02-09T14:26:06.000Z
diff --git a/src/Spectre.Console.Cli/ConfiguratorExtensions.cs b/src/Spectre.Console.Cli/ConfiguratorExtensions.cs
@@ -88,12 +88,12 @@ public static IConfigurator UseStrictParsing(this IConfigurator configurator)
 
         configurator.Settings.StrictParsing = true;
         return configurator;
-    }
-
+    }
+
     /// <summary>
     /// Tells the help writer whether or not to trim trailing period.
     /// </summary>
-    /// <param name="configurator">The configurator.</param>
+    /// <param name="configurator">The configurator.</param>
     /// <param name="trimTrailingPeriods">True to trim trailing period (default), false to not.</param>
     /// <returns>A configurator that can be used to configure the application further.</returns>
     public static IConfigurator TrimTrailingPeriods(this IConfigurator configurator, bool trimTrailingPeriods)
@@ -181,7 +181,8 @@ public static IConfigurator SetInterceptor(this IConfigurator configurator, ICom
     /// <param name="configurator">The configurator.</param>
     /// <param name="name">The name of the command branch.</param>
     /// <param name="action">The command branch configuration.</param>
-    public static void AddBranch(
+    /// <returns>A branch configurator that can be used to configure the branch further.</returns>
+    public static IBranchConfigurator AddBranch(
         this IConfigurator configurator,
         string name,
         Action<IConfigurator<CommandSettings>> action)
@@ -191,7 +192,7 @@ public static void AddBranch(
             throw new ArgumentNullException(nameof(configurator));
         }
 
-        configurator.AddBranch(name, action);
+        return configurator.AddBranch(name, action);
     }
 
     /// <summary>
@@ -201,7 +202,8 @@ public static void AddBranch(
     /// <param name="configurator">The configurator.</param>
     /// <param name="name">The name of the command branch.</param>
     /// <param name="action">The command branch configuration.</param>
-    public static void AddBranch<TSettings>(
+    /// <returns>A branch configurator that can be used to configure the branch further.</returns>
+    public static IBranchConfigurator AddBranch<TSettings>(
         this IConfigurator<TSettings> configurator,
         string name,
         Action<IConfigurator<TSettings>> action)
@@ -212,7 +214,7 @@ public static void AddBranch<TSettings>(
             throw new ArgumentNullException(nameof(configurator));
         }
 
-        configurator.AddBranch(name, action);
+        return configurator.AddBranch(name, action);
     }
 
     /// <summary>
diff --git a/src/Spectre.Console.Cli/IBranchConfigurator.cs b/src/Spectre.Console.Cli/IBranchConfigurator.cs
@@ -0,0 +1,14 @@
+namespace Spectre.Console.Cli;
+
+/// <summary>
+/// Represents a branch configurator.
+/// </summary>
+public interface IBranchConfigurator
+{
+    /// <summary>
+    /// Adds an alias (an alternative name) to the branch being configured.
+    /// </summary>
+    /// <param name="name">The alias to add to the branch being configured.</param>
+    /// <returns>The same <see cref="IBranchConfigurator"/> instance so that multiple calls can be chained.</returns>
+    IBranchConfigurator WithAlias(string name);
+}
diff --git a/src/Spectre.Console.Cli/IConfigurator.cs b/src/Spectre.Console.Cli/IConfigurator.cs
@@ -41,6 +41,7 @@ ICommandConfigurator AddDelegate<TSettings>(string name, Func<CommandContext, TS
     /// <typeparam name="TSettings">The command setting type.</typeparam>
     /// <param name="name">The name of the command branch.</param>
     /// <param name="action">The command branch configurator.</param>
-    void AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)
+    /// <returns>A branch configurator that can be used to configure the branch further.</returns>
+    IBranchConfigurator AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)
         where TSettings : CommandSettings;
 }
diff --git a/src/Spectre.Console.Cli/IConfiguratorOfT.cs b/src/Spectre.Console.Cli/IConfiguratorOfT.cs
@@ -51,6 +51,7 @@ ICommandConfigurator AddDelegate<TDerivedSettings>(string name, Func<CommandCont
     /// <typeparam name="TDerivedSettings">The derived command setting type.</typeparam>
     /// <param name="name">The name of the command branch.</param>
     /// <param name="action">The command branch configuration.</param>
-    void AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)
+    /// <returns>A branch configurator that can be used to configure the branch further.</returns>
+    IBranchConfigurator AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)
         where TDerivedSettings : TSettings;
 }
diff --git a/src/Spectre.Console.Cli/Internal/Configuration/BranchConfigurator.cs b/src/Spectre.Console.Cli/Internal/Configuration/BranchConfigurator.cs
@@ -0,0 +1,17 @@
+﻿namespace Spectre.Console.Cli;
+
+internal sealed class BranchConfigurator : IBranchConfigurator
+{
+    public ConfiguredCommand Command { get; }
+
+    public BranchConfigurator(ConfiguredCommand command)
+    {
+        Command = command;
+    }
+
+    public IBranchConfigurator WithAlias(string alias)
+    {
+        Command.Aliases.Add(alias);
+        return this;
+    }
+}
diff --git a/src/Spectre.Console.Cli/Internal/Configuration/Configurator.cs b/src/Spectre.Console.Cli/Internal/Configuration/Configurator.cs
@@ -48,12 +48,13 @@ public ICommandConfigurator AddDelegate<TSettings>(string name, Func<CommandCont
         return new CommandConfigurator(command);
     }
 
-    public void AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)
+    public IBranchConfigurator AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)
         where TSettings : CommandSettings
     {
         var command = ConfiguredCommand.FromBranch<TSettings>(name);
         action(new Configurator<TSettings>(command, _registrar));
-        Commands.Add(command);
+        var added = Commands.AddAndReturn(command);
+        return new BranchConfigurator(added);
     }
 
     ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)
@@ -74,7 +75,7 @@ ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)
         return result;
     }
 
-    void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)
+    IBranchConfigurator IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)
     {
         var command = ConfiguredCommand.FromBranch(settings, name);
 
@@ -86,6 +87,7 @@ void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBra
         }
 
         action(configurator);
-        Commands.Add(command);
+        var added = Commands.AddAndReturn(command);
+        return new BranchConfigurator(added);
     }
 }
diff --git a/src/Spectre.Console.Cli/Internal/Configuration/ConfiguratorOfT.cs b/src/Spectre.Console.Cli/Internal/Configuration/ConfiguratorOfT.cs
@@ -47,12 +47,13 @@ public ICommandConfigurator AddDelegate<TDerivedSettings>(string name, Func<Comm
         return new CommandConfigurator(command);
     }
 
-    public void AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)
+    public IBranchConfigurator AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)
         where TDerivedSettings : TSettings
     {
         var command = ConfiguredCommand.FromBranch<TDerivedSettings>(name);
         action(new Configurator<TDerivedSettings>(command, _registrar));
-        _command.Children.Add(command);
+        var added = _command.Children.AddAndReturn(command);
+        return new BranchConfigurator(added);
     }
 
     ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)
@@ -73,7 +74,7 @@ ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)
         return result;
     }
 
-    void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)
+    IBranchConfigurator IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)
     {
         var command = ConfiguredCommand.FromBranch(settings, name);
 
@@ -85,6 +86,7 @@ void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBra
         }
 
         action(configurator);
-        _command.Children.Add(command);
+        var added = _command.Children.AddAndReturn(command);
+        return new BranchConfigurator(added);
     }
 }
diff --git a/src/Spectre.Console.Cli/Unsafe/IUnsafeConfigurator.cs b/src/Spectre.Console.Cli/Unsafe/IUnsafeConfigurator.cs
@@ -19,5 +19,6 @@ public interface IUnsafeConfigurator
     /// <param name="name">The name of the command branch.</param>
     /// <param name="settings">The command setting type.</param>
     /// <param name="action">The command branch configurator.</param>
-    void AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action);
+    /// <returns>A branch configurator that can be used to configure the branch further.</returns>
+    IBranchConfigurator AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action);
 }
diff --git a/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.cs b/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.cs

Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,7 @@ ICommandConfigurator AddDelegate<TSettings>(string name, Func<CommandContext, TS`
`41`	`41`	`/// <typeparam name="TSettings">The command setting type.</typeparam>`
`42`	`42`	`/// <param name="name">The name of the command branch.</param>`
`43`	`43`	`/// <param name="action">The command branch configurator.</param>`
`44`		`- void AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)`
	`44`	`+ /// <returns>A branch configurator that can be used to configure the branch further.</returns>`
	`45`	`+ IBranchConfigurator AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)`
`45`	`46`	`where TSettings : CommandSettings;`
`46`	`47`	`}`
Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,7 @@ ICommandConfigurator AddDelegate<TDerivedSettings>(string name, Func<CommandCont`
`51`	`51`	`/// <typeparam name="TDerivedSettings">The derived command setting type.</typeparam>`
`52`	`52`	`/// <param name="name">The name of the command branch.</param>`
`53`	`53`	`/// <param name="action">The command branch configuration.</param>`
`54`		`- void AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)`
	`54`	`+ /// <returns>A branch configurator that can be used to configure the branch further.</returns>`
	`55`	`+ IBranchConfigurator AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)`
`55`	`56`	`where TDerivedSettings : TSettings;`
`56`	`57`	`}`
Original file line number	Diff line number	Diff line change
`@@ -48,12 +48,13 @@ public ICommandConfigurator AddDelegate<TSettings>(string name, Func<CommandCont`
`48`	`48`	`return new CommandConfigurator(command);`
`49`	`49`	`}`
`50`	`50`
`51`		`- public void AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)`
	`51`	`+ public IBranchConfigurator AddBranch<TSettings>(string name, Action<IConfigurator<TSettings>> action)`
`52`	`52`	`where TSettings : CommandSettings`
`53`	`53`	`{`
`54`	`54`	`var command = ConfiguredCommand.FromBranch<TSettings>(name);`
`55`	`55`	`action(new Configurator<TSettings>(command, _registrar));`
`56`		`- Commands.Add(command);`
	`56`	`+ var added = Commands.AddAndReturn(command);`
	`57`	`+ return new BranchConfigurator(added);`
`57`	`58`	`}`
`58`	`59`
`59`	`60`	`ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)`
`@@ -74,7 +75,7 @@ ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)`
`74`	`75`	`return result;`
`75`	`76`	`}`
`76`	`77`
`77`		`- void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)`
	`78`	`+ IBranchConfigurator IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)`
`78`	`79`	`{`
`79`	`80`	`var command = ConfiguredCommand.FromBranch(settings, name);`
`80`	`81`
`@@ -86,6 +87,7 @@ void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBra`
`86`	`87`	`}`
`87`	`88`
`88`	`89`	`action(configurator);`
`89`		`- Commands.Add(command);`
	`90`	`+ var added = Commands.AddAndReturn(command);`
	`91`	`+ return new BranchConfigurator(added);`
`90`	`92`	`}`
`91`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -47,12 +47,13 @@ public ICommandConfigurator AddDelegate<TDerivedSettings>(string name, Func<Comm`
`47`	`47`	`return new CommandConfigurator(command);`
`48`	`48`	`}`
`49`	`49`
`50`		`- public void AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)`
	`50`	`+ public IBranchConfigurator AddBranch<TDerivedSettings>(string name, Action<IConfigurator<TDerivedSettings>> action)`
`51`	`51`	`where TDerivedSettings : TSettings`
`52`	`52`	`{`
`53`	`53`	`var command = ConfiguredCommand.FromBranch<TDerivedSettings>(name);`
`54`	`54`	`action(new Configurator<TDerivedSettings>(command, _registrar));`
`55`		`- _command.Children.Add(command);`
	`55`	`+ var added = _command.Children.AddAndReturn(command);`
	`56`	`+ return new BranchConfigurator(added);`
`56`	`57`	`}`
`57`	`58`
`58`	`59`	`ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)`
`@@ -73,7 +74,7 @@ ICommandConfigurator IUnsafeConfigurator.AddCommand(string name, Type command)`
`73`	`74`	`return result;`
`74`	`75`	`}`
`75`	`76`
`76`		`- void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)`
	`77`	`+ IBranchConfigurator IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action)`
`77`	`78`	`{`
`78`	`79`	`var command = ConfiguredCommand.FromBranch(settings, name);`
`79`	`80`
`@@ -85,6 +86,7 @@ void IUnsafeConfigurator.AddBranch(string name, Type settings, Action<IUnsafeBra`
`85`	`86`	`}`
`86`	`87`
`87`	`88`	`action(configurator);`
`88`		`- _command.Children.Add(command);`
	`89`	`+ var added = _command.Children.AddAndReturn(command);`
	`90`	`+ return new BranchConfigurator(added);`
`89`	`91`	`}`
`90`	`92`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,6 @@ public interface IUnsafeConfigurator`
`19`	`19`	`/// <param name="name">The name of the command branch.</param>`
`20`	`20`	`/// <param name="settings">The command setting type.</param>`
`21`	`21`	`/// <param name="action">The command branch configurator.</param>`
`22`		`- void AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action);`
	`22`	`+ /// <returns>A branch configurator that can be used to configure the branch further.</returns>`
	`23`	`+ IBranchConfigurator AddBranch(string name, Type settings, Action<IUnsafeBranchConfigurator> action);`
`23`	`24`	`}`