This version is out of date, covering development from v5.0.0 to v5.12.2. It is maintained here only for inbound reference links from elsewhere.

Jump to the current version of aTbRef.

Tinderbox Icon

links[(item|group)].kind.[linkType].attribute


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Altered: 

 Function   [other Function type actions]

 Conditional Group   [operators of similar scope]

 Set & List creation   [other Set & List creation operators]

 Already in v5.0.0

 5.6.05.8.05.9.0


The links() operator builds a List from a collection of links. Prior to v5.8.0, a set was created.

links[(item|group)].kind.[linkType].$Attribute

selects the note whose links that should be inspected. From v5.9.0 the scope - i.e. what's looked at - can be single note (item) or one-or-more items (group); prior to this scope was single item only. From v5.10.0, text links are listed in anchor order (i.e. as ordered in $Text); prior to this the output was usually the same but was in fact arbitrary. The optional item|group argument may be:

N.B. The item|group argument is not fully evaluated - only use simple expressions.

Aliases can never the target of item|group, even by use of paths.

The kind argument filters the directionality of the links collected. It is mandatory, and should not be quoted. It can only be is one of these values:

The optional linkType argument is a regular expression pattern. It collects only links of a specified link type, or such type(s) as match the linkType pattern amongst the link type names defined in the current TBX. 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 double 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. From v5.10.1, single quotes can be used to enclose linkType but if the quoted string includes a single quote this must be backslash-escaped or double quote used instead:

links.outbound."Peter's place".$Name OK

links.outbound.'Peter's place'.$Name wrong

links.outbound.'Peter\'s place'.$Name OK

The attribute argument is the name of the attribute whose values are to be collected in the result. An attribute reference, e.g. $Name("nextSibling") is invalid - the command work but the reference is ignored and the stated attribute for the linked note is used.

If simply wishing to test the state of links between two items, consider the Boolean queries linkedFrom() and linkedTo().

Examples

$MyList=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'. This does the same but for all link types;

$MyList=links(/config).outbound..$Name 

For multi-word link type names use quotes (or if using regex characters):

$MyList=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:

$MyList=links.inbound."went to".$SchoolName 

collects a list of values of the attribute 'SchoolName' for notes that have an inbound link to the current note of link 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. In the same scenario:

$MyList=links.inbound..$Name 

will create a list containing duplicates.

When using links() in the context of an agent's action, remember that aliases can have different links to originals. Therefore, it likely you will want to use 'original' as the note item for the call.

The format() or List.format() operators can help make more use of links() data during export, e.g. as lists or lists of links. Internally, if analysing links and there is no real need to keep set-type data, using agents employing linkedTo() and linkedFrom() will find most of the same data as links() can provide.

From v5.8.0, links can be chained by dot operators pertinent to lists For instance:

$MyList=links.inbound..$Name.contains("Farnsworth") 

If desired the chaining can be done to a set of parentheses - this can sometimes help make sense of the intended order of execution of the tasks:

$MyList=(links.inbound."colleague of".$Name).sort("$StartDate") 

More examples of links() syntax:

links.outbound.agree.$Name 

links(this).outbound.agree.$Name 

links(children).inbound..$StartDate 

links("A note").outbound."example|agree".$Name 

links("A note;A different note").inbound."*untitled".$Path 

links($MyString).outbound..$TutorName 

links(find(descendedFrom("Some note")).inbound.my_link.$SomeAttribute 

links(find(descendedFrom("Some note")&$MyDate==$StartDate).outbound..$Width 

links($MySet).outbound.example.$Name 

links($MyList).inbound.note.$WordCount 


Possible relevant notes (via "Similar Notes" feature):


A Tinderbox Reference File : Actions & Rules : Operators : Action Operator Functional Types : Function actions : links[(item|group)].kind.[linkType].attribute