BEE Script:   var var =& var [context=string];

BEE Tag:     <beelink link=var var=var [context=string]>

A variable name is in fact an alias to a content storage (or more technically, an entry in the symbol table).  You may have two different variable names referring to the same variable.  This relationship is called a Reference.  Please note that the two variables (or even more) are of equal footing.  You cannot say that one is real and another is a shadow.  They're both handles to the same content storage.  They are both real and they are both shadows.

The "link" command establishes a new Reference (on the left-hand-side) to an existing variable (on the right-hand-side).  References can only be created across compatible structure in the BEE Variable hierarchy.  i.e. You can only link class to class, name to name, or element to element.  Linking incompatible structure does not cause an error but has no effect at all.

Example:

// Link all variables in oldClass to newClass

var newClass% =& oldClass%;

// Link all elements in oldClass%oldName to newClass%newName

var newClass%newName =& oldClass%oldName;

// Link the two elements only

var newClass%newName:newElm =& oldClass%oldName:oldElm;

If you link two classes together, changing a variable in one class will cause the corresponding variable (that of the same name) in another class to have the new value as well.  Moreover, creating new variables in one class will cause the other class to have the same new variable containing the same value.  In fact, there is only one class.

This general principal applies to two linked variables too.  Changing the value of an element in one variable will change the same element of the other, and creating an element in one will cause the other to have the same added to it, because they are the same variable.

Please note that the "clear" command is in fact clearing the reference to the variable's content storage, not the storage itself.  If you have created multiple references on the same variable, clearing one will NOT destroy others.  (Clearing the last reference to the variable effectively remove any means to access the variable from the Context.  After that, the question whether the content storage still exists is meaningless.)

Parameters

link is the name of the new variable (shadow) created to link to an existing variable (real).

var is the name of the existing variable (real) that the new variable (shadow) is linked to.

context is the context identifier of the existing variable to be linked to.  The {sys%context} variable always contains the context identifier of the current environment.  With this facility, you can pass the whole context (and all the classes in it) around.

For example, you can pass the parent's context to a function to allow it to access the parent's variables (can be done with the "parent" command as well).  On the other hand, a function can pass its context to the caller via the result%function variable so that the caller can access the function's local context using the "link" command.  (Yes, the local context of the function survive its exist but not accessible unless through the context parameter.)

Please be very careful about linking context.  It should be generally avoided unless there is an absolute need to do so and you know exactly what you are doing.