bencode 0.1.0 → 0.3.0

data/lib/bencode.rb

@@ -1,7 +1,6 @@
-# Thanks to Daniel Martin and all the other lads at ruby-lang for
-# helping me out.
-
-# bencode is a Ruby implementation of the Bencode data serialization 
+# = bencode.rb - Bencode Library
+# 
+# Bencode is a Ruby implementation of the Bencode data serialization 
 # format used in the BitTorrent protocol.
 #
 # == Synopsis
@@ -10,6 +9,45 @@
 #   42.bencode         #=> "i42e"
 #   [1, 2, 3].bencode  #=> "li1ei2ei3ee"
 # 
+# Bencoding (pronounced _bee-encode_) is a simple protocol, consiting of
+# only 4 value types.
+#
+# === Integers ===
+#
+# An integer is encoded an _i_ followed by the numeral itself, followed 
+# by an _e_. Leading zeros are not allowed. Negative values are prefixed
+# with a minus sign.
+#
+#   42.bencode  #=> "i42e"
+#   -2.bencode  #=> "i-2e"
+#   0.bencode   #=> "i0e"
+#
+# === Strings ===
+#   
+# Strings are a sequence of zero or more bytes. It is encoded as 
+# _<length>:<contents>_, where _length_ is the lenth of _contents_. _length_
+# must be non-negative.
+#
+#   "".bencode     #=> "0:"
+#   "foo".bencode  #=> "3:foo"
+#
+# === Lists ===
+#
+# Lists are encoded as _l_ followed by the elements, followed by _e_.
+# There is no element seperator.
+#
+#   [1, 2, 3].bencode  #=> "li1ei2ei3ee"
+#
+# === Dictionaries ===
+#
+# Dictionaries are encoded as _d<contents>e_, where _contents_ is a sequence
+# of keys and values. Each value is immediately preceded by a key. Keys must
+# be strings, and will appear in lexicographical order.
+#
+#   {"foo" => 3, "bar" => 1, "baz" => 2}.bencode  
+#     #=> "d3:bari1e3:bazi2e3:fooi3ee"
+# 
+# 
 # == Authors
 #
 # * Daniel Schierbeck
@@ -29,6 +67,7 @@
 # Bencode 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 the GNU General Public License for more details.
+#
 
 class Object
   # Raises an exception. Subclasses of Object must themselves
@@ -133,28 +172,16 @@ class BencodeError < StandardError
   end
 end
 
-class BdecodeError < StandardError
-  attr_reader :pos
-
-  def initialize(pos = nil) # :nodoc:
-    @pos = pos
-  end
-
-  def to_s # :nodoc:
-    if pos.nil?
-      "syntax error"
-    else
-      "syntax error near position #{pos}"
-    end
-  end
-end
+class BdecodeError < StandardError; end
 
 module Bencode
   class << self
+    # Bencodes +obj+
     def dump(obj)
       obj.bencode
     end
 
+    # Bdecodes +str+
     def load(str)
       require 'strscan'
 
@@ -164,6 +191,7 @@ module Bencode
       return obj
     end
 
+    # Bdecodes the file located at +path+
     def load_file(path)
       load(File.open(path).read)
     end
@@ -171,12 +199,10 @@ module Bencode
     def parse(scanner) # :nodoc:
       case token = scanner.scan(/[ild]|\d+:|\s/)
       when nil
-        raise BdecodeError, scanner.pos
+        raise BdecodeError
       when "i"
         number = scanner.scan(/0|(?:-?[1-9][0-9]*)/)
-        unless number and scanner.scan(/e/)
-          raise BdecodeError, scanner.pos
-        end
+        raise BdecodeError unless number and scanner.scan(/e/)
         return number.to_i
       when "l"
         ary = []
@@ -189,10 +215,7 @@ module Bencode
         hsh = {}
         until scanner.peek(1) == "e"
           key, value = parse(scanner), parse(scanner)
-          unless key.is_a? String
-            raise BdecodeError, "error at #{scanner.pos}: " + 
-                                "key must be a string"
-          end
+          raise BdecodeError, "key must be a string" unless key.is_a? String
           hsh.store(key, value)
         end
         scanner.pos += 1
@@ -205,7 +228,7 @@ module Bencode
       when /\s/
         nil
       else
-        raise BdecodeError, scanner.pos
+        raise BdecodeError
       end
     end
 

data/test/tc_bdecode.rb

@@ -1,5 +1,6 @@
 
 require 'test/unit'
+require 'rubygems'
 require 'bencode'
 
 class BdecodeTest < Test::Unit::TestCase

data/test/tc_bencode.rb

@@ -1,5 +1,6 @@
 
-require 'unit/test'
+require 'test/unit'
+require 'rubygems'
 require 'bencode'
 
 class BencodeTest < Test::Unit::TestCase

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.0
 specification_version: 1
 name: bencode
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-09-17 00:00:00 +02:00
-summary: Serialize and unserialize data to and from the Bencode format
+  version: 0.3.0
+date: 2006-09-29 00:00:00 +02:00
+summary: A Ruby implementation of the Bencode encoding used by BitTorrent
 require_paths: 
 - lib
 email: 
@@ -25,15 +25,16 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Daniel Schierbeck
 files: 
 - lib/bencode.rb
-- test/tc_bdecode.rb
 - test/tc_bencode.rb
-test_files: 
 - test/tc_bdecode.rb
+test_files: 
 - test/tc_bencode.rb
+- test/tc_bdecode.rb
 rdoc_options: []
 
 extra_rdoc_files: []