Regnus 5.5

The Random Text Scripting Language

The Regnus Scripting Tutorial

Part 6: Automatic Grammar Characters

One very useful feature of Regnus is a range of special characters called "Automatic Grammar Characters", or "AGCs", which can be inserted into your text in order to affect the characters near them in some way. This chapter documents these characters and explain how to use them.

Pluralisation

A common requirement in a Regnus script is to be able to pluralise nouns without resorting to including both singular and plural versions of each word in separate groups. For example:

START <Example>My friend has just one ##Fruit;, but I have several ##Fruits;!

GROUP Fruit
ENTRY banana
ENTRY plum
ENTRY apple

GROUP Fruits
ENTRY bananas
ENTRY plums
ENTRY apples

As you can see, this would be an inefficient way to write a script! Luckily, there is an AG character to solve this problem. To us it, simply place a tilde character ("~") at the end of any word which you would like to be pluralised. For example:

START <Example>My friend just has one ##Fruit;, but I have several ##Fruit;~!

GROUP Fruit
ENTRY banana
ENTRY plum
ENTRY apple

You will find when you run this example that the result of the second reference is automatically pluralised.

The pluralisation function is fairly intelligent, and will correctly pluralise most words in the English language. However, there are of course certain exceptions which it will incorrectly pluralise, and there is a way to get around this: the "MULTI" qualifier. This simply allows you to define a noun, and its plural form. So, to use one example which the parser will have trouble with:

START <Example>I like ##Animal;~!

GROUP Animal
ENTRY cat
ENTRY sheep

MULTI sheep:sheep

If you run this script, you will see that the parser correctly pluralises "cat" to "cats", but if you remove the "MULTI" qualifier, it will try to correct "sheep" to "sheeps", which is of course incorrect.

The "MULTI" qualifier can also be used to correct noun phrases which would otherwise be difficult to automatically pluralise. For example, consider the following:

START <Example>I have several ##AnimalGroup;~!

GROUP AnimalGroup
ENTRY flock of birds
ENTRY gaggle of geese

MULTI flock of birds:flocks of birds
MULTI gaggle of geese:gaggles of geese

Here, it is the first word of each of the phrases returned by the "AnimalGroup" group, rather than the last, but as definitions set by "MULTI" qualifiers always take precendence over standard pluralisation, they can be used to ensure that these phrases are pluralised correctly.

Text Case

Another common requirement in Regnus scripts is to be able to capitalise letters of words. For example, you may want to start a sentence with a random word, but also use that entry in the middle of a sentence.

In these cases, you can use the circumflex accent character ("^") to convert the following letter to uppercase. So, for instance:

START <Example>My name is ^elvis!

This would return the text "My name is Elvis!", as the circumflex forces the following character to be uppercase. This might not seem immediately useful, but consider the following situation:

START <Example>^##Fruit;~ are nice!

GROUP Fruit
ENTRY banana
ENTRY plum
ENTRY apple

Here, we have used both a pluralisation and a capitalisation character alongside the reference to the "Fruit" group, in order to convert (for example) "banana" into "Bananas", which is correct as it appears at the beginning of the sentence.

The circumflex can also be followed by a dot character in order to have the opposite effect, and convert the following character to lowercase. Thus, the above example could also be written in reverse:

START <Example>I have some ^.##Fruit;~!

GROUP Fruit
ENTRY Banana
ENTRY Plum
ENTRY Apple

Here, the entries in the "Fruit" group already begin with a capital letter, but as we are referencing the group in mid-sentence, we use the capitalisation AGC to force lowercase.

A second circumflex character will force a whole word to appear in block capitals:

START <Example>I have some ^^bananas and apples!

This example would return the text "I have some BANANAS and apples!".

The effects of the capitalisation character can also be applied to whole sections of text using parantheses:

START <Example>Hello there! ##MyNameIsElvis;

GROUP MyNameIsElvis
ENTRY I am ^.(Elvis Presley)!
ENTRY I am ^^(elvis presley)!
ENTRY I am ^(elvis presley)!

The first entry in the "MyNameIsElvis" group would return the text "I am elvis presley!", as all of the characters within the parantheses are forced to be lowercase. In the second entry, the returned text would be "I am ELVIS PRESLEY!", as all the characters are forced to be uppercase. The final example uses a single capitalisation character, and has the often-useful effect of applying namecase to span of text, meaning that the first letter of each word is capitalised. This entry would therefore return the text "I am Elvis Presley!", even though the contained text is originally lowercase.

New Lines

One issue you may well have already encountered is that, as Regnus relies on all text from an entry remaining on the same line as its qualifier, you cannot include line breaks in your scripts.

Luckily, the vertical line character ("|") achieves just that!

START <Example>This is line 1...|And this is line 2!|...And hey, this is line 3!

Conditional Spaces

Consider the following script:

START <Example>The cat sat ##Comfort; on the mat.

GROUP Comfort
ENTRY comfortably
ENTRY uncomfortably
ENTRY

Here, an empty "ENTRY" qualifier is used with the intention that in one third of cases, no adverb is used. However, as you will see, this will produce an erroneous two consecutive spaces in the output.

To solve this, the conditional space character can be used:

START <Example>The cat sat ##Comfort;_on the mat.

GROUP Comfort
ENTRY comfortably
ENTRY uncomfortably
ENTRY

By using the underscore character ("_"), a space is only inserted in this position if no preceding space character exists, which will cause the second space to appear only if an adverb is inserted.

Escape Characters

As you may have noticed, Regnus relies on a lot of special characters to signify various things, which has the side-effect of precluding these characters being used in the text of your script. For instance, if you want to include a hash character in your text, the parser will return an error message because it expects a reference, and if you include any of the AG characters, they will be treated as such rather than displayed in the text output.

So, to get around this, you can use Regnus' escape character, the asterisk ("*"), to overstep parsing of characters which you want to use exactly as they are. For example:

GROUP Example
ENTRY <Example 1>This will cause an error: #
ENTRY <Example 2>...But this won't: *#
ENTRY <Example 3>And if you want to include an asterisk, just use two!: **

Note: you can also use the asterisk to escape the letter "a" if there is a single example in your script which you want to debar from article correction, regardless of what word follows it.