The Regnus Scripting Tutorial
Part 10: Storing Results
There are some cases in which you may want your script to use the same reference result twice, in order for your generated text to make sense.
For example, consider the following script:
START <Storage Example>Earlier, I met ##RandomName;. ##RandomName; is an old friend of mine.
GROUP RandomName
ENTRY Albert Possini
ENTRY Forrest Corruthers
ENTRY Jack Sprat
Here, it is important that the name chosen by the first reference is the same one chosen by the second.
For these situations, Regnus allows you to store the result of a reference in one of a hundred available "storage slots", to be recalled whenever necessary later in the script.
The RTC which handles this is the right-hand triangular bracket, or "greater-than" character (">"), which causes the result of the given expression to be stored in a slot number of your choice.
How do you you select the slot number? Well, you may remember it being mentioned earlier in the tutorial that some reference types require more than one expression, and this is one of them!
When an RTC requires more than one expression, each expression in the reference is separated by a colon character (":"). So, for example:
#>Expression1:Expression2;In the case of the storage reference type, the result of the first expression decides the slot number in which to store the text, and the result of the second expression defines the text to be stored.
More specifically, the slot number used will be the numeric value of the text returned by the first expression... So, to give an example:
START <Storage Example>This will store the text "#>(10):Example;" in slot number 10.
GROUP Example
ENTRY Hello!
In this case, the text "Hello!", generated by the reference's second expression, will be stored in slot number 10, defined by the first expression "(10)".
And of course, the following will have the exact same result:
START <Storage Example>This will store the text "#>Example2:Example1;" in slot number 10.
GROUP Example1
ENTRY Hello!
GROUP Example2
ENTRY 10
In this case, the first expression, instead of being a literal expression returning the value "10", is a group expression which returns the value "10" from the group "Example2".
Note: As already mentioned, there are exactly one hundred slot numbers, but these range in value from zero to ninety-nine. Therefore, passing a value of minus one or one hundred will cause an error!
Note: Any expression resolving to a non-numeric character is simply understood to have a value of zero.
So anyway, how do we go about actually retrieving the text once we have stored it? Well, this is handled rather tidily by the third and final type of expression: the slot expression.
This type of expression is invoked by enclosing the expression in square brackets ("[" and "]"), and is treated in almost exactly the same way as a literal expression by the parser, except that it resolves to the contents of the slot number specified by the value of the final result. So, for example:
START <Storage Example>First, we store the text "#>(8):Example;" in slot number 8... Then, we retrieve it again and display it, like this: "##[8];"
GROUP Example
ENTRY Hello!
Here, the first reference stores the text "Hello!" in slot number 8, and then uses a reference with a standard "#" RTC with the expression "[8]", which returns the contents of slot 8.
And of course, as slot expressions are parsed in the same way as literal expressions, the following would have the exact same result:
START <Storage Example>First, we store the text "#>(8):(Hello!);" in slot number 8... Then, we retrieve it again and display it, like this: "##[##Example;];"
GROUP Example
ENTRY 8
In that example, the text stored in slot number 8 is defined by a literal expression rather than taken from another group, and the retrieval is made by a slot expression containing another standard reference, whose result is taken from the group "Example", and will therefore always return the value "8" (as this is the only entry, in this case).
Remember that the slot expression is fully parsed before being evaluated as a slot number, so you could even use multiple references within the slot expression to assemble the slot number:
START <Storage Example>First, we store the text "#>(18):(Hello!);" in slot number 18... Then, we retrieve it again and display it, like this: "##[##(1);##Example;];"
GROUP Example
ENTRY 8
And here's another somewhat convoluted example usage:
START <Storage Example>First, we store the text "#>(8):(Hello!);" in slot number #>(3):(8);... Then, we retrieve it again and display it, like this: "##[##[3];];"
In that example, we actually stored the value "8" into slot number 3 (in the second reference), and then retrieved the contents of slot number 8 by enclosing a reference to the contents of slot number 3 (which contains the value "8", remember) in the slot expression of the third reference!
As you can see, combining the different types of expression available to you can give you a lot of potentially useful possibilities!
So, back to our original example, in order to ensure that the same name is given twice, you would use the following method:
START <Storage Example>Earlier, I met #>(0):RandomName;. ##[0]; is an old friend of mine.
GROUP RandomName
ENTRY Albert Possini
ENTRY Forrest Corruthers
ENTRY Jack Sprat
And of course, as there are a hundred available slots, all of which are globally available to entries throughout the script, it is possible to store a number of pieces of information at once...
For example, examine the following script:
START <Storing Example>Earlier, I met ##RandomPerson;. ##[0]; was an old friend of mine.
GROUP RandomPerson
ENTRY #>(0):FirstName; #>(1):Surname;'s father, ##FirstName; ##[1];
ENTRY #>(0):FirstName; ##Surname;
GROUP FirstName
ENTRY Albert
ENTRY Forrest
ENTRY Jack
GROUP Surname
ENTRY Possini
ENTRY Corruthers
ENTRY Sprat
It may look rather complex, but try running it with your parser - you'll soon see how it works by watching the sentences generated.
It's actually very simple: the first reference to "RandomPerson" causes either of the selectable entries to save the result of their reference to "FirstName" into slot 0, meaning that it can be retrieved by the opening entry (the one labelled "Storing Example").
In the first entry under the group "RandomPerson", the result of the reference to "Surname" is also stored, but to slot 1 - this is used to simply make sure that both father and son in the story share the same surname.
The second reference to "FirstName" (the one generating the first name of the father) is not stored, as it is only used once. Thus, the father's surname is made the same as the son's by retrieving the son's stored surname from slot 1, and the son's first name is stored in slot 0, so when the parser returns to the original entry, the same name appears twice.
Well, go ahead and play with the script, anyway, and once that all makes sense, move on to the next chapter of the tutorial, which looks at some more ways of using storage slots!