PowerShell · iSazonov · Apr 21, 2025 · Apr 5, 2025 · Apr 5, 2025 · Apr 5, 2025
@@ -41,7 +41,7 @@ public sealed class JoinStringCommand : PSCmdlet
         /// Gets or sets the delimiter to join the output with.
         /// </summary>
         [Parameter(Position = 1)]
-        [ArgumentCompleter(typeof(JoinItemCompleter))]
+        [ArgumentCompleter(typeof(SeparatorArgumentCompleter))]
         [AllowEmptyString]
         public string Separator
         {
@@ -79,7 +79,7 @@ public string Separator
         /// Gets or sets a format string that is applied to each input object.
         /// </summary>
         [Parameter(ParameterSetName = "Format")]
-        [ArgumentCompleter(typeof(JoinItemCompleter))]
+        [ArgumentCompleter(typeof(FormatStringArgumentCompleter))]
         public string FormatString { get; set; }
 
         /// <summary>
@@ -160,79 +160,109 @@ protected override void EndProcessing()
         }
     }
 
-    [SuppressMessage(
-        "Microsoft.Performance",
-        "CA1812:AvoidUninstantiatedInternalClasses",
-        Justification = "Class is instantiated through late-bound reflection")]
-    internal class JoinItemCompleter : IArgumentCompleter
+    /// <summary>
+    /// Provides completion for the Separator parameter of the Join-String cmdlet.
+    /// </summary>
+    public class SeparatorArgumentCompleter : IArgumentCompleter
     {
-        public IEnumerable<CompletionResult> CompleteArgument(
-            string commandName,
-            string parameterName,
-            string wordToComplete,
-            CommandAst commandAst,
-            IDictionary fakeBoundParameters)
-        {
-            switch (parameterName)
-            {
-                case "Separator": return CompleteSeparator(wordToComplete);
-                case "FormatString": return CompleteFormatString(wordToComplete);
-            }
-
-            return null;
-        }
+        private static readonly string NewLineText =
+#if UNIX
+        "`n";
+#else
+        "`r`n";
+#endif
 
-        private static IEnumerable<CompletionResult> CompleteFormatString(string wordToComplete)
+        private static readonly IReadOnlyList<string> s_separatorValues = new List<string>
         {
-            var res = new List<CompletionResult>();
-            void AddMatching(string completionText)
-            {
-                if (completionText.StartsWith(wordToComplete, StringComparison.OrdinalIgnoreCase))
-                {
-                    res.Add(new CompletionResult(completionText));
-                }
-            }
-
-            AddMatching("'[{0}]'");
-            AddMatching("'{0:N2}'");
-            AddMatching("\"`r`n    `${0}\"");
-            AddMatching("\"`r`n    [string] `${0}\"");
+            ",",
+            ", ",
+            ";",
+            "; ",
+            NewLineText,
+            "-",
+            " ",
+        };
 
-            return res;
-        }
-
-        private IEnumerable<CompletionResult> CompleteSeparator(string wordToComplete)
+        private static readonly Dictionary<string, (string Tooltip, string ListItemText)> s_separatorMappings = new()
         {
-            var res = new List<CompletionResult>(10);
+            { ",", (TabCompletionStrings.SeparatorCommaToolTip, "Comma") },
+            { ", ", (TabCompletionStrings.SeparatorCommaSpaceToolTip, "Comma-Space") },
+            { ";", (TabCompletionStrings.SeparatorSemiColonToolTip, "Semi-Colon") },
+            { "; ", (TabCompletionStrings.SeparatorSemiColonSpaceToolTip, "Semi-Colon-Space") },
+            { NewLineText, (StringUtil.Format(TabCompletionStrings.SeparatorNewlineToolTip, NewLineText), "Newline") },
+            { "-", (TabCompletionStrings.SeparatorDashToolTip, "Dash") },
+            { " ", (TabCompletionStrings.SeparatorSpaceToolTip, "Space") },
+        };
 
-            void AddMatching(string completionText, string listText, string toolTip)
-            {
-                if (completionText.StartsWith(wordToComplete, StringComparison.OrdinalIgnoreCase))
-                {
-                    res.Add(new CompletionResult(completionText, listText, CompletionResultType.ParameterValue, toolTip));
-                }
-            }
+        private static string GetSeparatorToolTip(string separator)
+            => s_separatorMappings.TryGetValue(separator, out var mapping)
+                ? mapping.Tooltip
+                : separator;
 
-            AddMatching("', '", "Comma-Space", "', ' - Comma-Space");
-            AddMatching("';'", "Semi-Colon", "';'  - Semi-Colon ");
-            AddMatching("'; '", "Semi-Colon-Space", "'; ' - Semi-Colon-Space");
-            AddMatching($"\"{NewLineText}\"", "Newline", $"{NewLineText} - Newline");
-            AddMatching("','", "Comma", "','  - Comma");
-            AddMatching("'-'", "Dash", "'-'  - Dash");
-            AddMatching("' '", "Space", "' '  - Space");
-            return res;
-        }
+        private static string GetSeparatorListItemText(string separator)
+            => s_separatorMappings.TryGetValue(separator, out var mapping)
+                ? mapping.ListItemText
+                : separator;
 
