#include <balxml_decoder.h>

Detailed Description

Engine for decoding value-semantic objects in XML format. The decode methods are function templates that will decode any object that meets the requirements of a sequence or choice object as defined in the bdlat_sequencefunctions and bdlat_choicefunctions components. These generic frameworks provide a common compile-time interface for manipulating struct-like and union-like objects.

See balxml_decoder

Classes
struct	CustomizedManipulator

Public Member Functions
	Decoder (const DecoderOptions options, Reader reader, ErrorInfo errInfo, bslma::Allocator basicAllocator)

	Decoder (const DecoderOptions options, Reader reader, ErrorInfo errInfo=0, bsl::ostream errorStream=0, bsl::ostream warningStream=0, bslma::Allocator basicAllocator=0)

	~Decoder ()

void	close ()

int	open (bsl::istream &stream, const char *uri=0)

int	open (bsl::streambuf buffer, const char uri=0)

int	open (const char buffer, bsl::size_t length, const char uri=0)

int	open (const char *filename)

template<class TYPE >
bsl::istream &	decode (bsl::istream &stream, TYPE object, const char uri=0)

template<class TYPE >
int	decode (bsl::streambuf buffer, TYPE object, const char *uri=0)

template<class TYPE >
int	decode (const char buffer, bsl::size_t length, TYPE object, const char *uri=0)

template<class TYPE >
int	decode (const char filename, TYPE object)

template<class TYPE >
int	decode (TYPE *object)

template<class TYPE >
bsl::istream &	decodeAny (bsl::istream &stream, TYPE object, const char uri=0)

bsl::istream &	decodeAny (bsl::istream &stream, bdlar::AnyRef object, const char uri=0)

template<class TYPE >
int	decodeAny (bsl::streambuf buffer, TYPE object, const char *uri=0)

int	decodeAny (bsl::streambuf buffer, bdlar::AnyRef object, const char *uri=0)

template<class TYPE >
int	decodeAny (TYPE *object)

int	decodeAny (bdlar::AnyRef *object)

void	setNumUnknownElementsSkipped (int value)

const DecoderOptions *	options () const

Reader *	reader () const

ErrorInfo *	errorInfo () const

bsl::ostream *	errorStream () const

bsl::ostream *	warningStream () const

int	numUnknownElementsSkipped () const

ErrorInfo::Severity	errorSeverity () const

bslstl::StringRef	loggedMessages () const

int	errorCount () const

int	warningCount () const

Friends
class	Decoder_ElementContext

struct	Decoder_decodeImpProxy

class	Decoder_ErrorLogger

class	Decoder_ParseObject

Constructor & Destructor Documentation

◆ Decoder() [1/2]

balxml::Decoder::Decoder	(	const DecoderOptions *	options,
		Reader *	reader,
		ErrorInfo *	errInfo,
		bslma::Allocator *	basicAllocator
	)

◆ Decoder() [2/2]

