References to Containers

Most of the time, containers in a script are used by storing a value directly into a container—or reading a value from one—by simply specifying a variable name (or other container identifier) directly in the script. Sometimes it can be extremely useful, however, to store a reference to a container, which can later be used to access the value of that container. The reference holds the identity of a container rather than its value, and accessing the reference will read or write the contents of the container that it refers to.

Characteristics of References

References have a few characteristics that you will want to be aware of as you work with them. To begin to understand how references work, consider the following example using a reference to a simple variable:

In the first line above, a simple value (32) is assigned to an ordinary variable (age). The next line stores a reference to the variable age into the variable yearsOnThePlanet. Now, any access to the value of the yearsOnThePlanet variable will actually be accessing the value of the age variable, as illustrated by the next line of the script, The last two lines of the script increment that value of the age variable and show that the yearsOnThePlanet variable accesses the updated value.

References Bind Tightly

The connection established by a reference is “sticky” (yearsOnThePlanet is glued tightly to age in the above example) so assignments work in the other direction as well — changing the value of either will change the value of both:

Reference Syntax

References can be made using the words container, reference, reference to, or refer to, or using the shorthand symbol ‘@’ before the container. All of the following are equivalent:

References Can Be Stored in a List or a Property List

References can not only be stored in variables, as shown in the examples so far, but may also be stored as items in a list, or as properties of an object or property list. In this case, accessing the specific item or property that is a reference will access the container it refers to, as shown in this example:

References May Refer to Properties, Files, and Chunks

References may refer to any type of container, not just variables. This includes all the different types of container discussed earlier in this section, including properties, files, and even chunks of any container:

References Are Dynamic

When a reference is made to a property of an object or to a chunk of a container (such as "reference to word 3 of sentence") that reference is evaluated dynamically each time it is used. This means that if the contents of sentence are changed, the reference will always access the third word of its new contents.

References Are Not "Contagious"

Assignments in SenseTalk are always done by value unless a reference is explicitly indicated. So assigning a variable containing a reference to another variable will not create another reference, but only a copy of the current value of the source container. To create another reference, you must specifically indicate a reference during the asignment (specifying a reference to a reference will result in a second reference to the same source).

References Can Be Reassigned

Storing a reference into a variable that already contains a reference will simply reassign that variable. It will not change the value that the variable previously referred to:

To change the container that was referred to into a reference instead of reassigning the original reference variable, you can request that explicitly:

Deleting By Reference

Deleting a reference to a chunk or property with the delete command will delete the chunk or property it refers to (note that this is not the same as deleting the variable containing the reference — see below).

References Are Persistent

Once a variable becomes a reference, it stays tied to the container it refers to until it is reassigned as a different reference, or the reference itself is deleted. You might think that you could free up a reference variable for other uses by simply putting empty into it, but this will merely put empty into the container it refers to! To use the variable for another purpose, you must first delete it, using the delete variable command (not the delete command — see above). If the reference is stored as an item in a list or a property of an object, you can delete that item or property.

There are two exceptional cases where a reference can become a plain variable without explicitly deleting it. Commands that implicitly set the value of the special variable it (see the list in All About "it") will first break any reference stored in it before assigning it a new value. Also, if a repeat construct specifies a loop variable that is currently a reference, that reference will be cleared before the variable is used in the repeat.

Using References

References can be used in many ways in your scripts. Here are a few of the most common uses.

Passing Parameters by Reference

One common use of references is to pass a reference as a parameter to another handler. By passing a reference, the called handler is able to change the value in the local handler. Here is an example:

When the script above is run, it displays "candies". The variable tastyFood is passed by reference from the initial handler to the pluralize handler. Because it is a reference, when aWord is changed by the pluralize handler, it actually changes the value of the tastyFood variable in the initial handler.

Returning a Reference / Using a Function Result as a Container

Just as passing a reference to another handler gives that handler the ability to modify the contents of the container it refers to, it is sometimes useful for a function to be able to return a reference to a container that the caller can then modify. For instance, a function might return a reference to a global variable or a file selected by the function, or a reference to a chunk of such a container. To do this, there are two things that have to happen. First, the function being called must return a reference. Secondly, the calling handler must indicate that it wants to use the returned value as a container (by default, function return values are always treated by value otherwise).

As an example, suppose you want to insert a value into one of two lists, depending on which list has fewer items (a more realistic example might involve several lists). Here is a script that implements this idea using a function to select the appropriate list:

There are a lot of references in this example. The word "container" (or "@" or "reference") is required before the call to chooseContainer() to tell SenseTalk to treat the value returned by the function call as a container. For this example to work, the parameters must also be passed by reference (@firstBox, @secondBox) since they originate in the calling script, and of course the selected container must be returned by reference. The result is a function that accepts references to any two containers, and returns a reference to the one containing fewer items. Marking the function's incoming parameters as references (@c1, @c2) is optional, as it has no functional meaning in the current version of SenseTalk, but it helps to remind users of the chooseContainer function that it should be called with parameters passed by reference.

Determining if a Value is a Reference

In the preceding example, the chooseContainer() function indicates to users that it should be called using references by the use of "@" symbols before its parameters (@c1, @c2). However, SenseTalk doesn't enforce this in any way. To make the function more robust, it could check whether the parameters were actually passed by reference, and alert the user if it was called incorrectly. The is a (or is not a) operator can be used for this purpose. Here is an improved version of the function that performs this test:

Repeat With Each ... By Reference

A special "by reference" option of the repeat with each command will set the iterator variable to be a reference to the current element rather than merely its value. This can greatly simplify writing a script that not only iterates over the chunks of a container but makes changes to some of those elements, as in this example:

 

This topic was last updated on August 19, 2021, at 03:30:51 PM.

Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant