=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Protocol::BEP03::Bencode - BitTorrent Bencode Encoder/Decoder

=head1 SYNOPSIS

    use Net::BitTorrent::Protocol::BEP03::Bencode qw[bencode bdecode];

    my $raw = bencode( { a => [1, 2, 3] } );
    my $data = bdecode( $raw );

=head1 DESCRIPTION

Bencoding is the BitTorrent protocol's basic serialization and data organization format. The specification supports
integers, lists (arrays), dictionaries (hashes), and byte strings. This module implements the format used for metadata
and protocol messages.

=head1 FUNCTIONS

By default, nothing is exported. You may import any of the following functions by name or with the C<:all> tag.

=head2 C<bencode( $data )>

Encodes a Perl data structure into a bencoded string.

    my $raw = bencode( { a => [1, 2, 3] } );

This method handles scalars (strings and integers), array references, and hash references.

Expected parameters:

=over

=item C<$data>

The Perl data structure to encode (basic scalar, array reference, or hash reference).

=back

=head2 C<bdecode( $string, [$want_leftover] )>

Decodes a bencoded string into a Perl data structure.

    my $data = bdecode( $raw );

Expected parameters:

=over

=item C<$string>

The bencoded binary string.

=item C<$want_leftover> - optional

If true, returns a list containing the decoded data and the remaining string.

=back

This function will C<die> on malformed data.

=head1 SEE ALSO

=over

=item The BitTorrent Protocol Specification

L<https://bittorrent.org/beps/bep_0003.html>

=back

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut
