.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::MessagePack 3pm"
.TH Data::MessagePack 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Data::MessagePack \- MessagePack serializing/deserializing
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Data::MessagePack;
\&
\&    my $mp = Data::MessagePack\->new();
\&    $mp\->canonical\->utf8\->prefer_integer if $needed;
\&
\&    my $packed   = $mp\->pack($dat);
\&    my $unpacked = $mp\->unpack($dat);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module converts Perl data structures to MessagePack and vice versa.
.SH "ABOUT MESSAGEPACK FORMAT"
.IX Header "ABOUT MESSAGEPACK FORMAT"
MessagePack is a binary-based efficient object serialization format.
It enables to exchange structured objects between many languages like
JSON.  But unlike JSON, it is very fast and small.
.SS ADVANTAGES
.IX Subsection "ADVANTAGES"
.IP PORTABLE 4
.IX Item "PORTABLE"
The MessagePack format does not depend on language nor byte order.
.IP "SMALL IN SIZE" 4
.IX Item "SMALL IN SIZE"
.Vb 3
\&    say length(JSON::XS::encode_json({a=>1, b=>2}));   # => 13
\&    say length(Storable::nfreeze({a=>1, b=>2}));       # => 21
\&    say length(Data::MessagePack\->pack({a=>1, b=>2})); # => 7
.Ve
.Sp
The MessagePack format saves memory than JSON and Storable format.
.IP "STREAMING DESERIALIZER" 4
.IX Item "STREAMING DESERIALIZER"
MessagePack supports streaming deserializer. It is useful for
networking such as RPC.  See Data::MessagePack::Unpacker for
details.
.PP
If you want to get more information about the MessagePack format,
please visit to <http://msgpack.org/>.
.SH METHODS
.IX Header "METHODS"
.ie n .IP """my $packed = Data::MessagePack\->pack($data[, $max_depth]);""" 4
.el .IP "\f(CWmy $packed = Data::MessagePack\->pack($data[, $max_depth]);\fR" 4
.IX Item "my $packed = Data::MessagePack->pack($data[, $max_depth]);"
Pack the \f(CW$data\fR to messagepack format string.
.Sp
This method throws an exception when the perl structure is nested more
than \f(CW$max_depth\fR levels(default: 512) in order to detect circular
references.
.Sp
Data::MessagePack\->\fBpack()\fR throws an exception when encountering a
blessed perl object, because MessagePack is a language-independent
format.
.ie n .IP """my $unpacked = Data::MessagePack\->unpack($msgpackstr);""" 4
.el .IP "\f(CWmy $unpacked = Data::MessagePack\->unpack($msgpackstr);\fR" 4
.IX Item "my $unpacked = Data::MessagePack->unpack($msgpackstr);"
unpack the \f(CW$msgpackstr\fR to a MessagePack format string.
.ie n .IP """my $mp = Data::MesssagePack\->new()""" 4
.el .IP "\f(CWmy $mp = Data::MesssagePack\->new()\fR" 4
.IX Item "my $mp = Data::MesssagePack->new()"
Creates a new MessagePack instance.
.ie n .IP """$mp = $mp\->prefer_integer([ $enable ])""" 4
.el .IP "\f(CW$mp = $mp\->prefer_integer([ $enable ])\fR" 4
.IX Item "$mp = $mp->prefer_integer([ $enable ])"
.PD 0
.ie n .IP """$enabled = $mp\->get_prefer_integer()""" 4
.el .IP "\f(CW$enabled = $mp\->get_prefer_integer()\fR" 4
.IX Item "$enabled = $mp->get_prefer_integer()"
.PD
If \fR\f(CI$enable\fR\fI\fR is true (or missing), then the \f(CW\*(C`pack\*(C'\fR method tries a
string as an integer if the string looks like an integer.
.ie n .IP """$mp = $mp\->canonical([ $enable ])""" 4
.el .IP "\f(CW$mp = $mp\->canonical([ $enable ])\fR" 4
.IX Item "$mp = $mp->canonical([ $enable ])"
.PD 0
.ie n .IP """$enabled = $mp\->get_canonical()""" 4
.el .IP "\f(CW$enabled = $mp\->get_canonical()\fR" 4
.IX Item "$enabled = $mp->get_canonical()"
.PD
If \fR\f(CI$enable\fR\fI\fR is true (or missing), then the \f(CW\*(C`pack\*(C'\fR method will output
packed data by sorting their keys. This is adding a comparatively high
overhead.
.ie n .IP """$mp = $mp\->utf8([ $enable ])""" 4
.el .IP "\f(CW$mp = $mp\->utf8([ $enable ])\fR" 4
.IX Item "$mp = $mp->utf8([ $enable ])"
.PD 0
.ie n .IP """$enabled = $mp\->get_utf8()""" 4
.el .IP "\f(CW$enabled = $mp\->get_utf8()\fR" 4
.IX Item "$enabled = $mp->get_utf8()"
.PD
If \fR\f(CI$enable\fR\fI\fR is true (or missing), then the \f(CW\*(C`pack\*(C'\fR method will
apply \f(CWutf8::encode()\fR to all the string values.
.Sp
In other words, this property tell \f(CW$mp\fR to deal with \fBtext strings\fR.
See perlunifaq for the meaning of \fBtext string\fR.
.ie n .IP """$packed = $mp\->pack($data)""" 4
.el .IP "\f(CW$packed = $mp\->pack($data)\fR" 4
.IX Item "$packed = $mp->pack($data)"
.PD 0
.ie n .IP """$packed = $mp\->encode($data)""" 4
.el .IP "\f(CW$packed = $mp\->encode($data)\fR" 4
.IX Item "$packed = $mp->encode($data)"
.PD
Same as \f(CW\*(C`Data::MessagePack\->pack()\*(C'\fR, but properties are respected.
.ie n .IP """$data = $mp\->unpack($data)""" 4
.el .IP "\f(CW$data = $mp\->unpack($data)\fR" 4
.IX Item "$data = $mp->unpack($data)"
.PD 0
.ie n .IP """$data = $mp\->decode($data)""" 4
.el .IP "\f(CW$data = $mp\->decode($data)\fR" 4
.IX Item "$data = $mp->decode($data)"
.PD
Same as \f(CW\*(C`Data::MessagePack\->unpack()\*(C'\fR, but properties are respected.
.SH "Configuration Variables (DEPRECATED)"
.IX Header "Configuration Variables (DEPRECATED)"
.ie n .IP $Data::MessagePack::PreferInteger 4
.el .IP \f(CW$Data::MessagePack::PreferInteger\fR 4
.IX Item "$Data::MessagePack::PreferInteger"
Packs a string as an integer, when it looks like an integer.
.Sp
This variable is \fBdeprecated\fR.
Use \f(CW\*(C`$msgpack\->prefer_integer\*(C'\fR property instead.
.SH SPEED
.IX Header "SPEED"
This is a result of \fIbenchmark/serialize.pl\fR and \fIbenchmark/deserialize.pl\fR
on my SC440(Linux 2.6.32\-23\-server #37\-Ubuntu SMP).
(You should benchmark them with \fByour\fR data if the speed matters, of course.)
.PP
.Vb 12
\&    \-\- serialize
\&    JSON::XS: 2.3
\&    Data::MessagePack: 0.24
\&    Storable: 2.21
\&    Benchmark: running json, mp, storable for at least 1 CPU seconds...
\&          json:  1 wallclock secs ( 1.00 usr +  0.01 sys =  1.01 CPU) @ 141939.60/s (n=143359)
\&            mp:  1 wallclock secs ( 1.06 usr +  0.00 sys =  1.06 CPU) @ 355500.94/s (n=376831)
\&      storable:  1 wallclock secs ( 1.12 usr +  0.00 sys =  1.12 CPU) @ 38399.11/s (n=43007)
\&                 Rate storable     json       mp
\&    storable  38399/s       \-\-     \-73%     \-89%
\&    json     141940/s     270%       \-\-     \-60%
\&    mp       355501/s     826%     150%       \-\-
\&
\&    \-\- deserialize
\&    JSON::XS: 2.3
\&    Data::MessagePack: 0.24
\&    Storable: 2.21
\&    Benchmark: running json, mp, storable for at least 1 CPU seconds...
\&          json:  0 wallclock secs ( 1.05 usr +  0.00 sys =  1.05 CPU) @ 179442.86/s (n=188415)
\&            mp:  0 wallclock secs ( 1.01 usr +  0.00 sys =  1.01 CPU) @ 212909.90/s (n=215039)
\&      storable:  2 wallclock secs ( 1.14 usr +  0.00 sys =  1.14 CPU) @ 114974.56/s (n=131071)
\&                 Rate storable     json       mp
\&    storable 114975/s       \-\-     \-36%     \-46%
\&    json     179443/s      56%       \-\-     \-16%
\&    mp       212910/s      85%      19%       \-\-
.Ve
.SH CAVEAT
.IX Header "CAVEAT"
.SS "Unpacking 64 bit integers"
.IX Subsection "Unpacking 64 bit integers"
This module can unpack 64 bit integers even if your perl does not support them
(i.e. where \f(CW\*(C`perl \-V:ivsize\*(C'\fR is 4), but you cannot calculate these values
unless you use \f(CW\*(C`Math::BigInt\*(C'\fR.
.SH TODO
.IX Header "TODO"
.IP "Error handling" 4
.IX Item "Error handling"
MessagePack cannot deal with complex scalars such as object references,
filehandles, and code references. We should report the errors more kindly.
.IP "Streaming deserializer" 4
.IX Item "Streaming deserializer"
The current implementation of the streaming deserializer does not have internal
buffers while some other bindings (such as Ruby binding) does. This limitation
will astonish those who try to unpack byte streams with an arbitrary buffer size
(e.g. \f(CW\*(C`while(read($socket, $buffer, $arbitrary_buffer_size)) { ... }\*(C'\fR).
We should implement the internal buffer for the unpacker.
.SH FAQ
.IX Header "FAQ"
.IP "Why does Data::MessagePack have pure perl implementations?" 4
.IX Item "Why does Data::MessagePack have pure perl implementations?"
msgpack C library uses C99 feature, VC++6 does not support C99. So pure perl version is needed for VC++ users.
.SH AUTHORS
.IX Header "AUTHORS"
Tokuhiro Matsuno
.PP
Makamaka Hannyaharamitu
.PP
gfx
.SH "THANKS TO"
.IX Header "THANKS TO"
Jun Kuriyama
.PP
Dan Kogai
.PP
FURUHASHI Sadayuki
.PP
hanekomu
.PP
Kazuho Oku
.PP
syohex
.SH LICENSE
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://msgpack.org/> is the official web site for the  MessagePack format.
.PP
Data::MessagePack::Unpacker
.PP
AnyEvent::MPRPC