xmlprinter.h

GPS Manager is a GUI for downloading, organizing, maintaining, and uploading GPS data (i.e. tracks,

/*
gpsmgr: A program for managing GPS information
Copyright (C) 2003 Austin Bingham

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

You can reach the author at:
    [e-mail]
*/

#ifndef XMLPRINTER_H
#define XMLPRINTER_H

#include <iosfwd>
#include <map>
#include <string>

class Properties;

//------------------------------------------------------------------------------
/** This is a simple utility class for printing nice looking XML documents.
    Basically, provide it with an output stream and an indentation token and
    it will format your output in a simple, intuitive way. */

class XMLPrinter
{
public:
    typedef std::map<std::string, std::string> Attrs;
    
public:
    /**
       Constructs an XMLPrinter that writes to the provided Writer

       @param _out The output writer that the xml is printed to
    */
    XMLPrinter(std::ostream& os);
    
    /**
       Constructs an XMLPrinter that writes to the provided writer, using
       a given indentation token
       
       @param _out The output writer that the xml is printed to
       @param _indent_token The token used for indentation
    */
    XMLPrinter(std::ostream& os, const std::string& indentToken);

    /**
       Flushes any pending output to the output writer. Call this before
       ending the writing process.
       
       @throws Exception<IOError> Thrown if the flush operation encounters
                                  an error
     */
    void flushWrites() const;

    /**
       Write a string to the output writer
       
       @param _sz The string to write mOS
       @throws Exception<IOError> Thrown if there is an error writing
                                  to the stream
     */
    void write(const std::string& sz) const;

    /**
       Write a string to the output writer followed by a new line
       
       @param _sz The string to write mOS
       @throws Exception<IOError> Thrown if there is an error writing to the
                                  stream
     */
    void writeLn(const std::string& sz) const;

    /**
       Constructs a simple, one-line XML element with the given tag name
       and character data. 
       
       @param _tag The name of the element to create
       @param _data The character data for the element
       @return A const string& in the format <CODE><_tag>_data</_tag></CODE>
     */
    std::string simpleTag(const std::string& tag,
		     const std::string& data) const;

    /**
       Construct a simple, one-line XML element with the given tag name,
       attributes, and character data.
     
       @param _tag The name of the element to create
       @param _data The character data for the element
       @param _atts The attributes for the element. Each key-value pair in the
                    map if an attribute name (key) and its data (value).
       @return A const string& in the format <CODE><_tag>_data</_tag></CODE> 
     */
    std::string simpleTag(const std::string& tag,
		     const std::string& data,
		     const Attrs& atts) const;

    /**
       Construct a simple, one-line XML element with the given tag name,
       attributes, and no character data (i.e. <NAME/>)
     
       @param _tag The name of the element to create
       @param _atts The attributes for the element. Each key-value pair in the
                    map if an attribute name (key) and its data (value).
       @return A const string& in format <CODE><_tag attribute=value/>
     */
    std::string simpleTag(const std::string& tag,
		     const Attrs& atts) const;

    /**
       Construct a simple, one-line XML element with the given tag name 
       and no character data (i.e. <NAME/>)
       
       @param _tag The name of the element to create
       @return A const string& in format <CODE><_tag/>
     */
    std::string simpleTag(const std::string& tag) const;

    /**
       Returns the opening tag for an XML element. Also, increases indentation
       level by one.
       
       @param _sz The name of the element that we are creating the tag for
       @return A string in the format <CODE><_sz></CODE>
     */
    std::string open(const std::string& tag) const;

    /**
       Returns the opening tag for an XML element. Increases indentation level
       by one.
       
       @param _sz The name of the element that we are creating the tag for
       @param _atts The attributes for the element. Each key-value pair in the
                    map if an attribute name (key) and its data (value).
       @return A string in the format <CODE><_sz [attributes]><CODE>
     */
    std::string open(const std::string& tag,
		const Attrs& atts) const;

    /**
       Construct a closing tag for an XML element
     
       @param _sz The name of the element that we are constructing a closing tag for
       @param A string of the format <CODE></_sz></CODE>
     */
    std::string close(const std::string& tag, bool indent = true) const;


    /**
       Construct XML comment tag
     
       @param text The text of the comment
     */
    std::string comment(const std::string& text) const;
    
    std::string getIndentToken() const;
    void setIndentToken(const std::string& tok);
    
private:
    /**
       Converts a map of attribute-name/attribute-value pairs into a string
       suitable for insertion into an XML element open tag
     
       @param _atts The attributes for the element. Each key-value pair in the
                    map if an attribute name (key) and its data (value).
       @return A string of the format <CODE>ATTNAME1="ATTVALUE1" ATTNAME2="ATTVALUE2"</CODE>, etc. 
     */
    std::string transformAttributes(const Attrs& atts) const;

    /**
       Return the proper indentation to use for a new line based on the
       current indentation level and the indentation token
     */
    std::string getIndentString() const;
    
private:
    std::ostream& mOS;
    std::string mIndent;
    int mIndentLevel;
};

#endif