The Basics of the NCL API

The core API has not changed from version 2.0 to 2.1.

NCL parses an std::istream by creating a NxsToken object around the stream (a better name for the class would be NxsTokenizer). Rather than using a low-level C++ istream operations, the NxsToken allows you to process a file by the NEXUS tokenizing rules - comments are skipped and NEXUS's quoting rules are obeyed.

A NxsReader instance is capable of reading an entire stream (usually a file) by interacting with the NxsToken until EOF is reached. The NxsReader's job is to identify the blocks in a file, and hand off the procesing of each block to an appropriate block reader (or skip the block if no reader is found).

The objects that read each block are instances of NxsBlock (perhaps a better name for this class would be NxsBlockReader). After the NxsReader chooses which block should handle a portion of NEXUS file, it will call the NxsBlock::Read function and pass in the NxsToken object which is poised to return tokens for the block that is to be read next.

Client code uses NCL by:

creating a NxsReader object,
registering the NxsBlock objects that will process all of the NEXUS blocks that are not to be skipped,
create a NxsToken object around the istream to be read,
calling the Execute(NxsToken) method of the reader, and
retrieving the parsed information from the NxsBlocks In version 2.0 of the API, the client would have to retrieve the information from NxsBlock in hooks (such as NxsBlock::ExitingBlock) during the parse.

The main extensions to this basic structure that are new to version 2.1 are

The ability to register NxsBlock factories rather than NxsBlocks (this enables parsing of the entire file, rather than requiring the client to harvest all of the information via hooks called during the parse);
public blocks have been extended to deal with the TITLE and LINK commands introduced by Mesquite;
other formats can be parsed by a special version of the NxsReader called a MultiFormatReader;
various extensions to individual blocks (such as full implementation of ASSUMPTIONS block, and the addition of MrBayes' "Datatype=Mixed..." subcommand in the Characters block's FORMAT command;
"implied" blocks are now created during some parses

Simplest example of reading

The simplest (and admittedly least useful) NCL client that uses the version 2.1 API would be the following fragment:

#include "ncl/nxsmultiformat.h"

int main(int argc, char * argv[])
{
MultiFormatReader nexusReader(-1, NxsReader::WARNINGS_TO_STDERR);
try {
    nexusReader.ReadFilepath(argv[1], MultiFormatReader::NEXUS_FORMAT);
    }
catch(...)
    {
    nexusReader.DeleteBlocksFromFactories();
    throw;
    }
nexusReader.DeleteBlocksFromFactories();

return 0;
}

If you were to save this file as "simpleNCLClient.cpp" and save this Makefile in the same directory then you could build the client. You would also need to specify the location of your NCL installation (see notes in the Makefile about NCL_INSTALL_DIR)

Reading non-NEXUS file formats

Despite the name "Nexus Class Library" NCL will actually read other file formats. NCL does not diagnose file format type. However, if you have data in PHYLIP, relaxed FASTA, ALN format or trees in Newick file then you can ask the MultiFormatReader to parse these files by passing in the appropriate MultiFormatReader::DataFormatType or format name (see the MultiFormatReader::getFormatNames() method).

NCL actually coerces inforamation from these sources into NxsTaxaBlock, NxsCharactersBlocks..., so the user of library does not have to change the code associated with querying NCL for information in order to support these formats.

Support for PhyloXML and nexml are planned.

Next see Getting information out of NCL for information on getting parsed information out of NCL.

Brief Directory: