From 47a4095bb191eb807d4ee5110bf2c571e8f7972e Mon Sep 17 00:00:00 2001
From: Anton Tarasenko <dkanus@gmail.com>
Date: Mon, 27 Jun 2022 04:01:41 +0700
Subject: [PATCH] Add `TextTemplate` class

---
 sources/Manifest.uc                     |  29 +-
 sources/Text/Tests/TEST_TextTemplate.uc | 361 +++++++++
 sources/Text/TextAPI.uc                 |  87 ++-
 sources/Text/TextTemplate.uc            | 975 ++++++++++++++++++++++++
 4 files changed, 1434 insertions(+), 18 deletions(-)
 create mode 100644 sources/Text/Tests/TEST_TextTemplate.uc
 create mode 100644 sources/Text/TextTemplate.uc

diff --git a/sources/Manifest.uc b/sources/Manifest.uc
index e1fead3..4f5e9b7 100644
--- a/sources/Manifest.uc
+++ b/sources/Manifest.uc
@@ -42,18 +42,19 @@ defaultproperties
     testCases(11)   = class'TEST_JSON'
     testCases(12)   = class'TEST_TextCache'
     testCases(13)   = class'TEST_FormattedStrings'
-    testCases(14)   = class'TEST_User'
-    testCases(15)   = class'TEST_Memory'
-    testCases(16)   = class'TEST_DynamicArray'
-    testCases(17)   = class'TEST_AssociativeArray'
-    testCases(18)   = class'TEST_CollectionsMixed'
-    testCases(19)   = class'TEST_Iterator'
-    testCases(20)   = class'TEST_Command'
-    testCases(21)   = class'TEST_CommandDataBuilder'
-    testCases(22)   = class'TEST_LogMessage'
-    testCases(23)   = class'TEST_DatabaseCommon'
-    testCases(24)   = class'TEST_LocalDatabase'
-    testCases(25)   = class'TEST_AcediaConfig'
-    testCases(26)   = class'TEST_UTF8EncoderDecoder'
-    testCases(27)   = class'TEST_AvariceStreamReader'
+    testCases(14)   = class'TEST_TextTemplate'
+    testCases(15)   = class'TEST_User'
+    testCases(16)   = class'TEST_Memory'
+    testCases(17)   = class'TEST_DynamicArray'
+    testCases(18)   = class'TEST_AssociativeArray'
+    testCases(19)   = class'TEST_CollectionsMixed'
+    testCases(20)   = class'TEST_Iterator'
+    testCases(21)   = class'TEST_Command'
+    testCases(22)   = class'TEST_CommandDataBuilder'
+    testCases(23)   = class'TEST_LogMessage'
+    testCases(24)   = class'TEST_DatabaseCommon'
+    testCases(25)   = class'TEST_LocalDatabase'
+    testCases(26)   = class'TEST_AcediaConfig'
+    testCases(27)   = class'TEST_UTF8EncoderDecoder'
+    testCases(28)   = class'TEST_AvariceStreamReader'
 }
