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

Methods for writing NUML to files and text strings. More...

#include <NUMLWriter.h>

Public Member Functions

 NUMLWriter ()
 Creates a new NUMLWriter. More...
 
 ~NUMLWriter ()
 Destroys this NUMLWriter. More...
 
int setProgramName (const std::string &name)
 
int setProgramVersion (const std::string &version)
 
bool writeNUML (const NUMLDocument *d, const std::string &filename)
 Writes the given NUML document to filename. More...
 
bool writeNUML (const NUMLDocument *d, std::ostream &stream)
 Writes the given NUML document to the output stream. More...
 
char * writeToString (const NUMLDocument *d)
 Writes the given NUML document to an in-memory string and returns a pointer to it. More...
 

Static Public Member Functions

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

Protected Attributes

std::string mProgramName
 
std::string mProgramVersion
 

Detailed Description

Methods for writing NUML to files and text strings.

The NUMLWriter class is the converse of NUMLReader, and provides the main interface for serializing NUML models into XML and writing the result to files and text strings. The methods for writing NUML all take an NUMLDocument object and a destination. They return a boolean value to indicate success or failure.

Constructor & Destructor Documentation

◆ NUMLWriter()

LIBNUML_CPP_NAMESPACE_BEGIN NUMLWriter::NUMLWriter ( )

Creates a new NUMLWriter.

◆ ~NUMLWriter()

NUMLWriter::~NUMLWriter ( )

Destroys this NUMLWriter.

Member Function Documentation

◆ hasBzip2()

bool NUMLWriter::hasBzip2 ( )
static

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

LibNUML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libNUML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libNUML it is running.

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

◆ hasZlib()

bool NUMLWriter::hasZlib ( )
static

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

LibNUML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libNUML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libNUML it is running.

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

◆ setProgramName()

int NUMLWriter::setProgramName ( const std::string &  name)
 Sets the name of this program, i.e., the program that is about to
 write out the NUMLDocument.

 If the program name and version are set (setProgramVersion()), the
 following XML comment, intended for human consumption, will be written
 at the beginning of the document:
 @verbatim
 @param name the name of this program (where "this program" refers to
 program in which libNUML is embedded, not libNUML itself!)

 @return integer value indicating success/failure of the
 function.  @if clike The value is drawn from the
 enumeration #OperationReturnValues_t. @endif The possible values
 returned by this function are:
 @li LIBNUML_OPERATION_SUCCESS

 @see setProgramVersion(const std::string& version)

◆ setProgramVersion()

int NUMLWriter::setProgramVersion ( const std::string &  version)
 Sets the version of this program, i.e., the program that is about to
 write out the NUMLDocument.

 If the program version and name are set (setProgramName()), the
 following XML comment, intended for human consumption, will be written
 at the beginning of the document:
 @verbatim
 @param version the version of this program (where "this program"
 refers to program in which libNUML is embedded, not libNUML itself!)

 @return integer value indicating success/failure of the
 function.  @if clike The value is drawn from the
 enumeration #OperationReturnValues_t. @endif The possible values
 returned by this function are:
 @li LIBNUML_OPERATION_SUCCESS

 @see setProgramName(const std::string& name)

◆ writeNUML() [1/2]

bool NUMLWriter::writeNUML ( const NUMLDocument d,
const std::string &  filename 
)

Writes the given NUML document to filename.

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), libNUML assumes the caller wants the file to be written compressed in gzip. Similarly, if the given filename ends with ".zip" or ".bz2", libNUML assumes the caller wants the file to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be written uncompressed. Special considerations for the zip format: If the given filename ends with ".zip", the file placed in the zip archive will have the suffix ".xml" or ".numl". For example, the file in the zip archive will be named "test.xml" if the given filename is "test.xml.zip" or "test.zip". Similarly, the filename in the archive will be "test.numl" if the given filename is "test.numl.zip".

Note
To write 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 write files in bzip2 format. (Both of these are the default configurations for libNUML.) Errors about unreadable files will be logged and this method will return false 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.
Parameters
dthe NUML document to be written
filenamethe name or full pathname of the file where the NUML is to be written.
Returns
true on success and false if the filename could not be opened for writing.

◆ writeNUML() [2/2]

bool NUMLWriter::writeNUML ( const NUMLDocument d,
std::ostream &  stream 
)

Writes the given NUML document to the output stream.

Parameters
dthe NUML document to be written
streamthe stream object where the NUML is to be written.
Returns
true on success and false if one of the underlying parser components fail (rare).
true on success and false if one of the underlying parser components fail (rare).

◆ writeToString()

LIBNUML_EXTERN char * NUMLWriter::writeToString ( const NUMLDocument d)

Writes the given NUML document to an in-memory string and returns a pointer to it.

The string is owned by the caller and should be freed (with free()) when no longer needed.

Parameters
dthe NUML document to be written
Returns
the string on success and 0 if one of the underlying parser components fail.

Member Data Documentation

◆ mProgramName

std::string NUMLWriter::mProgramName
protected

◆ mProgramVersion

std::string NUMLWriter::mProgramVersion
protected

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