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:

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

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);

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:

 All Classes Functions Variables Enumerations Enumerator Friends
Generated on Mon Mar 29 16:37:12 2010 for NCL by  doxygen 1.6.3