links[(scope)].directionStr.[linkTypeRegex].attributeNameRefStr

Operator Type:

Operator Scope of Action:

Operator Purpose:

Data Type Returned:

Operator First Added:

Operator in Current Baseline:

Operator Last Altered:

Operator Uses Regular Expressions:

Operator Uses Scoped Arguments:

Operator Has Optional Arguments:

Function [other Function type actions]

Conditional Group [operators of similar scope]

Dictionary, Set & List operations [other Dictionary, Set & List operations operators]

List [about List data type]

v4.0.0

Baseline

As at baseline

[More on regular expressions in Tinderbox]

[More on scoped arguments in Action Code]

[More on optional operator arguments]

links[(scope)].directionStr.[linkTypeRegex].attributeNameStr

The links() operator builds a List from a collection of links. It selects the note(s) whose links should be inspected.

Note: although links() is not deprecated, Eastgate advise that for many existing uses of links(), employing eachLink() may provide better/easier control.

The scope is one or more items (defining scope), but note the scope argument is not fully evaluated, so only use simple expressions. scope never matches aliases. When using links() in the context of an agent's action, remember that aliases can have different basic links to their originals. Therefore, it is likely that act action using 'this' will want to replace it with 'original' as the scope when re-used in an agent action.

The mandatory directionStr argument filters the directionality of the links collected. It is mandatory, and should not be quoted. Note that links() can only test for one link direction at a time, i.e. in or out. The directionStr may or may not be in quotes but its value can only be either one of these two:

inbound
outbound

The optional linkTypeRegex argument is evaluated as a regular expression. Although the most normal usage will be as a literal string of a single link type name. Regex use allows for It collects only links of a specified link type, or such type(s) as match the linkTypeRegex regex amongst the link type names defined in the current TBX. Regular expression wild-card characters are permitted and retain their special meanings. If the linkTypeStr value contains white space or periods, it must be enclosed in double quotes:

links.outbound."responds to".$Name

If linkTypeRegex is left empty, links of all types are collected except prototype links. Prototype links are always omitted. Single quotes can be used to enclose linkTypeRegex 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 is evaluated for regex.

The attributeNameRefStr argument is the $-prefixed reference to 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, i.e. attributeNameRefStr is a literal value and cannot be an expression.

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 List 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.

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.

The links() function can be chained by dot operators pertinent to use with List type data. But, as links() uses dot-chained arguments, it is necessary to use parentheses to chain other dot operators. Thus, to get a count of the number of linked items found:

(links(children).inbound..$StartDate).size

In addition, the use of parentheses helps make sense of the intended order of execution of the tasks chained to links():

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