-        public string NewLineText
+        /// <summary>
+        /// Returns completion results for Separator parameter.
+        /// </summary>
+        /// <param name="commandName">The command name.</param>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="wordToComplete">The word to complete.</param>
+        /// <param name="commandAst">The command AST.</param>
+        /// <param name="fakeBoundParameters">The fake bound parameters.</param>
+        /// <returns>List of Completion Results.</returns>
+        public IEnumerable<CompletionResult> CompleteArgument(
+            string commandName,
+            string parameterName,
+            string wordToComplete,
+            CommandAst commandAst,
+            IDictionary fakeBoundParameters)
+                => CompletionHelpers.GetMatchingResults(
+                    wordToComplete,
+                    possibleCompletionValues: s_separatorValues,
+                    listItemTextMapping: GetSeparatorListItemText,
+                    toolTipMapping: GetSeparatorToolTip,
+                    resultType: CompletionResultType.ParameterValue);
+    }
+
+    /// <summary>
+    /// Provides completion for the FormatString parameter of the Join-String cmdlet.
+    /// </summary>
+    public class FormatStringArgumentCompleter : IArgumentCompleter
+    {
+        private static readonly IReadOnlyList<string> s_formatStringValues = new List<string>
         {
-            get
-            {
+            "[{0}]",
+            "{0:N2}",
 #if UNIX
-                return "`n";
+            "`n    `${0}",
+            "`n    [string] `${0}",
 #else
-                return "`r`n";
+            "`r`n    `${0}",
+            "`r`n    [string] `${0}",
 #endif
-            }
-        }
+        };
+
+        /// <summary>
+        /// Returns completion results for FormatString parameter.
+        /// </summary>
+        /// <param name="commandName">The command name.</param>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="wordToComplete">The word to complete.</param>
+        /// <param name="commandAst">The command AST.</param>
+        /// <param name="fakeBoundParameters">The fake bound parameters.</param>
+        /// <returns>List of Completion Results.</returns>
+        public IEnumerable<CompletionResult> CompleteArgument(
+            string commandName,
+            string parameterName,
+            string wordToComplete,
+            CommandAst commandAst,
+            IDictionary fakeBoundParameters)
+                => CompletionHelpers.GetMatchingResults(
+                    wordToComplete,
+                    possibleCompletionValues: s_formatStringValues,
+                    escapeStrategy: WildcardPattern.Escape);
     }
 }
@@ -21,36 +21,66 @@ internal static class CompletionHelpers
         /// <param name="wordToComplete">The word to complete.</param>
         /// <param name="possibleCompletionValues">The possible completion values to iterate.</param>
         /// <param name="toolTipMapping">The optional tool tip mapping delegate.</param>
+        /// <param name="listItemTextMapping">The optional list item text mapping delegate.</param>
         /// <param name="resultType">The optional completion result type. Default is Text.</param>
-        /// <returns></returns>
+        /// <param name="escapeStrategy">
+        /// A delegate that specifies how to escape the word to complete. If null, no escaping is applied.
+        /// </param>
+        /// <returns>List of matching completion results.</returns>
         internal static IEnumerable<CompletionResult> GetMatchingResults(
             string wordToComplete,
             IEnumerable<string> possibleCompletionValues,
             Func<string, string> toolTipMapping = null,
-            CompletionResultType resultType = CompletionResultType.Text)
+            Func<string, string> listItemTextMapping = null,
+            CompletionResultType resultType = CompletionResultType.Text,
+            Func<string, string> escapeStrategy = null)
         {
             string quote = HandleDoubleAndSingleQuote(ref wordToComplete);
-            var pattern = WildcardPattern.Get(wordToComplete + "*", WildcardOptions.IgnoreCase);
 
             foreach (string value in possibleCompletionValues)
             {
-                if (pattern.IsMatch(value))
+                if (IsMatch(value, wordToComplete, escapeStrategy))
                 {
                     string completionText = QuoteCompletionText(value, quote);
+                    string toolTip = toolTipMapping?.Invoke(value) ?? value;
+                    string listItemText = listItemTextMapping?.Invoke(value) ?? value;
 
-                    string listItemText = value;
-
-                    yield return new CompletionResult(
-                        completionText,
-                        listItemText,
-                        resultType,
-                        toolTip: toolTipMapping is null
-                            ? listItemText
-                            : toolTipMapping(value));
+                    yield return new CompletionResult(completionText, listItemText, resultType, toolTip);
                 }
             }
         }
 
