big batch of progress

[chaz/yoink] / src / deserializer.hh

diff --git a/src/deserializer.hh b/src/deserializer.hh
index 733ce3912f33652d20697bff046d357ba0e2581d..f2b0bccc06d1ade59f920f120cbf42d3a262148c 100644 (file)
--- a/src/deserializer.hh
+++ b/src/deserializer.hh
@@ -44,23 +44,72 @@
 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();
 
+
+       /**
+        * This exception is thrown upon deserialization errors.
+        */
+
        struct exception : std::runtime_error
        {
                explicit exception(const std::string& what_arg) :
@@ -68,6 +117,7 @@ public:
        };
 
 private:
+       class deserializer_impl;
        boost::shared_ptr<deserializer_impl> impl;
 };
 
@@ -77,3 +127,5 @@ private:
 
 #endif // _DESERIALIZER_HH_
 
+/** vim: set ts=4 sw=4 tw=80: *************************************************/
+