[Mono.Options] Add `CommandSet.GetCompletions()` (#10426)

* [Mono.Options] Add `CommandSet.GetCompletions()`

Add a `Mono.Options.CommandSet.GetCompletions()` method, which returns
all possible commands which match a given "completion prefix".

This is intended for e.g. bash completion support.

* Bump API snapshot submodule

6 files changed, 144 insertions, 8 deletions

diff --git a/mcs/class/Mono.Options/Documentation/en/examples/commands.cs b/mcs/class/Mono.Options/Documentation/en/examples/commands.cs
index 619a856a181..4d515f84cd7 100644
--- a/mcs/class/Mono.Options/Documentation/en/examples/commands.cs
+++ b/mcs/class/Mono.Options/Documentation/en/examples/commands.cs
@@ -5,6 +5,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 
 using Mono.Options;
 
@@ -25,6 +26,9 @@ class CommandDemo {
 			new Command ("echo", "Echo arguments to the screen") {
 				Run = ca => Console.WriteLine ("{0}", string.Join (" ", ca)),
 			},
+			new Command ("equinox", "Does something with the equinox?") {
+				Run = ca => Console.WriteLine ("{0}", string.Join (" ", ca)),
+			},
 			new RequiresArgsCommand (),
 			"Commands with spaces are supported:",
 			new Command ("has spaces", "spaces?!") {
@@ -35,8 +39,20 @@ class CommandDemo {
 				new Command ("file type", "Does something or other.") {
 					Run = ca => Console.WriteLine ("File type set to: {0}", string.Join (" ", ca)),
 				},
+				new Command ("output", "Sets  output location") {
+					Run = ca => Console.WriteLine ("Output set to: {0}", string.Join (" ", ca)),
+				},
 			},
 		};
+		commands.Add (new Command ("completions", "Show CommandSet completions") {
+				Run = ca => {
+					var start = ca.Any() ? string.Join (" ", ca) : "";
+					Console.WriteLine ($"Showing CommandSet completions for prefix '{start}':");
+					foreach (var completion in commands.GetCompletions (start)) {
+						Console.WriteLine ($"\tcompletion: {completion}");
+					}
+				},
+		});
 		commands.Add (commands);
 		return commands.Run (args);
 	}
diff --git a/mcs/class/Mono.Options/Documentation/en/examples/commands.in b/mcs/class/Mono.Options/Documentation/en/examples/commands.in
index 8c2e1a1cbdb..ae16748e870 100644
--- a/mcs/class/Mono.Options/Documentation/en/examples/commands.in
+++ b/mcs/class/Mono.Options/Documentation/en/examples/commands.in
@@ -27,3 +27,11 @@ mono Documentation/en/examples/commands.exe help invalid-command
 mono Documentation/en/examples/commands.exe has spaces
 
 mono Documentation/en/examples/commands.exe set file type whatever
+
+mono Documentation/en/examples/commands.exe completions
+
+mono Documentation/en/examples/commands.exe completions e
+
+mono Documentation/en/examples/commands.exe completions s
+
+mono Documentation/en/examples/commands.exe completions s o
diff --git a/mcs/class/Mono.Options/Documentation/en/examples/commands.txt b/mcs/class/Mono.Options/Documentation/en/examples/commands.txt
index 0bfa31d9dc6..9a2cc070801 100644
--- a/mcs/class/Mono.Options/Documentation/en/examples/commands.txt
+++ b/mcs/class/Mono.Options/Documentation/en/examples/commands.txt
@@ -2,7 +2,6 @@ $ mono commands.exe
 Use `commands help` for usage.
 
 $ mono commands.exe --help
-# HelpCommand.Invoke: arguments=
 usage: commands COMMAND [OPTIONS]
 
 Mono.Options.CommandSet sample app.
@@ -12,15 +11,17 @@ Global options:
 
 Available commands:
         echo                 Echo arguments to the screen
+        equinox              Does something with the equinox?
         requires-args        Class-based Command subclass
 Commands with spaces are supported:
         has spaces           spaces?!
 Nested CommandSets are also supported. They're invoked similarly to commands
 with spaces.
         set file type        Does something or other.
+        set output           Sets  output location
+        completions          Show CommandSet completions
 
 $ mono commands.exe help
-# HelpCommand.Invoke: arguments=
 usage: commands COMMAND [OPTIONS]
 
 Mono.Options.CommandSet sample app.
@@ -30,28 +31,32 @@ Global options:
 
 Available commands:
         echo                 Echo arguments to the screen
+        equinox              Does something with the equinox?
         requires-args        Class-based Command subclass
 Commands with spaces are supported:
         has spaces           spaces?!
 Nested CommandSets are also supported. They're invoked similarly to commands
 with spaces.
         set file type        Does something or other.
+        set output           Sets  output location
+        completions          Show CommandSet completions
 
 $ mono commands.exe help --help
-# HelpCommand.Invoke: arguments=--help
 Usage: commands COMMAND [OPTIONS]
 Use `commands help COMMAND` for help on a specific command.
 
 Available commands:
 
+        completions          Show CommandSet completions
         echo                 Echo arguments to the screen
+        equinox              Does something with the equinox?
         has spaces           spaces?!
         requires-args        Class-based Command subclass
         set file type        Does something or other.
+        set output           Sets  output location
         help                 Show this message and exit
 
 $ mono commands.exe help echo
-# HelpCommand.Invoke: arguments=echo
 --help
 
 $ mono commands.exe echo --help
@@ -65,7 +70,6 @@ commands: Missing required argument `--name=NAME`.
 commands: Use `commands help requires-args` for details.
 
 $ mono commands.exe help requires-args
-# HelpCommand.Invoke: arguments=requires-args
 usage: commands requires-args [OPTIONS]
 
 Class-based Command subclass example.
@@ -87,7 +91,6 @@ commands: Unknown command: invalid-command
 commands: Use `commands help` for usage.
 
 $ mono commands.exe help invalid-command
-# HelpCommand.Invoke: arguments=invalid-command
 commands: Unknown command: invalid-command
 commands: Use `commands help` for usage.
 
@@ -96,3 +99,28 @@ spaces, yo!
 
 $ mono commands.exe set file type whatever
 File type set to: whatever
+
+$ mono commands.exe completions
+Showing CommandSet completions for prefix '':
+	completion: echo
+	completion: equinox
+	completion: requires-args
+	completion: has spaces
+	completion: completions
+	completion: help
+	completion: set file type
+	completion: set output
+
+$ mono commands.exe completions e
+Showing CommandSet completions for prefix 'e':
+	completion: echo
+	completion: equinox
+
+$ mono commands.exe completions s
+Showing CommandSet completions for prefix 's':
+	completion: set file type
+	completion: set output
+
+$ mono commands.exe completions s o
+Showing CommandSet completions for prefix 's o':
+	completion: set output
diff --git a/mcs/class/Mono.Options/Makefile b/mcs/class/Mono.Options/Makefile
index 28d27326fe0..6c4c9194d76 100644
--- a/mcs/class/Mono.Options/Makefile
+++ b/mcs/class/Mono.Options/Makefile
@@ -59,6 +59,7 @@ Documentation/en/examples/Mono.Options.dll: $(the_lib)
 
 %.exe: %.cs Documentation/en/examples/Mono.Options.dll
 	$(CSCOMPILE) -debug:portable -r:$(topdir)/class/lib/$(PROFILE)/Mono.Posix.dll -r:$(topdir)/class/lib/$(PROFILE)/System.Core.dll -r:$(topdir)/class/lib/$(PROFILE)/System.dll \
+	-r:$(topdir)/class/lib/$(PROFILE)/mscorlib.dll \
 	-r:$(topdir)/class/lib/$(PROFILE)/Mono.Options.dll -out:$@ $<
 
 Documentation/en/examples/locale/es/LC_MESSAGES/localization.mo: Documentation/en/examples/localization-es.po
@@ -72,7 +73,8 @@ Documentation/en/examples/localization.exe: Documentation/en/examples/locale/es/
 	while read line 0<&3 ; do \
 		if test -n "$$line" ; then \
 			echo "$$ $$line" | sed 's#Documentation/en/examples/##' >> $@ ; \
-			sh -c "$$line" >> $@ 2>&1 ; \
+			cmd=`echo "$$line" | sed 's,mono ,MONO_PATH="$(topdir)/class/lib/$(BUILD_TOOLS_PROFILE)$(PLATFORM_PATH_SEPARATOR)" $(RUNTIME) ,g'` ; \
+			sh -c "$$cmd" >> $@ 2>&1 ; \
 		else \
 			echo "" >> $@ ; \
 		fi ; \
diff --git a/mcs/class/Mono.Options/Mono.Options/Options.cs b/mcs/class/Mono.Options/Mono.Options/Options.cs
index 780530a8da9..821937e7596 100644
--- a/mcs/class/Mono.Options/Mono.Options/Options.cs
+++ b/mcs/class/Mono.Options/Mono.Options/Options.cs
@@ -1782,6 +1782,53 @@ namespace Mono.Options
 			return false;
 		}
 
