AcediaFramework
/
AcediaCore
2
0
Fork 0
Code Issues 9 Pull Requests Releases Wiki Activity
Browse Source

Add `TextTemplate` class

pull/8/head
Anton Tarasenko 2 years ago
parent
03cf5c5745
commit
47a4095bb1
4 changed files with 1434 additions and 18 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 29
      sources/Manifest.uc
  2. 361
      sources/Text/Tests/TEST_TextTemplate.uc
  3. 87
      sources/Text/TextAPI.uc
  4. 975
      sources/Text/TextTemplate.uc

29
sources/Manifest.uc
Unescape View File

@ -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'
}

361
sources/Text/Tests/TEST_TextTemplate.uc
Unescape View File

@ -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"
}

87
sources/Text/TextAPI.uc
Unescape View File

@ -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)

975
sources/Text/TextTemplate.uc
Unescape View File

@ -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) = "&&"
}
Write Preview
Loading…
Cancel
Save