Templates¶

A template text is essentially a placeholder text parsed by the Grammar Engine. While processing, detected placeholders will be filled with variables (as far as they're defined).

The values inserted are typically adjusted to be grammatically correct given their context. For this to work properly, it might be necessary to add extra markup, denoting additional information such as required articles or grammatical cases.

Variable Types¶

The Grammer Engine differentiates between three types of variables that may be inserted using placeholders.

Built-in Constants¶

Built-in Constants have fixed values and start with grammar::. They can't be overwritten in any way. The following table includes a list of all constants and example values.

These may be used just like any other variable, although they're mostly for debugging purposes, e.g. to determine how old a specific build is or which fixes are included.

Powered by Lingoona Grammar Engine v<<grammar::version>>

This example would result in the version number to be inserted:

Powered by Lingoona Grammar Engine v1.7.1

Global Variables¶

Global Variables are identified by name and can be set by developers. These can be used like any other variable, for example:

Welcome, <<player_name>>. I've been waiting for you. My name is <<npc>>. Is this your first time <<l:location>>?

Based on the values of these variables, the results could look like this:

Welcome, Mr. Jones. I've been waiting for you. My name is Müller. Is this your first time in Berlin?

It's completely up to the developers which variables are available and their actual content.

Dynamic Variables¶

Dynamic Variables are identified by numbers and are passed directly when the Grammar Engine is invoked.

Dynamic variables are always identified by an increasing index, starting at 1, then 2, etc. A special variable 0 exists, but is used for internal purposes only and shouldn't be queried as it's exact contents may expose undefined behavior.

Basic Text Template¶

A minimalistic template is just a static text with no special placeholders:

Hello World!

This will be returned as-is without modifications.

Placeholders can be defined using special opening and closing brackets. While these might be project dependent, the default format is <<var>>, where var might be a named constant or variable or a number denoting a dynamic parameter.

Hello, <<name>>! Have you seen the <<object>>?

The final result could look like this:

Hello, Michael! Have you seen the tower?

Implicit Context Detection¶

If no tagging information is provided inside the placeholder, the Grammar Engine will try to implicitly derive the needed articles or pronouns together with the applicable grammatical case based on the word in front of the placeholder.

While this might be of limited use in languages such as Russian or even English, it allows most German and French use cases to simply skip tagging altogether.

<<X:1>> - You see a <<1>>.

This example will print the raw variable contents (enforced by the tagging with X:) followed by the completed sentence. Here the English parser will detect the indetermined article a in front of the placeholder and set the proper internal request flag accordingly.

skeleton^n - You see a skeleton.

axe^n - You see an axe.

golden sword^nd - You see the golden sword.

Mario^M - You see Mario.

As you can see, the article is dynamically adjusted based on the variable contents. The following line would net the same results, explicitly tagging the placeholder to show an:

<<X:1>> - You see <<a:1>>.

For this to work properly, the used articles have to assume the placeholder is going to hold an male singular name, even if that won't be the case:

🇩🇪<<X:1>> - Ich bringe meinen <<1>> ins Haus.

Here the German meinen will be properly detected as the accusative version of the first person singular possessive pronoun. This will result in the proper possessive pronoun being used, even if the variable later holds a female or neuter name.

🇩🇪Hund^m - Ich bringe meinen Hund ins Haus.

🇩🇪Ente^f - Ich bringe meine Ente ins Haus.

🇩🇪Gäste^p - Ich bringe meine Gäste ins Haus.

Explicit Context Definition¶

Instead of relying on automatic context detection – or whenever this isn't possible – there's also a way to define a grammatical case and/or specify extra flags when defining placeholders.

Grammatical Case¶

The Grammar Library is capable of handling the following grammatical cases. If no case is given, the nominative case is assumed.

Placeholder Tags¶

Placeholder tags may be a combination of the following tags. Certain combinations might cause undefined behavior. For example, you shouldn't use combinations such as Zz, transforming all characters to uppercase and lowercase at the "same" time.

General Tags¶

Pronoun Tags¶

Switches¶

Parts of a template can be dynamically adjusted based on a variable's gender or numerical value. To achieve this, the switches "body" section is simply appended to the variable's name or index.

Gender Switches¶

A gender switch consists of at least a male and female case. Depending on the individual language, there can be extra cases for neuter, plural, and plural 2.

<<var{male/female/neuter/plural/plural2}>>

If required, individual cases may insert the value of the variable by using $s:

<<var{male $s/female $s/neuter $s/plural $s/plural2 $s}>>

Numerical Switches¶

Similar to gender switches, variables can also be evaluated to a numerical value. By default, the Grammar Engine will try to read a number from the beginning of the variable's contents.

<<var[one/many]>>

<<var[zero/one/many]>>

If required, individual cases may insert the read number of the variable by using $d and the full value of the variable using $s.

<<var[zero $s/one $s/many $s]>>

<<var[zero $d/one $d/many $d]>>

Multiplication¶

It is possible to make a placeholder automatically show a count and adjusting to singular or plural forms accordingly.

While most of this is also possible using numerical switches, this approach allows more dynamic text as well as the use of proper plural forms.

Default Usage¶

For this to work, two placeholder indexes have to be concatenated using *:

<<X:1>> - <<X:2>> - You've obtained a <<1*2>>!

Based on the numerical value in variable 1 and the name in variable 2, this could lead to different results:

0 - item^n - You've obtained no item!

1 - item^n - You've obtained an item!

2 - item^n - You've obtained 2 items!

Forced Numbers¶

It's also possible to name the first index with a leading zero:

<<X:1>> - <<X:2>> - You've obtained a <<01*2>>!

This will force written out numbers in all cases:

0 - item^n - You've obtained 0 items!

1 - item^n - You've obtained 1 item!

2 - item^n - You've obtained 2 items!

Static Text¶

Rather than providing a second variable, it's also possible to embed text with tags directly. This is mostly useful for instances where a number is inserted into static text, but the text should change.

<<X:1>> - You've obtained a <<1*item^n>>!

0 - You've obtained no item!

1 - You've obtained an item!

2 - You've obtained 2 items!

Same results may be achieved using numerical switches.

List Formatting¶

The Grammar Engine is capable of automatically collecting all non-empty variables in a given range (start and end index) and formatting them into a language specific list and applying proper conjunctions and punctuation. This makes it easier to create flexible lists without having to worry about the actual amount of elements being used.

Lists may be composed utilizing <<and()>>, <<or()>>, or <<nor()>>.

Find <<and(1,4)>> inside the cave.

Assuming the dynamic variables/parameters from 1 to 4 include three names (and one empty value) this results in:

Find Mike, Jane, and Michelle inside the cave.

If only two of them are set the result is adjusted accordingly:

Find Mike and Jane inside the cave.