+		public IEnumerable<string> GetCompletions (string prefix = null)
+		{
+			string rest;
+			ExtractToken (ref prefix, out rest);
+
+			foreach (var command in this) {
+				if (command.Name.StartsWith (prefix, StringComparison.OrdinalIgnoreCase)) {
+					yield return command.Name;
+				}
+			}
+
+			if (NestedCommandSets == null)
+				yield break;
+
+			foreach (var subset in NestedCommandSets) {
+				if (subset.Suite.StartsWith (prefix, StringComparison.OrdinalIgnoreCase)) {
+					foreach (var c in subset.GetCompletions (rest)) {
+						yield return $"{subset.Suite} {c}";
+					}
+				}
+			}
+		}
+
+		static void ExtractToken (ref string input, out string rest)
+		{
+			rest      = "";
+			input     = input ?? "";
+
+			int top   = input.Length;
+			for (int i = 0; i < top; i++) {
+				if (char.IsWhiteSpace (input [i]))
+					continue;
+
+				for (int j = i; j < top; j++) {
+					if (char.IsWhiteSpace (input [j])) {
+						rest  = input.Substring (j).Trim ();
+						input = input.Substring (i, j).Trim ();
+						return;
+					}
+				}
+				rest  = "";
+				if (i != 0)
+					input = input.Substring (i).Trim ();
+				return;
+			}
+		}
+
 		public int Run (IEnumerable<string> arguments)
 		{
 			if (arguments == null)
@@ -1879,7 +1926,6 @@ namespace Mono.Options
 		public override int Invoke (IEnumerable<string> arguments)
 		{
 			var extra   = new List<string> (arguments ?? new string [0]);
-			Console.WriteLine ($"# HelpCommand.Invoke: arguments={string.Join (" ", arguments)}");
 			var _       = CommandSet.Options.MessageLocalizer;
 			if (extra.Count == 0) {
 				CommandSet.Options.WriteOptionDescriptions (CommandSet.Out);
diff --git a/mcs/class/Mono.Options/Test/Mono.Options/CommandSetTest.cs b/mcs/class/Mono.Options/Test/Mono.Options/CommandSetTest.cs
index 89ee1494749..93dbb3f21cf 100644
--- a/mcs/class/Mono.Options/Test/Mono.Options/CommandSetTest.cs
+++ b/mcs/class/Mono.Options/Test/Mono.Options/CommandSetTest.cs
@@ -130,6 +130,42 @@ namespace MonoTests.Mono.Options
 		}
 
 		[Test]
+		public void GetCompletions ()
+		{
+			var commands = new CommandSet ("example") {
+				new Command ("a"),
+				new Command ("aa"),
+				new Command ("a a"),
+				new Command ("cs c"),
+				new CommandSet ("cs") {
+					new CommandSet ("cs2") {
+						new CommandSet ("cs3") {
+							new Command ("cs-cs2-cs3-c"),
+						},
+					},
+				},
+			};
+			Assert.IsTrue (new[]{
+					"a",
+					"aa",
+					"a a",
+					"cs c",
+					"cs cs2 cs3 cs-cs2-cs3-c",
+			}.SequenceEqual (commands.GetCompletions ()));
+
+			Assert.IsTrue (new[]{
+					"a",
+					"aa",
+					"a a",
+			}.SequenceEqual (commands.GetCompletions ("a")));
+
+			Assert.IsTrue (new[]{
+					"cs c",
+					"cs cs2 cs3 cs-cs2-cs3-c",
+			}.SequenceEqual (commands.GetCompletions ("cs")));
+		}
+
+		[Test]
 		public void Run_Help ()
 		{
 			var o = new StringWriter ();