Regina Calculation Engine
Classes | Typedefs | Functions | Variables
File

Classes

class  regina::FileInfo
 Stores information about a Regina data file, including file type and version. More...
 
class  regina::GlobalDirs
 Provides global routines that return directories in which various components of Regina are installed on the system. More...
 
class  regina::XMLCallback
 Provides the callbacks for an XMLParser required to parse an entire file using a series of XMLElementReader objects. More...
 
class  regina::XMLElementReader
 Used to read the contents of a single XML element. More...
 
class  regina::XMLCharsReader
 A reader for an XML element that contains only characters. More...
 

Typedefs

typedef FileInfo regina::NFileInfo
 Deprecated typedef for backward compatibility. More...
 
typedef GlobalDirs regina::NGlobalDirs
 Deprecated typedef for backward compatibility. More...
 

Functions

const std::string & regina::FileInfo::pathname () const
 Returns the pathname of the data file being described. More...
 
int regina::FileInfo::type () const
 Returns the type of data file. More...
 
const std::string & regina::FileInfo::typeDescription () const
 Returns a human-readable description of the type of data file. More...
 
const std::string & regina::FileInfo::engine () const
 Returns the version of the calculation engine that wrote this file. More...
 
bool regina::FileInfo::isCompressed () const
 Returns whether this file is stored in compressed format. More...
 
bool regina::FileInfo::isInvalid () const
 Returns whether the file metadata could not be read. More...
 
static FileInforegina::FileInfo::identify (const std::string &idPathname)
 Return information about the given Regina data file. More...
 
void regina::FileInfo::writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
void regina::FileInfo::writeTextLong (std::ostream &out) const
 Writes a detailed text representation of this object to the given output stream. More...
 
static std::string regina::GlobalDirs::home ()
 Returns Regina's primary home directory on the system. More...
 
static std::string regina::GlobalDirs::pythonModule ()
 Returns the directory in which Regina's python module is installed, or the empty string if the module is installed in python's standard site-packages directory. More...
 
static std::string regina::GlobalDirs::census ()
 Returns the directory containing the large machine-encoded census data files. More...
 
static std::string regina::GlobalDirs::pythonLibs ()
 Returns the directory in which optional "helper" Python libraries are installed. More...
 
static std::string regina::GlobalDirs::examples ()
 Returns the directory in which example data files (including the smaller but human-browsable census data files) are installed. More...
 
static std::string regina::GlobalDirs::engineDocs ()
 Returns the directory in which API documentation for Regina's calculation engine is installed. More...
 
static std::string regina::GlobalDirs::data ()
 Returns the directory containing miscellaneous data files for internal use Regina's calculation engine. More...
 
static void regina::GlobalDirs::setDirs (const std::string &homeDir, const std::string &pythonModuleDir, const std::string &censusDir=std::string())
 Tells Regina where data files are installed. More...
 
 regina::XMLCallback::XMLCallback (XMLElementReader &newTopReader, std::ostream &newErrStream)
 Creates a new callback object. More...
 
virtual regina::XMLCallback::~XMLCallback ()
 Destroys this callback object. More...
 
int regina::XMLCallback::state () const
 Returns the state that this callback object is currently in. More...
 
void regina::XMLCallback::abort ()
 Aborts processing of the XML file completely. More...
 
virtual void regina::XMLCallback::start_document (regina::xml::XMLParser *parser)
 Called at the start of the document. More...
 
virtual void regina::XMLCallback::end_document ()
 Called when the document is finalised. More...
 
virtual void regina::XMLCallback::start_element (const std::string &n, const regina::xml::XMLPropertyDict &p)
 Called when an element's opening tag is encountered. More...
 
virtual void regina::XMLCallback::end_element (const std::string &n)
 Called when an element's closing tag is encountered. More...
 
virtual void regina::XMLCallback::characters (const std::string &s)
 Called when characters are encountered. More...
 
virtual void regina::XMLCallback::warning (const std::string &s)
 Called when a parser warning occurs. More...
 
virtual void regina::XMLCallback::error (const std::string &s)
 Called when a parser error occurs. More...
 
virtual void regina::XMLCallback::fatal_error (const std::string &s)
 Called when a parser fatal error occurs. More...
 
 regina::XMLElementReader::XMLElementReader ()
 Creates a new element reader. More...
 
virtual regina::XMLElementReader::~XMLElementReader ()
 Destroys this element reader. More...
 
virtual void regina::XMLElementReader::startElement (const std::string &tagName, const regina::xml::XMLPropertyDict &tagProps, XMLElementReader *parentReader)
 Signifies that parsing of this XML element is beginning. More...
 
virtual void regina::XMLElementReader::initialChars (const std::string &chars)
 Signifies that the initial text belonging to this XML element has been read. More...
 
