.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Convert::Bencode_XS 3pm"
.TH Convert::Bencode_XS 3pm "2006-11-12" "perl v5.34.0" "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"
Convert::Bencode_XS \- Faster conversions to/from Bencode format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Convert::Bencode_XS qw(bencode bdecode);
\& use Data::Dumper;
\& 
\& print "Serializing:\en", bencode([123, [\*(Aq\*(Aq], "XXX"]), "\en\en";
\& 
\& print Dumper bdecode(\*(Aqd3:fool3:bar4:stube6:numberi123ee\*(Aq);
\&
\& _\|_END_\|_
\& Serializing:
\& li123el0:e3:XXXe
\&
\& $VAR1 = {
\&   \*(Aqnumber\*(Aq => \*(Aq123\*(Aq,
\&   \*(Aqfoo\*(Aq => [
\&               \*(Aqbar\*(Aq,
\&               \*(Aqstub\*(Aq
\&            ]
\& };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.IP "bencode($stuff)" 4
.IX Item "bencode($stuff)"
Returns a bencoded string representing what's in \f(CW$stuff\fR. \f(CW$stuff\fR can be
either a scalar, an array reference or a hash reference. Every nesting of
these data structures is allowed, other ones will croak.
.IP "bdecode($bencoded)" 4
.IX Item "bdecode($bencoded)"
Returns a Perl data structure: it could be either a scalar, array reference
or hash reference depending on what's in \f(CW$bencoded\fR. Dictionaries are 
converted in hashes, lists in arrays, scalars in strings. 
If \f(CW$COERCE\fR (see below) is set
to a false value then scalars encoded like integers will be \fBcleanse()\fR before
being returned so that a re-serialization of the structure will give back
exactly the same bencoded string.
.SH "TO COERCE AND TO CLEANSE"
.IX Header "TO COERCE AND TO CLEANSE"
Read on just if you are having problems serializing some data using this module:
it should work \*(L"as is\*(R" for 99% of cases. But if you're unlucky enough
maybe you need to read this chapter.
.PP
The original definition of the Bencode protocol poses some problems 
when ported to
languages other than Python, cause:
.PP
1) there is a distinction between integers and strings
.PP
2) integers are allowed to be any length.
.PP
This is kinda contradictory so we have to come up with specialized 
solutions to serialize certain types of data. For instance, strings that
looks like integers. This is cause there is little distinction between the two
in Perl. So, by default, \fBbencode()\fR will serialize all strings that looks like
integers as integers. Example:
.PP
.Vb 2
\& print bencode("123");
\& # outputs "i123e"
.Ve
.PP
If you don't want this to happen you can do this:
.PP
.Vb 3
\& $Convert::Bencode_XS::COERCE = 0; #this is 1 by default
\& print bencode("123");
\& # outputs "3:123"
.Ve
.PP
Setting \f(CW$Convert::Bencode_XS::COERCE\fR to a false value will serialize everything
that is a string as a string. But what about numbers? If they are hardcoded
into your program
there should be no problem. Otherwise you need to cleanse them. Example:
.PP
.Vb 1
\& use Convert::Bencode_XS qw(:all); # imports also cleanse() and $COERCE
\& 
\& $COERCE = 0;
\&
\& print bencode(123);
\& # outputs "i123e"
\& 
\& my ($num) = "abc123def" =~ /(\ed+)/;
\& print bencode($num);
\& # outputs "3:123", but we know it is a number!
\& cleanse($num);  #  cleanse() to the rescue!
\& print bencode($num);
\& # outputs "i123e"
.Ve
.PP
Problems may arise if you want to use a arbitrary sequence of integers as
a real integer, mainly because it could surpass the maximum allowed by
your platform. (At the moment there is no solution for that). See the tests
in this distribution to have a better idea of what works and what not.
.SH "WHY?"
.IX Header "WHY?"
Convert::Bencode_XS exists for a couple of reasons, first of all performance.
Especially \fBbdecode()\fR is between 10 and 200 times faster than 
Convert::Bencode version (depending on file): 
the great speed increase is in part due to the iterative
algorithm used. \fBbencode()\fR is written in C for better performance, but
it still uses a recursive algorithm. It manages to be
around 3 to 5 times faster than Convert::Bencode version.
Check out the \*(L"extras\*(R" directory in this distribution for benchmarks.
.PP
The second reason is fun and i wished to try out something i learnt about \s-1XS\s0
programming.
.SH "BUGS"
.IX Header "BUGS"
.SS "In \fBbencode()\fP"
.IX Subsection "In bencode()"
\&\- No detection of recursive references yet
.PP
Next come not real \s-1BUGS\s0 but more liberal interpretation of the protocol:
.PP
\&\- Hashes keys are forced to be strings. So if we find a number we don't
croak, but we use it as a string.
.PP
\&\- Strings like \*(L"007\*(R" will be treated as strings and encoded as such
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The Bencode format is described at 
http://bitconjurer.org/BitTorrent/protocol.html
.PP
The original Python bencode and bdecode functions can be found in file
bencode.py in the BitTorrent sources.
.PP
See also Convert::Bencode by R. Kyle Murphy for a PurePerl implementation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Giulio Motta, <giulienk@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003\-2006 by Giulio Motta
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.1 or,
at your option, any later version of Perl 5 you may have available.