namespace dc {
-class serializable;
+class serializable; // forward declaration
typedef boost::shared_ptr<serializable> serializable_ptr;
-class deserializer_impl;
-
class deserializer
{
public:
+
+ /**
+ * Construction is initialization. A deserializer can be constructed with
+ * either an input stream or a string representing a filename that will be
+ * read from. If a stream is provided, it will not be closed after parsing,
+ * but the parser may read past the end of usable bytes, so you should not
+ * use a deserializer on a stream that you expect to continue to use after
+ * the deserialization.
+ * @param comments If true, C and C++-style comments will be allowed and
+ * ignored by the parser.
+ * @param check If true, UTF-8 strings will be checked for validity and an
+ * exception thrown if such a problem exists. Otherwise strings will not be
+ * checked.
+ */
+
deserializer(const std::string& filePath, bool comments = false,
bool check = false);
deserializer(std::istream& input, bool comments = false, bool check = false);
+
+ /**
+ * Parse the object from of the stream. The stream is considered to be
+ * dominated by the parser and may read and discard bytes past the end of
+ * the actual parsed object. Only one object can be deserialized by the
+ * deserializer.
+ */
+
serializable_ptr deserialize();
+ /**
+ * Used by serializable objects to parse themselves. These methods should
+ * generally not be used directory for deserialization. This one returns
+ * the next object in the queue which has been parsed. This method may
+ * block if more data is pending and an object has not bee constructed yet.
+ * The caller takes ownership of the object which has been allocated with
+ * the new operator and must therefore be sure to delete the object as
+ * appropriated. Null (0) will be returned by this method to signify one of
+ * three things: 1) the end of an array, 2) the end of a map/dictionary, or
+ * 3) there is nothing more to be obtained. Container objects will be empty
+ * and will have to be filled with their contained elements by repeatedly
+ * calling this method until a null is returned. This method will continue
+ * to return the same value until pop() is called which will cause this
+ * method to return the next object as expected.
+ */
+
serializable* pullNext();
+
+ /**
+ * If the object returned by pullNext() has been received successfully and
+ * the caller is ready for the next object, this method should be called to
+ * take that object off of the queue.
+ */
+
void pop();
- struct parser_error : std::runtime_error
+
+ /**
+ * This exception is thrown upon deserialization errors.
+ */
+
+ struct exception : std::runtime_error
{
- explicit parser_error(const std::string& what_arg) :
+ explicit exception(const std::string& what_arg) :
std::runtime_error(what_arg) {}
};
private:
+ class deserializer_impl;
boost::shared_ptr<deserializer_impl> impl;
};
#endif // _DESERIALIZER_HH_
+/** vim: set ts=4 sw=4 tw=80: *************************************************/
+