---

Serializer.h

//  Serializer - base class for storing Serializables
//  Copyright (C) 2000-2003 bozo & sgbeal @users.sourceforge.net
//
//  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.

#ifndef _FUN_SERIALIZER_H
#define _FUN_SERIALIZER_H

#include <fun/fun.h>
#include <fun/Serializable.h>
#include <qlist.h>

class QString;
class QColor;
class QPoint;
class QSize;

namespace fun {

//  Remove when you can...
#define SERIALIZER_API_COMPAT 1

/**
*  Serializer is an abstract base class for objects which can store
*  Serializable objects to files or streams.  Depending on the subclass'
*  implementation, the data may be stored natively, or it may be converted to
*  strings, or stuck in a database, etc.
*
*  Think of a Serializer as taking key/value pairs of data, where the values
*  may be Serializable objects, which implies a tree structure.  Duplicate
*  keys are allowed, but note that the only way to get at the values for
*  duplicate keys in a Deserializer is to use one of the forms of get() which
*  takes a reference to a list of Serializables or QStrings.
*
*  As Serializer is abstract, subclasses must provide implementations for
*  the following methods:
*  - put(const QString &key, const QString &val)
*  - put(const QString &key, const Serializable &val)
*  - setSerializableClass(const char *name)
*  Also, setComment() does nothing in the base class.
*/
class Serializer
{
    public:
    /**
    *  Creates an empty Serializer node.
    */
    Serializer() { }
    virtual ~Serializer() { }

    /**
    *  Adds a new element containing the given string value.
    *  This is one of the methods which subclasses must implement.
    */
    virtual void put(const QString &key, const QString &val) = 0;

    /**
    *  Adds a new element containing the given string value.
    *  (this one is because put(key, "bleh") was calling the bool version!)
    */
    void put(const QString &key, const char *val) { put(key, QString(val)); }

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given int value to a string.
    */
    virtual void put(const QString &key, int val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given unsigned int value to a string.
    */
    virtual void put(const QString &key, unsigned val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given bool value to a string.
    */
    virtual void put(const QString &key, bool val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given float value to a string.
    */
    virtual void put(const QString &key, float val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given double value to a string.
    */
    virtual void put(const QString &key, double val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given QColor value to a string in the format #rrggbb.
    */
    virtual void put(const QString &key, const QColor &val);

    /**
    *  Adds a new element containing the given Serializable value.
    *  Passing a NULL Serializable here has the same effect as not
    *  calling it at all.
    *
    *  This is one of the methods which subclasses must implement.
    */
    virtual void put(const QString &key, const Serializable *val) = 0;

    /**
    *  Calls put() for each element in the list.
    */
    virtual void put(const QString &key, const QPtrList<Serializable> &list);

    /**
    *  Calls put() for each element in the list.  To serialize an entire
    *  std::vector<Serializable *>, call put(key, vec.begin(), vec.end()).
    */
    template <class InputIterator>
    void put(const QString &key, InputIterator begin, InputIterator end) { while (begin != end) put(key, *begin++); }

    /**
    *  Calls put() for each Serializable element in the list.  This is
    *  because even if Foo is a subclass of Serializable, QPtrList<Foo>
    *  can't be (or isn't being) treated as a QPtrList<Serializable>.
    */
    template <class SC>
    void put(const QString &key, const QPtrList<SC> &list);

    /**
    *  Calls put() for each Serializable element in the array of pointers.
    *  NULL elements in the list will be ignored... nuts, that means you
    *  can't rely on it to deserialize the same way.  OK, how about the
    *  behavior is undefined in that case, ha ha.
    */
    template <class SC>
    void put(const QString &key, const SC * const *list, unsigned len);

    /**
    *  Calls put() for each element in the list.  Note that in the result
    *  there may be no way to tell "null" and "empty" strings apart.
    */
    virtual void put(const QString &key, const QStringList &list);

    /**
    *  Calls put() for each element in the list.  Note that in the result
    *  there may be no way to tell "null" and "empty" strings apart.
    */
    virtual void put(const QString &key, const QString *list, unsigned len);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given QPoint value to a string in the format "x,y".
    */
    virtual void put(const QString &key, const QPoint &val);

    /**
    *  This is just like the string version of put(), except that it
    *  converts the given QSize value to a string in the format "x,y".
    */
    virtual void put(const QString &key, const QSize &val);

    /**
    *  This sets the name of the Serializable subclass name, so that the same
    *  class can be instantiated during deserialization.  Every Serializable's
    *  serialize() method should call this with its own class name after
    *  calling its superclass' serialize().
    *
    *  This is one of the methods which subclasses must implement.
    */
    virtual void setSerializableClass(const char *name) = 0;

    /**
    *  Sets an optional comment which will be associated with a child
    *  element.  Note that if you have multiple elements with the same
    *  key, you're probably only going to have one comment.
    *
    *  The default base class behavior is to do nothing.
    */
    virtual void setComment(const QString &key, const QString &comment);

#if SERIALIZER_API_COMPAT
    void putString(const QString &key, const QString &val) { put(key, val); }
    void putInt(const QString &key, int val) { put(key, val); }
    void putUInt(const QString &key, unsigned val) { put(key, val); }
    void putBool(const QString &key, bool val) { put(key, val); }
    void putFloat(const QString &key, float val) { put(key, val); }
    void putDouble(const QString &key, double val) { put(key, val); }
    void putColor(const QString &key, const QColor &val) { put(key, val); }
    void putSerializable(const QString &key, const Serializable &val) { put(key, &val); }
    void putSerializables(const QString &key, const QPtrList<Serializable> &list) { put(key, list); }
    void putStrings(const QString &key, const QStringList &list) { put(key, list); }
    void putPoint( const QString &key, const QPoint &val ) { put(key, val); }
    void putSize( const QString &key, const QSize &val ) { put(key, val); }
#endif
};

template <class SC>
void
Serializer::put(const QString &key, const QPtrList<SC> &list)
{
    for(QPtrListIterator<SC> it(list); it.current(); ++it)
    {
        Serializable *sp = dynamic_cast<Serializable *>(it.current());
        if (sp) put(key, sp);
        else
        {
            NOT_DONE("need to warn that non-Serializable object is being ignored?");
        }
    }
}

template <class SC>
void
Serializer::put(const QString &key, const SC * const *list, unsigned len)
{
    for(unsigned i = 0; i < len; ++i)
    {
        if (list[i] == NULL) continue;
        const Serializable *sp = dynamic_cast<const Serializable *>(list[i]);
        if (sp) put(key, sp);
        else
        {
            NOT_DONE("need to warn that non-Serializable object is being ignored?");
        }
    }
}

}  //  namespace fun

#endif  //  _FUN_SERIALIZER_H

---