From d0af8aa9f11bfd9c6ded625f5591db25d42153ad Mon Sep 17 00:00:00 2001 From: frsyuki Date: Sun, 23 May 2010 21:10:49 +0900 Subject: [PATCH] ruby: rdoc --- ruby/pack.c | 132 ++++++++++++++++++++++++--- ruby/rbinit.c | 12 +++ ruby/unpack.c | 244 ++++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 370 insertions(+), 18 deletions(-) diff --git a/ruby/pack.c b/ruby/pack.c index 387bab6a..7f569239 100644 --- a/ruby/pack.c +++ b/ruby/pack.c @@ -51,6 +51,16 @@ static ID s_append; rb_raise(rb_eArgError, "wrong number of arguments (%d for 0)", argc); \ } + +/* + * Document-method: NilClass#to_msgpack + * + * call-seq: + * nil.to_msgpack(out = '') -> String + * + * Serializes the nil into raw bytes. + * This calls to_msgpack reflectively for internal elements. + */ static VALUE MessagePack_NilClass_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -58,6 +68,16 @@ static VALUE MessagePack_NilClass_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: TrueClass#to_msgpack + * + * call-seq: + * true.to_msgpack(out = '') -> String + * + * Serializes the true into raw bytes. + * This calls to_msgpack reflectively for internal elements. + */ static VALUE MessagePack_TrueClass_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -65,6 +85,16 @@ static VALUE MessagePack_TrueClass_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: FalseClass#to_msgpack + * + * call-seq: + * false.to_msgpack(out = '') -> String + * + * Serializes false into raw bytes. + * This calls to_msgpack reflectively for internal elements. + */ static VALUE MessagePack_FalseClass_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -73,6 +103,15 @@ static VALUE MessagePack_FalseClass_to_msgpack(int argc, VALUE *argv, VALUE self } +/* + * Document-method: Fixnum#to_msgpack + * + * call-seq: + * fixnum.to_msgpack(out = '') -> String + * + * Serializes the Fixnum into raw bytes. + * This calls to_msgpack reflectively for internal elements. + */ static VALUE MessagePack_Fixnum_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -85,6 +124,15 @@ static VALUE MessagePack_Fixnum_to_msgpack(int argc, VALUE *argv, VALUE self) #define RBIGNUM_SIGN(b) (RBIGNUM(b)->sign) #endif +/* + * Document-method: Bignum#to_msgpack + * + * call-seq: + * bignum.to_msgpack(out = '') -> String + * + * Serializes the Bignum into raw bytes. + * This calls to_msgpack reflectively for internal elements. + */ static VALUE MessagePack_Bignum_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -97,6 +145,15 @@ static VALUE MessagePack_Bignum_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: Float#to_msgpack + * + * call-seq: + * float.to_msgpack(out = '') -> String + * + * Serializes the Float into raw bytes. + */ static VALUE MessagePack_Float_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -104,6 +161,15 @@ static VALUE MessagePack_Float_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: String#to_msgpack + * + * call-seq: + * string.to_msgpack(out = '') -> String + * + * Serializes the String into raw bytes. + */ static VALUE MessagePack_String_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -112,6 +178,15 @@ static VALUE MessagePack_String_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: Symbol#to_msgpack + * + * call-seq: + * symbol.to_msgpack(out = '') -> String + * + * Serializes the Symbol into raw bytes. + */ static VALUE MessagePack_Symbol_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -122,6 +197,16 @@ static VALUE MessagePack_Symbol_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + +/* + * Document-method: Array#to_msgpack + * + * call-seq: + * array.to_msgpack(out = '') -> String + * + * Serializes the Array into raw bytes. + * This calls to_msgpack method reflectively for internal elements. + */ static VALUE MessagePack_Array_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -134,6 +219,7 @@ static VALUE MessagePack_Array_to_msgpack(int argc, VALUE *argv, VALUE self) return out; } + #ifndef RHASH_SIZE // Ruby 1.8 #define RHASH_SIZE(h) (RHASH(h)->tbl ? RHASH(h)->tbl->num_entries : 0) #endif @@ -146,6 +232,15 @@ static int MessagePack_Hash_to_msgpack_foreach(VALUE key, VALUE value, VALUE out return ST_CONTINUE; } +/* + * Document-method: Hash#to_msgpack + * + * call-seq: + * hash.to_msgpack(out = '') -> String + * + * Serializes the Hash into raw bytes. + * This calls to_msgpack method reflectively for internal keys and values. + */ static VALUE MessagePack_Hash_to_msgpack(int argc, VALUE *argv, VALUE self) { ARG_BUFFER(out, argc, argv); @@ -155,6 +250,17 @@ static VALUE MessagePack_Hash_to_msgpack(int argc, VALUE *argv, VALUE self) } +/** + * Document-method: MessagePack.pack + * + * call-seq: + * MessagePack.pack(object, out = '') -> String + * + * Serializes the object into raw bytes. The encoding of the string is ASCII-8BIT on Ruby 1.9. + * This method is same as object.to_msgpack(out = ''). + * + * _out_ is an object that implements *<<* method like String or IO. + */ static VALUE MessagePack_pack(int argc, VALUE* argv, VALUE self) { VALUE out; @@ -173,16 +279,22 @@ void Init_msgpack_pack(VALUE mMessagePack) { s_to_msgpack = rb_intern("to_msgpack"); s_append = rb_intern("<<"); - rb_define_method_id(rb_cNilClass, s_to_msgpack, MessagePack_NilClass_to_msgpack, -1); - rb_define_method_id(rb_cTrueClass, s_to_msgpack, MessagePack_TrueClass_to_msgpack, -1); - rb_define_method_id(rb_cFalseClass, s_to_msgpack, MessagePack_FalseClass_to_msgpack, -1); - rb_define_method_id(rb_cFixnum, s_to_msgpack, MessagePack_Fixnum_to_msgpack, -1); - rb_define_method_id(rb_cBignum, s_to_msgpack, MessagePack_Bignum_to_msgpack, -1); - rb_define_method_id(rb_cFloat, s_to_msgpack, MessagePack_Float_to_msgpack, -1); - rb_define_method_id(rb_cString, s_to_msgpack, MessagePack_String_to_msgpack, -1); - rb_define_method_id(rb_cArray, s_to_msgpack, MessagePack_Array_to_msgpack, -1); - rb_define_method_id(rb_cHash, s_to_msgpack, MessagePack_Hash_to_msgpack, -1); - rb_define_method_id(rb_cSymbol, s_to_msgpack, MessagePack_Symbol_to_msgpack, -1); + + rb_define_method(rb_cNilClass, "to_msgpack", MessagePack_NilClass_to_msgpack, -1); + rb_define_method(rb_cTrueClass, "to_msgpack", MessagePack_TrueClass_to_msgpack, -1); + rb_define_method(rb_cFalseClass, "to_msgpack", MessagePack_FalseClass_to_msgpack, -1); + rb_define_method(rb_cFixnum, "to_msgpack", MessagePack_Fixnum_to_msgpack, -1); + rb_define_method(rb_cBignum, "to_msgpack", MessagePack_Bignum_to_msgpack, -1); + rb_define_method(rb_cFloat, "to_msgpack", MessagePack_Float_to_msgpack, -1); + rb_define_method(rb_cString, "to_msgpack", MessagePack_String_to_msgpack, -1); + rb_define_method(rb_cArray, "to_msgpack", MessagePack_Array_to_msgpack, -1); + rb_define_method(rb_cHash, "to_msgpack", MessagePack_Hash_to_msgpack, -1); + rb_define_method(rb_cSymbol, "to_msgpack", MessagePack_Symbol_to_msgpack, -1); + + /** + * MessagePack module is defined in rbinit.c file. + * mMessagePack = rb_define_module("MessagePack"); + */ rb_define_module_function(mMessagePack, "pack", MessagePack_pack, -1); } diff --git a/ruby/rbinit.c b/ruby/rbinit.c index 80d1d8cb..050abde9 100644 --- a/ruby/rbinit.c +++ b/ruby/rbinit.c @@ -20,6 +20,18 @@ static VALUE mMessagePack; +/** + * Document-module: MessagePack + * + * MessagePack is a binary-based efficient object serialization library. + * It enables to exchange structured objects between many languages like JSON. + * But unlike JSON, it is very fast and small. + * + * require 'msgpack' + * msg = [1,2,3].to_msgpack #=> "\x93\x01\x02\x03" + * MessagePack.unpack(msg) #=> [1,2,3] + * + */ void Init_msgpack(void) { mMessagePack = rb_define_module("MessagePack"); diff --git a/ruby/unpack.c b/ruby/unpack.c index 3a95e5a4..9a2c4572 100644 --- a/ruby/unpack.c +++ b/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 + */ +