// 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
#include
#include
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 &list);
/**
* Calls put() for each element in the list. To serialize an entire
* std::vector, call put(key, vec.begin(), vec.end()).
*/
template
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
* can't be (or isn't being) treated as a QPtrList.
*/
template
void put(const QString &key, const QPtrList &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
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 &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
void
Serializer::put(const QString &key, const QPtrList &list)
{
for(QPtrListIterator it(list); it.current(); ++it)
{
Serializable *sp = dynamic_cast(it.current());
if (sp) put(key, sp);
else
{
NOT_DONE("need to warn that non-Serializable object is being ignored?");
}
}
}
template
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(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
| Generated by: stephan on cheyenne on Mon Aug 11 14:06:52 2003, using kdoc 2.0a54. |