ruby: rdoc

ruby/unpack.c

@@ -205,6 +205,12 @@ static int template_execute_wrap(msgpack_unpack_t* mp,
 
 
 static VALUE cUnpacker;
+
+
+/**
+ * Document-module: MessagePack::UnpackerError
+ *
+ */
 static VALUE eUnpackError;
 
 
@@ -243,6 +249,22 @@ static ID append_method_of(VALUE stream)
 	}
 }
 
+/**
+ * Document-method: MessagePack::Unpacker#initialize
+ *
+ * call-seq:
+ *   MessagePack::Unpacker.new(stream = nil)
+ *
+ * Creates instance of MessagePack::Unpacker.
+ *
+ * You can specify a _stream_ for input stream.
+ * It is required to implement *sysread* or *readpartial* method.
+ *
+ * With the input stream, buffers will be feeded into the deserializer automatically.
+ *
+ * Without the input stream, use *feed* method manually. Or you can manage the buffer manually
+ * with *execute*, *finished?*, *data* and *reset* methods.
+ */
 static VALUE MessagePack_Unpacker_initialize(int argc, VALUE *argv, VALUE self)
 {
 	VALUE stream;
@@ -268,12 +290,29 @@ static VALUE MessagePack_Unpacker_initialize(int argc, VALUE *argv, VALUE self)
 	return self;
 }
 
+
+/**
+ * Document-method: MessagePack::Unpacker#stream
+ *
+ * call-seq:
+ *   unpacker.stream
+ *
+ * Gets the input stream.
+ */
 static VALUE MessagePack_Unpacker_stream_get(VALUE self)
 {
 	UNPACKER(self, mp);
 	return mp->user.stream;
 }
 
+/**
+ * Document-method: MessagePack::Unpacker#stream=
+ *
+ * call-seq:
+ *   unpacker.stream = stream
+ *
+ * Resets the input stream. You can set nil not to use input stream.
+ */
 static VALUE MessagePack_Unpacker_stream_set(VALUE self, VALUE val)
 {
 	UNPACKER(self, mp);
@@ -282,6 +321,15 @@ static VALUE MessagePack_Unpacker_stream_set(VALUE self, VALUE val)
 	return val;
 }
 
+
+/**
+ * Document-method: MessagePack::Unpacker#feed
+ *
+ * call-seq:
+ *   unpacker.feed(data)
+ *
+ * Fills the internal buffer with the specified buffer.
+ */
 static VALUE MessagePack_Unpacker_feed(VALUE self, VALUE data)
 {
 	UNPACKER(self, mp);
@@ -290,6 +338,20 @@ static VALUE MessagePack_Unpacker_feed(VALUE self, VALUE data)
 	return Qnil;
 }
 
+/**
+ * Document-method: MessagePack::Unpacker#fill
+ *
+ * call-seq:
+ *   unpacker.fill -> length of read data
+ *
+ * Fills the internal buffer using the input stream.
+ *
+ * If the input stream is not specified, it returns nil.
+ * You can set it on *initialize* or *stream=* methods.
+ *
+ * This methods raises exceptions that _stream.sysread_ or
+ * _stream.readpartial_ method raises.
+ */
 static VALUE MessagePack_Unpacker_fill(VALUE self)
 {
 	UNPACKER(self, mp);
@@ -313,6 +375,18 @@ static VALUE MessagePack_Unpacker_fill(VALUE self)
 	return LONG2FIX(len);
 }
 
+
+/**
+ * Document-method: MessagePack::Unpacker#each
+ *
+ * call-seq:
+ *   unpacker.each {|object| }
+ *
+ * Deserializes objects repeatedly. This calls *fill* method automatically.
+ *
+ * UnpackError is throw when parse error is occured.
+ * This method raises exceptions that *fill* method raises.
+ */
 static VALUE MessagePack_Unpacker_each(VALUE self)
 {
 	UNPACKER(self, mp);
@@ -352,6 +426,7 @@ static VALUE MessagePack_Unpacker_each(VALUE self)
 	return Qnil;
 }
 
+
 static inline VALUE MessagePack_unpack_impl(VALUE self, VALUE data, unsigned long dlen)
 {
 	msgpack_unpack_t mp;
@@ -376,12 +451,34 @@ static inline VALUE MessagePack_unpack_impl(VALUE self, VALUE data, unsigned lon
 	}
 }
 
