NxsReader Class Reference

This is the class that orchestrates the reading of a NEXUS data file, and so is the central class to NCL. More...

#include <nxsreader.h>

List of all members.

Public Types
enum	WarningHandlingMode { IGNORE_WARNINGS, WARNINGS_TO_STDERR, WARNINGS_TO_STDOUT, WARNINGS_ARE_ERRORS }
enum	NxsWarnLevel {   UNCOMMON_SYNTAX_WARNING = 0, SKIPPING_CONTENT_WARNING = 1, OVERWRITING_CONTENT_WARNING = 2, DEPRECATED_WARNING = 3,   AMBIGUOUS_CONTENT_WARNING = 4, ILLEGAL_CONTENT_WARNING = 5, PROBABLY_INCORRECT_CONTENT_WARNING = 6, FATAL_WARNING = 7,   SUPPRESS_WARNINGS_LEVEL = 8 }
Public Member Functions
	NxsReader ()
virtual void	Add (NxsBlock *newBlock)
void	Detach (NxsBlock *newBlock)
virtual void	AddFactory (NxsBlockFactory *)
void	RemoveFactory (NxsBlockFactory *)
virtual void	Execute (NxsToken &token, bool notifyStartStop=true)
void	ReadFilepath (const char *filename)
void	ReadFilestream (std::istream &inf)
void	ReadStringAsNexusContent (const std::string &s)
virtual void	DebugReportBlock (NxsBlock &nexusBlock)
const char *	NCLNameAndVersion ()
const char *	NCLCopyrightNotice ()
const char *	NCLHomePageURL ()
virtual void	ExecuteStarting ()
virtual void	ExecuteStopping ()
virtual bool	EnteringBlock (NxsString blockName)
virtual void	ExitingBlock (NxsString blockName)
virtual void	OutputComment (const NxsString &comment)
virtual void	SkippingDisabledBlock (NxsString blockName)
virtual void	SkippingBlock (NxsString blockName)
virtual void	NexusWarn (const std::string &s, NxsWarnLevel warnLevel, file_pos pos, long line, long col)
void	NexusWarnToken (const std::string &m, NxsWarnLevel warnLevel, const ProcessedNxsToken &token)
void	NexusWarnToken (const std::string &m, NxsWarnLevel warnLevel, const NxsToken &token)
virtual void	NexusError (NxsString msg, file_pos pos, long line, long col)
virtual void	ClearUsedBlockList ()
NxsBlock *	CreateBlockFromFactories (const std::string &currBlockName, NxsToken &token, NxsBlockFactory **sourceOfBlock=NULL)
BlockReaderList	GetUsedBlocksInOrder ()
BlockReaderList	GetBlocksFromLastExecuteInOrder ()
BlockTypeToBlockList	GetUsedBlocks ()
std::set< NxsBlock * >	GetSetOfAllUsedBlocks ()
NxsTaxaBlockAPI *	GetLastStoredTaxaBlock ()
NxsCharactersBlockAPI *	GetLastStoredCharactersBlock ()
NxsTreesBlockAPI *	GetLastStoredTreesBlock ()
NxsTaxaBlockAPI *	GetTaxaBlockByTitle (const char *title, unsigned *nMatches)
NxsCharactersBlockAPI *	GetCharBlockByTitle (const char *title, unsigned *nMatches)
NxsTreesBlockAPI *	GetTreesBlockByTitle (const char *title, unsigned *nMatches)
NxsTaxaBlockFactory *	GetTaxaBlockFactory ()
void	SetTaxaBlockFactory (NxsTaxaBlockFactory *)
virtual void	DeleteBlocksFromFactories ()
unsigned	RemoveBlockFromUsedBlockList (NxsBlock *)
virtual void	ClearContent ()
virtual void	AddReadBlock (const NxsString &blockID, NxsBlock *block)
void	cullIdenticalTaxaBlocks (bool v=true)
std::vector< std::string >	GetAllTitlesForBlock (const NxsBlock *b) const
void	SetAlwaysReportStatusMessages (bool v)
void	SetWarningOutputLevel (NxsWarnLevel lev)
virtual void	statusMessage (const std::string &m) const
bool	BlockListEmpty ()
unsigned	PositionInBlockList (NxsBlock *b)
void	Reassign (NxsBlock *oldb, NxsBlock *newb)
void	AssignBlockPriority (NxsBlock *b, int priorityLevel)
int	GetBlockPriority (NxsBlock *b) const
void	DemoteBlocks (int priorityLevel=-1)
Static Public Member Functions
static void	setNCLCatchesSignals (bool)
static bool	getNCLCatchesSignals ()
static unsigned	getNumSignalIntsCaught ()
static void	setNumSignalsIntsCaught (unsigned)
Protected Member Functions
void	CoreExecutionTasks (NxsToken &token, bool notifyStartStop=true)
void	AddBlockToUsedBlockList (const std::string &, NxsBlock *, NxsToken *)
bool	BlockIsASingeltonReader (NxsBlock *) const
void	BlockReadHook (const NxsString &currBlockName, NxsBlock *currBlock, NxsToken *token=NULL)
bool	ExecuteBlock (NxsToken &token, const NxsString &currBlockName, NxsBlock *currBlock, NxsBlockFactory *sourceOfBlock)
NxsBlock *	FindBlockOfTypeByTitle (const std::string &btype, const char *title, unsigned *nMatches)
NxsBlock *	FindBlockByTitle (const BlockReaderList &chosenBlockList, const char *title, unsigned *nMatches)
NxsBlock *	GetLastStoredBlockByID (const std::string &key)
NxsTaxaBlockAPI *	GetOriginalTaxaBlock (const NxsTaxaBlockAPI *) const
bool	IsRepeatedTaxaBlock (const NxsTaxaBlockAPI *) const
void	NewBlockTitleCheckHook (const std::string &blockname, NxsBlock *p, NxsToken *token)
bool	ReadUntilEndblock (NxsToken &token, const std::string &currBlockName)
void	RegisterAltTitle (const NxsBlock *b, std::string t)
std::set< NxsBlock * >	RemoveBlocksFromFactoriesFromUsedBlockLists ()
virtual void	PostBlockReadingHook (NxsBlock &)
Static Protected Member Functions
static BlockReaderList	parseFileWithReader (NxsReader &reader, const char *filepath, bool parsePrivateBlocks=true, bool storeTokenInfo=true)

