Referents

[Previous] [Next]

Referents are variables that can be output before their final values have been assigned. With referents, you can put placeholder variables in your output and then later assign or change their values. The following program illustrates the placeholder quality of referents:

 process output "Goodbye, " || referent "world-type" || " world!" set referent "world-type" to "cruel" 

The result of this program is to output the line "Goodbye, cruel world!"

The following example is more complex:

 process local stream fowl set fowl to "Duck%n" set referent "water" to "Duck%n" output fowl output referent "water" set fowl to "bar%n" set referent "water" to "bar%n" 

The output of this program is

 Duck bar 

While the output value of stream fowl didn't change values after being output, the output value of referent water did. The final value of both variables did change to water, but only the output of the referent reflected this change.

Notice that while the stream fowl had to be declared before it was used, the referent water did not. All you need to do to create and use a referent is give it a name and set it to a value.

Another simple example of referents in action is in outputting page numbers that include of n values—for example, page 1 of 8. Until a document has been completely processed, you cannot know for certain how many pages it will have. With referents, however, you can simply put a placeholder where the page numbers will be in the output. After the document has been completely processed and the number of pages determined, the final values can be plugged into the referents.

The following program changes the number of a list of plays in a text file. Each time the program finds a number at the beginning of a line, it updates the referent play-count and outputs the current play number and the referent. Though the referent is updated and output each time the rule fires, all output copies of the referent are displayed with the referent's final value:

 find line-start digit+ => play-number set referent "play-count" to play-number output "Play " || play-number || " of " || referent "play-count" process submit file #args[1] 

For the following input file:

 1 Hamlet 2 Richard III 3 Macbeth 4 Romeo and Juliet 5 King Lear 

the preceding program would produce the following output:

 Play 1 of 5     Hamlet Play 2 of 5     Richard III Play 3 of 5     Macbeth Play 4 of 5     Romeo and Juliet Play 5 of 5     King Lear 

By default, referents are resolved when the program ends. However, you can create a referents scope that will allow you to use using nested-referents to resolve referents earlier:

 find line-start digit+ => play-number set referent "play-count" to play-number output "Play " || play-number || " of " || referent "play-count" process using nested-referents submit file #args[1] 

In this example, a referents scope is created that applies only to the submit action. Referents will be resolved as soon as the scanning initiated by submit is complete, rather than when the program ends.