virtual XMLElementReaderregina::XMLElementReader::startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
 Signifies that a subelement of this XML element is about to be parsed. More...
 
virtual void regina::XMLElementReader::endSubElement (const std::string &subTagName, XMLElementReader *subReader)
 Signifies that parsing has finished for a subelement of this XML element. More...
 
virtual void regina::XMLElementReader::endElement ()
 Signifies that parsing of this XML element is finished. More...
 
virtual void regina::XMLElementReader::usingParser (regina::xml::XMLParser *parser)
 Called for the top-level element in an XML file when parsing begins. More...
 
virtual void regina::XMLElementReader::abort (XMLElementReader *subReader)
 Signifies that XML parsing has been aborted. More...
 
 regina::XMLCharsReader::XMLCharsReader ()
 Creates a new XML element reader. More...
 
const std::string & regina::XMLCharsReader::chars ()
 Returns the characters stored in the XML element that has been read. More...
 
virtual void regina::XMLCharsReader::initialChars (const std::string &chars)
 Signifies that the initial text belonging to this XML element has been read. More...
 

Variables

static const int regina::FileInfo::TYPE_XML
 Represents a new-style XML data file. More...
 
static const int regina::XMLCallback::WAITING
 Signifies that the top-level XML element has not yet been seen. More...
 
static const int regina::XMLCallback::WORKING
 Signifies that XML elements are currently being processed. More...
 
static const int regina::XMLCallback::DONE
 Signifies that processing of all XML elements has finished. More...
 
static const int regina::XMLCallback::ABORTED
 Signifies that XML processing was aborted. More...
 

Detailed Description

Typedef Documentation

◆ NFileInfo

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NFileInfo has now been renamed to FileInfo.

◆ NGlobalDirs

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NGlobalDirs has now been renamed to GlobalDirs.

Function Documentation

◆ abort() [1/2]

void regina::XMLCallback::abort ( )

Aborts processing of the XML file completely.

The XMLParser may continue sending information but it will be completely ignored by this XMLCallback object from this point onwards.

All currently active readers will have XMLElementReader::abort() called upon them and all except for the top-level reader will be destroyed.

◆ abort() [2/2]

void regina::XMLElementReader::abort ( XMLElementReader subReader)
inlinevirtual

Signifies that XML parsing has been aborted.

This element reader will be destroyed shortly after this routine is called.

The default implementation does nothing.

Parameters
subReaderthe corresponding child reader if a subelement is currently being parsed, or 0 otherwise. If this parameter is non-zero, it is guaranteed that abort() has already been called upon the child reader and that the child reader has not yet been destroyed.

Reimplemented in regina::XMLPacketReader.

◆ census()

std::string regina::GlobalDirs::census ( )
inlinestatic

Returns the directory containing the large machine-encoded census data files.

These data files are not human-browsable: instead they are built for fast performance and small size. Users can access them by calling Census::lookup().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/data/census .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine data directory.

◆ characters()

virtual void regina::XMLCallback::characters ( const std::string &  s)
virtual

Called when characters are encountered.

Parameters
sthe characters encountered.

Reimplemented from regina::xml::XMLParserCallback.

◆ chars()

const std::string & regina::XMLCharsReader::chars ( )
inline

Returns the characters stored in the XML element that has been read.

Returns
the characters stored in the XML element.

◆ data()

std::string regina::GlobalDirs::data ( )
inlinestatic

Returns the directory containing miscellaneous data files for internal use Regina's calculation engine.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/data .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine data directory.

◆ end_document()

virtual void regina::XMLCallback::end_document ( )
virtual

Called when the document is finalised.

Reimplemented from regina::xml::XMLParserCallback.

◆ end_element()

virtual void regina::XMLCallback::end_element ( const std::string &  n)
virtual

Called when an element's closing tag is encountered.

This is called immediately after start_element() if the opening tag is in <tag/> format.

Parameters
nthe name of the tag.

Reimplemented from regina::xml::XMLParserCallback.

◆ endElement()

void regina::XMLElementReader::endElement ( )
inlinevirtual

Signifies that parsing of this XML element is finished.

It is guaranteed that endSubElement() has not yet been called upon the parent reader (if one exists).

The default implementation does nothing.

◆ endSubElement()

void regina::XMLElementReader::endSubElement ( const std::string &  subTagName,
XMLElementReader subReader 
)
inlinevirtual

Signifies that parsing has finished for a subelement of this XML element.

The default implementation does nothing.

Parameters
subTagNamethe name of the subelement closing tag.
subReaderthe child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >::GroupPresentationPropertyReader, regina::detail::XMLTriangulationReaderBase< dim >::AbelianGroupPropertyReader, regina::XMLPacketReader, and regina::XMLGroupPresentationReader.

◆ engine()

