shelf-type? shelf-name (^ | key) string-expression

The key operator is used to select the item on a shelf that has the specified key. The keyword ^ can be used as a synonym for the key operator.

This construct can be more powerful than numeric indexing with the item operator, because it allows associating an arbitrary string value with each item on the shelf. The keys can be composed from dynamic values, and there is no effective limit on their length.

An item on a shelf can be assigned a key by the actions new, set new, and set key. Just as each item on a shelf has a unique positional index, every key on a shelf must be unique. The has key operator can be used to guarantee this.

Key-based selection is a good method of setting up an association list. In a stream shelf, each item can be bound to a buffer which is set to some value. When each item is created, it can be given a key that is related to the value according to some function. Association lists can also be used with counters and streams.

  global stream toc variable
  ...
  do when toc has key "title-3"
     remove toc key "title-3"
  done