balxml::Decoder::Decoder	(	const DecoderOptions *	options,
		Reader *	reader,
		ErrorInfo *	errInfo = `0`,
		bsl::ostream *	errorStream = `0`,
		bsl::ostream *	warningStream = `0`,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a decoder object using the specified options and the specified reader to perform the XML-level parsing. If the (optionally) specified errorInfo is non-null, it is used to store information about most serious error encountered during parsing. During parsing, error and warning messages will be written to the (optionally) specified errorStream and warningStream respectively.

Precondition: The behavior is undefined unless options and reader are both non-zero. The behavior becomes undefined if the objects pointed to by any of the arguments is destroyed before this object has completed parsing.

◆ ~Decoder()

balxml::Decoder::~Decoder ( )

Call close and destroy this object.

Member Function Documentation

◆ close()

void balxml::Decoder::close ( )

Put the associated Reader object (i.e., the reader specified at construction) into a closed state.

◆ decode() [1/5]

template<class TYPE >

bsl::istream & balxml::Decoder::decode	(	bsl::istream &	stream,
		TYPE *	object,
		const char *	uri = `0`
	)

Decode the specified object of parameterized TYPE from the specified input stream. Return a reference to the modifiable stream. If a decoding error is detected, stream.fail() will be true after this method returns. The (optionally) specified uri is used for identifying the input document in error messages. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

◆ decode() [2/5]

template<class TYPE >

int balxml::Decoder::decode	(	bsl::streambuf *	buffer,
		TYPE *	object,
		const char *	uri = `0`
	)

Decode the specified object of parameterized TYPE from the specified stream buffer. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

◆ decode() [3/5]

template<class TYPE >

int balxml::Decoder::decode	(	const char *	buffer,
		bsl::size_t	length,
		TYPE *	object,
		const char *	uri = `0`
	)

Decode the specified object of parameterized TYPE from the memory at the specified buffer address, having the specified length. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

◆ decode() [4/5]

template<class TYPE >

int balxml::Decoder::decode	(	const char *	filename,
		TYPE *	object
	)

Decode the specified object of parameterized TYPE from the file with the specified filename. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

◆ decode() [5/5]

template<class TYPE >

int balxml::Decoder::decode ( TYPE * object )

inline

Decode the specified object of parameterized TYPE from the input source specified by a previous call to open and leave the reader in an open state. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

Precondition: The behavior is undefined unless this call was preceded by a prior successful call to open

◆ decodeAny() [1/6]

int balxml::Decoder::decodeAny ( bdlar::AnyRef * object )

◆ decodeAny() [2/6]

bsl::istream & balxml::Decoder::decodeAny	(	bsl::istream &	stream,
		bdlar::AnyRef *	object,
		const char *	uri = `0`
	)

◆ decodeAny() [3/6]

template<class TYPE >

bsl::istream & balxml::Decoder::decodeAny	(	bsl::istream &	stream,
		TYPE *	object,
		const char *	uri = `0`
	)

inline

Decode the specified object of parameterized TYPE from the specified input stream. Return a reference to the modifiable stream. If a decoding error is detected, stream.fail() will be true after this method returns. The (optionally) specified uri is used for identifying the input document in error messages. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions.

Note: Note that this function behaves identically to decode, but does not instantiate any templates at compile time at the expense of being slightly slower at runtime; see the balxml package documentation for more details.

◆ decodeAny() [4/6]

int balxml::Decoder::decodeAny	(	bsl::streambuf *	buffer,
		bdlar::AnyRef *	object,
		const char *	uri = `0`
	)

◆ decodeAny() [5/6]

template<class TYPE >

int balxml::Decoder::decodeAny	(	bsl::streambuf *	buffer,
		TYPE *	object,
		const char *	uri = `0`
	)

inline

Decode the specified object of parameterized TYPE from the specified stream buffer. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions.

Note: Note that this function behaves identically to decode, but does not instantiate any templates at compile time at the expense of being slightly slower at runtime; see the balxml package documentation for more details.

◆ decodeAny() [6/6]

template<class TYPE >

int balxml::Decoder::decodeAny ( TYPE * object )

inline

Decode the specified object of parameterized TYPE from the input source specified by a previous call to open and leave the reader in an open state. Return 0 on success, and a non-zero value otherwise. A compilation error will result unless TYPE conforms to the requirements of a bdlat sequence or choice, as described in bdlat_sequencefunctions and bdlat_choicefunctions .

Precondition: The behavior is undefined unless this call was preceded by a prior successful call to open.

Note: Note that this function behaves identically to decode, but does not instantiate any templates at compile time at the expense of being slightly slower at runtime; see the balxml package documentation for more details.

◆ errorCount()

int balxml::Decoder::errorCount ( ) const

inline

Return the number of errors that occurred during decoding. This number is reset to zero on a call to open.

◆ errorInfo()

ErrorInfo * balxml::Decoder::errorInfo ( ) const

inline

Return a pointer to the modifiable error-reporting structure associated with this decoder (i.e., the errInfo pointer provided at construction). The value stored in the error structure is reset to indicate no error on a successful call to open.

◆ errorSeverity()

ErrorInfo::Severity balxml::Decoder::errorSeverity ( ) const

Return the severity of the most severe warning or error encountered during the last call to the decode method. The severity is reset each time decode is called.

◆ errorStream()

bsl::ostream * balxml::Decoder::errorStream ( ) const

inline

Return pointer to the error stream.

◆ loggedMessages()

bslstl::StringRef balxml::Decoder::loggedMessages ( ) const

Return a string containing any error, warning, or trace messages that were logged during the last call to the decode method. The log is reset each time decode is called.

◆ numUnknownElementsSkipped()

int balxml::Decoder::numUnknownElementsSkipped ( ) const

inline

Return the number of unknown elements that were skipped during the previous decoding operation.

Note: Note that unknown elements are skipped only if true == options()->skipUnknownElements().

◆ open() [1/4]

int balxml::Decoder::open	(	bsl::istream &	stream,
		const char *	uri = `0`
	)

inline

Open the associated Reader object (see Reader::open) to read XML data from the specified stream. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success and non-zero otherwise.

◆ open() [2/4]

int balxml::Decoder::open	(	bsl::streambuf *	buffer,
		const char *	uri = `0`
	)

Open the associated Reader object (see Reader::open) to read XML data from the specified stream buffer. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success and non-zero otherwise.

◆ open() [3/4]

int balxml::Decoder::open	(	const char *	buffer,
		bsl::size_t	length,
		const char *	uri = `0`
	)

Open the associated Reader object (see Reader::open) to read XML data from memory at the specified buffer, with the specified length. The (optionally) specified uri is used for identifying the input document in error messages. Return 0 on success and non-zero otherwise.

◆ open() [4/4]

int balxml::Decoder::open ( const char * filename )

Open the associated Reader object (see Reader::open) to read XML data from the file with the specified filename. Return 0 on success and non-zero otherwise.

◆ options()

const DecoderOptions * balxml::Decoder::options ( ) const

inline

Return a pointer to the non-modifiable decoder options provided at construction.

◆ reader()

Reader * balxml::Decoder::reader ( ) const

inline

Return the a pointer to the modifiable reader associated with this decoder (i.e., the reader pointer provided at construction).

◆ setNumUnknownElementsSkipped()

void balxml::Decoder::setNumUnknownElementsSkipped ( int value )

inline

Set the number of unknown elements skipped by the decoder during the current decoding operation to the specified value.

Precondition: The behavior is undefined unless 0 <= value.

◆ warningCount()

int balxml::Decoder::warningCount ( ) const

inline

Return the number of warnings that occurred during decoding. This number is reset to zero on a call to open.

◆ warningStream()

bsl::ostream * balxml::Decoder::warningStream ( ) const

inline

Return pointer to the warning stream.

Friends And Related Symbol Documentation

◆ Decoder_decodeImpProxy

friend struct Decoder_decodeImpProxy

friend

◆ Decoder_ElementContext

friend class Decoder_ElementContext

friend

◆ Decoder_ErrorLogger

friend class Decoder_ErrorLogger

friend

◆ Decoder_ParseObject

friend class Decoder_ParseObject

friend

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

balxml_decoder.h

Detailed Description

Classes

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ Decoder() [1/2]

◆ Decoder() [2/2]

◆ ~Decoder()

Member Function Documentation

◆ close()

◆ decode() [1/5]

◆ decode() [2/5]

◆ decode() [3/5]

◆ decode() [4/5]

◆ decode() [5/5]

◆ decodeAny() [1/6]

◆ decodeAny() [2/6]

◆ decodeAny() [3/6]

◆ decodeAny() [4/6]

◆ decodeAny() [5/6]

◆ decodeAny() [6/6]

◆ errorCount()

◆ errorInfo()

◆ errorSeverity()

◆ errorStream()

◆ loggedMessages()

◆ numUnknownElementsSkipped()

◆ open() [1/4]

◆ open() [2/4]

◆ open() [3/4]

◆ open() [4/4]

◆ options()

◆ reader()

◆ setNumUnknownElementsSkipped()

◆ warningCount()

◆ warningStream()

Friends And Related Symbol Documentation

◆ Decoder_decodeImpProxy

◆ Decoder_ElementContext

◆ Decoder_ErrorLogger

◆ Decoder_ParseObject