libNuML 1.1.1
Library for reading / writing NuML documents
NUMLReader Class Reference

The reader class implementing reading NuML documents from file / string. More...

#include <NUMLReader.h>

Public Member Functions

 NUMLReader ()
 Creates a new NUMLReader and returns it. More...
 
virtual ~NUMLReader ()
 Destroys this NUMLReader. More...
 
NUMLDocumentreadNUML (const std::string &filename)
 Reads an NUML document from a file. More...
 
NUMLDocumentreadNUMLFromFile (const std::string &filename)
 Reads an NUML document from a file. More...
 
NUMLDocumentreadNUMLFromString (const std::string &xml)
 Reads an NUML document from the given XML string. More...
 

Static Public Member Functions

static bool hasZlib ()
 Predicate returning true or false depending on whether libNUML is linked with zlib at compile time. More...
 
static bool hasBzip2 ()
 Predicate returning true or false depending on whether libNUML is linked with bzip2 at compile time. More...
 

Protected Member Functions

NUMLDocumentreadInternal (const char *content, bool isFile=true)
 Used by readNUML() and readNUMLFromString(). More...
 

Detailed Description

The reader class implementing reading NuML documents from file / string.

Constructor & Destructor Documentation

◆ NUMLReader()

LIBNUML_CPP_NAMESPACE_BEGIN NUMLReader::NUMLReader ( )

Creates a new NUMLReader and returns it.

◆ ~NUMLReader()

NUMLReader::~NUMLReader ( )
virtual

Destroys this NUMLReader.

Member Function Documentation

◆ hasBzip2()

bool NUMLReader::hasBzip2 ( )
static

Predicate returning true or false depending on whether libNUML is linked with bzip2 at compile time.

Predicate returning true or false depending on whether libNUML is linked with bzip2.

Returns
true if bzip2 is linked, false otherwise.
true if libNUML is linked with bzip2, false otherwise.

◆ hasZlib()

bool NUMLReader::hasZlib ( )
static

Predicate returning true or false depending on whether libNUML is linked with zlib at compile time.

Predicate returning true or false depending on whether libNUML is linked with zlib.

Returns
true if zlib is linked, false otherwise.
true if libNUML is linked with zlib, false otherwise.

◆ readInternal()

NUMLDocument * NUMLReader::readInternal ( const char *  content,
bool  isFile = true 
)
protected

Used by readNUML() and readNUMLFromString().

@docnote The native C++ implementation of this method defines a default argument value. In the documentation generated for different libNUML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libNUML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

TODO d->setModel(NULL);

◆ readNUML()

NUMLDocument * NUMLReader::readNUML ( const std::string &  filename)

Reads an NUML document from a file.

If the file named filename does not exist or its content is not valid NUML, one or more errors will be logged with the NUMLDocument object returned by this method. Callers can use the methods on NUMLDocument such as NUMLDocument::getNumErrors() and to get the errors. The object returned by is an NUMLError object, and it has methods to get the error code, category, and severity level of the problem, as well as a textual description of the problem. The possible severity levels range from informational messages to fatal errors; see the documentation for NUMLError for more information.

If the file filename could not be read, the file-reading error will appear first. The error code can provide a clue about what happened. For example, a file might be unreadable (either because it does not actually exist or because the user does not have the necessary access priviledges to read it) or some sort of file operation error may have bee reported by the underlying operating system. Callers can check for these situations using code such as the following:

NUMLReader* reader = new NUMLReader();
NUMLDocument* doc = reader.readNUML(filename);
if (doc->getNumErrors() > 0)
{
if (doc->getError(0)->getId() == XMLError::FileUnreadable)
{
// Handle case of unreadable file here.
}
else if (doc->getError(0)->getId() == XMLError::FileOperationError)
{
// Handle case of other file error here.
}
else
{
// Handle other cases -- see error codes defined in XMLErrorCode_t
// for other possible cases to check.
}
}
This represents the numl document that contains all information.
Definition: NUMLDocument.h:107
unsigned int getNumErrors() const
Returns the number of errors or warnings mencountered during parsing, consistency checking,...
Definition: NUMLDocument.cpp:525
const NUMLError * getError(unsigned int n) const
Returns the nth error or warning encountered during parsing, consistency checking,...
Definition: NUMLDocument.cpp:514
The reader class implementing reading NuML documents from file / string.
Definition: NUMLReader.h:45
NUMLReader()
Creates a new NUMLReader and returns it.
Definition: NUMLReader.cpp:36
NUMLDocument * readNUML(const std::string &filename)
Reads an NUML document from a file.
Definition: NUMLReader.cpp:82

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with ".zip" or ".bz2", the file is assumed to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest ignored.