---

Detailed Description

This is the class that orchestrates the reading of a NEXUS data file, and so is the central class to NCL.

NxsReader does not call delete on any of the blocks that are added to it via the Add method.

In the "classic" (v2.0) NCL API:

1. An NxsReader is created.
2. pointers to instances of NxsBlocks that are expected to be needed should be added to `blockList' using the NxsReader::Add() member function.
3. NxsReader::Execute() 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 NxsBlock::Read() method is called.
4. NxsReader::PostBlockReadingHook(NxsBlock) is called after a block is successfully read. This allows one to gather the parsed data from the NxsBlock. If another block of the same type is encountered, then NxsBlock::Reset() will be called and the same NxsBlock instance will be used to read the next block.

Versions of NCL after 2.0.04 also support a "factory API" augments the former behavior:

1. An NxsReader is created.
2. In addition to NxsBlocks added using the Add method, you can register instances of a NxsBlockFactory using the NxsReader::AddFactory() method.
3. In the NxsReader::Execute() method, if an appropriate block is not found in the `blockList` then the the factories are asked to create a block for the current block name. The first non-NULL block pointer returned is used.
4. PostBlockReadingHook is still called, but blocks created by a factory will not be "recycled" later in the NxsReader::Execute(), so it is not necessary to pull all of the data out of them. -If a block created by a factory is skipped or has an error, then the factory will be notified using NxsBlockFactory::BlockError(NxsBlock *) or NxsBlockFactory::BlockSkipped(NxsBlock *). In the event of skipping or an error, NxsReader will never refer to that instance of the factory-created block again. Hence the base class behavior of BlockError() and BlockSkipped() is to delete the instance.
5. Every time a NxsBlock successfully reads a NEXUS block, the NxsBlock is added to container of "used" blocks. When a block is Reset() it is removed from this container. NxsReader::GetUsedBlocks() can be called at any point to get a copy of this container (which maps a block type name to a list of NxsBlock*). This container thus stores the state of the parsed NEXUS file. If no blocks were recycled (if all of the blocks came from factories rather than blocks added using NxsReader::Add() method), then the GetUsedBlocks will contain binary representation of every block parsed.

Important: The use of the factories that are supplied with NCL can trigger casts of pointers. This can be unsafe if you create NxsBlocks that do not have the expected inheritance. For example, if you create a class to read Taxa blocks, but do NOT derive this class from NxsTaxaBlockAPI then the casts will be unsafe. If you do this, and you wish to use the factory API then you must write your own factories.

See NCL_TOP/examples/normalizer examples for an example of the factory API (using the MultiFormatReader). In those examples the PublicNexusReader::PublicNexusReader() constructor is the function that installs the templates for a clone factory.

Errors in NEXUS files

When an illegal construct is found, a NxsException is raised. This exception is caught within NxsReader::Execute and NxsReader::NexusError is called. This allows subclasses of NxsReader to handle exceptional circumstances by overriding one function. Whenever you are using a NxsReader instance that is NOT a subclass of ExceptionRaisingNxsReader this is still the behavior (thus any code that was written to the v2.0 API will still have this behavior).

ExceptionRaisingNxsReader implements NexusError by raising another NxsException. This results in the exception being propagated to the caller. The newer NxsReader classes (including PublicNexusReader and MultiFormatReader) are derived from ExceptionRaisingNxsReader. So their Execute methods will also raise NxsExceptions. Deriving a subclass of these classes and overriding NexusError would prevent this behavior.

The advantage of ExceptionRaisingNxsReader is that one is no longer required to subclass NxsReader to handle errors.

Signal Handling in NCL:

Traditionally, the user of an application can send an SIGINT to cause it to stop. NCL has very limited support for handling signals, and this support is turned off by default.

If you want NCL to raise an NxsSignalCanceledParseException if a signal is encountered during a parse then call: NxsReader::setNCLCatchesSignals(true); before calling Execute on your NxsReader instance. Note that only the slowly-parsed blocks (TREES and CHARACTERS) and the NxsReader currently check to see if a signal has been caught. So the NxsSignalCanceledParseException will often have a generic message indicating that the signal was caught during the parse.

The NCL signal handler is only installed during NxsReader::Execute calls!

Note: that if you want your program to exit on SIGINT, you can leave the signal handling turned off. If you do turn NCL's signal handling on, then after you do your apps clean up you'll have to exit by something like this: signal(SIGINT, SIG_DFL); kill(getpid(), SIGINT);

See also:

http://www.cons.org/cracauer/sigint.html

Definition at line 118 of file nxsreader.h.

---

The documentation for this class was generated from the following files:

• nxsreader.h
• nxspublicblocks.cpp
• nxsreader.cpp