LINK syntax

From ASCEND

The language supports certain semantic object associations now. Additional, user-defined associations with user(or their agent) interpretations are needed for things like DAE, BVP, etc solvers.

[edit] The existing associations

• ARE_THE_SAME-- merge two existing instances recursively, resulting in one object with two names.
• ARE_ALIKE-- keep the formal types of a list of instances identical, which prevents the user from doing dumb things and enables them to avoid writing most IS_REFINED_TO statements.
• ALIASES-- define a new name by pointing at an existing instance, usually to assemble an array or expose a part buried in a lower-level model.

[edit] The proposed associations extensions

Syntax:

• Declarative section: LINK( 'key', comma-separated-list-of-names);
• Methods section: LINK(as-above); UNLINK(as-above);

Semantics:

• Each MODEL instance gets a link table listing the links defined locally.
• The elements of this table defined in the declarative section are fixed.
• The elements defined in the methods may be added and removed by running methods or API (user-interface) calls.
• Redundant entries (identical key and namelist) are ignored.
• Any instance name (subarrays, atoms, subatomics) are allowed in list-of-names.
• Only symbol_constants and symbol literals (single quoted) are allowed as keys.
• A link which is defined in a method and later redefined in a type refinement as a declarative link is allowed. A warning is generated and the declarative link semantics wins.
• There is no way to make a declarative "down-in" link (link appear in another model scope).
• There is no guarantee that the names in namelist exist, but user many turn on compiler options that generate warnings or compilation errors if the names cannot be resolved to instances.

• The link table is one for both declarative and method links, but only the method links can be unlinked. We may wish to revisit and see if UNLINK is declaratively allowed in a refinement of the model where a LINK was declared. For the DAE case this would be rather odd, of course.

[edit] API functionality (initial) design

symbollist getLinkTypes (instance, bool recursive)
 /** find all the keys in link table(s), optionally recursive. */

 listoflinkobject getLinks(instance, key, bool recursive)
 /**< get all links matching key, optionally recursive. */

 const linktable getLinkTable(instance)

 void addLink(instance, key, namelist)

 void removeLink(instance, key, namelist) /* or removeLink(link-object) more likely. */

 void removeNondeclarativeLinks(instance, key, bool recursive)
 /**< remove dynamically made links matching key or all if key given is NULL,
 optionally recursive.  */

 instancelistlist getLinkInstances(instance, link-object, status)

 /* return the instances matching list of names in link. Unresolved names result
 in a null list entry and a Find status, but best effort is applied rather than
 fail-fast. Each name in the  namelist is expanded to a list of instances, which
 captures the ascend set semantics usage correctly. */

 instancelist getLinkInstancesFlat(instance, link-object, status)
 /**< as the non-flat version, but any error results in a null list return and all
 found instances are simply appended to one big gllist. */

 bool isDeclarative(link-object)
 /**< - tell if it's dynamic or not. */