Aliases in the Document

Definition

Objects may be used more than once in a document. A typical example which comes to mind is a pictogram repeated on every page, but there are a lot of other such duplicated use of objects : styles, families, etc.

Rather than storing every identical object multiple times, VP uses an aliasing scheme (also known as linking in UNIX or NTFS file systems). The original object is moved to a special block of the document (the alias block) and every occurrence of the object is replaced by a link, which is called an alias in the VP terminology.

Alias object

An alias object is implemented as a raw object of category OBJCAT_LINK which contains the index of the referrer object directly preceding the aliased object :

 
{
    ObjectHead      head;           //  OBJCAT_LINK
    ObjectIndex     referrer;       //  link to referrer object
};
 

Aliased object and Referrer object

The aliased object is stored in the document alias block. It is preceded by a typed object (a VP::DocObj::ReferrerObject) containing an array of indexes referring to the aliases :

 
struct ReferrerObject : public TypedObject {
    
    ObjectIndex     alias[n];       //  table of referring aliases
};
 

Aliasing an object

Turning an object into an alias is called aliasing. It implies following steps, if the object is not yet aliased :

• Create a ReferrerObject in the document alias block.
• Move the object from its original position to the alias block, just after the freshly created referrer object.
• Create an alias object at the object's original position. Make it point to the referrer object.
• Update the referrer object in order to have a back-pointer from the referrer to the alias.

If the object is already aliased, the following steps are taken :

• Create an alias object and make it point to the existing referrer object.
• Grow the referrer object and update it in order to have an additional back-pointer to the freshly created alias.

Document alias manipulation methods

The document class (VP::Document) provides several methods to manipulate aliases :

• VP::Document::AddAlias, add an alias to an object (or a block of objects). If the object (block) is not yet referred to by an alias, then it is moved to the alias block. If an alias is specified instead of an object (block), then the referred object (block) is used instead.
• VP::Document::RemoveAlias, remove an alias to an object (block). If the number of aliases referring to the object (block) falls to zero, then the object (block) is deleted.
• VP::Document::ResolveAlias, find and return the object (block) referred to by the alias. 
• VP::Document::ResolveAliasReferrer, find and return one of the aliases referring to the specified object (block).

Locking aliased objects

It is not possible to lock an aliased object, i.e. to avoid that it disappears when there is no longer any visible link to it. This means that an object may not maintain a reference to an aliased object without having guaranteeing that at least one link points to it.

Thus, commands such as CloneStyle have to maintain an alias (link) in the scratch zone for aliased objects they refer to, and for which there is no guarantee that another link exists.