Regnus 5.5

The Random Text Scripting Language

The Regnus Scripting Tutorial

Part 14: More Reference Types

There are a variety of different types of reference in Regnus which allow you to handle expressions in various different ways. The most important of these have already been looked at earlier in this tutorial, but this chapter will list and briefly explain the remaining RTCs and how to use them.

The Group Reference

This is a single-expression reference type invoked using the plus character ("+"), and returns text selected at random from an entry within a group with the name returned by its expression, essentially allowing you to treat any expression type as if it were a group expression. So, for example:

START <Example>I have a #+(Tools); and a #+SelectType;.

GROUP SelectType
ENTRY Animals

ENTRY hammer
ENTRY nail

GROUP Animals
ENTRY badger

It is important to understand that the reference "##Example;" would be exactly functionally the same as "#+(Example);", but not the same as "#+Example;", which would first get an entry from the group "Example" because of the group expression, and then retrieve an entry from a group with a name matching the returned text from that group, due to the group reference RTC.

The Label Reference

This reference type is invoked using the underscore character ("_"), and returns text from an entry whose label matches the text returned by its expression.

START <Example 1>#_ExampleGroup; #_(Example 2);
START <Example 2>Hello!

GROUP ExampleGroup
ENTRY Example 2

The label "Example 1" from the above example should return the text "Hello! Hello!", as the first reference reads from the label name returned by the group "ExampleGroup" (which will always return "Example 2"), and the second reference returns text from the label with the name returned by the literal expression "(Example 2)", thus both return text from the same entry.

The Script Reference

This reference type allows you to generate text from a different Regnus script file. It expects two expressions, and is invoked with the dollar character ("$").

The first expression should return the name of the external script which you want to pars, and the second expression should return the name of the label within that script from which you want to return text.

Note: the first expression will need to contain path data if the external script is located in a different directory to the current script! However, paths will be adjusted by the Regnus parser to match the convention of the platform, so you should feel welcome to use slashes or backslashes as you prefer (though bear in mind that backslashes in a literal expression will need to be escaped, so forward slashes are probably much more sensible!)

START <Example>#$(NameOfScript):(NameOfLabel);

Note: It is important to note that when you generate text from an external script using the "$" RTC, all data from your script's slot-numbers will be shared with the new script. This gives the advantage of being able to share data between scripts, but also means that you have to be very careful not to accidentally overwrite data which you want to keep for later in the execution!

The Comparative Exclusion Reference

Don't let the name fool you; this type of reference is actually very simple, but very powerful! It is called using the forward slash character ("/").

Essentially, it allows you to define two expressions, and ensure that the second is exclusive from the first. So, for instance:

START <Example>#/(apple):Fruit;

ENTRY apple
ENTRY banana

If you try running this script, you will find that the parser will never produce the result "apple". This is because the group-reference to "Fruit" is made exclusive from the literal expression "apple", so it can never be allowed to produce this result.

This is also very useful when combined with slot expressions, as it allows you to store an arbitrary result, and make a future reference exclusive from it, without affecting your usual local or global exclusions.