René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Provide base class or extend interface for Argument Completers","articleBody":"### Summary of the new feature / enhancement\n\nRelated to https://github.com/PowerShell/PowerShell-RFC/pull/269\n\nWe should provide a base class for Argument completers, so it is easier for users to create completers in C#.\n\n### **Current State**\n\n- User implements `IArgumentCompleter` interface.\n- User implements `CompleteArgument` method.\n- User has to write custom matching logic and handle quotes themselves.\n- Internal PowerShell completers need to call like static methods `CompletionCompleters.GetMatchingResults`, which is also repeated in every completer. This method's behaviour is also still in the internal API and not exposed for general use.\n\n### Proposed State\n\n- User implements derived Argument completer class from base abstract class `ArgumentCompleter`.\n- User only needs to implement abstract method `GetPossibleCompletionValues()`. Has the option to also override `ToolTipMapping`, `ListItemTextMapping` or `CompletionResultType`.\n- Abstract class implements `CompleteArgument` method. This cannot be overridden since it sets properties on base class and calls `GetMatchingResults`, which can be overridden since its behaviour can change.\n- Make sure base class is public and can be consumed by anyone writing completers in C#. I am not sure what assembly this can go into but it makes sense for base class to remain in core code so our internal completers can use it as well. \n- Internal PowerShell completers can also derive from this base class and become simplified. \n\n### Other considerations\n\n- Current base class example I've created does not include broad support for escaping; we'd probably need a way to include that in base class since its very cumbersome to do that yourself.\n- Ensure base class does not become fragile, but I suspect this won't be an issue if it exposes the right things and allows core completion functionality to be overridden in derived classes. I'd expect that once the base class is finalised and has flexibility with options it would probably not require much change. \n- Extend interface to include this functionality and provide default methods.\n\n### Proposed technical implementation details (optional)\n\n### Proposed Base Class - Option 1\n\n\u003cdetails\u003e\n\n```csharp\nusing System.Collections;\nusing System.Collections.Generic;\nusing System.Management.Automation.Language;\n\nnamespace System.Management.Automation\n{\n    public abstract class ArgumentCompleter : IArgumentCompleter\n    {\n        // Readonly properties which are visible in derived classes\n        protected string CommandName { get; private set; }\n        protected string ParameterName { get; private set; }\n        protected string WordToComplete { get; private set; }\n        protected CommandAst CommandAst { get; private set; }\n        protected IDictionary FakeBoundParameters { get; private set; }\n        \n        // User can optionally override these\n        protected virtual bool ShouldComplete { get; set; } = true;\n        protected virtual CompletionResultType CompletionResultType { get; set; } = CompletionResultType.Text;\n        protected virtual Func\u003cstring, string\u003e ToolTipMapping { get; set; }\n        protected virtual Func\u003cstring, string\u003e ListItemTextMapping { get; set; }\n        protected virtual bool EscapeGlobbingPath { get; set; }\n\n        // User must implement this\n        protected abstract IEnumerable\u003cstring\u003e GetPossibleCompletionValues();\n\n        // Default CompleteArgument implementation\n        // Cannot be overriden since it sets properties on base class and calls GetMatchingResults which can be overriden\n        public IEnumerable\u003cCompletionResult\u003e CompleteArgument(\n            string commandName,\n            string parameterName,\n            string wordToComplete,\n            CommandAst commandAst,\n            IDictionary fakeBoundParameters)\n        {\n            CommandName = commandName;\n            ParameterName = parameterName;\n            WordToComplete = wordToComplete;\n            CommandAst = commandAst;\n            FakeBoundParameters = fakeBoundParameters;\n            return ShouldComplete ? GetMatchingResults(wordToComplete) : [];\n        }\n\n        // Default matching with quote handling implementation encapsulated in base class\n        // Can be overriden if default behaviour needs to change\n        protected virtual IEnumerable\u003cCompletionResult\u003e GetMatchingResults(string wordToComplete)\n        {\n            string quote = CompletionCompleters.HandleDoubleAndSingleQuote(ref wordToComplete);\n\n            foreach (string value in GetPossibleCompletionValues())\n            {\n                if (value.StartsWith(wordToComplete, StringComparison.OrdinalIgnoreCase))\n                {\n                    string completionText = QuoteCompletionText(completionText: value, quote, EscapeGlobbingPath);\n\n                    string toolTip = ToolTipMapping?.Invoke(value) ?? value;\n                    string listItemText = ListItemTextMapping?.Invoke(value) ?? value;\n\n                    yield return new CompletionResult(completionText, listItemText, CompletionResultType, toolTip);\n                }\n            }\n        }\n\n        // Quote escaping which is probably fine to start out with but can be expanded later\n        private static string QuoteCompletionText(string completionText, string quote, bool escapeGlobbingPath)\n        {\n            if (CompletionCompleters.CompletionRequiresQuotes(completionText, escapeGlobbingPath))\n            {\n                string quoteInUse = string.IsNullOrEmpty(quote) ? \"'\" : quote;\n\n                completionText = quoteInUse == \"'\"\n                    ? completionText.Replace(\"'\", \"''\")\n                    : completionText.Replace(\"`\", \"``\").Replace(\"$\", \"`$\");\n\n                if (escapeGlobbingPath)\n                {\n                    completionText = quoteInUse == \"'\"\n                        ? completionText.Replace(\"[\", \"`[\").Replace(\"]\", \"`]\")\n                        : completionText.Replace(\"[\", \"``[\").Replace(\"]\", \"``]\");\n                }\n\n                return quoteInUse + completionText + quoteInUse;\n            }\n\n            return quote + completionText + quote;\n        }\n    }\n}\n\n```\n\n\u003c/details\u003e\n\n### Proposed extension of Interface - Option 2\n\n\u003cdetails\u003e\n\n```csharp\n    public interface IArgumentCompleter\n    {\n        /// \u003csummary\u003e\n        /// Implementations of this function are called by PowerShell to complete arguments.\n        /// \u003c/summary\u003e\n        /// \u003cparam name=\"commandName\"\u003eThe name of the command that needs argument completion.\u003c/param\u003e\n        /// \u003cparam name=\"parameterName\"\u003eThe name of the parameter that needs argument completion.\u003c/param\u003e\n        /// \u003cparam name=\"wordToComplete\"\u003eThe (possibly empty) word being completed.\u003c/param\u003e\n        /// \u003cparam name=\"commandAst\"\u003eThe command ast in case it is needed for completion.\u003c/param\u003e\n        /// \u003cparam name=\"fakeBoundParameters\"\u003e\n        /// This parameter is similar to $PSBoundParameters, except that sometimes PowerShell cannot or\n        /// will not attempt to evaluate an argument, in which case you may need to use \u003cparamref name=\"commandAst\"/\u003e.\n        /// \u003c/param\u003e\n        /// \u003creturns\u003e\n        /// A collection of completion results, most like with \u003csee cref=\"CompletionResult.ResultType\"/\u003e set to\n        /// \u003csee cref=\"CompletionResultType.ParameterValue\"/\u003e.\n        /// \u003c/returns\u003e\n        IEnumerable\u003cCompletionResult\u003e CompleteArgument(\n            string commandName,\n            string parameterName,\n            string wordToComplete,\n            CommandAst commandAst,\n            IDictionary fakeBoundParameters)\n        {\n            CommandName = commandName;\n            ParameterName = parameterName;\n            WordToComplete = wordToComplete;\n            CommandAst = commandAst;\n            FakeBoundParameters = fakeBoundParameters;\n            return ShouldComplete ? GetMatchingResults(wordToComplete) : [];\n        }\n\n        /// \u003csummary\u003e\n        /// Gets the name of the command that needs argument completion.\n        /// \u003c/summary\u003e\n        protected static string? CommandName { get; private set; }\n\n        /// \u003csummary\u003e\n        /// Gets the name of the parameter that needs argument completion.\n        /// \u003c/summary\u003e\n        protected static string? ParameterName { get; private set; }\n\n        /// \u003csummary\u003e\n        /// Gets the word being completed.\n        /// \u003c/summary\u003e\n        protected static string? WordToComplete { get; private set; }\n\n        /// \u003csummary\u003e\n        /// Gets the command abstract syntax tree (AST).\n        /// \u003c/summary\u003e\n        protected static CommandAst? CommandAst { get; private set; }\n\n        /// \u003csummary\u003e\n        /// Gets the fake bound parameters similar to $PSBoundParameters.\n        /// \u003c/summary\u003e\n        protected static IDictionary? FakeBoundParameters { get; private set; }\n\n        /// \u003csummary\u003e\n        /// Gets value indicating whether to perform completion.\n        /// \u003c/summary\u003e\n        protected bool ShouldComplete =\u003e true;\n\n        /// \u003csummary\u003e\n        /// Gets the type of the completion result.\n        /// \u003c/summary\u003e\n        protected CompletionResultType CompletionResultType =\u003e CompletionResultType.Text;\n\n        /// \u003csummary\u003e\n        /// Gets the mapping function for tooltips.\n        /// \u003c/summary\u003e\n        protected Func\u003cstring, string\u003e? ToolTipMapping =\u003e null;\n\n        /// \u003csummary\u003e\n        /// Gets the mapping function for list item texts.\n        /// \u003c/summary\u003e\n        protected Func\u003cstring, string\u003e? ListItemTextMapping =\u003e null;\n\n        /// \u003csummary\u003e\n        /// Gets value indicating whether to escape globbing paths.\n        /// \u003c/summary\u003e\n        protected bool EscapeGlobbingPath =\u003e false;\n\n        /// \u003csummary\u003e\n        /// Gets the possible completion values.\n        /// \u003c/summary\u003e\n        protected IEnumerable\u003cstring\u003e PossibleCompletionValues =\u003e [];\n\n        /// \u003csummary\u003e\n        /// Matches the possible completion values against the word to complete.\n        /// \u003c/summary\u003e\n        /// \u003cparam name=\"wordToComplete\"\u003eThe word to complete, which is used as a pattern for matching possible values.\u003c/param\u003e\n        /// \u003creturns\u003eAn \u003csee cref=\"IEnumerable{CompletionResult}\"/\u003e containing the matching completion results.\u003c/returns\u003e\n        /// \u003cremarks\u003eThis method handles different variations of completions, including considerations for quotes and escaping globbing paths.\u003c/remarks\u003e\n        protected IEnumerable\u003cCompletionResult\u003e GetMatchingResults(string wordToComplete)\n        {\n            string quote = CompletionCompleters.HandleDoubleAndSingleQuote(ref wordToComplete);\n\n            foreach (string value in PossibleCompletionValues)\n            {\n                if (value.StartsWith(wordToComplete, StringComparison.OrdinalIgnoreCase))\n                {\n                    string completionText = QuoteCompletionText(completionText: value, quote, EscapeGlobbingPath);\n\n                    string toolTip = ToolTipMapping?.Invoke(value) ?? value;\n                    string listItemText = ListItemTextMapping?.Invoke(value) ?? value;\n\n                    yield return new CompletionResult(completionText, listItemText, CompletionResultType, toolTip);\n                }\n            }\n        }\n\n        /// \u003csummary\u003e\n        /// Quotes the completion text.\n        /// \u003c/summary\u003e\n        /// \u003cparam name=\"completionText\"\u003eThe text to complete.\u003c/param\u003e\n        /// \u003cparam name=\"quote\"\u003eThe quote to use.\u003c/param\u003e\n        /// \u003cparam name=\"escapeGlobbingPath\"\u003eTrue if the globbing path needs to be escaped; otherwise, false.\u003c/param\u003e\n        /// \u003creturns\u003e\n        /// A quoted string if quoting is necessary.\n        /// \u003c/returns\u003e\n        private static string QuoteCompletionText(string completionText, string quote, bool escapeGlobbingPath)\n        {\n            if (CompletionCompleters.CompletionRequiresQuotes(completionText, escapeGlobbingPath))\n            {\n                string quoteInUse = string.IsNullOrEmpty(quote) ? \"'\" : quote;\n\n                completionText = quoteInUse == \"'\"\n                    ? completionText.Replace(\"'\", \"''\")\n                    : completionText.Replace(\"`\", \"``\").Replace(\"$\", \"`$\");\n\n                if (escapeGlobbingPath)\n                {\n                    completionText = quoteInUse == \"'\"\n                        ? completionText.Replace(\"[\", \"`[\").Replace(\"]\", \"`]\")\n                        : completionText.Replace(\"[\", \"``[\").Replace(\"]\", \"``]\");\n                }\n\n                return quoteInUse + completionText + quoteInUse;\n            }\n\n            return quote + completionText + quote;\n        }\n\n    }\n```\n\n\u003c/details\u003e","author":{"url":"https://github.com/ArmaanMcleod","@type":"Person","name":"ArmaanMcleod"},"datePublished":"2025-02-16T03:34:16.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":7},"url":"https://github.com/25033/PowerShell/issues/25033"}