const std::string & regina::FileInfo::engine ( ) const
inline

Returns the version of the calculation engine that wrote this file.

Returns
the engine version for this file.

◆ engineDocs()

std::string regina::GlobalDirs::engineDocs ( )
inlinestatic

Returns the directory in which API documentation for Regina's calculation engine is installed.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/engine-docs .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine documentation directory.

◆ error()

virtual void regina::XMLCallback::error ( const std::string &  s)
virtual

Called when a parser error occurs.

Parameters
sthe error message.

Reimplemented from regina::xml::XMLParserCallback.

◆ examples()

std::string regina::GlobalDirs::examples ( )
inlinestatic

Returns the directory in which example data files (including the smaller but human-browsable census data files) are installed.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/examples .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's example and census data directory.

◆ fatal_error()

virtual void regina::XMLCallback::fatal_error ( const std::string &  s)
virtual

Called when a parser fatal error occurs.

Parameters
sthe error message.

Reimplemented from regina::xml::XMLParserCallback.

◆ home()

std::string regina::GlobalDirs::home ( )
inlinestatic

Returns Regina's primary home directory on the system.

This directory should contains subdirectories data, icons/, examples/ and so on.

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's primary home directory.

◆ identify()

static FileInfo* regina::FileInfo::identify ( const std::string &  idPathname)
static

Return information about the given Regina data file.

Internationalisation:\n This routine makes no assumptions about the
character encoding used in the given path name, and simply passes it through unchanged to low-level C/C++ file I/O routines. If a FileInfo structure is returned, its pathname() routine will use the same encoding that is passed here.
Parameters
idPathnamethe pathname of the data file to be examined.
Returns
a newly created FileInfo structure containing information about the given file, or 0 if the file type could not be identified.

◆ initialChars() [1/2]

void regina::XMLElementReader::initialChars ( const std::string &  chars)
inlinevirtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters
charsthe initial text for this element.

Reimplemented in regina::XMLCharsReader, regina::detail::XMLSimplexReader< dim >, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, regina::XMLAngleStructureReader, and regina::XMLAbelianGroupReader.

◆ initialChars() [2/2]

void regina::XMLCharsReader::initialChars ( const std::string &  chars)
inlinevirtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters
charsthe initial text for this element.

Reimplemented from regina::XMLElementReader.

◆ isCompressed()

bool regina::FileInfo::isCompressed ( ) const
inline

Returns whether this file is stored in compressed format.

Currently this option only applies to XML data files.

Returns
true if this file is compressed or false otherwise.

◆ isInvalid()

bool regina::FileInfo::isInvalid ( ) const
inline

Returns whether the file metadata could not be read.

Returns
true if the metadata could not be read, false otherwise.

◆ pathname()

const std::string & regina::FileInfo::pathname ( ) const
inline

Returns the pathname of the data file being described.

Internationalisation:\n The \ref i18n "character encoding" used in the pathname will
be whatever was originally passed to identify(). This might or might not be UTF-8, since it needs to be understood by the low-level C/C++ file I/O routines.
Returns
the pathname.

◆ pythonLibs()

std::string regina::GlobalDirs::pythonLibs ( )
inlinestatic

Returns the directory in which optional "helper" Python libraries are installed.

These libraries are not a formal part of Regina, but can be made to load automatically as extra user libraries through Regina's python settings.

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/pylib .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's optional Python library directory.

◆ pythonModule()

std::string regina::GlobalDirs::pythonModule ( )
inlinestatic

Returns the directory in which Regina's python module is installed, or the empty string if the module is installed in python's standard site-packages directory.

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's python module directory.

◆ setDirs()

static void regina::GlobalDirs::setDirs ( const std::string &  homeDir,
const std::string &  pythonModuleDir,
const std::string &  censusDir = std::string() 
)
static

Tells Regina where data files are installed.

You must call this at runtime if Regina is not installed in the location that was configured by cmake at build time (e.g., if you are running a MacOSX app bundle).

Empty strings are treated as follows:

  • If homeDir or censusDir is an empty string, then the corresponding directory will not be changed.
  • If pythonDir is an empty string then this has an explicit meaning, namely that the python module has been installed in python's standard site-packages directory.
Parameters
homeDirRegina's primary home directory; this will be returned by homeDir().
pythonModuleDirthe directory containing Regina's python module, or the empty string if the module has been installed in python's standard site-packages directory; this will be returned by pythonModule().
censusDirThe directory containing the large machine-encoded census data files; this will be returned by census().

◆ start_document()

virtual void regina::XMLCallback::start_document ( regina::xml::XMLParser parser)
virtual

Called at the start of the document.

Parameters
parserthe XML parser that is currently parsing this document.

Reimplemented from regina::xml::XMLParserCallback.

◆ start_element()

