Class for storing a stream of xml tokens. More...

#include <importutils.hxx>

Inheritance diagram for oox::formulaimport::XmlStream:

Classes
struct	AttributeList
	Structure representing a list of attributes. More...

struct	Tag
	Structure representing a tag, including its attributes and content text immediately following it. More...

Public Member Functions
	XmlStream ()

bool	atEnd () const

Tag	currentTag () const

int	currentToken () const

void	moveToNextTag ()
	Moves position to the next tag. More...

Tag	ensureOpeningTag (int token)
	Ensures that an opening tag with the given token is read. More...

Tag	checkOpeningTag (int token)
	Tries to find an opening tag with the given token. More...

void	ensureClosingTag (int token)
	Ensures that a closing tag with the given token is read. More...

bool	findTag (int token)
	Tries to find the given token, until either found (returns true) or end of current element. More...

void	handleUnexpectedTag ()
	Handle the current (unexpected) tag. More...

Protected Member Functions
Tag	checkTag (int token, bool optional)

bool	findTagInternal (int token, bool silent)

void	skipElementInternal (int token, bool silent)

Protected Attributes
std::vector< Tag >	tags

unsigned int	pos

Detailed Description

Class for storing a stream of xml tokens.

A part of an XML file can be parsed and stored in this stream, from which it can be read as if parsed linearly. The purpose of this class is to allow simpler handling of XML files, unlike the usual LO way of using callbacks, context handlers and similar needlessly complicated stuff (YMMV).

The advantages of this approach is easy to read and debug code (as it is just functions reading tokens one by one and calling other functions, compared to having to use callbacks and temporary storage). The disadvantage is that the XML structure needs to be handled manually by the code.

Note that tag identifiers are simply int values and the API does not care besides matching their values to XML stream contents and requiring that the values are not as high as TAG_OPENING. Be prepared for the fact that some of the functions may throw exceptions if the input stream does not match the required token (TBD).

The API tries to make the common idioms as simple as possible, see the following examples.

Parse <tagone attr="value"><tagtwo>text</tagtwo></tagone> , where tagtwo is optional:

XmlStream::Tag tagoneTag = stream.ensureOpeningTag( tagone );
if( attributeTag.hasAttribute( attr ))
    ... = attributeTag.attribute( attr, defaultValueOfTheRightType );
if( XmlStream::Tag tagtwoTag = stream.checkOpeningTag( tagtwo ))
{
    ... = tagtwoTag.text;
    stream.ensureClosingTag( tagtwo );
}
stream.ensureClosingTag( tagone );

Parse an element that may contain several sub-elements of different types in random order:

