Skip to content

Locality

Local navigation

Here are the methods by which you can navigate easily from a node to its neighbours: parents and children, previous and next siblings.

L

The Locality API is exposed as L or Locality.

otype parameter

In all of the following L-functions, if the otype parameter is passed, the result is filtered and only nodes with otype=nodeType are retained.

Results of the L. functions are tuples, not single nodes

Even if an L-function returns a single node, it is packed in a tuple. So to get the node itself, you have to dereference the tuple:

1
L.u(node)[0]
L.u()
1
L.u(node, otype=nodeType)
Description

Produces an ordered tuple of nodes upward, i.e. embedder nodes.

node

The node whose embedder nodes will be delivered. The result never includes node itself. But other nodes linked to the same set of slots as node count as embedder nodes. But slots are never embedders.

L.d()
1
L.d(node, otype=nodeType)
Description

Produces an ordered tuple of nodes downward, i.e. embedded nodes.

node

The node whose embedded nodes will be delivered. The result never includes node itself. But other nodes linked to the same set of slots as node count as embedded nodes. But nothing is embedded in slots.

L.n()
1
L.n(node, otype=nodeType)
Description

Produces an ordered tuple of adjacent next nodes.

node

The node whose right adjacent nodes will be delivered; i.e. the nodes whose first slot immediately follow the last slot of node. The result never includes node itself.

L.p()
1
L.p(node, otype=nodeType)
Description

Produces an ordered tuple of adjacent previous nodes from node, i.e. nodes whose last slot just precedes the first slot of node.

Description

Produces an ordered tuple of adjacent previous nodes.

node

The node whose lefy adjacent nodes will be delivered; i.e. the nodes whose last slot immediately precede the first slot of node.

Locality and levels

Here is something that is very important to be aware of when using sortNodes and the L.d(n) and L.u(n) methods.

When we order nodes and report on which nodes embed which other nodes, we do not only take into account the sets of slots the nodes occupy, but also their level. See levels.

Both the L.d(n) and L.u(n) work as follows:

  • L.d(n) returns nodes such that embedding nodes come before embedded nodes words)
  • L.u(n) returns nodes such that embedded nodes come before embedding nodes books)

N.B.: Suppose you have node types verse and sentence, and usually a verse has multiple sentences, but not vice versa. Then you expect that

  • L.d(verseNode) will contain sentence nodes,
  • L.d(sentenceNode) will not contain verse nodes.

But if there is a verse with exactly one sentence, and both have exactly the same words, then that is a case where:

  • L.d(verseNode) will contain one sentence node,
  • L.d(sentenceNode) will contain one verse node.