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 FileInfo * | regina::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 XMLElementReader * | regina::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

typedef FileInfo regina::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

typedef GlobalDirs regina::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 | ) |

inline virtual

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

  subReader | the 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 | ( |  | ) |

inline static

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

  s | the 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 | ( |  | ) |

inline static

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

  n | the name of the tag.

Reimplemented from regina::xml::XMLParserCallback.

## endElement()

void regina::XMLElementReader::endElement | ( |  | ) |

inline virtual

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

inline virtual

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

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the 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 | ( |  | ) |

inline static

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

  s | the error message.

Reimplemented from regina::xml::XMLParserCallback.

## examples()

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

inline static

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

  s | the error message.

Reimplemented from regina::xml::XMLParserCallback.

## home()

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

inline static

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

  idPathname | the 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 | ) |

inline virtual

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

  chars | the 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 | ) |

inline virtual

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

  chars | the 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 | ( |  | ) |

inline static

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

inline static

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

  homeDir | Regina's primary home directory; this will be returned by homeDir().
  pythonModuleDir | the 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().
  censusDir | The 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

  parser | the 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

  n | the name of the tag.
  p | a 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
| ) |  |

inline virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters

  tagName | the name of the opening tag for this element.
  tagProps | the properties associated with the opening tag.
  parentReader | the 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
| ) |  |

inline virtual

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

  subTagName | the name of the subelement opening tag.
  subTagProps | the 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 | ) |

inline virtual

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

  parser | the current XML parser.

## warning()

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

virtual

Called when a parser warning occurs.

Parameters

  s | the 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

  out | the 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

  out | the output stream to which to write.

## XMLCallback()

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

inline

Creates a new callback object.

Parameters

  newTopReader | the 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.
  newErrStream | the 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 | ( |  | ) |

inline virtual

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