Merge pull request #224 from Lombiq/issue/OSOE-351

OSOE-351: Adding params-using CliProgram.GetCommand() overload, StringExtensions docs

Lombiq.HelpfulLibraries.Cli/CliProgram.cs

@@ -18,6 +18,12 @@ public class CliProgram
 
     public CliProgram(string command) => _command = command + OperatingSystemHelper.GetExecutableExtension();
 
+    /// <summary>
+    /// Creates a <see cref="Command"/> object based on the passed <paramref name="arguments"/>.
+    /// </summary>
+    public Command GetCommand(params object[] arguments) =>
+        GetCommand(arguments.ToList());
+
     /// <summary>
     /// Creates a <see cref="Command"/> object based on the passed <paramref name="arguments"/>.
     /// </summary>
@@ -70,6 +76,27 @@ public async Task ExecuteAsync(
     public Task ExecuteAsync(CancellationToken token, params object[] arguments) =>
         ExecuteAsync(arguments, additionalExceptionText: null, token);
 
+    /// <summary>
+    /// Calls the command specified in the constructor with the provided arguments, and returns the standard output as a
+    /// string. If the process doesn't succeed or outputs to the standard error stream then an exception is thrown.
+    /// </summary>
+    /// <param name="token">Passed into the CliWrap <see cref="Command"/>.</param>
+    /// <param name="arguments">
+    /// The arguments passed to the command. If an item is not a <see langword="string"/>, then it's converted using the
+    /// <see cref="CultureInfo.InvariantCulture"/> formatter.
+    /// </param>
+    /// <returns>The standard output as a string.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// <para>Thrown if the command fails or outputs to the error stream. The format is like this:</para>
+    /// <code>
+    /// The {command} {arguments} command failed with the output below.
+    /// {additional exception text}
+    /// {standard error output}
+    /// </code>
+    /// </exception>
+    public Task<string> ExecuteAndGetOutputAsync(CancellationToken token, params object[] arguments) =>
+        ExecuteAndGetOutputAsync(arguments, additionalExceptionText: null, token);
+
     /// <summary>
     /// Calls the command specified in the constructor with the provided arguments, and returns the standard output as a
     /// string. If the process doesn't succeed or outputs to the standard error stream then an exception is thrown.

Lombiq.HelpfulLibraries.Common/Extensions/StringExtensions.cs

@@ -130,14 +130,15 @@ public static string ReplaceOrdinalIgnoreCase(this string text, string oldValue,
         text.Replace(oldValue, newValue ?? string.Empty, StringComparison.OrdinalIgnoreCase);
 
     /// <summary>
-    /// A shortcut for <c>string.Equals(string, StringComparison.Ordinal)</c>.
+    /// Use simple <see cref="string"/> equality check with <c>=</c> instead, since it already uses ordinal string
+    /// comparison.
     /// </summary>
     [Obsolete("The string equals operator already uses ordinal string comparison.")]
     public static bool EqualsOrdinal(this string text, string? value) =>
         throw new NotSupportedException();
 
     /// <summary>
-    /// A shortcut for <c>string.Contains(string, StringComparison.Ordinal)</c>.
+    /// Use <c>string.Contains(string)</c> instead, since it already uses ordinal string comparison..
     /// </summary>
     [Obsolete("The string.Contains(value) member method already uses ordinal string comparison.")]
     public static bool ContainsOrdinal(this string text, string value) =>
@@ -168,7 +169,7 @@ public static bool EndsWithOrdinal(this string text, string value) =>
         text.EndsWith(value, StringComparison.Ordinal);
 
     /// <summary>
-    /// A shortcut for <c>string.Replace(string, string, StringComparison.Ordinal)</c>.
+    /// Use <c>string.Replace(string, string) instead, since it already uses ordinal string comparison.</c>.
     /// </summary>
     [Obsolete("The string.Replace(oldValue, newValue) member method already uses ordinal string comparison.")]
     public static string ReplaceOrdinal(this string text, string oldValue, string? newValue = "") =>