Expression Text Formatierung

The expression language includes a Expression Grammatik to provide formatting groups, references and coalescing in C# strings.

Example

Below is a short example that uses these constructs to create a very flexible formatting string for a person.

{id}'s full name: <{ln}, {fn}??withheld>

This example includes the following rules:

The person's id is always includes at the beginning (regardless of whether it is set to a non-null value).
If both ln and fn are set, they are both included and separated with a comma and a space.
If only one of ln or fn is set, that value is included.
If neither ln or fn is set, the word "withheld" is included instead.

Referencing data

References and embedded expressions are indicated with curly brackets:

{A}
{A.B[2] + C('text')}
{A.B(C)}

The angle bracket indicates a format group, where constant text is only included if one or both adjoining references are non-empty. The expression to the right of the ?? (coalesce) operator is used if the format group evaluates to empty. The ?? section is optional.

Reserved characters (<, ? and {) can be escaped with a backslash.

More examples

The following examples will try to illustrate the various paths that an evaluation of a formatting group can take.

<{A}, {B}>

A	B	Result

1	2	1, 2
1		1
	2	2

<{A};{B};{C}: Message>

A	B	C	Result

1	2	3	1;2;3: Message
1	2		1;2
1			1
	2	3	2;3: Message

<{A} items??empty>

A	Result
1	1 items
	empty

<{A}, {B}.??<{C}??Nothing defined!>>

A	B	C	Result
1	2	3	1, 2
	2	3	2
1		3	1
		3	3
			Nothing defined!

Advanced Examples

A real-world example with several data fields can take a few more iterations to get them right. Let's take a look below.

Format groups can be scattered and nested throughout the given text, to create something quite complex, like the example below:

My name is <{LastName}, {FirstName} {MiddleInitial}.> and my phone number is <{MobNumber}??<{TelNumber}??<{FaxNumber}>>>.

LastName	FirstName	MiddleInitial	MobNumber	TelNumber	FaxNumber	Result
Doe	John	Q	0765551111	0765552222	0765553333	My name is Doe
Doe	John	Q		0765552222	0765553333	My name is Doe
Doe	John			0765552222	0765553333	My name is Doe
Doe					0765553333	My name is Doe and my phone number is 0765553333.
Doe						My name is Doe and my phone number is .
	John					My name is John and my phone number is .
					0765553333	My name is and my phone number is 0765553333.
						My name is and my phone number is .

We can see from the sample input above that there are several instances where a phrase is included although all the data values are empty. The expression would work much better if the two formatting groups were merged.

The following example fixes these drawbacks by wrapping everything in a further formatting group.

<My name is <{LastName}, {FirstName}, {MiddleInitial}.> and my phone number is <{MobNumber}??<{TelNumber}??<{FaxNumber}>>>.??No data>

LastName	FirstName	MiddleInitial	MobNumber	TelNumber	FaxNumber	Result
Doe	John	Q	0765551111	0765552222	0765553333	My name is Doe
Doe	John	Q		0765552222	0765553333	My name is Doe
Doe	John			0765552222	0765553333	My name is Doe
Doe					0765553333	My name is Doe and my phone number is 0765553333.
Doe						My name is Doe
	John					My name is John
					0765553333	0765553333.
						No data

As you can see, the fallbacks for missing data are now better, printing "No data" when absolutely nothing has been specified.

Writing tests

The following code illustrates how to test an expression using C# and NUnit with various inputs.

The test is written so that you can copy/paste most of it to your own solution and change the number of and the names of the parameters.

[TestCase("Doe", "John", "Q", "0765551111", "0765552222", "0765553333", "My name is Doe, John Q. and my phone number is 0765551111.")]
[TestCase("Doe", "John", "Q", "", "0765552222", "0765553333", "My name is Doe, John Q. and my phone number is 0765552222.")]
[TestCase("Doe", "John", "", "", "0765552222", "0765553333", "My name is Doe, John and my phone number is 0765552222.")]
[TestCase("Doe", "", "", "", "", "0765553333", "My name is Doe and my phone number is 0765553333.")]
[TestCase("Doe", "", "", "", "", "", "My name is Doe")]
[TestCase("", "John", "", "", "", "", "My name is John")]
[TestCase("", "", "", "", "", "0765553333", "0765553333.")]
[TestCase(null, null, null, null, null, null, "No data")]
[TestCase("", "", "", "", "", "", "No data")]
public void TestFormattingExamples(
  [CanBeNull] string lastName,
  [CanBeNull] string firstName,
  [CanBeNull] string middleInitial,
  [CanBeNull] string mobileNumber,
  [CanBeNull] string telNumber,
  [CanBeNull] string faxNumber,
  [NotNull] string expectedResult)
{
  var parser = GetInstance<IExpressionParser>();
  var expressionText = $"'<My name is <{{{nameof(lastName)}}}, {{{nameof(firstName)}}} {{{nameof(middleInitial)}}}.> and my phone number is <{{{nameof(mobileNumber)}}}??<{{{nameof(telNumber)}}}??<{{{nameof(faxNumber)}}}>>>.??No data>'";
  var expression = parser.CreateExpression(expressionText, false);
  var context = new ExpressionContext
  {
    [nameof(lastName)] = lastName,
    [nameof(firstName)] = firstName,
    [nameof(middleInitial)] = middleInitial,
    [nameof(mobileNumber)] = mobileNumber,
    [nameof(telNumber)] = telNumber,
    [nameof(faxNumber)] = faxNumber
  };

  Assert.That(expression.TryGetValue(context, out var value));
  Assert.That(value.ToString(), Is.EqualTo(expectedResult));
}