streamline and document the API for mathml xml stream reading

2 files changed, 72 insertions, 40 deletions

diff --git a/oox/inc/oox/mathml/importutils.hxx b/oox/inc/oox/mathml/importutils.hxx
index 01baf981eb1f..f7c353da9887 100644
--- a/oox/inc/oox/mathml/importutils.hxx
+++ b/oox/inc/oox/mathml/importutils.hxx
@@ -50,24 +50,60 @@ const int TAG_CLOSING = 1 << 30;
 #define OPENING( token ) ( TAG_OPENING | token )
 #define CLOSING( token ) ( TAG_CLOSING | token )
 
+/**
+ 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 needlesly
+ complicated stuff (YMMV).
+
+ @since 3.5.0
+*/
 class OOX_DLLPUBLIC XmlStream
 {
 public:
     XmlStream();
-    bool nextIsEnd() const;
-    int peekNextToken() const;
-    int getNextToken();
-    oox::AttributeList getAttributes();
-    rtl::OUString getCharacters();
+    /**
+     Structure representing a tag, including its attributes and content text immediatelly following it.
+    */
+    struct Tag
+    {
+        Tag( int token = XML_TOKEN_INVALID,
+            const com::sun::star::uno::Reference< com::sun::star::xml::sax::XFastAttributeList >& attributes = com::sun::star::uno::Reference< com::sun::star::xml::sax::XFastAttributeList >(),
+            const rtl::OUString& text = rtl::OUString());
+        int token; ///< tag type, or XML_TOKEN_INVALID
+        AttributeList attributes;
+        rtl::OUString text;
+    };
+    /**
+     @return true if current position is at the end of the XML stream
+    */
+    bool atEnd() const;
+    /**
+     @return data about the current tag
+    */
+    Tag currentTag() const;
+    /**
+     @return the token for the current tag
+    */
+    int currentToken() const;
+    /**
+     Moves position to the next tag.
+    */
+    void moveToNextTag();
 protected:
-    // TODO one list containing all 3?
-    std::vector< int > tokens;
-    std::vector< oox::AttributeList > attributes;
-    std::vector< rtl::OUString > characters;
-    int pos;
+    std::vector< Tag > tags;
+    unsigned int pos;
 };
 
-// use this to create the data and then cast to the base class for reading
+/**
+ This class is used for creating XmlStream.
+
+ Simply use this class and then pass it as XmlStream to the consumer.
+
+ @since 3.5.0
+*/
 class OOX_DLLPUBLIC XmlStreamBuilder
 : public XmlStream
 {
@@ -79,6 +115,13 @@ public:
     void appendCharacters( const rtl::OUString& characters );
 };
 
+inline XmlStream::Tag::Tag( int t, const com::sun::star::uno::Reference< com::sun::star::xml::sax::XFastAttributeList >& a, const rtl::OUString& txt )
+: token( t )
+, attributes( a )
+, text( txt )
+{
+}
+
 } // namespace
 } // namespace
 
diff --git a/oox/source/mathml/importutils.cxx b/oox/source/mathml/importutils.cxx
index 1381724ec407..95f81c802e83 100644
--- a/oox/source/mathml/importutils.cxx
+++ b/oox/source/mathml/importutils.cxx
@@ -41,62 +41,51 @@ namespace formulaimport
 {
 
 XmlStream::XmlStream()
-: pos( -1 )
+: pos( 0 )
 {
     // make sure our extra bit does not conflict with values used by oox
     assert( TAG_OPENING > ( 1024 << NMSP_SHIFT ));
 }
 
-bool XmlStream::nextIsEnd() const
+bool XmlStream::atEnd() const
 {
-    return pos + 1 >= int( tokens.size());
+    return pos >= tags.size();
 }
 
-int XmlStream::getNextToken()
+XmlStream::Tag XmlStream::currentTag() const
 {
-    ++pos;
-    if( pos < int( tokens.size()))
-        return tokens[ pos ];
-    return XML_TOKEN_INVALID;
+    if( pos >= tags.size())
+        return Tag();
+    return tags[ pos ];
 }
 
-int XmlStream::peekNextToken() const
+int XmlStream::currentToken() const
 {
-    if( pos - 1 < int( tokens.size()))
-        return tokens[ pos + 1 ];
-    return XML_TOKEN_INVALID;
+    if( pos >= tags.size())
+        return XML_TOKEN_INVALID;
+    return tags[ pos ].token;
 }
 
-AttributeList XmlStream::getAttributes()
+void XmlStream::moveToNextTag()
 {
-    assert( pos < int( attributes.size()));
-    return attributes[ pos ];
-}
-
-rtl::OUString XmlStream::getCharacters()
-{
-    assert( pos < int( characters.size()));
-    return characters[ pos ];
+    if( pos < tags.size())
+        ++pos;
 }
 
 void XmlStreamBuilder::appendOpeningTag( int token, const uno::Reference< xml::sax::XFastAttributeList >& attrs )
 {
-    tokens.push_back( OPENING( token ));
-    attributes.push_back( AttributeList( attrs ));
-    characters.push_back( rtl::OUString());
+    tags.push_back( Tag( OPENING( token ), attrs ));
 }
 
 void XmlStreamBuilder::appendClosingTag( int token )
 {
-    tokens.push_back( CLOSING( token ));
-    attributes.push_back( AttributeList( uno::Reference< xml::sax::XFastAttributeList >()));
-    characters.push_back( rtl::OUString());
+    tags.push_back( Tag( CLOSING( token )));
 }
 
 void XmlStreamBuilder::appendCharacters( const rtl::OUString& chars )
 {
-    assert( !characters.empty());
-    characters.back() = chars;
+    assert( !tags.empty());
+    tags.back().text = chars;
 }
 
 } // namespace