Convert::Bencode_XS(3pm)

1Convert::Bencode_XS(3)User Contributed Perl DocumentationConvert::Bencode_XS(3)
2
3
4

NAME

6       Convert::Bencode_XS - Faster conversions to/from Bencode format
7

SYNOPSIS

9        use Convert::Bencode_XS qw(bencode bdecode);
10        use Data::Dumper;
11
12        print "Serializing:\n", bencode([123, [''], "XXX"]), "\n\n";
13
14        print Dumper bdecode('d3:fool3:bar4:stube6:numberi123ee');
15
16        __END__
17        Serializing:
18        li123el0:e3:XXXe
19
20        $VAR1 = {
21          'number' => '123',
22          'foo' => [
23                      'bar',
24                      'stub'
25                   ]
26        };
27

DESCRIPTION

29       bencode($stuff)
30           Returns a bencoded string representing what's in $stuff. $stuff can
31           be either a scalar, an array reference or a hash reference. Every
32           nesting of these data structures is allowed, other ones will croak.
33
34       bdecode($bencoded)
35           Returns a Perl data structure: it could be either a scalar, array
36           reference or hash reference depending on what's in $bencoded.
37           Dictionaries are converted in hashes, lists in arrays, scalars in
38           strings.  If $COERCE (see below) is set to a false value then
39           scalars encoded like integers will be cleanse() before being
40           returned so that a re-serialization of the structure will give back
41           exactly the same bencoded string.
42

TO COERCE AND TO CLEANSE

44       Read on just if you are having problems serializing some data using
45       this module: it should work "as is" for 99% of cases. But if you're
46       unlucky enough maybe you need to read this chapter.
47
48       The original definition of the Bencode protocol poses some problems
49       when ported to languages other than Python, cause:
50
51       1) there is a distinction between integers and strings
52
53       2) integers are allowed to be any length.
54
55       This is kinda contradictory so we have to come up with specialized
56       solutions to serialize certain types of data. For instance, strings
57       that looks like integers. This is cause there is little distinction
58       between the two in Perl. So, by default, bencode() will serialize all
59       strings that looks like integers as integers. Example:
60
61        print bencode("123");
62        # outputs "i123e"
63
64       If you don't want this to happen you can do this:
65
66        $Convert::Bencode_XS::COERCE = 0; #this is 1 by default
67        print bencode("123");
68        # outputs "3:123"
69
70       Setting $Convert::Bencode_XS::COERCE to a false value will serialize
71       everything that is a string as a string. But what about numbers? If
72       they are hardcoded into your program there should be no problem.
73       Otherwise you need to cleanse them. Example:
74
75        use Convert::Bencode_XS qw(:all); # imports also cleanse() and $COERCE
76
77        $COERCE = 0;
78
79        print bencode(123);
80        # outputs "i123e"
81
82        my ($num) = "abc123def" =~ /(\d+)/;
83        print bencode($num);
84        # outputs "3:123", but we know it is a number!
85        cleanse($num);  #  cleanse() to the rescue!
86        print bencode($num);
87        # outputs "i123e"
88
89       Problems may arise if you want to use a arbitrary sequence of integers
90       as a real integer, mainly because it could surpass the maximum allowed
91       by your platform. (At the moment there is no solution for that). See
92       the tests in this distribution to have a better idea of what works and
93       what not.
94

WHY?

96       Convert::Bencode_XS exists for a couple of reasons, first of all
97       performance.  Especially bdecode() is between 10 and 200 times faster
98       than Convert::Bencode version (depending on file): the great speed
99       increase is in part due to the iterative algorithm used. bencode() is
100       written in C for better performance, but it still uses a recursive
101       algorithm. It manages to be around 3 to 5 times faster than
102       Convert::Bencode version.  Check out the "extras" directory in this
103       distribution for benchmarks.
104
105       The second reason is fun and i wished to try out something i learnt
106       about XS programming.
107

BUGS

109   In bencode()
110       - No detection of recursive references yet
111
112       Next come not real BUGS but more liberal interpretation of the
113       protocol:
114
115       - Hashes keys are forced to be strings. So if we find a number we don't
116       croak, but we use it as a string.
117
118       - Strings like "007" will be treated as strings and encoded as such
119

AUTHOR

131       Giulio Motta, <giulienk@cpan.org>
132

COPYRIGHT AND LICENSE

134       Copyright (C) 2003-2006 by Giulio Motta
135
136       This library is free software; you can redistribute it and/or modify it
137       under the same terms as Perl itself, either Perl version 5.8.1 or, at
138       your option, any later version of Perl 5 you may have available.
139
140
141
142perl v5.30.1                      2020-01-29            Convert::Bencode_XS(3)