+/**
+ * Document-method: MessagePack::Unpacker.unpack_limit
+ *
+ * call-seq:
+ *   MessagePack::Unpacker.unpack_limit(data, limit) -> object
+ *
+ * Deserializes one object over the specified buffer upto _limit_ bytes.
+ *
+ * UnpackError is throw when parse error is occured, the buffer is insufficient
+ * to deserialize one object or there are extra bytes.
+ */
 static VALUE MessagePack_unpack_limit(VALUE self, VALUE data, VALUE limit)
 {
 	CHECK_STRING_TYPE(data);
 	return MessagePack_unpack_impl(self, data, NUM2ULONG(limit));
 }
 
+/**
+ * Document-method: MessagePack::Unpacker.unpack
+ *
+ * call-seq:
+ *   MessagePack::Unpacker.unpack(data) -> object
+ *
+ * Deserializes one object over the specified buffer.
+ *
+ * UnpackError is throw when parse error is occured, the buffer is insufficient
+ * to deserialize one object or there are extra bytes.
+ */
 static VALUE MessagePack_unpack(VALUE self, VALUE data)
 {
 	CHECK_STRING_TYPE(data);
@@ -411,7 +508,20 @@ static VALUE MessagePack_Unpacker_execute_impl(VALUE self, VALUE data,
 	}
 }
 
-/* compat */
+/**
+ * Document-method: MessagePack::Unpacker#execute_limit
+ *
+ * call-seq:
+ *   unpacker.unpack_limit(data, offset, limit) -> next offset
+ *
+ * Deserializes one object over the specified buffer from _offset_ bytes upto _limit_ bytes.
+ *
+ * This method doesn't use the internal buffer.
+ *
+ * Call *reset()* method before calling this method again.
+ *
+ * UnpackError is throw when parse error is occured.
+ */
 static VALUE MessagePack_Unpacker_execute_limit(VALUE self, VALUE data,
 		VALUE off, VALUE limit)
 {
@@ -420,7 +530,24 @@ static VALUE MessagePack_Unpacker_execute_limit(VALUE self, VALUE data,
 			(size_t)NUM2ULONG(off), (size_t)NUM2ULONG(limit));
 }
 
-/* compat */
+/**
+ * Document-method: MessagePack::Unpacker#execute
+ *
+ * call-seq:
+ *   unpacker.unpack(data, offset) -> next offset
+ *
+ * Deserializes one object over the specified buffer from _offset_ bytes.
+ *
+ * This method doesn't use the internal buffer.
+ *
+ * Call *reset()* method before calling this method again.
+ *
+ * This returns offset that was parsed to.
+ * Use *finished?* method to check an object is deserialized and call *data*
+ * method if it returns true.
+ *
+ * UnpackError is throw when parse error is occured.
+ */
 static VALUE MessagePack_Unpacker_execute(VALUE self, VALUE data, VALUE off)
 {
 	CHECK_STRING_TYPE(data);
@@ -428,7 +555,16 @@ static VALUE MessagePack_Unpacker_execute(VALUE self, VALUE data, VALUE off)
 			(size_t)NUM2ULONG(off), (size_t)RSTRING_LEN(data));
 }
 
-/* compat */
+/**
+ * Document-method: MessagePack::Unpacker#finished?
+ *
+ * call-seq:
+ *   unpacker.finished?
+ *
+ * Returns true if an object is ready to get with data method.
+ *
+ * Use this method with execute method.
+ */
 static VALUE MessagePack_Unpacker_finished_p(VALUE self)
 {
 	UNPACKER(self, mp);
@@ -438,14 +574,30 @@ static VALUE MessagePack_Unpacker_finished_p(VALUE self)
 	return Qfalse;
 }
 
-/* compat */
+/**
+ * Document-method: MessagePack::Unpacker#data
+ *
+ * call-seq:
+ *   unpacker.data
+ *
+ * Gets the object deserialized by execute method.
+ *
+ * Use this method with execute method.
+ */
 static VALUE MessagePack_Unpacker_data(VALUE self)
 {
 	UNPACKER(self, mp);
 	return template_data(mp);
 }
 
