#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/bencode:1:1)))
@title[#:version "0.2"]{@bold{bencode}: BitTorrent Bencode Decoding in Scheme}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/bencode-scheme/" #:underline? #f]{http://www.neilvandyke.org/bencode-scheme/}

@defmodule[(planet neil/bencode:1:1)]

      

@section{Introduction}


      

The @bold{bencode} library is for parsing the @italic{bencoding} format of the BitTorrent network protocol into basic Scheme data types (and currently PLT-specific byte strings).  This is useful for inspecting @tt{.torrent} files, and might later be used in the implementation of a BitTorrent client or protocol analyzer.


      

The format interpretation is based on the undated @link["http://www.bittorrent.com/protocol.html"]{BitTorrent protocol documentation Web page} as viewed on 2005-04-17.  The mapping from those bencoding types to Scheme types is:


      

@itemize[

@item{@italic{String}
            

PLT byte string.


          }


@item{@italic{Integer}
            

Scheme integer.


          }


@item{@italic{List}
            

Scheme list.


          }


@item{@italic{Dictionary}
            

Scheme list with the symbol @tt{dictionary} as its head, and an association list as its tail.


          }



]


      

For example, a parse of a certain real-world @tt{.torrent} file:


      

@SCHEMEBLOCK[
(unbencode (open-input-file "debian.torrent"))
==>
((dictionary
  (#"announce"      . #"http://cdimage.debian.org:6969/announce")
  (#"comment"       . #"Debian CD from cdimage.debian.org")
  (#"creation date" . 1105009474)
  (#"info"
   dictionary
   (#"length"       . 600158208)
   (#"name"         . #"debian-30r4-i386-binary-1.iso")
   (#"piece length" . 524288)
   (#"pieces"       . [...large byte string...]))))
]


      

@tt{bencode.scm} is currently specific to PLT 299/3xx, due to the need for byte I/O and some representation for byte sequences.  Otherwise, the code has been written to require only R5RS, SRFI-6, and SRFI-23.


    
      

@section{API}


      

@defproc[(unbencode-single (port any/c)) any/c]{
          

Parses a single bencoding object (and any child objects, in the case of a list or dictionary) from input port @schemevarfont{port} and yields the Scheme representation.


        }

      

@defproc[(unbencode (port any/c)) any/c]{
          

Yields a list of the Scheme representations of all bencoding objects parsed from input port @schemevarfont{port}.


        }

    
      

@section{History}


      

@itemize[

@item{Version 0.2 --- 2009-03-03 -- PLaneT @tt{(1 1)}
            

Library is now LPGL 3.  Converted to author's new Scheme administration system.


          }


@item{Version 0.1 --- 2005-04-17 -- PLaneT @tt{(1 0)}
            

Initial release.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2005-2009 Neil Van Dyke.  This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version.  This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.  See http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.