Parameters
filenamethe name or full pathname of the file to be read.
Returns
a pointer to the NUMLDocument created from the NUML content.
See also
NUMLError
Note
LibNUML versions 2.x and 3.x behave differently in error handling in several respects. One difference is how early some errors are caught and whether libNUML continues processing a file in the face of some early errors. In general, libNUML 3.x stops parsing NUML inputs sooner than libNUML 2.x in the face of XML errors because the errors may invalidate any further NUML content. For example, a missing XML declaration at the beginning of the file was ignored by libNUML 2.x but in version 3.x, it will cause libNUML to stop parsing the rest of the input altogether. While this behavior may seem more severe and intolerant, it was necessary in order to provide uniform behavior regardless of which underlying XML parser (Expat, Xerces, libxml2) is being used by libNUML. The XML parsers themselves behave differently in their error reporting, and sometimes libNUML has to resort to the lowest common denominator.
To read a gzip/zip file, libNUML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libNUML.) Errors about unreadable files will be logged if a compressed filename is given and libNUML was not linked with the corresponding required library.
NUMLReader::hasZlib() and NUMLReader::hasBzip2() can be used to check whether libNUML has been linked with each library.

◆ readNUMLFromFile()

NUMLDocument * NUMLReader::readNUMLFromFile ( const std::string &  filename)

Reads an NUML document from a file.

If the file named filename does not exist or its content is not valid NUML, one or more errors will be logged with the NUMLDocument object returned by this method. Callers can use the methods on NUMLDocument such as NUMLDocument::getNumErrors() and to get the errors. The object returned by is an NUMLError object, and it has methods to get the error code, category, and severity level of the problem, as well as a textual description of the problem. The possible severity levels range from informational messages to fatal errors; see the documentation for NUMLError for more information.

If the file filename could not be read, the file-reading error will appear first. The error code can provide a clue about what happened. For example, a file might be unreadable (either because it does not actually exist or because the user does not have the necessary access priviledges to read it) or some sort of file operation error may have bee reported by the underlying operating system. Callers can check for these situations using code such as the following:

NUMLReader* reader = new NUMLReader();
NUMLDocument* doc = reader.readNUML(filename);
if (doc->getNumErrors() > 0)
{
if (doc->getError(0)->getId() == XMLError::FileUnreadable)
{
// Handle case of unreadable file here.
}
else if (doc->getError(0)->getId() == XMLError::FileOperationError)
{
// Handle case of other file error here.
}
else
{
// Handle other cases -- see error codes defined in XMLErrorCode_t
// for other possible cases to check.
}
}

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with ".zip" or ".bz2", the file is assumed to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest ignored.

Parameters
filenamethe name or full pathname of the file to be read.
Returns
a pointer to the NUMLDocument created from the NUML content.
See also
NUMLError
Note
LibNUML versions 2.x and 3.x behave differently in error handling in several respects. One difference is how early some errors are caught and whether libNUML continues processing a file in the face of some early errors. In general, libNUML 3.x stops parsing NUML inputs sooner than libNUML 2.x in the face of XML errors because the errors may invalidate any further NUML content. For example, a missing XML declaration at the beginning of the file was ignored by libNUML 2.x but in version 3.x, it will cause libNUML to stop parsing the rest of the input altogether. While this behavior may seem more severe and intolerant, it was necessary in order to provide uniform behavior regardless of which underlying XML parser (Expat, Xerces, libxml2) is being used by libNUML. The XML parsers themselves behave differently in their error reporting, and sometimes libNUML has to resort to the lowest common denominator.
To read a gzip/zip file, libNUML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libNUML.) Errors about unreadable files will be logged if a compressed filename is given and libNUML was not linked with the corresponding required library.
NUMLReader::hasZlib() and NUMLReader::hasBzip2() can be used to check whether libNUML has been linked with each library.

◆ readNUMLFromString()

NUMLDocument * NUMLReader::readNUMLFromString ( const std::string &  xml)

Reads an NUML document from the given XML string.

This method is flexible with respect to the presence of an XML declaration at the beginning of the string. In particular, if the string in xml does not begin with the XML declaration <?xml version='1.0' encoding='UTF-8'?>, then this method will automatically prepend the declaration to xml.

This method will log a fatal error if the content given in the parameter xml is not NUML. See the method documentation for for an example of code for testing the returned error code.

Parameters
xmla string containing a full NUML model
Returns
a pointer to the NUMLDocument created from the NUML content.

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