-/* compat */
+/**
+ * Document-method: MessagePack::Unpacker#reset
+ *
+ * call-seq:
+ *   unpacker.reset
+ *
+ * Resets the internal state of the unpacker.
+ */
 static VALUE MessagePack_Unpacker_reset(VALUE self)
 {
 	UNPACKER(self, mp);
@@ -467,20 +619,96 @@ void Init_msgpack_unpack(VALUE mMessagePack)
 	eUnpackError = rb_define_class_under(mMessagePack, "UnpackError", rb_eStandardError);
 	cUnpacker = rb_define_class_under(mMessagePack, "Unpacker", rb_cObject);
 	rb_define_alloc_func(cUnpacker, MessagePack_Unpacker_alloc);
+
 	rb_define_method(cUnpacker, "initialize", MessagePack_Unpacker_initialize, -1);
+
+	/* Buffered API */
 	rb_define_method(cUnpacker, "feed", MessagePack_Unpacker_feed, 1);
 	rb_define_method(cUnpacker, "fill", MessagePack_Unpacker_fill, 0);
 	rb_define_method(cUnpacker, "each", MessagePack_Unpacker_each, 0);
 	rb_define_method(cUnpacker, "stream", MessagePack_Unpacker_stream_get, 0);
 	rb_define_method(cUnpacker, "stream=", MessagePack_Unpacker_stream_set, 1);
-	rb_define_module_function(mMessagePack, "unpack", MessagePack_unpack, 1);
-	rb_define_module_function(mMessagePack, "unpack_limit", MessagePack_unpack_limit, 2);
 
-	/* backward compatibility */
+	/* Unbuffered API */
 	rb_define_method(cUnpacker, "execute", MessagePack_Unpacker_execute, 2);
 	rb_define_method(cUnpacker, "execute_limit", MessagePack_Unpacker_execute_limit, 3);
 	rb_define_method(cUnpacker, "finished?", MessagePack_Unpacker_finished_p, 0);
 	rb_define_method(cUnpacker, "data", MessagePack_Unpacker_data, 0);
 	rb_define_method(cUnpacker, "reset", MessagePack_Unpacker_reset, 0);
+
+	/**
+	 * MessagePack module is defined in rbinit.c file.
+	 * mMessagePack = rb_define_module("MessagePack");
+	 */
+	rb_define_module_function(mMessagePack, "unpack", MessagePack_unpack, 1);
+	rb_define_module_function(mMessagePack, "unpack_limit", MessagePack_unpack_limit, 2);
 }
 
+/**
+ * Document-module: MessagePack::Unpacker
+ *
+ * Deserializer class that includes Buffered API and Unbuffered API.
+ *
+ *
+ * Buffered API uses the internal buffer of the Unpacker.
+ * Following code uses Buffered API with an input stream:
+ *
+ *   # create an unpacker with input stream.
+ *   pac = MessagePack::Unpacker.new(stdin)
+ *   
+ *   # deserialize object one after another.
+ *   pac.each {|obj|
+ *     # ...
+ *   }
+ *
+ *
+ * Following code doesn't use the input stream and feeds buffer
+ * using *fill* method. This is useful to use special stream
+ * or with event-driven I/O library.
+ *
+ *   # create an unpacker without input stream.
+ *   pac = MessagePack::Unpacker.new()
+ *   
+ *   # feed buffer to the internal buffer.
+ *   pac.feed(input_bytes)
+ *   
+ *   # deserialize object one after another.
+ *   pac.each {|obj|
+ *     # ...
+ *   }
+ *
+ * You can manage the buffer manually with the combination of
+ * *execute*, *finished?*, *data* and *reset* method.
+ *
+ *   # create an unpacker.
+ *   pac = MessagePack::Unpacker.new()
+ *   
+ *   # manage buffer and offset manually.
+ *   offset = 0
+ *   buffer = ''
+ *   
+ *   # read some data into the buffer.
+ *   buffer << [1,2,3].to_msgpack
+ *   buffer << [4,5,6].to_msgpack
+ *   
+ *   while true
+ *     offset = pac.execute(buffer, offset)
+ *   
+ *     if pac.finished?
+ *       obj = pac.data
+ *   
+ *       buffer.slice!(0, offset)
+ *       offset = 0
+ *       pac.reset
+ *   
+ *       # do something with the object
+ *       # ...
+ *
+ *       # repeat execution if there are more data.
+ *       next unless buffer.empty?
+ *     end
+ *
+ *     break
+ *   end
+ */
+