The Regnus Scripting Tutorial
Part 4: Exclusive References
As briefly mentioned earlier, when you declare a reference using a hash, the character directly after the hash tells Regnus how to deal with the reference. This character is called a "Reference Type Character", or RTC. In all the examples so far, a second hash character has been used as the RTC, which has no special effect on the reference. However, there are other RTCs you can use...
One common requirement of a Regnus script is to return several results from the same group, but ensure that the same result is not returned twice. For example:
START <Example>My ##Animal; is not a ##Animal;!
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
In this example, it would obviously not be desirable for the script to return the sentence "My cat is not a cat!"
However, as you will see if you run this script, as both references are entirely random, there is a good chance that you will see the same animal selected for both. What is needed, of course, is a way to ensure that the results of both entries are exclusive from each other.
This is actually very easy using the exclusion RTC, represented by the ampersand ("&") character:
START <Example>My #&Animal; is not a #&Animal;!
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
If you run this script now, you will find that none of the animal types will be returned twice. This is because no exclusive reference will return the same result as another exclusive reference in the same script.
Of course, this would not work if only one of the references were exclusive...
START <Example>My ##Animal; is not a #&Animal;!
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
...Here, as only the second reference uses the ampersand RTC, it is still possible for it to return the same result as the previous reference, which is not exclusive.
Exclusive references of this kind do not need to be in the same entry to work, either; they will remain exclusive no matter how deeply nested they are in the script. For example:
START <Example>My #&Animal; is not a ##Predator;!
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
GROUP Predator
ENTRY #&Animal;-eating #&Animal;
Here, none of the references to the group "Animal" will return the same result, even though they are in different groups.
However, there are of course some situations in which the global nature of the exclusivity is undesired... For example:
START <Example>I have a #&Predator; but my friend has a #&Predator;.
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
GROUP Predator
ENTRY #&Animal;-eating #&Animal;
Here, you might want to allow both repetitions of the reference to "Predator" to return the same animal names (provided the whole phrase was not the same). So for example, this script as it is currently written, would never return the phrase "I have a dog-eating fish but my friend has a dog-eating cat!", because the word "dog" cannot be returned twice.
To solve this, we use a "locally exclusive" reference type (as opposed to the "globally exclusive" type as above). This is invoked using the asterisk character ("*") as an RTC, and will only force references to be exclusive from each other when they reside in the same entry.
Thus, the following script would work as desired:
START <Example>I have a #*Predator; but my friend has a #*Predator;.
GROUP Animal
ENTRY cat
ENTRY dog
ENTRY fish
ENTRY bird
GROUP Predator
ENTRY #*Animal;-eating #*Animal;
Note: Be careful when using exclusivity! If you include more exclusive references than there are possibilities of variation in the referenced content, you will cause your parser to fall into an infinite logic loop and hang!
There is also a third type of reference dealing with exclusivity. This is the "comparative exclusion" reference, but this will be covered later in the tutorial!
For now, once you are comfortable with the concept of exclusivity, please move ahead to the next chapter!