grama.commonAncestors

Returns all common ancestors of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

grama.commonAncestors(id1: (String | Number), id2: (String | Number))
Parameters
id1 ((String | Number)) the first id
id2 ((String | Number)) the second id

grama.closestCommonAncestor

Returns the id of the closest ancestor of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

When using the predicate a return value of false will cause grama to look for the next closest common ancestor, i.e. the returned id is not of the actual closest ancestor, but the closest one that matches the predicate.

grama.closestCommonAncestor(id1: (String | Number), id2: (String | Number), $0: Object): (String | Number)
Parameters
id1 ((String | Number)) the first id
id2 ((String | Number)) the second id
$0 (Object) options
Name Description
$0.predicate Function? (default null) a function that if supplied needs to return true in order to accept the common ancestor. If not supplied the actual closest common ancestor is accepted.
Returns
(String | Number): the id of the closest common ancestor or null if it doesn't exist

grama.furthestCommonAncestor

Returns the id of the furthest ancestor of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

When using the predicate a return value of false will cause grama to look for the next furthest common ancestor, i.e. the returned id is not of the actual furthest ancestor, but the furthest one that matches the predicate.

grama.furthestCommonAncestor(id1: (String | Number), id2: (String | Number), $0: Object): (String | Number)
Parameters
id1 ((String | Number)) the first id
id2 ((String | Number)) the second id
$0 (Object) options
Name Description
$0.predicate Function? (default null) a function that if supplied needs to return true in order to accept the common ancestor. If not supplied the actual furthest common ancestor is accepted.
Returns
(String | Number): the id of the furthest common ancestor or null if it doesn't exist

grama.closestAncestor

Finds the closes ancestor that matches the predicate. If two ancestors match the predicate and have the same distance, the first one found is returned.

Therefore this function is non-deterministic since it depends on the order in which ancestors were added.

grama.closestAncestor(id: (String | Number), predicate: Function): (String | Number)
Parameters
id ((String | Number)) the id of the node whose ancestors to evaluate
predicate (Function) a function that needst to return true if the ancestor satisfies the criteria
Returns
(String | Number): the id of the first ancestor matching the predicate

grama.allAncestors

Finds all ancestors that match the predicate.

grama.allAncestors(id: (String | Number), predicate: Function): Set<(String | Number)>
Parameters
id ((String | Number)) the id of the node whose ancestors to evaluate
predicate (Function) a function that needst to return true if the ancestor satisfies the criteria
Returns
Set<(String | Number)>: the ids of all ancestors matching the predicate

grama.closestDescendant

Finds the closes descendant that matches the predicate. If two descendants match the predicate and have the same distance, the first one found is returned.

Therefore this function is non-deterministic since it depends on the order in which descendants were added.

grama.closestDescendant(id: (String | Number), predicate: Function): (String | Number)
Parameters
id ((String | Number)) the id of the node whose descendants to evaluate
predicate (Function) a function that needst to return true if the descendant satisfies the criteria
Returns
(String | Number): the id of the first descendant matching the predicate

grama.allDescendants

Finds all descendants that match the predicate.

grama.allDescendants(id: (String | Number), predicate: Function): Set<(String | Number)>
Parameters
id ((String | Number)) the id of the node whose descendants to evaluate
predicate (Function) a function that needst to return true if the descendant satisfies the criteria
Returns
Set<(String | Number)>: the ids of all descendants matching the predicate

grama.closestSibling

Finds the closest sibling to the node with the provided id that matches the predicate.

It's not exactly a sibling but any node that is a descendant of an ancestor of the node with the provided id.

We consider the siblings closest if the distance from the node at id to the common ancestor is shortest.

For instance in the example below we are trying to find the closest sibling of WriteStream:Close. Our predicate looks for anything that is a WriteStream:Write.

WriteStream:Write2 is considered a closer sibling since the common ancestor Read2 is at a shorter distance to WriteStream:Close than Read1 which is the ancestor of the other WriteStream:Write1.

           -- ReadStream:Open -- Read1 -- Read2 -- Read3 -- WriteStream:Close
         /                           \          \
Parent                                \           -- WriteStream:Write2
         \                              -- WriteStream:Write1
           -- WriteStream:Open
grama.closestSibling(id: (String | Number), predicate: Function): (String | Number)
Parameters
id ((String | Number)) the id of the node whose closest sibling we are trying to find
predicate (Function) needs to return true in order to determine a node as a sibling, it is invoked with ({ descendantId, descendantDistance, ancestorId, ancestorDistance }) .
Returns
(String | Number): the id of the closest sibling matching the predicate

grama.allSiblings

Finds the all siblings to the node with the provided id that match the predicate.

It's not exactly a sibling but any node that is a descendant of an ancestor of the node with the provided id.

For instance in the example below we are trying to find all siblings to WriteStream:Close that start with WriteStream. The result would include WriteStream:Write2, WriteStream:Write1 and WriteStream:Open.

           -- ReadStream:Open -- Read1 -- Read2 -- Read3 -- WriteStream:Close
         /                           \          \
Parent                                \           -- WriteStream:Write2
         \                              -- WriteStream:Write1
           -- WriteStream:Open
grama.allSiblings(id: (String | Number), predicate: Function): Set<(String | Number)>
Parameters
id ((String | Number)) the id of the node whose siblings we are trying to find
predicate (Function) needs to return true in order to determine a node as a sibling, it is invoked with ({ descendantId, descendantDistance, ancestorId, ancestorDistance }) .
Returns
Set<(String | Number)>: the ids of the siblings matching the predicate

grama.has

Determines if the given id is part of the nodes that were passed to grama.

grama.has(id: (String | Number)): Boolean
Parameters
id ((String | Number)) the id we are verifying
Returns
Boolean: true if so otherwise false

grama.get

Retrieves the node with the given id from the nodes that were passed to grama.

grama.get(id: (String | Number)): Object
Parameters
id ((String | Number)) the id we are trying to get
Returns
Object: the node with the supplied id or null if not found

askGrama

Creates grama who will tell you about the ancestry of the nodes you passed.

askGrama($0: Object): Object
Parameters
$0 (Object) options
Name Description
$0.nodes Array<Object> the nodes to be added to the ancestry
$0.id String the name of the property that returns the id of each node
$0.parentId String the name of the property that returns the id of the parent of each node
Returns
Object: an instance of Grama