NEXUS CLASS LIBRARY: NxsReader Class

NEXUS CLASS LIBRARY | home | classes | functions

# Class NxsReader

## Enums

NxsTolerateFlags

## Data Members

blockList, currBlock

## Member Functions

Add, BlockListEmpty, DebugReportBlock, Detach, EnteringBlock, Execute, ExecuteStarting, ExecuteStopping, ExitingBlock, NCLCopyrightNotice, NCLHomePageURL, NCLNameAndVersion, NexusError, NxsReader, ~NxsReader, OutputComment, PositionInBlockList, Reassign, SkippingBlock, SkippingDisabledBlock

## Class Description

This is the class that orchestrates the reading of a NEXUS data file. An object of this class should be created, and objects of any block classes that are expected to be needed should be added to blockList using the Add member function. The Execute member function is then called, which reads the data file until encountering a block name, at which point the correct block is looked up in blockList and that object's Read method called.

### Key to symbols and colors

public, protected, private, `A` = abstract, `C` = constructor, `D` = destructor, `I` = inline, `S` = static, `V` = virtual, `F` = friend

Enums

`enum NxsTolerateFlags` |
| `allowMissingInEquate = 0x0001`
|  | if set, equate symbols are allowed for missing data symbol
| `allowPunctuationInNames = 0x0002`
|  | if set, some punctuation is allowed within tokens representing labels for taxa, characters, and sets

Data Members

|  | `NxsBlock` |  | `*blockList`
|  |  |  | pointer to first block in list of blocks
|  | `NxsBlock` |  | `*currBlock`
|  |  |  | pointer to current block in list of blocks

Member Functions