+        /// <summary>
+        /// Represents a method that checks whether a value matches a word or pattern.
+        /// </summary>
+        /// <param name="value">The input string to evaluate for a match.</param>
+        /// <param name="wordToComplete">The word or pattern to compare against.</param>
+        /// <param name="escapeStrategy">
+        /// A delegate that specifies how to escape the word to complete. If null, no escaping is applied.
+        /// </param>
+        /// <returns>
+        /// <c>true</c> if the value matches the word (case-insensitively) or the wildcard pattern; otherwise, <c>false</c>.
+        /// </returns>
+        internal delegate bool MatchDelegate(string value, string wordToComplete, Func<string, string> escapeStrategy = null);
+
+        internal static readonly MatchDelegate IsMatch = (value, wordToComplete, escapeStrategy) =>
+        {
+            string normalizedWord = WildcardPattern.Unescape(wordToComplete.ReplaceLineEndings("`"));
+
+            bool match = value.StartsWith(normalizedWord, StringComparison.OrdinalIgnoreCase);
+
+            if (!match)
+            {
+                string escapedWord = escapeStrategy?.Invoke(wordToComplete) ?? wordToComplete;
+
+                match = WildcardPattern
+                    .Get(escapedWord + "*", WildcardOptions.IgnoreCase)
+                    .IsMatch(value);
+            }
+
+            return match;
+        };
+
         /// <summary>
         /// Removes wrapping quotes from a string and returns the quote used, if present.
         /// </summary>
@@ -105,7 +135,7 @@ internal static string HandleDoubleAndSingleQuote(ref string wordToComplete)
                 return quoteInUse;
             }
 
-            bool hasFrontQuoteAndNoBackQuote = 
+            bool hasFrontQuoteAndNoBackQuote =
                 (hasFrontSingleQuote || hasFrontDoubleQuote) && !hasBackSingleQuote && !hasBackDoubleQuote;
 
             if (hasFrontQuoteAndNoBackQuote)
@@ -124,6 +154,7 @@ internal static string HandleDoubleAndSingleQuote(ref string wordToComplete)
         ///   <item><description>There are parsing errors in the input string.</description></item>
         ///   <item><description>The parsed token count is not exactly two (the input token + EOF).</description></item>
         ///   <item><description>The first token is a string or a PowerShell keyword containing special characters.</description></item>
+        ///   <item><description>The first token is a semi colon or comma token.</description></item>
         /// </list>
         /// </summary>
         /// <param name="completion">The input string to analyze for quoting requirements.</param>
@@ -139,15 +170,25 @@ internal static bool CompletionRequiresQuotes(string completion)
             Token firstToken = tokens[0];
             bool isStringToken = firstToken is StringToken;
             bool isKeywordToken = (firstToken.TokenFlags & TokenFlags.Keyword) != 0;
+            bool isSemiToken = firstToken.Kind == TokenKind.Semi;
+            bool isCommaToken = firstToken.Kind == TokenKind.Comma;
 
             if ((!requireQuote && isStringToken) || (isExpectedTokenCount && isKeywordToken))
             {
                 requireQuote = ContainsCharsToCheck(firstToken.Text);
             }
 
+            else if (isExpectedTokenCount && (isSemiToken || isCommaToken))
+            {
+                requireQuote = true;
+            }
+
             return requireQuote;
         }
 
+        private static bool ContainsEscapedNewlineString(string text)
+            => text.Contains("`n", StringComparison.Ordinal);
+
         private static bool ContainsCharsToCheck(ReadOnlySpan<char> text)
             => text.ContainsAny(s_defaultCharsToCheck);
 
@@ -165,6 +206,12 @@ private static bool ContainsCharsToCheck(ReadOnlySpan<char> text)
         /// </returns>
         internal static string QuoteCompletionText(string completionText, string quote)
         {
+            // Escaped newlines e.g. `r`n need be surrounded with double quotes
+            if (ContainsEscapedNewlineString(completionText))
+            {
+                return "\"" + completionText + "\"";
+            }
+
             if (!CompletionRequiresQuotes(completionText))
             {
                 return quote + completionText + quote;

@@ -586,4 +586,25 @@ using type &lt;AliasName&gt; = &lt;.NET-type&gt;</value>
   <data name="RegistryUnknownToolTip" xml:space="preserve">
     <value>An unsupported registry data type.</value>
   </data>
+  <data name="SeparatorCommaToolTip" xml:space="preserve">
+    <value>',' - Comma</value>
+  </data>
+  <data name="SeparatorCommaSpaceToolTip" xml:space="preserve">
+    <value>', ' - Comma-Space</value>
+  </data>
+  <data name="SeparatorSemiColonToolTip" xml:space="preserve">
+    <value>';' - Semi-Colon</value>
+  </data>
+  <data name="SeparatorSemiColonSpaceToolTip" xml:space="preserve">
+    <value>'; ' - Semi-Colon-Space</value>
+  </data>
+  <data name="SeparatorNewlineToolTip" xml:space="preserve">
+    <value>{0} - Newline</value>
+  </data>
+  <data name="SeparatorDashToolTip" xml:space="preserve">
+    <value>'-' - Dash</value>
+  </data>
+  <data name="SeparatorSpaceToolTip" xml:space="preserve">
+    <value>' ' - Space</value>
+  </data>
 </root>