generic-library/msgpack
1
0
Fork 0
mirror of https://github.com/msgpack/msgpack-c.git synced 2025-03-19 21:18:23 +01:00
Code Issues Projects Releases Wiki Activity

ruby: rdoc

Browse Source
This commit is contained in:
frsyuki 2010-05-23 21:10:49 +09:00
parent f8173e93f5
commit d0af8aa9f1
3 changed files with 370 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
ruby/pack.c
View File

@ -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);
}

12
ruby/rbinit.c
View File

@ -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");

244
ruby/unpack.c
View File

@ -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
*/