virtual void regina::XMLCallback::start_element ( const std::string &  n,
const regina::xml::XMLPropertyDict p 
)
virtual

Called when an element's opening tag is encountered.

Parameters
nthe name of the tag.
pa dictionary of all the properties of the tag.

Reimplemented from regina::xml::XMLParserCallback.

◆ startElement()

void regina::XMLElementReader::startElement ( const std::string &  tagName,
const regina::xml::XMLPropertyDict tagProps,
XMLElementReader parentReader 
)
inlinevirtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters
tagNamethe name of the opening tag for this element.
tagPropsthe properties associated with the opening tag.
parentReaderthe reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented in regina::XMLGroupPresentationReader, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, regina::XMLAngleStructureReader, regina::XMLAbelianGroupReader, regina::detail::XMLSimplicesReader< dim >, and regina::detail::XMLSimplexReader< dim >.

◆ startSubElement()

XMLElementReader * regina::XMLElementReader::startSubElement ( const std::string &  subTagName,
const regina::xml::XMLPropertyDict subTagProps 
)
inlinevirtual

Signifies that a subelement of this XML element is about to be parsed.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters
subTagNamethe name of the subelement opening tag.
subTagPropsthe properties associated with the subelement opening tag.
Returns
a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented in regina::XMLPacketReader, regina::XMLGroupPresentationReader, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, regina::XMLAngleStructureReader, regina::detail::XMLTriangulationReaderBase< dim >::GroupPresentationPropertyReader, regina::detail::XMLTriangulationReaderBase< dim >::AbelianGroupPropertyReader, and regina::detail::XMLSimplicesReader< dim >.

◆ state()

int regina::XMLCallback::state ( ) const
inline

Returns the state that this callback object is currently in.

The returned value will be one of the state constants defined in this class.

Returns
the current state of this callback object.

◆ type()

int regina::FileInfo::type ( ) const
inline

Returns the type of data file.

The type will be given as one of the file type constants defined in this class.

Returns
the type of data file.

◆ typeDescription()

const std::string & regina::FileInfo::typeDescription ( ) const
inline

Returns a human-readable description of the type of data file.

Returns
a description of the type of data file.

◆ usingParser()

void regina::XMLElementReader::usingParser ( regina::xml::XMLParser parser)
inlinevirtual

Called for the top-level element in an XML file when parsing begins.

This allows direct access to the parser if needed (for instance, to change the character encoding).

The default implementation does nothing.

Parameters
parserthe current XML parser.

◆ warning()

virtual void regina::XMLCallback::warning ( const std::string &  s)
virtual

Called when a parser warning occurs.

Parameters
sthe warning message.

Reimplemented from regina::xml::XMLParserCallback.

◆ writeTextLong()

void regina::FileInfo::writeTextLong ( std::ostream &  out) const

Writes a detailed text representation of this object to the given output stream.

Python:\n Not present.
Parameters
outthe output stream to which to write.

◆ writeTextShort()

void regina::FileInfo::writeTextShort ( std::ostream &  out) const

Writes a short text representation of this object to the given output stream.

Python:\n Not present.
Parameters
outthe output stream to which to write.

◆ XMLCallback()

regina::XMLCallback::XMLCallback ( XMLElementReader newTopReader,
std::ostream &  newErrStream 
)
inline

Creates a new callback object.

Parameters
newTopReaderthe element reader to use for the top-level XML element. This is the only element reader that will not be destroyed once parsing has finished.
newErrStreamthe output stream to which any warning or error messages should be sent.

◆ XMLCharsReader()

regina::XMLCharsReader::XMLCharsReader ( )
inline

Creates a new XML element reader.

◆ XMLElementReader()

regina::XMLElementReader::XMLElementReader ( )
inline

Creates a new element reader.

◆ ~XMLCallback()

virtual regina::XMLCallback::~XMLCallback ( )
virtual

Destroys this callback object.

Any element reader (aside from the top-level reader) that has not yet been destroyed will have abort() called upon it and will be destroyed at this point.

◆ ~XMLElementReader()

regina::XMLElementReader::~XMLElementReader ( )
inlinevirtual

Destroys this element reader.

The default implementation does nothing.

Variable Documentation

◆ ABORTED

const int regina::XMLCallback::ABORTED
static

Signifies that XML processing was aborted.

◆ DONE

const int regina::XMLCallback::DONE
static

Signifies that processing of all XML elements has finished.

◆ TYPE_XML

const int regina::FileInfo::TYPE_XML
static

Represents a new-style XML data file.

◆ WAITING

const int regina::XMLCallback::WAITING
static

Signifies that the top-level XML element has not yet been seen.

◆ WORKING

const int regina::XMLCallback::WORKING
static

Signifies that XML elements are currently being processed.


Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).