|  | `void` |  | `Add``(NxsBlock *newBlock)`
|  |  |  | Adds newBlock to the end of the list of NxsBlock objects growing from blockList. If blockList points to NULL, this function sets blockList to point to newBlock. Calls SetNexus method of newBlock to inform newBlock of the NxsReader object that now owns it. This is useful when the newBlock object needs to communicate with the outside world through the NxsReader object, such as when it issues progress reports as it is reading the contents of its block.
|  | `bool` |  | `BlockListEmpty``()`
|  |  |  | If blockList data member still equals NULL, returns true; otherwise, returns false. blockList will not be equal to NULL if the Add function has been called to add a block object to the list.
V |  | `void` |  | `DebugReportBlock``(NxsBlock &nexusBlock)`
|  |  |  | This function was created for purposes of debugging a new NxsBlock. This version does nothing; to create an active DebugReportBlock function, override this version in the derived class and call the Report function of nexusBlock. This function is called whenever the main NxsReader Execute function encounters the [&spillall] command comment between blocks in the data file. The Execute function goes through all blocks and passes them, in turn, to this DebugReportBlock function so that their contents are displayed. Placing the [&spillall] command comment between different versions of a block allows multiple blocks of the same type to be tested using one long data file. Say you are interested in testing whether the normal, transpose, and interleave format of a matrix can all be read correctly. If you put three versions of the block in the data file one after the other, the second one will wipe out the first, and the third one will wipe out the second, unless you have a way to report on each one before the next one is read. This function provides that ability.
|  | `void` |  | `Detach``(NxsBlock *oldBlock)`
|  |  |  | Detaches oldBlock from the list of NxsBlock objects growing from blockList. If blockList itself points to oldBlock, this function sets blockList to point to `oldBlock->next'. Note: the object pointed to by oldBlock is not deleted, it is simply detached from the linked list. No harm is done in Detaching a block pointer that has already been detached previously; if oldBlock is not found in the block list, Detach simply returns quietly. If oldBlock is found, its SetNexus object is called to set the NxsReader pointer to NULL, indicating that it is no longer owned by (i.e., attached to) a NxsReader object.
V |  | `bool` |  | `EnteringBlock``(NxsString blockName)`
|  |  |  | Called by the NxsReader object when a block named blockName is entered. Allows derived class overriding this function to notify user of progress in parsing the NEXUS file. Also gives program the opportunity to ask user if it is ok to purge data currently contained in this block. If user is asked whether existing data should be deleted, and the answer comes back no, then then the overrided function should return false, otherwise it should return true. This (base class) version always returns true.
|  | `void` |  | `Execute``(NxsToken &token, bool notifyStartStop)`
|  |  |  | Reads the NxsReader data file from the input stream provided by token. This function is responsible for reading through the name of a each block. Once it has read a block name, it searches blockList for a block object to handle reading the remainder of the block's contents. The block object is responsible for reading the END or ENDBLOCK command as well as the trailing semicolon. This function also handles reading comments that are outside of blocks, as well as the initial "#NEXUS" keyword. The notifyStartStop argument is provided in case you do not wish the ExecuteStart and ExecuteStop functions to be called. These functions are primarily used for creating and destroying a dialog box to show progress, and nested Execute calls can thus cause problems (e.g., a dialog box is destroyed when the inner Execute calls ExecuteStop and the outer Execute still expects the dialog box to be available). Specifying notifyStartStop false for all the nested Execute calls thus allows the outermost Execute call to control creation and destruction of the dialog box.
V |  | `void` |  | `ExecuteStarting``()`
|  |  |  | Called just after Execute member function reads the opening "#NEXUS" token in a NEXUS data file. Override this virtual base class function if your application needs to do anything at this point in the execution of a NEXUS data file (e.g. good opportunity to pop up a dialog box showing progress). Be sure to call the Execute function with the notifyStartStop argument set to true, otherwise ExecuteStarting will not be called.
V |  | `void` |  | `ExecuteStopping``()`
|  |  |  | Called when Execute member function encounters the end of the NEXUS data file, or the special comment [&LEAVE] is found between NEXUS blocks. Override this virtual base class function if your application needs to do anything at this point in the execution of a NEXUS data file (e.g. good opportunity to hide or destroy a dialog box showing progress). Be sure to call the Execute function with the notifyStartStop argument set to true, otherwise ExecuteStopping will not be called.
V |  | `void` |  | `ExitingBlock``(NxsString blockName)`
|  |  |  | Called by the NxsReader object when a block named blockName is being exited. Allows derived class overriding this function to notify user of progress in parsing the NEXUS file.
|  | `char` |  | `*NCLCopyrightNotice``()`
|  |  |  | Returns a string containing the copyright notice for the NxsReader Class Library, useful for reporting the use of this library by programs that interact with the user.
|  | `char` |  | `*NCLHomePageURL``()`
|  |  |  | Returns a string containing the URL for the NxsReader Class Library internet home page.
|  | `char` |  | `*NCLNameAndVersion``()`
|  |  |  | Returns a string containing the name and current version of the NxsReader Class Library, useful for reporting the use of this library by programs that interact with the user.
V |  | `void` |  | `NexusError``(NxsString msg, file_pos pos, long line, long col)`
|  |  |  | Called when an error is encountered in a NEXUS file. Allows program to give user details of the error as well as the precise location of the error.
C |  | `` |  | `NxsReader``()`
|  |  |  | Initializes both blockList and currBlock to NULL.
D |  | `` |  | `~NxsReader``()`
|  |  |  | Nothing to be done.
V |  | `void` |  | `OutputComment``(const NxsString &comment)`
|  |  |  | This function may be used to report progess while reading through a file. For example, the NxsAllelesBlock class uses this function to report the name of the population it is currently reading so the user doesn't think the program has hung on large data sets.
|  | `unsigned` |  | `PositionInBlockList``(NxsBlock *b)`
|  |  |  | Returns position (first block has position 0) of block b in blockList. Returns UINT_MAX if b cannot be found in blockList.
|  | `void` |  | `Reassign``(NxsBlock *oldb, NxsBlock *newb)`
|  |  |  | Reassign should be called if a block (oldb) is about to be deleted (perhaps to make way for new data). Create the new block (newb) before deleting oldb, then call Reassign to replace oldb in blockList with newb. Assumes oldb exists and is in blockList.
V |  | `void` |  | `SkippingBlock``(NxsString blockName)`
|  |  |  | This function is called when an unknown block named blockName is about to be skipped. Override this pure virtual function to provide an indication of progress as the NEXUS file is being read.
V |  | `void` |  | `SkippingDisabledBlock``(NxsString blockName)`
|  |  |  | This function is called when a disabled block named blockName is encountered in a NEXUS data file being executed. Override this pure virtual function to handle this event in an appropriate manner. For example, the program may wish to inform the user that a data block was encountered in what is supposed to be a tree file.