Lurch core classes

Class

Connection

The Connection class is a thin API to make it easy to access connection data stored in MathConcept instances. Specifically, the construction and destruction of Connection objects has nothing to do with the actual connections that exist among nodes in a MathConcept hierarchy, but rather these objects are created for convenience in accessing and modifying those connections.

Specifically, the data for a connection between two MathConcepts is stored as follows. Assume we have MathConcepts X and Y with IDs idX and idY, respectively, and a connection from X to Y that has ID C and associated data D (which is an arbitrary Map stored as JSON). This information is stored by the following convention.

  • MathConcept X will have an attribute with key "_conn target C" and value idY.
  • MathConcept Y will have an attribute with key "_conn source C" and value idX.
  • MathConcept X will have an attribute with key "_conn data C" and value D.

In each of the above examples, the literal value C is not in the attribute key, but rather the ID of the connection we're referring to as C.

While it would be possible to create, edit, and/or remove such data with just the attribute getters and setters on MathConcept instances, this would be very inconvenient. It will produce cleaner code if we treat connections as first-class citizens by creating this class. But its instances merely hide the details of manipulating the data as described above; they do not store their own data. In particular:

  • We might have multiple instances of the Connection class all in existence at once, all referring to the exact same connection. This does not make multiple copies of the connection; it merely gives us multiple ways to refer to it.
  • We might have no instances of the Connection class in existence for some particular connection. This does not make the connection go away; it merely means we don't currently have objects that refer to it.

Constructor

new Connection(id)

This function constructs a new instance, and in that sense behaves very much like withID(), but that function is to be preferred over this one for two reasons.

  1. This function always returns a Connection instance, since it is the constructor, even if the parameter passed is not the ID of any existing Connection. The resulting Connection instance will not be of any use to the client.
  2. Calling a constructor gives the illusion that the connection object is forming a connection between two MathConcepts, while the withID() function suggests the truth more accurately, that we are simply getting ahold of an already-existing connection. To form a new connection between two MathConcepts, use the create() function instead.

Parameters

  • id string

    The globally unique ID of a connection among MathConcept instances

See

Source

Classes

Connection

Members

IDs

Each Connection should have a globally unique ID, and there should be a dictionary of such IDs that give us a way to create a Connection instance with that ID.

This Map stores the association of Connection IDs (keys) with MathConcept instances (values), such that the MathConcept IDs[x] is the source of the Connection with ID x.

This data structure should not be accessed by clients; it is private to this class. Use withID() instead.

See

Source

Methods

attr(attributes) → {boolean}

This function is equivalent to zero or more calls to the setAttribute() function in immediate succession, except that they are combined into a single modification of the source MathConcept, to minimize the number of events generated.

Parameters

  • attributes *

    If this is an array, it is treated as an array of key-value pairs, and we use each such pair to update the data for this connection. If this is a Map, then all of its key-value pairs are used instead, in the same way. If this is any other kind of JavaScript object, then all of its keys and values are used instead, in the same way.

See

Returns

  • boolean

    True if and only if it succeeded in writing the data into the source MathConcept. This fails only if this object has no source().

Source

clearAttributes(…keys) → {boolean}

Remove zero or more key-value pairs from the data associated with this connection. The data for a connection is a set of key-value pairs, stored in the source MathConcept for the connection, as described in the conventions documented at the top of this class. This function removes zero or more pairs from that set, based on the list of keys it is given. It makes only one call to the setAttribute() function in the source MathConcept, therefore generating only one willBeChanged event and one wasChanged event in that MathConcept.

Parameters

  • keys Array.<string> <repeatable>

    The keys to remove

See

Returns

  • boolean

    True if and only if it succeeded in altering the data in the source MathConcept. This fails only if this object has no source().

Source

getAttribute(key) → {*}

Look up a value in the data associated with this connection. The data for a connection is a set of key-value pairs, stored in the source MathConcept for the connection, as described in the conventions documented at the top of this class. This function looks up one value in that set of key-value pairs, given a key.

Parameters

  • key string

    The key for the attribute to look up

See

Returns

  • *

    The value corresponding to the given key

Source

getAttributeKeys() → {Array.<string>}

The list of keys for all attributes of this connection. The data for a connection is a set of key-value pairs, stored in the source MathConcept for the connection, as described in the conventions documented at the top of this class. This function looks up all the keys in that data and returns them.

