LibreOffice Module oox (master)  1
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
oox::formulaimport::XmlStream Class Reference

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

#include <importutils.hxx>

Inheritance diagram for oox::formulaimport::XmlStream:
[legend]

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< Tagtags
 
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:
3.5

Definition at line 111 of file importutils.hxx.

Constructor & Destructor Documentation

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

Definition at line 154 of file importutils.cxx.

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

Member Function Documentation

bool oox::formulaimport::XmlStream::atEnd ( ) const
Returns
true if current position is at the end of the XML stream

Definition at line 161 of file importutils.cxx.

References pos, and tags.

Referenced by findTagInternal(), and handleUnexpectedTag().

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 191 of file importutils.cxx.

References checkTag(), and OPENING.

XmlStream::Tag oox::formulaimport::XmlStream::checkTag ( int  token,
bool  optional 
)
protected
XmlStream::Tag oox::formulaimport::XmlStream::currentTag ( ) const
Returns
data about the current tag

Definition at line 166 of file importutils.cxx.

References pos, and tags.

Referenced by checkTag().

int oox::formulaimport::XmlStream::currentToken ( ) const
Returns
the token for the current tag

Definition at line 173 of file importutils.cxx.

References pos, tags, and XML_TOKEN_INVALID.

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

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 196 of file importutils.cxx.

References checkTag(), and CLOSING.

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 186 of file importutils.cxx.

References checkTag(), and OPENING.

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 229 of file importutils.cxx.

References findTagInternal().

Referenced by checkTag(), and skipElementInternal().

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

Definition at line 234 of file importutils.cxx.

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

Referenced by checkTag(), and findTag().

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

Handle the current (unexpected) tag.

Definition at line 301 of file importutils.cxx.

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

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

Moves position to the next tag.

Definition at line 180 of file importutils.cxx.

References pos, and tags.

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

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

Member Data Documentation

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

Definition at line 214 of file importutils.hxx.

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

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

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