Dodo doc > Variables and Functions > Linked References
A link is an object that can be shared to establish a relationship between several objects. If a value is associated with the link it is called a linked reference.
Linked references are often used to store values that are shared by more than one object instance. A linked reference can also be used in a function, where an argument by reference cannot.
To use linked references, the dodo file should contain:
use link
Linked references are variables or constants of type "Link" with a target type. If they don't have an initial value, their initial state is "null" and they cannot be converted to the target type. The Link constructor is used to create a linked reference with an initial value.
Examples:
Link(<with: House>) property # initially null def number = Link(10)
Where necessary, dodo converts a linked reference to its target type so it can be used in the same way as the target type. A linked reference in "null" state cannot be converted to its target type and using it the same way raises an exception.
Examples:
draw(paper, property) # Exception 2 * number
Passing a variable by reference never involves a conversion. Because a Link variable is not of the same type as the target, linked references have a special syntax that allow the operation to use directly the target so no conversion is required.
That special syntax is to prefix the variable name with "link!".
Examples:
.link!property = showHome GenerateNumber(.link!number)
When a linked reference is copied to a different Link variable the copy becomes inactive. Using it as argument by reference raises an exception. The copy can be reactivated with the Activate() method.
Example:
.self.house = property # inactive self.house.Activate()
A function declaration can include an active linked reference parameter. Its type is prefixed with "*" to mark it as active.
When calling the function the variable name needs to be prefixed with "*" too.
Example:
def addToDirectory(*Link(<with: Directory>), Link(<with: House>), Details) addToDirectory(*directory, house, details)
If there is a list of objects "directory" with a linked reference attribute house, the objects that link to a particular reference property can be found with:
directory[where house = property]
If the objects in a first list directory are related to the objects in a second list street by sharing a linked reference house, the two lists can be joined together with:
[for entry in directory; for address in street; where entry.house = address.house]