This version is out of date, covering development as far as v4.2.5. It is maintained here only for inbound reference links from elsewhere.

Jump to the current version of aTbRef.

A Tinderbox Reference File : Actions & Rules : Set creation operators : links() operator

links() operator

The v4.0.0 links() operator builds a Set from a collection of links.

links[(notes)].kind.[linkType].attribute

selects one or more notes' links should be collected. The optional notes argument may be:

omitted (including notes' enclosing brackets) - in which case the implied context is 'this'.
a named single note
an item object (e.g. parent)
a group object (e.g. ancestors)
a path (/config/details).

The note argument is not evaluated.

The kind argument is one of these values:

inbound
outbound
web

and filters the directionality of the links collected.

The optional linkType argument collects only links of a specified link type, such as may be defined in the current TBX. linkType is a regular expression, so regular expression wild-card characters are permitted and retain their special meanings. If the linkType value contains white space or periods, it must be enclosed in quotes:

links.outbound."responds to".Name

If linkType is left empty, links of all types are collected except prototype links. Prototype links are always omitted.

The attribute argument is the name of the attribute whose values are to be collected in the result.

For example:

MySet=links(/config).outbound.supports.Name

constructs a set of all the titles (from Name attribute) of notes that are linked to the top-level note named 'config' via links with the link type 'supports'. For multi-word link type names use quotes:

MySet=links(/config).outbound."agrees with".Name

Whilst it is likely that 'Name' will be the most usual value for attribute, it can be any currently defined attribute:

MySet=links(all).inbound."went to".SchoolName

collects a set of all the values of attribute 'SchoolName' for notes that are linked to via an inbound links of type "went to".

Beware when using a TBX that has notes with duplicate (same) Name values. As a set contains unique values, if several notes have identical names, then

MySet=links.inbound..Name

will list the distinct Names only once in MySet, and so the latter will have fewer values than the actual number of matching links.

Up: Set creation operators
Previous: collect_if() operator

[Last updated: 3 Dec 2008]

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]