stream.ensureOpeningTag( element );
while( !stream.atEnd() && stream.currentToken() != CLOSING( element ))
    {
    switch( stream.currentToken())
    {
        case OPENING( subelement1 ):
            handleSubElement1();
            break;
        case OPENING( subelement2 ):
            ... process subelement2;
            break;
        default:
            stream.handleUnexpectedTag();
            break;
    }
stream.ensureClosingTag( element );

If there may not be a zero number of sub-elements, use a helper bool variable or use a do-while loop.

Parse an element that may contain an unknown number of sub-elements of the same type:

stream.ensureOpeningTag( element );
while( !stream.atEnd() && stream.findTag( OPENING( subelement )))
    {
    handleSubelement();
    }
stream.ensureClosingTag( element );

If there may not be a zero number of sub-elements, use a helper bool variable or use a do-while loop.

Available since: \n 3.5

Definition at line 111 of file importutils.hxx.

Constructor & Destructor Documentation

◆ XmlStream()

oox::formulaimport::XmlStream::XmlStream ( )

Definition at line 155 of file importutils.cxx.

References NMSP_SHIFT, and oox::formulaimport::TAG_OPENING.

Member Function Documentation

◆ atEnd()

bool oox::formulaimport::XmlStream::atEnd ( ) const

Returns: true if current position is at the end of the XML stream

Definition at line 162 of file importutils.cxx.

References pos, and tags.

Referenced by findTagInternal(), and handleUnexpectedTag().

◆ checkOpeningTag()

XmlStream::Tag oox::formulaimport::XmlStream::checkOpeningTag ( int token )

Tries to find an opening tag with the given token.

Works similarly like ensureOpeningTag(), but if a matching tag is not found, the position in the stream is not altered. The primary use of this function is to check for optional elements.

Returns: the matching found opening tag, or empty tag if not found

Definition at line 192 of file importutils.cxx.

References checkTag(), and OPENING.

◆ checkTag()

XmlStream::Tag oox::formulaimport::XmlStream::checkTag	(	int	token,
		bool	optional
	)

protected

Definition at line 202 of file importutils.cxx.

References currentTag(), currentToken(), findTag(), findTagInternal(), moveToNextTag(), pos, and SAL_WARN.

Referenced by checkOpeningTag(), ensureClosingTag(), and ensureOpeningTag().

◆ currentTag()

XmlStream::Tag oox::formulaimport::XmlStream::currentTag ( ) const

Returns: data about the current tag

Definition at line 167 of file importutils.cxx.

References pos, and tags.

Referenced by checkTag().

◆ currentToken()

int oox::formulaimport::XmlStream::currentToken ( ) const

Returns: the token for the current tag

Definition at line 174 of file importutils.cxx.

References pos, tags, and XML_TOKEN_INVALID.

Referenced by checkTag(), findTagInternal(), handleUnexpectedTag(), and skipElementInternal().

◆ ensureClosingTag()

void oox::formulaimport::XmlStream::ensureClosingTag ( int token )

Ensures that a closing tag with the given token is read.

Like ensureOpeningTag(), if not, writes out a warning and tries to recover by skipping tags until found (or until the current element would end). If found, the position in the stream is afterwards moved to the next tag.

Definition at line 197 of file importutils.cxx.

References checkTag(), and CLOSING.

◆ ensureOpeningTag()

XmlStream::Tag oox::formulaimport::XmlStream::ensureOpeningTag ( int token )

Ensures that an opening tag with the given token is read.

If the current tag does not match, writes out a warning and tries to recover by skipping tags until found (or until the current element would end). If found, the position in the stream is afterwards moved to the next tag.

Returns: the matching found opening tag, or empty tag if not found

Definition at line 187 of file importutils.cxx.

References checkTag(), and OPENING.

◆ findTag()

bool oox::formulaimport::XmlStream::findTag ( int token )

Tries to find the given token, until either found (returns true) or end of current element.

Position in the stream is set to make the tag current (i.e. it will be the next one read).

Definition at line 230 of file importutils.cxx.

References findTagInternal().

Referenced by checkTag(), and skipElementInternal().

◆ findTagInternal()

bool oox::formulaimport::XmlStream::findTagInternal	(	int	token,
		bool	silent
	)

protected

Definition at line 235 of file importutils.cxx.

References atEnd(), CLOSING, currentToken(), moveToNextTag(), OPENING, SAL_INFO, and SAL_WARN.

Referenced by checkTag(), and findTag().

◆ handleUnexpectedTag()

void oox::formulaimport::XmlStream::handleUnexpectedTag ( )

Handle the current (unexpected) tag.

Definition at line 302 of file importutils.cxx.

References atEnd(), CLOSING, currentToken(), moveToNextTag(), SAL_INFO, and skipElementInternal().

◆ moveToNextTag()

void oox::formulaimport::XmlStream::moveToNextTag ( )

Moves position to the next tag.

Definition at line 181 of file importutils.cxx.

References pos, and tags.

Referenced by checkTag(), findTagInternal(), handleUnexpectedTag(), and skipElementInternal().

◆ skipElementInternal()

void oox::formulaimport::XmlStream::skipElementInternal	(	int	token,
		bool	silent
	)

protected

Definition at line 283 of file importutils.cxx.

References currentToken(), findTag(), moveToNextTag(), OPENING, SAL_INFO, SAL_WARN, and oox::formulaimport::TAG_CLOSING.

Referenced by handleUnexpectedTag().

Member Data Documentation

◆ pos

unsigned int oox::formulaimport::XmlStream::pos

protected

Definition at line 214 of file importutils.hxx.

Referenced by atEnd(), checkTag(), currentTag(), currentToken(), and moveToNextTag().

◆ tags

std::vector<Tag> oox::formulaimport::XmlStream::tags

protected

Definition at line 213 of file importutils.hxx.

Referenced by oox::formulaimport::XmlStreamBuilder::appendCharacters(), oox::formulaimport::XmlStreamBuilder::appendClosingTag(), oox::formulaimport::XmlStreamBuilder::appendOpeningTag(), atEnd(), currentTag(), currentToken(), and moveToNextTag().

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

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ XmlStream()

Member Function Documentation

◆ atEnd()

◆ checkOpeningTag()

◆ checkTag()

◆ currentTag()

◆ currentToken()

◆ ensureClosingTag()

◆ ensureOpeningTag()

◆ findTag()

◆ findTagInternal()

◆ handleUnexpectedTag()

◆ moveToNextTag()

◆ skipElementInternal()

Member Data Documentation

◆ pos

◆ tags