\ No newline at end of file
diff --git a/sources/Text/Tests/TEST_TextTemplate.uc b/sources/Text/Tests/TEST_TextTemplate.uc
new file mode 100644
index 0000000..cd49fd7
--- /dev/null
+++ b/sources/Text/Tests/TEST_TextTemplate.uc
@@ -0,0 +1,361 @@
+/**
+ *  Set of tests for functionality of `TextTemplate`.
+ *      Copyright 2022 Anton Tarasenko
+ *------------------------------------------------------------------------------
+ * This file is part of Acedia.
+ *
+ * Acedia is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Acedia is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Acedia.  If not, see <https://www.gnu.org/licenses/>.
+ */
+class TEST_TextTemplate extends TestCase
+    abstract;
+
+protected static function TESTS()
+{
+    Context("Testing `TextTemplate` class' ability to handle empty (erroneous)"
+        @ "argument declarations.");
+    Test_EmptyDeclarations();
+    Context("Testing `TextTemplate` class' ability to handle numeric"
+        @ "argument declarations.");
+    Test_NumericDeclarationsAmount();
+    Test_NumericDeclarationsOrder();
+    Test_NumericDeclarationsNoOrder();
+    Test_NumericDeclarationsRandomValues();
+    Context("Testing `TextTemplate` class' ability to handle text"
+        @ "argument declarations.");
+    Test_TextDeclarationsGet();
+    Test_TextDeclarationsEmptyCollect();
+    Test_TextDeclarationsCollect();
+    Test_TextDeclarationsOverwriteCollect();
+    Context("Testing complex `TextTemplate` scenarios.");
+    Test_Reset();
+    Test_Complex();
+    Test_Formatted();
+}
+
+protected static function Test_EmptyDeclarations()
+{
+    local TextTemplate instance;
+
+    Issue("Empty `TextTemplate` is not collected into empty text.");
+    instance = __().text.MakeTemplate_S("");
+    TEST_ExpectTrue(instance.Collect().IsEmpty());
+
+    Issue("`TextTemplate` with empty numeric definition is not properly"
+        @ "collected.");
+    instance = __().text.MakeTemplate_S("%");
+    TEST_ExpectTrue(instance.Collect().IsEmpty());
+    instance = __().text.MakeTemplate_S("With some%text");
+    TEST_ExpectTrue(instance.Collect().ToString() == "With sometext");
+
+    Issue("`TextTemplate` with empty text definition is not properly"
+        @ "collected.");
+    instance = __().text.MakeTemplate_S("%%");
+    TEST_ExpectTrue(instance.Collect().IsEmpty());
+    instance = __().text.MakeTemplate_S("With some%%%text and %%%%more!");
+    TEST_ExpectTrue(instance.Collect().ToString() == "With sometext and more!");
+
+    Issue("`TextTemplate` with definitions opened at the very end is not"
+        @ "properly collected.");
+    instance = __().text.MakeTemplate_S("Some text: %");
+    TEST_ExpectTrue(instance.Collect().ToString() == "Some text: ");
+    instance = __().text.MakeTemplate_S("Another example: %%");
+    TEST_ExpectTrue(instance.Collect().ToString() == "Another example: ");
+}
+
+protected static function Test_NumericDeclarationsAmount()
+{
+    local TextTemplate instance;
+
+    Issue("`GetNumericArgsAmount()` does not return `0` for `Text` without any"
+        @ "numeric declarations.");
+    instance = __().text.MakeTemplate_S("");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 0);
+    instance = __().text.MakeTemplate_S("With some%text");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 0);
+    instance = __().text.MakeTemplate_S("With some%%%text and %%%%more!");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 0);
+    instance = __().text.MakeTemplate_S("With some%%valid arg%text and"
+        @ "%%me too%%more!");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 0);
+
+    Issue("`GetNumericArgsAmount()` does not correctly counts numeric"
+        @ "declarations.");
+    instance = __().text.MakeTemplate_S("just %1 %2 %3 %t %4 %5 %%text one!%%"
+        @" %6 %7 %8");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 8);
+
+    Issue("`GetNumericArgsAmount()` does not correctly counts numeric"
+        @ "declarations with escaped '%' characters.");
+    instance = __().text.MakeTemplate_S("just &%1 %2 %3 %t &%4 %5 %%text one!%%"
+        @" %6 %7 %8");
+    TEST_ExpectTrue(instance.GetNumericArgsAmount() == 6);
+}
+
+protected static function Test_NumericDeclarationsOrder()
+{
+    local TextTemplate instance;
+
+    Issue("Basic numeric declarations are not working as intended.");
+    instance = __().text.MakeTemplate_S("This is argument: %1!");
+    instance.Arg(P("<enter_phrase_here>"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "This is argument: <enter_phrase_here>!");
+    instance = __().text.MakeTemplate_S("just %1 %2 %3 %4 %5 %6 %7 %8");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"))
+        .Arg(P("f")).Arg(P("g")).Arg(P("h"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "just a b c d e f g h");
+
+    Issue("Basic numeric declarations are not working as intended after"
+        @ "specifying too many.");
+    instance = __().text.MakeTemplate_S("This is argument: %1!");
+    instance.Arg(P("<enter_phrase_here>")).Arg(P("Now this is too much!"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "This is argument: <enter_phrase_here>!");
+    instance = __().text.MakeTemplate_S("just %1 %2 %3 %4 %5 %6 %7 %8");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"))
+        .Arg(P("f")).Arg(P("g")).Arg(P("h")).Arg(P("i")).Arg(P("j"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "just a b c d e f g h");
+
+    Issue("Basic numeric declarations are not working as intended after"
+        @ "specifying too little.");
+    instance = __().text.MakeTemplate_S("This is argument: %1!");
+    TEST_ExpectTrue(instance.Collect().ToString() == "This is argument: !");
+    instance = __().text.MakeTemplate_S("just %1 %2 %3 %4 %5 %6 %7 %8");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"));
+    TEST_ExpectTrue(instance.Collect().ToString() == "just a b c d e   ");
+}
+
+protected static function Test_NumericDeclarationsNoOrder()
+{
+    local TextTemplate instance;
+
+    Issue("Basic numeric declarations are not working as intended.");
+    instance = __().text.MakeTemplate_S("This is argument: %2! And this: %1!!");
+    instance.Arg(P("<enter_phrase_here>")).Arg(P("heh"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "This is argument: heh! And this: <enter_phrase_here>!!");
+    instance = __().text.MakeTemplate_S("just %1 %3 %5 %2 %4 %8 %6 %7");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"))
+        .Arg(P("f")).Arg(P("g")).Arg(P("h"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "just a c e b d h f g");
+
+    Issue("Basic numeric declarations are not working as intended after"
+        @ "specifying too many.");
+    instance = __().text.MakeTemplate_S("just %1 %3 %5 %2 %4 %8 %6 %7");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"))
+        .Arg(P("f")).Arg(P("g")).Arg(P("h")).Arg(P("i")).Arg(P("j"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "just a c e b d h f g");
+
+    Issue("Basic numeric declarations are not working as intended after"
+        @ "specifying too little.");
+    instance = __().text.MakeTemplate_S("just %1 %3 %5 %2 %4 %8 %6 %7");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c"));
+    TEST_ExpectTrue(instance.Collect().ToString() == "just a c  b    ");
+}
+
+protected static function Test_NumericDeclarationsRandomValues()
+{
+    local TextTemplate instance;
+
+    Issue("Basic numeric declarations are not working as intended when using"
+        @ "arbitrary integer values.");
+    instance = __().text.MakeTemplate_S("This is argument:"
+        @ "%205! And this: %-7!!");
+    instance.Arg(P("<enter_phrase_here>")).Arg(P("heh"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "This is argument: heh! And this: <enter_phrase_here>!!");
+    instance = __().text.MakeTemplate_S("just %-3912842 %0 %666 %-111 %34"
+        @ "%666999 %10234 %10235");
+    instance.Arg(P("a")).Arg(P("b")).Arg(P("c")).Arg(P("d")).Arg(P("e"))
+        .Arg(P("f")).Arg(P("g")).Arg(P("h"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "just a c e b d h f g");
+}
+
+protected static function Test_TextDeclarationsGet()
+{
+    local TextTemplate  instance;
+    local array<Text>   result;
+
+    Issue("Specified text labels aren't properly returned by"
+        @ "the `GetTextlabels()` method.");
+    instance = __().text.MakeTemplate_S("This is argument: %%argument!%% and"
+        @ "so its this: %%another arg%%");
+    result = instance.GetTextArgs();
+    TEST_ExpectTrue(result[0].ToString() == "argument!");
+    TEST_ExpectTrue(result[1].ToString() == "another arg");
+    TEST_ExpectTrue(result.length == 2);
+    instance.TextArg(P("another arg"), P("heh"))
+        .TextArg(P("argument!"), P("<enter_phrase_here>"));
+    result = instance.GetTextArgs();
+    TEST_ExpectTrue(result[0].ToString() == "argument!");
+    TEST_ExpectTrue(result[1].ToString() == "another arg");
+    TEST_ExpectTrue(result.length == 2);
+
+    instance = __().text.MakeTemplate_S("Here: %2 %76 %4 %5 %8");
+    result = instance.GetTextArgs();
+    TEST_ExpectTrue(result.length == 0);
+
+    instance = __().text.MakeTemplate_S("More %%complex%% %7 %%/example% here,"
+        @ "yes. Very %%complex%!");
+    result = instance.GetTextArgs();
+    TEST_ExpectTrue(result[0].ToString() == "complex");
+    TEST_ExpectTrue(result[1].ToString() == "/example");
+    TEST_ExpectTrue(result.length == 2);
+}
+
+protected static function Test_TextDeclarationsEmptyCollect()
+{
+    local TextTemplate instance;
+
+    Issue("`TextTempalte` is not properly collected with it contains empty"
+@         "text labels.");
+    instance = __().text.MakeTemplate_S("This is argument: %%%% and"
+        @ "so its this: %%%");
+    instance.TextArg(P(""), P("what do y'll know?!"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == ("This is argument: what do y'll know?! and so its this:"
+            @ "what do y'll know?!"));
+}
+
+protected static function Test_TextDeclarationsCollect()
+{
+    local TextTemplate instance;
+
+    Issue("Specified text labels aren't properly collected.");
+    instance = __().text.MakeTemplate_S("This is argument: %%argument!%% and"
+        @ "so its this: %%another arg%%");
+    instance.TextArg(P("another arg"), P("heh"))
+        .TextArg(P("argument!"), P("<enter_phrase_here>"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "This is argument: <enter_phrase_here> and so its this: heh");
+
+    Issue("Specified text labels aren't properly collected when duplicate"
+        @ "labels are present.");
+    instance = __().text.MakeTemplate_S("More %%complex%% %7 %%/example% here,"
+        @ "yes. Very %%complex%!");
+    instance.TextArg(P("complex"), P("simple")).TextArg(P("/example"), P("!!"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "More simple  !! here, yes. Very simple!");
+
+    Issue("Specified text labels aren't properly collected when specified"
+        @ "too little arguments.");
+    instance = __().text.MakeTemplate_S("More %%complex%% %7 %%/example% here,"
+        @ "yes. Very %%complex% and %%nasty%%!!!");
+    instance.TextArg(P("complex"), P("simple")).TextArg(P("nasty"), P("-_-"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "More simple   here, yes. Very simple and -_-!!!");
+
+    Issue("Specified text labels aren't properly collected when specified"
+        @ "too many arguments.");
+    instance = __().text.MakeTemplate_S("More %%complex%% %11 %%/example% here,"
+        @ "yes. Very %%complex% and %%nasty%%!!!");
+    instance.TextArg(P("complex"), P("simple")).TextArg(P("nasty"), P("-_-"))
+        .TextArg(P("/usr/bin"), P("geronimo")).TextArg(P("/example"), P("???"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "More simple  ??? here, yes. Very simple and -_-!!!");
+}
+
+protected static function Test_TextDeclarationsOverwriteCollect()
+{
+    local TextTemplate instance;
+
+    Issue("Specified text labels aren't properly collected when some labels"
+        @ "are overwritten.");
+    instance = __().text.MakeTemplate_S("More %%complex%% %7 %%/example% here,"
+        @ "yes. Very %%complex%!");
+    instance.TextArg(P("complex"), P("simple")).TextArg(P("/example"), P("!!"))
+        .TextArg(P("complex"), P("nasty")).TextArg(P("/exe"), P("???"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == "More nasty  !! here, yes. Very nasty!");
+}
+
+protected static function Test_Reset()
+{
+    local TextTemplate instance;
+
+    Issue("`Reset()` does not properly reset user's input.");
+    instance = __().text.MakeTemplate_S("Testing %1, %2, %3 and %%one%%,"
+        @ "%%two%% + %%three%%");
+    instance.Arg_S("1").Arg_S("2").Arg_S("3").Arg_S("more?");
+    instance
+        .TextArg(P("one"), P("4"))
+        .TextArg(P("two"), P("5"))
+        .TextArg(P("three"), P("6"));
+    instance.Reset().Arg_S("HEY").Arg_S("ARE").Arg_S("YOU");
+    instance
+        .TextArg(P("one"), P("READY"))
+        .TextArg(P("two"), P("TO"))
+        .TextArg(P("three"), P("GO?"));
+    TEST_ExpectTrue(instance.Collect().ToString() == ("Testing HEY, ARE, YOU"
+        @ "and READY, TO + GO?"));
+}
+
+protected static function Test_Complex()
+{
+    local TextTemplate  instance;
+    local array<Text>   result;
+
+    Issue("Specified text labels aren't properly collected in complex scenario"
+        @ "with several numeric / text arguments and escaped characters.");
+    instance = __().text.MakeTemplate_S("Welcome %%MoonAndStar%%, it is %7 nice"
+        @ "to %-2 %%you%%. %%MoonAndStar%% drop your %%weapons%%, it is not too"
+        @ "%0 for &m&y %%mercy%&%!");
+    instance
+        .TextArg(P("MoonAndStar"), P("Nerevar"))
+        .TextArg(P("you"), P("you"))
+        .TextArg(P("weapons"), P("cheats"))
+        .Arg(P("see"))
+        .Arg(P("late"))
+        .Arg(P("so"));
+    TEST_ExpectTrue(instance.Collect().ToString()
+        == ("Welcome Nerevar, it is so nice to see you."
+        @ "Nerevar drop your cheats, it is not too late for &m&y %!"));
+    result = instance.GetTextArgs();
+    TEST_ExpectTrue(result[0].ToString() == "MoonAndStar");
+    TEST_ExpectTrue(result[1].ToString() == "you");
+    TEST_ExpectTrue(result[2].ToString() == "weapons");
+    TEST_ExpectTrue(result[3].ToString() == "mercy");
+    TEST_ExpectTrue(result.length == 4);
+}
+
+protected static function Test_Formatted()
+{
+    local TextTemplate instance;
+
+    Issue("Specified text labels aren't properly collected in complex scenario"
+        @ "with several numeric / text arguments and escaped characters and"
+        @ "we are asking to parse template as a formatted string"
+        @ "(`CollectFormatted()` method).");
+    instance = __().text.MakeTemplate_S("Test simple {%%color%% %1} string"
+        @ "that is {%2 %%what%%}!");
+    instance
+        .Arg(P("formatted"))
+        .Arg(P("$blue"))
+        .TextArg(P("color"), P("$red"))
+        .TextArg(P("what"), P("colored"));
+    TEST_ExpectTrue(instance.CollectFormatted().ToFormattedString()
+        == ("Test simple {rgb(255,0,0) formatted} string that is"
+            @ "{rgb(0,0,255) colored}!"));
+}
+
+defaultproperties
+{
+    caseName = "TextTemplate"
+    caseGroup = "Text"
+}
\ No newline at end of file
diff --git a/sources/Text/TextAPI.uc b/sources/Text/TextAPI.uc
index 9c87c53..ae2757d 100644
--- a/sources/Text/TextAPI.uc
+++ b/sources/Text/TextAPI.uc
@@ -667,6 +667,41 @@ public final function array<BaseText> PartsS(string source)
     return result;
 }
 
+/**
+ *  Creates and initializes with `source` new `TextTemplate` instance.
+ *
+ *  @param  source  Data to initialize new `TextTemplate` with.
+ *  @return `TextTemplate` based on `source`.
+ *      `none` if given `source` is `none`.
+ */
+public final function TextTemplate MakeTemplate(BaseText source)
+{
+    local TextTemplate newTemplate;
+    if (source == none) {
+        return none;
+    }
+    newTemplate = TextTemplate(_.memory.Allocate(class'TextTemplate'));
+    newTemplate.Initialize(source);
+    return NewTemplate;
+}
+
+/**
+ *  Creates and initializes with `source` new `TextTemplate` instance.
+ *
+ *  @param  source  Data to initialize new `TextTemplate` with.
+ *  @return `TextTemplate` based on `source`.
+ *      `none` if given `source` is `none`.
+ */
+public final function TextTemplate MakeTemplate_S(string source)
+{
+    local MutableText   wrapper;
+    local TextTemplate  result;
+    wrapper = FromStringM(source);
+    result = MakeTemplate(wrapper);
+    _.memory.Free(wrapper);
+    return result;
+}
+
 /**
  *  Creates a new, empty `MutableText`.
  *
@@ -751,12 +786,56 @@ public final function MutableText FromColoredStringM(string source)
 }
 
 /**
- *  Creates a `Text` that will contain a given formatted `string`.
+ *  Creates a `Text` that will contain a parsed formatted string inside
+ *  the given `BaseText`.
+ *
+ *  To create `MutableText` instead use `FromFormattedM()` method.
+ *
+ *  @param  source  Formatted string inside `Text` that will be parsed into
+ *      returned `Text`.
+ *  @return New instance of `Text` that will contain parsed formatted `source`.
+ */
+public final function Text FromFormatted(BaseText source)
+{
+    local MutableText   builder;
+    local Text          result;
+    if (source == none) {
+        return none;
+    }
+    builder = MutableText(_.memory.Allocate(class'MutableText'));
+    result = builder.AppendFormatted(source).Copy();
+    builder.FreeSelf();
+    return result;
+}
+
+/**
+ *  Creates a `MutableText` that will contain a parsed formatted string inside
+ *  the given `BaseText`.
+ *
+ *  To create `Text` instead use `FromFormatted()` method.
+ *
+ *  @param  source  Formatted string inside `Text` that will be parsed into
+ *      returned `Text`.
+ *  @return New instance of `MutableText` that will contain parser formatted
+ *      `source`.
+ */
+public final function MutableText FromFormattedM(BaseText source)
+{
+    local MutableText newText;
+    if (source == none) {
+        return none;
+    }
+    newText = MutableText(_.memory.Allocate(class'MutableText'));
+    return newText.AppendFormatted(source);
+}
+
+/**
+ *  Creates a `Text` that will contain parsed formatted `string`.
  *
  *  To create `MutableText` instead use `FromFormattedStringM()` method.
  *
  *  @param  source  Formatted `string` that will be copied into returned `Text`.
- *  @return New instance of `Text` that will contain passed formatted `string`.
+ *  @return New instance of `Text` that will contain parsed formatted `string`.
  */
 public final function Text FromFormattedString(string source)
 {
@@ -769,13 +848,13 @@ public final function Text FromFormattedString(string source)
 }
 
 /**
- *  Creates a `MutableText` that will contain a given formatted `string`.
+ *  Creates a `MutableText` that will contain parsed formatted `string`.
  *
  *  To create immutable `Text` instead use `FromFormattedString()` method.
  *
  *  @param  source  Formatted `string` that will be copied into
  *      returned `MutableText`.
- *  @return New instance of `MutableText` that will contain passed
+ *  @return New instance of `MutableText` that will contain parsed
  *      formatted `string`.
  */
 public final function MutableText FromFormattedStringM(string source)
diff --git a/sources/Text/TextTemplate.uc b/sources/Text/TextTemplate.uc
new file mode 100644
index 0000000..c1aa044
--- /dev/null
+++ b/sources/Text/TextTemplate.uc
@@ -0,0 +1,975 @@
+/**
+ *      Class that allows to work with simple text templates in the form of
+ *  "Template example, following can be replaced: %1, %2, %3 or %4" or
+ *  "%%instigator%% {%%rage_color%% raged} %%target_zed%%!".
+ *  Part noted by '%' characters can be replaced with arbitrary values.
+ *  It should be more efficient that simply repeatedly calling
+ *  `MutableText.Replace()` method.
+ *      Copyright 2022 Anton Tarasenko
+ *------------------------------------------------------------------------------
+ * This file is part of Acedia.
+ *
+ * Acedia is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Acedia is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Acedia.  If not, see <https://www.gnu.org/licenses/>.
+ */
+class TextTemplate extends AcediaObject;
+
+/**
+ *  # `TextTemplate`
+ *
+ *      This class allows to do more efficient replacements in the templates of
+ *  form "Template example, following can be replaced: %1, %2, %3 or %4" or
+ *  "%%instigator%% {%%rage_color%% raged} %%target_zed%%!" that simple
+ *  repeating of `MutableText.Replace()` method would allow.
+ *
+ *  ## Usage
+ *
+ *      All `TextTemplate`s must be initialized before they can be used.
+ *  `_.text.MakeTemplate()` method is considered a recommended way to create
+ *  a new `TextTemplate` and will initialize it for you. In case you have
+ *  manually allocated `TextTemplate` you need to simply call
+ *  `TextTemplate.Initialize()` method and provide is with a template source
+ *  with designated replaceable part (called *labels*). Any label is designated
+ *  by either:
+ *
+ *      * Specifying a number after a single '%' character (numeric labels);
+ *      * Or specifying a textual value in between double percent sequence "%%".
+ *
+ *      Numeric labels can then be replaced with user values by various provided
+ *  `Arg...()` methods and text labels by `TextArg...()` methods. To reuse
+ *  template with another values replacing specified labels, simply call
+ *  `TextTemplate.Reset()` method and fill labels anew.
+ *
+ *  ### Escaped sequences
+ *
+ *      `TextTemplate` allows for the escaped sequences in the style of
+ *  formatted strings: the ones based on the '&' character. More precisely, if
+ *  you wish to enter actual '%' character in the template, you can escape it
+ *  with "&%" and it will be treaded as simply '%' character and not a part of
+ *  label definition.
+ *      NOTE: any other escaped sequences will be ignored and translated
+ *  one-to-one. For example, "{%%color%% &{...&}&%!}", if specified that
+ *  "color" -> "$red", will be translated into "{$red &{...&}%!}". This allows
+ *  to use `TextTemplate`s to prepare formatted strings in a more convenient
+ *  fashion.
+ *
+ *  ### Error handling
+ *
+ *  `TextTemplate` lack any means of reporting errors in template's formatting
+ *  and tries to correct as many errors as possible.
+ *  
+ *      1. If after the single '%' character follows not a number, but another
+ *          character - that '%' will be ignored and thrown away;
+ *      2. After opening text label with double percent "%%" to stop specifying
+ *          the text label it is sufficient to type a single '%' character.
+ *
+ *  ### Numeric labels values
+ *
+ *  You can specify any values for numeric labels and they will be filled in
+ *  order. However the proper notation is to start with `1` and then use
+ *  following natural numbers in order (e.g. "%1", "%2", "%3", etc.).
+ *
+ *  ### Text labels duplicates
+ *
+ *  It is allowed for the same text label to appear several times in a template
+ *  and each entry will be replaced with a specified user value.
+ *
+ *  ### Unspecified arguments
+ *
+ *  If no argument was given for some label - it will simply be replaced with
+ *  empty text.
+ */
+
+//  *Labels* will be an internal name for the parts of the template that is
+//  supposed to be replaced. This struct describes one such part.
+struct Label
+{
+    //      If Label starts with two percent characters ("%%"), then it is
+    //  a text Label and we will remember contents within "%%...%%" in this
+    //  field (`textLabel != none`).
+    //      Otherwise it is a numeric Label and `textLabel` will be set
+    //  to `none`.
+    var MutableText textLabel;
+    //  For numeric labels - number after that percent character '%'.
+    //  In case numeric labels were specified incorrectly, these values will
+    //  be normalized to start from `1` and increase by +1, while preserving
+    //  their order.
+    var int         numberLabel;
+    //  Before which part (from `parts`) to insert this Label?
+    var int         insertionIndex;
+};
+
+var private bool                initialized;
+//  Remembers amount of numeric labels in the template
+var private int                 numericLabelsAmount;
+//  Arrays of labels and parts in between that template got broken into
+//  during initialization
+var private array<Label>        labels;
+var private array<MutableText>  parts;
+
+//  Values user specified as replacements to the labels
+var private array<Text>         numericArguments;
+//  Fort text arguments we keep two arrays of equal size: `textLabels` records
+//  what text Label is replaced and `textArguments` (at the same index)
+//  records with what it needs to be replaced
+var private array<Text>         textLabels;
+var private array<Text>         textArguments;
+
+var private const int TPERCENT, TAMPERSAND;
+
+const CODEPOINT_PERCENT     = 37;   // '%'
+const CODEPOINT_AMPERSAND   = 38;   // '&'
+
+protected function Finalizer()
+{
+    local int i;
+    //  Clear user input
+    Reset();
+    //  Clear numeric labels
+    numericLabelsAmount   = 0;
+    _.memory.FreeMany(parts);
+    //  Clear text Labels
+    parts.length = 0;
+    for (i = 0; i < Labels.length; i += 1) {
+        _.memory.Free(Labels[i].textLabel);
+    }
+    labels.length = 0;
+    //  Now we can safely mark caller template as not initialized
+    initialized = false;
+}
+
+/**
+ *  Checks if caller `TextTemplate` was already initialized.
+ *
+ *  If you use recommended means of creating `TextTemplate`s (`MakeTemplate` and
+ *  `MakeTemplate_S`), then all your templates for not `none` arguments will be
+ *  initialized.
+ *
+ *  @return `true` if it was initialized and `false` otherwise.
+ */
+public final function bool IsInitialized()
+{
+    return initialized;
+}
+
+/**
+ *  Initializes caller `TextTemplate` with a given `input`.
+ *
+ *  Initialization should only be performed once for every `TextTemplate` -
+ *  right after its allocation, before any use.
+ *
+ *  If you use recommended means of creating `TextTemplate`s (`MakeTemplate`),
+ *  then all your templates for not `none` arguments will be initialized.
+ *
+ *  @param  input   `string` containing template to prepare `TextTemplate` from.
+ */
+public final function Initialize_S(string input)
+{
+    local MutableText wrapper;
+    wrapper = _.text.FromStringM(input);
+    Initialize(wrapper);
+    _.memory.Free(wrapper);
+}
+
+/**
+ *  Initializes caller `TextTemplate` with a given `input`.
+ *
+ *  Initialization should only be performed once for every `TextTemplate` -
+ *  right after its allocation, before any use.
+ *
+ *  If you use recommended means of creating `TextTemplate`s (`MakeTemplate`),
+ *  then all your templates for not `none` arguments will be initialized.
+ *
+ *  @param  input   Text containing template to prepare `TextTemplate` from.
+ */
+public final function Initialize(BaseText input)
+{
+    local Parser                parser;
+    local MutableText           nextPart;
+    local BaseText.Character    percent, nextCharacter;
+
+    if (input == none) {
+        return;
+    }
+    percent = _.text.CharacterFromCodePoint(CODEPOINT_PERCENT);
+    parser  = input.Parse();
+    while (!parser.HasFinished())
+    {
+        nextPart = MatchUntilUnescapedPercent(parser); //  guaranteed success
+        parts[parts.length] = nextPart;
+        if (parser.HasFinished()) {
+            break;
+        }
+        //  If there is still input - next character is definitely "%"
+        parser.MCharacter(nextCharacter).Confirm();
+        parser.MCharacter(nextCharacter);   //  But what is this?
+        if (parser.Ok() && _.text.IsCodePoint(nextCharacter, CODEPOINT_PERCENT))
+        {
+            //  "%%" prefix (already confirmed) - should have text Label
+            MatchTextLabel(parser, percent);
+        }
+        else
+        {
+            //  single "%" prefix - look for number
+            MatchNumericLabel(parser.R());
+        }
+    }
+    initialized = true;
+    _.memory.Free(parser);
+    NormalizeArguments();
+}
+
+private final function MatchTextLabel(
+    Parser              parser,
+    BaseText.Character  percentCharacter)
+{
+    local MutableText nextLabel;
+
+    parser.MUntil(nextLabel, percentCharacter).Confirm();
+    labels[labels.length] = MakeTextLabel(nextLabel);
+    //  Tries to parse "%%", but will be content with a single "%"
+    parser.Match(T(TPERCENT)).Confirm();
+    parser.Match(T(TPERCENT)).Confirm();
+    //  Just reset to last properly parsed point in case of the failure
+    parser.R();
+}
+
+private final function MatchNumericLabel(Parser parser)
+{
+    local int nextNumericLabel;
+    if (parser.MInteger(nextNumericLabel).Ok()) {
+        labels[labels.length] = MakeNumericLabel(nextNumericLabel);
+    }
+    parser.Confirm();
+    //  Just reset to last properly parsed point in case of the failure
+    parser.R();
+}
+
+//  Normalize enumeration by replacing them with natural numbers sequence:
+//  [0, 1, 2, ...] in the same order:
+//  [2, 6, 3] -> [0, 2, 1]
+//  [-2, 0, 4, -7] -> [1, 2, 3, 0]
+//  [1, 1, 2, 1] -> [0, 1, 3, 2]
+private final function NormalizeArguments()
+{
+    local int           i;
+    local int           nextArgument;
+    local int           lowestArgument, lowestArgumentIndex;
+    local array<int>    argumentsOrder, normalizedArguments;
+    for (i = 0; i < labels.length; i += 1)
+    {
+        if (labels[i].textLabel == none)
+        {
+            numericLabelsAmount += 1;
+            argumentsOrder[argumentsOrder.length] = labels[i].numberLabel;
+        }
+    }
+    normalizedArguments.length = argumentsOrder.length;
+    while (nextArgument < normalizedArguments.length)
+    {
+        //  Find next minimal index and record next natural number
+        //  (`nextArgument`) into it
+        for (i = 0; i < argumentsOrder.length; i += 1)
+        {
+            if (argumentsOrder[i] < lowestArgument || i == 0)
+            {
+                lowestArgumentIndex = i;
+                lowestArgument = argumentsOrder[i];
+            }
+        }
+        argumentsOrder[lowestArgumentIndex] = MaxInt;
+        normalizedArguments[lowestArgumentIndex] = nextArgument;
+        nextArgument += 1;
+    }
+    nextArgument = 0;
+    for (i = 0; i < labels.length; i += 1)
+    {
+        if (labels[i].textLabel == none)
+        {
+            labels[i].numberLabel = normalizedArguments[nextArgument];
+            nextArgument += 1;
+        }
+    }
+}
+
+private final function Label MakeTextLabel(MutableText Label2)
+{
+    local Label result;
+    result.textLabel = Label2;
+    result.insertionIndex = parts.length;
+    return result;
+}
+
+private final function Label MakeNumericLabel(int Label2)
+{
+    local Label result;
+    result.numberLabel = Label2;
+    result.insertionIndex = parts.length;
+    return result;
+}
+
+//      Skips until next non-escaped (that is "&%") '%' character
+//  (or until the end).
+//      It returns any contents inside `parser` before that character replacing
+//  "&%" with simply "%", but leaving all other escaped sequences intact,
+//  e.g. "&a" -> "&a" and "&{" -> "&{". This is needed to allow parsing of
+//  the result of substitution as a formatted string.
+private final function MutableText MatchUntilUnescapedPercent(Parser parser)
+{
+    local MutableText           result, nextMatched;
+    local BaseText.Character    ampersand, nextCharacter;
+    local array<Text>           delimiters;
+
+    ampersand = _.text.CharacterFromCodePoint(CODEPOINT_AMPERSAND);
+    delimiters[0] = T(TPERCENT);
+    delimiters[1] = T(TAMPERSAND);
+    result = _.text.Empty();
+    while (!parser.HasFinished())
+    {
+        parser.MUntilMany(nextMatched, delimiters).Confirm();
+        result.Append(nextMatched);
+        _.memory.Free(nextMatched);
+        if (parser.HasFinished()) {
+            break;
+        }
+        parser.MCharacter(nextCharacter);
+        //  If this is "%": we are done
+        if (_.text.IsCodePoint(nextCharacter, CODEPOINT_PERCENT))
+        {
+            parser.R();
+            return result;
+        }
+        //  Otherwise it is "&": skip it and the next character
+        parser.MCharacter(nextCharacter).Confirm();
+        if (!parser.Ok())
+        {
+            result.AppendCharacter(ampersand);
+            return result;
+        }
+        if (!_.text.IsCodePoint(nextCharacter, CODEPOINT_PERCENT)) {
+            result.AppendCharacter(ampersand);
+        }
+        result.AppendCharacter(nextCharacter);
+    }
+    parser.Confirm();
+    return result;
+}
+
+/**
+ *  Resets any data user entered into this template via any "Arg"-methods.
+ *
+ *  This method allows to reuse a once initialized `TextTemplate` any amount of
+ *  times.
+ *
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate Reset()
+{
+    if (!initialized) {
+        return self;
+    }
+    _.memory.FreeMany(numericArguments);
+    _.memory.FreeMany(textLabels);
+    _.memory.FreeMany(textArguments);
+    numericArguments.length = 0;
+    textLabels.length     = 0;
+    textArguments.length    = 0;
+    return self;
+}
+
+/**
+ *  Returns amount of numeric arguments inside the caller `TextTemplate`.
+ *
+ *  @return Amount of numeric arguments inside the caller `TextTemplate`.
+ *      `-1` for uninitialized `TextTemplate`s.
+ */
+public final function int GetNumericArgsAmount()
+{
+    if (initialized) {
+        return numericLabelsAmount;
+    }
+    return -1;
+}
+
+/**
+ *  Returns array of text arguments inside the caller `TextTemplate`.
+ *
+ *  @return Array of text arguments inside the caller `TextTemplate`.
+ *      Empty array for uninitialized `TextTemplate`s.
+ */
+public final function array<Text> GetTextArgs()
+{
+    local int           i, j;
+    local bool          duplicate;
+    local array<Text>   result;
+    if (!initialized) {
+        return result;
+    }
+    for (i = 0; i < labels.length; i += 1)
+    {
+        if (labels[i].textLabel == none) {
+            continue;
+        }
+        duplicate = false;
+        for (j = 0; j < result.length; j += 1)
+        {
+            if (result[j].Compare(labels[i].textLabel))
+            {
+                duplicate = true;
+                break;
+            }
+        }
+        if (!duplicate && labels[i].textLabel != none) {
+            result[result.length] = labels[i].textLabel.Copy();
+        }
+    }
+    return result;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`. `none` values will be ignored (method will do nothing).
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate Arg_S(string argument)
+{
+    local MutableText wrapper;
+    wrapper = _.text.FromStringM(argument);
+    Arg(wrapper);
+    _.memory.Free(wrapper);
+    return self;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`. `none` equals to an empty text.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate Arg(BaseText argument)
+{
+    if (numericLabelsAmount <= numericArguments.length) {
+        return self;
+    }
+    if (argument != none) {
+        numericArguments[numericArguments.length] = argument.Copy();
+    }
+    else {
+        numericArguments[numericArguments.length] = none;
+    }
+    return self;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` integer value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate ArgInt(int argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromIntM(argument);
+    Arg(textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` floating point value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate ArgFloat(float argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromFloatM(argument);
+    Arg(textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` boolean value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate ArgBool(bool argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromBoolM(argument);
+    Arg(textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next numeric argument with `argument` class value.
+ *
+ *  If all numeric arguments were already filled this call will do nothing.
+ *
+ *  @param  argument    Value to replace next numeric argument in the caller
+ *      `TextTemplate`.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate ArgClass(class<Object> argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromClassM(argument);
+    Arg(textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with `argument` value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArg_S(string label, string argument)
+{
+    local MutableText labelWrapper, argumentWrapper;
+    labelWrapper    = _.text.FromStringM(label);
+    argumentWrapper = _.text.FromStringM(argument);
+    TextArg(labelWrapper, argumentWrapper);
+    _.memory.Free(labelWrapper);
+    _.memory.Free(argumentWrapper);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with `argument` value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with. `none` is equal to an empty text.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArg(BaseText label, BaseText argument)
+{
+    local int i;
+    if (label == none) {
+        return self;
+    }
+    for (i = 0; i < textLabels.length; i += 1)
+    {
+        if (label.Compare(textLabels[i]))
+        {
+            _.memory.Free(textArguments[i]);
+            if (argument != none) {
+                textArguments[i] = argument.Copy();
+            }
+            else {
+                textArguments[i] = none;
+            }
+            return self;
+        }
+    }
+    if (label != none) {
+        textLabels[textLabels.length] = label.Copy();
+    }
+    else {
+        textLabels[textLabels.length] = none;   
+    }
+    if (argument != none) {
+        textArguments[i] = argument.Copy();
+    }
+    else {
+        textArguments[i] = none;
+    }
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with integer `argument`
+ *  value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgInt_S(string label, int argument)
+{
+    local MutableText labelWrapper;
+    local MutableText textRepresentation;
+    labelWrapper = _.text.FromStringM(label);
+    textRepresentation = _.text.FromIntM(argument);
+    TextArg(labelWrapper, textRepresentation);
+    _.memory.Free(textRepresentation);
+    _.memory.Free(labelWrapper);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with integer `argument`
+ *  value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgInt(BaseText label, int argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromIntM(argument);
+    TextArg(label, textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with floating point
+ *  `argument` value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgFloat_S(string label, float argument)
+{
+    local MutableText labelWrapper;
+    local MutableText textRepresentation;
+    labelWrapper = _.text.FromStringM(label);
+    textRepresentation = _.text.FromFloatM(argument);
+    TextArg(labelWrapper, textRepresentation);
+    _.memory.Free(textRepresentation);
+    _.memory.Free(labelWrapper);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with floating point
+ *  `argument` value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgFloat(BaseText label, float argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromFloatM(argument);
+    TextArg(label, textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with boolean `argument`
+ *  value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgBool_S(string label, bool argument)
+{
+    local MutableText labelWrapper;
+    local MutableText textRepresentation;
+    labelWrapper = _.text.FromStringM(label);
+    textRepresentation = _.text.FromBoolM(argument);
+    TextArg(labelWrapper, textRepresentation);
+    _.memory.Free(textRepresentation);
+    _.memory.Free(labelWrapper);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with boolean `argument`
+ *  value.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgBool(BaseText label, bool argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromBoolM(argument);
+    TextArg(label, textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with class value `argument`.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgClass_S(
+    string          label,
+    class<Object>   argument)
+{
+    local MutableText labelWrapper;
+    local MutableText textRepresentation;
+    labelWrapper = _.text.FromStringM(label);
+    textRepresentation = _.text.FromClassM(argument);
+    TextArg(labelWrapper, textRepresentation);
+    _.memory.Free(textRepresentation);
+    _.memory.Free(labelWrapper);
+    return self;
+}
+
+/**
+ *  Replaces next text argument with label `label` with class value `argument`.
+ *
+ *  If all text argument with that label was already set, then it will override
+ *  previous value.
+ *
+ *  @param  label       Label of the text argument to replace.
+ *  @param  argument    Value to replace specified text argument in the caller
+ *      `TextTemplate` with.
+ *  @return Reference to the caller `TextTemplate` to allow for method chaining.
+ */
+public final function TextTemplate TextArgClass(
+    BaseText        label,
+    class<Object>   argument)
+{
+    local MutableText textRepresentation;
+    textRepresentation = _.text.FromClassM(argument);
+    TextArg(label, textRepresentation);
+    _.memory.Free(textRepresentation);
+    return self;
+}
+
+private final function Text BorrowNumericArg(int index)
+{
+    if (index < 0)                          return none;
+    if (index >= numericArguments.length)   return none;
+
+    return numericArguments[index];
+}
+
+private final function Text BorrowTextArg(BaseText Label)
+{
+    local int i;
+    if (Label == none) {
+        return none;
+    }
+    for (i = 0; i < textLabels.length; i += 1)
+    {
+        if (Label.Compare(textLabels[i])) {
+            return textArguments[i];
+        }
+    }
+    return none;
+}
+
+/**
+ *  Assembles initialized `TextTemplate` from provided arguments into a final
+ *  `Text` result.
+ *
+ *  Unspecified arguments will be replaced with empty texts.
+ *
+ *  Returns `string`. To return mutable `Text` or `MutableText` use
+ *  `Collect()` or `CollectM()`.
+ *
+ *  @return Result of replacing all argument inside caller `TextTemplate` with
+ *      arguments, specified by user.
+ */
+public final function string Collect_S()
+{
+    return _.text.ToString(CollectM());
+}
+
+/**
+ *  Assembles initialized `TextTemplate` from provided arguments into a final
+ *  `Text` result.
+ *
+ *  Unspecified arguments will be replaced with empty texts.
+ *
+ *  Returns immutable `Text`. To return mutable `MutableText` use `CollectM()`.
+ *
+ *  @return Result of replacing all argument inside caller `TextTemplate` with
+ *      arguments, specified by user.
+ */
+public final function Text Collect()
+{
+    local MutableText mutableResult;
+
+    mutableResult = CollectM();
+    if (mutableResult != none) {
+        return mutableResult.IntoText();
+    }
+    return none;
+}
+
+/**
+ *  Assembles initialized `TextTemplate` from provided arguments into a final
+ *  `Text` result.
+ *
+ *  Unspecified arguments will be replaced with empty texts.
+ *
+ *  Returns mutable `MutableText`. To return immutable `Text` use `CollectM()`.
+ *
+ *  @return Result of replacing all argument inside caller `TextTemplate` with
+ *      arguments, specified by user.
+ */
+public final function MutableText CollectM()
+{
+    local int           i, labelCounter;
+    local Label         nextLabel;
+    local MutableText   builder;
+    if (!initialized) {
+        return none;
+    }
+    builder = _.text.Empty();
+    for (i = 0; i < parts.length; i += 1)
+    {
+        if (    labelCounter < labels.length
+            &&  labels[labelCounter].insertionIndex == i)
+        {
+            nextLabel = labels[labelCounter];
+            if (nextLabel.textLabel == none) {
+                builder.Append(BorrowNumericArg(nextLabel.numberLabel));
+            }
+            else {
+                builder.Append(BorrowTextArg(nextLabel.textLabel));
+            }
+            labelCounter += 1;
+        }
+        builder.Append(parts[i]);
+    }
+    while (labelCounter < labels.length)
+    {
+        nextLabel = labels[labelCounter];
+        if (nextLabel.textLabel == none) {
+            builder.Append(BorrowNumericArg(nextLabel.numberLabel));
+        }
+        else {
+            builder.Append(BorrowTextArg(nextLabel.textLabel));
+        }
+        labelCounter += 1;
+    }
+    return builder;
+}
+
+/**
+ *  Assembles initialized `TextTemplate` from provided arguments and parses
+ *  resulting text as formatted string.
+ *
+ *  Allows to do things like specify color inside formatted strings:
+ *  "{%%color_arg%% ColoredText}".
+ *
+ *  Unspecified arguments will be replaced with empty texts.
+ *
+ *  Returns immutable `Text`. To return mutable `MutableText` use `CollectM()`.
+ *
+ *  @return Result of replacing all argument inside caller `TextTemplate` with
+ *      arguments, specified by user and then parsing that intermediate result
+ *  as a formatting string. 
+ */
+public final function Text CollectFormatted()
+{
+    local Text          result;
+    local MutableText   source;
+    source = CollectM();
+    if (source == none) {
+        return none;
+    }
+    result = _.text.FromFormatted(source);
+    _.memory.Free(source);
+    return result;
+}
+
+/**
+ *  Assembles initialized `TextTemplate` from provided arguments and parses
+ *  resulting text as formatted string.
+ *
+ *  Allows to do things like specify color inside formatted strings:
+ *  "{%%color_arg%% ColoredText}".
+ *
+ *  Unspecified arguments will be replaced with empty texts.
+ *
+ *  Returns mutable `MutableText`. To return immutable `Text` use `CollectM()`.
+ *
+ *  @return Result of replacing all argument inside caller `TextTemplate` with
+ *      arguments, specified by user and then parsing that intermediate result
+ *  as a formatting string. 
+ */
+public final function MutableText CollectFormattedM()
+{
+    local MutableText result, source;
+    source = CollectM();
+    if (source == none) {
+        return none;
+    }
+    result = _.text.FromFormattedM(source);
+    _.memory.Free(source);
+    return result;
+}
+
+defaultproperties
+{
+    TPERCENT    = 0
+    stringConstants(0) = "%"
+    TAMPERSAND  = 1
+    stringConstants(1) = "&&"
+}
\ No newline at end of file