Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Convert::Bencode_XS(3)User Contributed Perl DocumentatioConvert::Bencode_XS(3)

NAME
       Convert::Bencode_XS - Faster conversions	to/from	Bencode	format

SYNOPSIS
	use Convert::Bencode_XS	qw(bencode bdecode);
	use Data::Dumper;

	print "Serializing:\n",	bencode([123, [''], "XXX"]), "\n\n";

	print Dumper bdecode('d3:fool3:bar4:stube6:numberi123ee');

	__END__
	Serializing:
	li123el0:e3:XXXe

	$VAR1 =	{
	  'number' => '123',
	  'foo'	=> [
		      'bar',
		      'stub'
		   ]
	};

DESCRIPTION
       bencode($stuff)
	   Returns a bencoded string representing what's in $stuff. $stuff can
	   be either a scalar, an array	reference or a hash reference. Every
	   nesting of these data structures is allowed,	other ones will	croak.

       bdecode($bencoded)
	   Returns a Perl data structure: it could be either a scalar, array
	   reference or	hash reference depending on what's in $bencoded.
	   Dictionaries	are converted in hashes, lists in arrays, scalars in
	   strings.  If	$COERCE	(see below) is set to a	false value then
	   scalars encoded like	integers will be cleanse() before being
	   returned so that a re-serialization of the structure	will give back
	   exactly the same bencoded string.

TO COERCE AND TO CLEANSE
       Read on just if you are having problems serializing some	data using
       this module: it should work "as is" for 99% of cases. But if you're
       unlucky enough maybe you	need to	read this chapter.

       The original definition of the Bencode protocol poses some problems
       when ported to languages	other than Python, cause:

       1) there	is a distinction between integers and strings

       2) integers are allowed to be any length.

       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,	bencode() will serialize all
       strings that looks like integers	as integers. Example:

	print bencode("123");
	# outputs "i123e"

       If you don't want this to happen	you can	do this:

	$Convert::Bencode_XS::COERCE = 0; #this	is 1 by	default
	print bencode("123");
	# outputs "3:123"

       Setting $Convert::Bencode_XS::COERCE 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:

	use Convert::Bencode_XS	qw(:all); # imports also cleanse() and $COERCE

	$COERCE	= 0;

	print bencode(123);
	# outputs "i123e"

	my ($num) = "abc123def"	=~ /(\d+)/;
	print bencode($num);
	# outputs "3:123", but we know it is a number!
	cleanse($num);	#  cleanse() to	the rescue!
	print bencode($num);
	# outputs "i123e"

       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.

WHY?
       Convert::Bencode_XS exists for a	couple of reasons, first of all
       performance.  Especially	bdecode() 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.	bencode() 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	"extras" directory in this
       distribution for	benchmarks.

       The second reason is fun	and i wished to	try out	something i learnt
       about XS	programming.

BUGS
   In bencode()
       - No detection of recursive references yet

       Next come not real BUGS but more	liberal	interpretation of the
       protocol:

       - Hashes	keys are forced	to be strings. So if we	find a number we don't
       croak, but we use it as a string.

       - Strings like "007" will be treated as strings and encoded as such

SEE ALSO
       The Bencode format is described at
       http://bitconjurer.org/BitTorrent/protocol.html

       The original Python bencode and bdecode functions can be	found in file
       bencode.py in the BitTorrent sources.

       See also	Convert::Bencode by R. Kyle Murphy for a PurePerl
       implementation.

AUTHOR
       Giulio Motta, <giulienk@cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2003-2006 by Giulio Motta

       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.

perl v5.32.0			  2006-11-12		Convert::Bencode_XS(3)

NAME | SYNOPSIS | DESCRIPTION | TO COERCE AND TO CLEANSE | WHY? | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Convert::Bencode_XS&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help