void NxsBlock::HandleLinkCommand ( NxsToken & token ) [virtual]

The LINK command was invented for use in Mesquite where multiple instances of a particular type of data-containing block are allowed.

The NEXUS specification does not discuss the correct behavior in such cases.

Some of the problems caused by failing to specify how multiple data-containing block should be handled can be avoided by explicitly linking blocks. For instance a CHARACTERS block may have a "LINK taxa=TaxaBlockTitle;" to indicate which block of taxa it uses.

The NxsBlock version merely raises a NxsUnimplementedException.

Before version 2.1 Links between blocks were "off" by default (see below) In version 2.1, the block scoping was made more robust, so the Link API was enabled for all factory-created blocks in the commonly-used PublicNexusReader. In 2.1 and greater it is safe to call SetImplementsLinkAPI(true) on any block (as far as we know).

LINK API in NCL version > 2.0.04 and < 2.1 NCL versions after 2.0.04 will support for LINK for the public blocks, but will have the functionality turned off by default (for backwards-compatibility). When turned-off, LINK commands will be skipped. Calling SetImplementsLinkAPI(true) on an instance will enable the use of the HandleLinkCommand() and WriteLinkCommand()

HandleLinkCommand should be a pure virtual function, but implementing it that way would break old code that uses NCL. Instead the ImplementsLinkAPI/SetImplementsLinkAPI mechanism was invented. NCL components will only call HandleLinkCommand() or WriteLinkCommand() if ImplementsLinkAPI() returns true. For backward compatibility default all blocks have linkAPI=false.

Client code should always call ImplementsLinkAPI() to check whether HandleLinkCommand() or WriteLinkCommand() are available. Failure to do this may result in NxsUnimplementedException() being called.

Reimplemented in NxsAssumptionsBlock, NxsCharactersBlock, NxsDistancesBlock, NxsTreesBlock, and NxsUnalignedBlock.

Definition at line 249 of file nxsblock.cpp.