--- /dev/null
+
+/*******************************************************************************
+
+ Copyright (c) 2009, Charles McGarvey
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*******************************************************************************/
+
+#ifndef _MOOF_DESERIALIZER_HH_
+#define _MOOF_DESERIALIZER_HH_
+
+/**
+ * @file Deserializer.hh
+ * Deserialize structures and types from input on a stream.
+ */
+
+#include <istream>
+#include <string>
+#include <stdexcept>
+
+#include <boost/shared_ptr.hpp>
+
+
+namespace Mf {
+
+
+class Serializable; // forward declaration
+typedef boost::shared_ptr<Serializable> SerializablePtr;
+
+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.
+ */
+
+ SerializablePtr 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();
+
+
+ /**
+ * This exception is thrown upon deserialization errors.
+ */
+
+ struct Exception : std::runtime_error
+ {
+ explicit Exception(const std::string& what_arg) :
+ std::runtime_error(what_arg) {}
+ };
+
+private:
+ class DeserializerImpl;
+ boost::shared_ptr<DeserializerImpl> impl_;
+};
+
+
+} // namespace Mf
+
+
+#endif // _MOOF_DESERIALIZER_HH_
+
+/** vim: set ts=4 sw=4 tw=80: *************************************************/
+