add - doc - Added the BuildVtSequence() function

We've added the useful BuildVtSequence() function

---

This function can build your VT sequence using just the enumeration of VtSequenceSpecificTypes, which contains all the VT sequences supported by VT.NET.

---

Type: add
Breaking: False
Doc Required: True
Part: 1/1

VT.NET.Tests/VtSequenceBuilderTests.cs

@@ -23,7 +23,6 @@
  */
 
 using Shouldly;
-using System.Text.RegularExpressions;
 using VT.NET.Builder;
 using VT.NET.Builder.Types;
 
@@ -2096,5 +2095,36 @@ public static void TestGeneratePmPrivacyMessage(string proprietaryCommands)
             Should.NotThrow(() => actual = PmSequences.GeneratePmPrivacyMessage(proprietaryCommands));
             actual.ShouldBe(result);
         }
+
+        /// <summary>
+        /// Builds VT sequence with arguments
+        /// </summary>
+        [Test]
+        [TestCase(VtSequenceSpecificTypes.CsiEraseRectangularArea, 1, 3, 3, 3, ExpectedResult = $"\x1B[1;3;3;3$z")]
+        [TestCase(VtSequenceSpecificTypes.PmPrivacyMessage, "Kermit", ExpectedResult = $"\x1B^Kermit\x9C")]
+        [TestCase(VtSequenceSpecificTypes.OscOperatingSystemCommand, "0;Hello", ExpectedResult = $"\x1B]0;Hello\x07")]
+        [TestCase(VtSequenceSpecificTypes.OscOperatingSystemCommandAlt, "0;Hello", ExpectedResult = $"\x1B]0;Hello\x9C")]
+        [TestCase(VtSequenceSpecificTypes.EscDesignateG2CharacterSetAlt, "Z", ExpectedResult = $"\x1B,Z")]
+        [TestCase(VtSequenceSpecificTypes.DcsRequestResourceValues, "776964654368617273", ExpectedResult = $"\x1BP+Q776964654368617273\x9C")]
+        [TestCase(VtSequenceSpecificTypes.ApcApplicationProgramCommand, "Kermit", ExpectedResult = $"\x1B_Kermit\x9C")]
+        public static string TestBuildVtSequence(VtSequenceSpecificTypes specificType, params object[] arguments)
+        {
+            string actual = "";
+            Should.NotThrow(() => actual = VtSequenceBuilderTools.BuildVtSequence(specificType, arguments));
+            return actual;
+        }
+
+        /// <summary>
+        /// Builds VT sequence without arguments
+        /// </summary>
+        [Test]
+        [TestCase(VtSequenceSpecificTypes.EscInvokeG1CharacterSetGr, ExpectedResult = $"\x1B~")]
+        [TestCase(VtSequenceSpecificTypes.C1ReturnTerminalId, ExpectedResult = $"\x1BZ")]
+        public static string TestBuildVtSequenceNoArgs(VtSequenceSpecificTypes specificType)
+        {
+            string actual = "";
+            Should.NotThrow(() => actual = VtSequenceBuilderTools.BuildVtSequence(specificType));
+            return actual;
+        }
     }
 }

VT.NET/Builder/Types/ApcSequences.cs

@@ -33,7 +33,7 @@ namespace VT.NET.Builder.Types
     public static class ApcSequences
     {
         /// <summary>
-        /// [APC Pt ST] Regular expression for privacy message
+        /// [APC Pt ST] Regular expression for application program command
         /// </summary>
         public static string ApcApplicationProgramCommandSequenceRegex { get => @"(\x9f|\x1b_).+\x9c"; }
 

VT.NET/Builder/Types/OscSequences.cs

@@ -33,9 +33,14 @@ namespace VT.NET.Builder.Types
     public static class OscSequences
     {
         /// <summary>
-        /// [OSC Ps ; Pt BEL / ST] Regular expression for operating system command
+        /// [OSC Ps ; Pt BEL] Regular expression for operating system command
         /// </summary>
-        public static string OscOperatingSystemCommandSequenceRegex { get => @"(\x9D|\x1B\]).+(\x07|\x9c)"; }
+        public static string OscOperatingSystemCommandSequenceRegex { get => @"(\x9D|\x1B\]).+[\x07]"; }
+
+        /// <summary>
+        /// [OSC Ps ; Pt ST] Regular expression for operating system command
+        /// </summary>
+        public static string OscOperatingSystemCommandAltSequenceRegex { get => @"(\x9D|\x1B\]).+[\x9c]"; }
 
         /// <summary>
         /// [OSC Ps ; Pt BEL] Generates an escape sequence that can be used for the console
@@ -55,7 +60,7 @@ public static string GenerateOscOperatingSystemCommand(string proprietaryCommand
         public static string GenerateOscOperatingSystemCommandAlt(string proprietaryCommands)
 	    {
 		    string result = $"{VtSequenceBasicChars.EscapeChar}]{proprietaryCommands}{VtSequenceBasicChars.StChar}";
-	        var regexParser = new Regex(OscOperatingSystemCommandSequenceRegex);
+	        var regexParser = new Regex(OscOperatingSystemCommandAltSequenceRegex);
 		    if (!regexParser.IsMatch(result))
 		        throw new Exception("VT.NET failed to generate a working VT sequence. Make sure that you've specified values correctly.");
 		    return result;

VT.NET/Builder/VtSequenceBuilderTools.cs

@@ -0,0 +1,62 @@
+/*
+ * MIT License
+ * 
+ * Copyright (c) 2022 Aptivi
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+using System;
+using System.Text.RegularExpressions;
+
+namespace VT.NET.Builder
+{
+    /// <summary>
+    /// VT sequence builder tools
+    /// </summary>
+    public static class VtSequenceBuilderTools
+    {
+        /// <summary>
+        /// Builds a VT sequence using specific types
+        /// </summary>
+        /// <param name="specificType"></param>
+        /// <param name="arguments"></param>
+        /// <returns></returns>
+        /// <exception cref="Exception"></exception>
+        public static string BuildVtSequence(VtSequenceSpecificTypes specificType, params object[] arguments)
+        {
+            string result;
+
+            // Check the type
+            if (!Enum.IsDefined(typeof(VtSequenceSpecificTypes), specificType))
+                throw new Exception($"Cannot build VT sequence for nonexistent type {Convert.ToInt32(specificType)}");
+
+            // Now, get the method and the sequence regex using reflection
+            var regexGettingType = new Regex("(?<=[a-z0-9])[A-Z].*");
+            string typeName = $"{regexGettingType.Replace(specificType.ToString(), "")}Sequences";
+            string generatorName = $"Generate{specificType}";
+            var sequencesType = Type.GetType($"VT.NET.Builder.Types.{typeName}");
+            var sequenceRegexGenerator = sequencesType.GetMethod(generatorName);
+
+            // Now, get the sequence
+            result = sequenceRegexGenerator.Invoke(null, arguments).ToString();
+            return result;
+        }
+    }
+}