See

Returns

  • Array.<string>

    A list of strings, each one a key. If this Connection instance has an invalid ID or any other misconfiguration, this result will be undefined.

Source

handleIDChange(oldID, newID)

When a MathConcept is undergoing a change of ID, if it is part of any connection, that connection will need to update how it is stored in the attributes of either the source or target, to stay consistent with the MathConcept's change of ID.

This function can be called when a MathConcept's ID changes, and if that MathConcept exists on either end of this connection, it will update the data on the other end to stay in sync with the ID change.

Clients should never need to call this; it is for use exclusively by the MathConcept class.

Parameters

  • oldID string

    The old ID of the changing MathConcept

  • newID string

    The new ID of the changing MathConcept

See

Source

hasAttribute(key) → {boolean}

Check whether a key exists in the data associated with this connection. The data for a connection is a set of key-value pairs, stored in the source MathConcept for the connection, as described in the conventions documented at the top of this class. This function looks up a key and returns whether or not that key is present in the data.

Parameters

  • key string

    The key to look up

See

Returns

  • boolean

    True if the key exists in the data, false if it does not or if there is any other problem with the lookup (such as this instance's ID being invalid)

Source

remove() → {boolean}

Delete a new connection between two MathConcept instances. This deletes data from the attributes of those two instances, data representing the connection, and thus generates one willBeChanged event and one wasChanged event in each. It also removes this Connection's ID from the global mapping.

Returns

  • boolean

    True if and only if it succeeded in deleting the data in the source and target MathConcepts. This fails only if this object has no source() or no target().

Source

setAttribute(key, value) → {boolean}

Store a value in the data associated with this connection. The data for a connection is a set of key-value pairs, stored in the source MathConcept for the connection, as described in the conventions documented at the top of this class. This function adds or overwrites a pair in that set, given the new key and value to use. This therefore generates one willBeChanged event and one wasChanged event in the source MathConcept.

Parameters

  • key string

    The key for the attribute to add or change

  • value *

    The new value to associate with the key. This should be data that is amenable to JSON encoding.

See

Returns

  • boolean

    True if and only if it succeeded in writing the data into the source MathConcept. This fails only if this object has no source().

Source

static

create(connectionID, sourceID, targetID, dataopt) → {Connection}

Create a new connection between two MathConcept instances. This writes data into the attributes of those two instances, data representing the connection, and then returns a Connection instance that gives convenient access to that data.

Parameters

  • connectionID string

    The ID to be used for the newly formed connection. This must not already exist in the IDs mapping; if it does, this function takes no action.

  • sourceID string

    The ID of the MathConcept that should be the source of the new connection. If no MathConcept has this ID, this function takes no action.

  • targetID string

    The ID of the MathConcept that should be the target of the new connection. If no MathConcept has this ID, this function takes no action.

  • data * <optional>
     null

    Optional data to be assigned to the newly formed connection. This parameter will be passed directly to the attr() function; see its documentation for the acceptable types and their meanings.

Returns

  • Connection

    A Connection instance for the newly created connection between the source and target. This return value can be safely ignored, because the connection data is stored in the source and target MathConcepts, and is not dependent on the Connection object itself. But this return value will be false if any step in the process fails, including if the connection ID is already in use or the source or target IDs are invalid.

Source

static

transferConnections(giver, receiver) → {boolean}

When replacing a MathConcept in a hierarchy with another, we often want to transfer all connections that went into or out of the old MathConcept to its replacement instead. This function performs that task.

Parameters

  • giver MathConcept

    The MathConcept that will lose its connections

  • receiver MathConcept

    The MathConcept that will gain them

See

Returns

  • boolean

    Whether the operation succeeds, which happens as long as the receiver has a tracked ID and all relevant connections can be successfully removed from one place and recreated in another

Source

static

withID(id) → {Connection}

Create a Connection instance representing the connection with the given ID. Keep in mind that connections among MathConcepts are stored as data within those MathConcepts, and this class is merely a convenient API for manipulating that data. So a connection exists independently of how many (zero or more) Connection instances exist in memory. If you want to query or manipulate a connection, it is handy to get a Connection instance for it, using this function.

Parameters

  • id string

    The globally unique ID of a connection among MathConcept instances

Returns

  • Connection

    A Connection instance representing the connection whose ID was given, or undefined if the given ID is not in the IDs mapping

Source