tnetstring 0.3.0 → 0.3.1

data/lib/tnetstring.rb

@@ -1,4 +1,22 @@
+require 'tnetstring/errors'
+
 module TNetstring
+  # Converts a tnetstring into the encoded data structure.
+  #
+  # It expects a string argument prefixed with a valid tnetstring and
+  # returns a tuple of the parsed object and any remaining string input.
+  #
+  # === Example
+  #
+  #  str = '5:12345#'
+  #  TNetstring.parse(str)
+  #
+  #  #=> [12345, '']
+  #
+  #  str = '11:hello world,abc123'
+  #
+  #  #=> ['hello world', 'abc123']
+  #
   def self.parse(tnetstring)
     payload, payload_type, remain = parse_payload(tnetstring)
     value = case payload_type
@@ -11,7 +29,7 @@ module TNetstring
     when '}'
       parse_dictionary(payload)
     when '~'
-      assert payload.length == 0, "Payload must be 0 length for null."
+      assert payload.length == 0, "Payload must be 0 length for null"
       nil
     when '!'
       parse_boolean(payload)
@@ -21,22 +39,22 @@ module TNetstring
     [value, remain]
   end
 
-  def self.parse_payload(data)
-    assert data, "Invalid data to parse, it's empty."
+  def self.parse_payload(data) # :nodoc:
+    assert data, "Invalid data to parse; it's empty"
     length, extra = data.split(':', 2)
     length = length.to_i
     assert length <= 999_999_999, "Data is longer than the specification allows"
-    assert length >= 0, "Data length cannot be negative!"
+    assert length >= 0, "Data length cannot be negative"
 
     payload, extra = extra[0, length], extra[length..-1]
-    assert extra, "No payload type: %s, %s" % [payload, extra]
+    assert extra, "No payload type: #{payload}, #{extra}"
     payload_type, remain = extra[0,1], extra[1..-1]
 
-    assert payload.length == length, "Data is wrong length %d vs %d" % [length, payload.length]
+    assert payload.length == length, "Data is wrong length: #{length} expected but was #{payload.length}"
     [payload, payload_type, remain]
   end
 
-  def self.parse_list(data)
+  def self.parse_list(data) # :nodoc:
     return [] if data.length == 0
     list = []
     value, remain = parse(data)
@@ -49,7 +67,7 @@ module TNetstring
     list
   end
 
-  def self.parse_dictionary(data)
+  def self.parse_dictionary(data) # :nodoc:
     return {} if data.length == 0
 
     key, value, extra = parse_pair(data)
@@ -62,26 +80,44 @@ module TNetstring
     result
   end
 
-  def self.parse_pair(data)
+  def self.parse_pair(data) # :nodoc:
     key, extra = parse(data)
-    assert extra, "Unbalanced dictionary store."
+    assert key.kind_of?(String), "Dictionary keys must be Strings"
+    assert extra, "Unbalanced dictionary store"
     value, extra = parse(extra)
-    assert value, "Got an invalid value, null not allowed."
+    assert value, "Got an invalid value, null not allowed"
 
     [key, value, extra]
   end
 
-  def self.parse_boolean(data)
+  def self.parse_boolean(data) # :nodoc:
     case data
     when "false"
       false
     when "true"
       true
     else
-      raise "Boolean wasn't 'true' or 'false'"
+      assert false, "Boolean wasn't 'true' or 'false'"
     end
   end
 
+  # Constructs a tnetstring out of the given object. Valid Ruby object types
+  # include strings, integers, boolean values, nil, arrays, and hashes. Arrays
+  # and hashes may contain any of the previous valid Ruby object types, but
+  # hash keys must be strings.
+  #
+  # === Example
+  #
+  #  int = 12345
+  #  TNetstring.encode(int)
+  #
+  #  #=> '5:12345#'
+  #
+  #  hash = {'hello' => 'world'}
+  #  TNetstring.encode(hash)
+  #
+  #  #=> '16:5:hello,5:world,}'
+  #
   def self.encode(obj)
     if obj.kind_of?(Integer)
       int_str = obj.to_s
@@ -98,16 +134,16 @@ module TNetstring
     elsif obj.kind_of?(Hash)
       encode_dictionary(obj)
     else
-      assert false, "Object must be of a primitive type"
+      assert false, "Object must be of a primitive type: #{obj.inspect}"
     end
   end
 
-  def self.encode_list(list)
+  def self.encode_list(list) # :nodoc:
     contents = list.map {|item| encode(item)}.join
     "#{contents.length}:#{contents}]"
   end
 
-  def self.encode_dictionary(dict)
+  def self.encode_dictionary(dict) # :nodoc:
     contents = dict.map do |key, value|
       assert key.kind_of?(String), "Dictionary keys must be Strings"
       "#{encode(key)}#{encode(value)}"
@@ -115,7 +151,7 @@ module TNetstring
     "#{contents.length}:#{contents}}"
   end
 
-  def self.assert(truthy, message)
-    raise message unless truthy
+  def self.assert(truthy, message) # :nodoc:
+    raise ProcessError.new(message) unless truthy
   end
 end

data/lib/tnetstring/errors.rb

@@ -0,0 +1,3 @@
+module TNetstring
+  class ProcessError < StandardError; end
+end

data/lib/tnetstring/version.rb

@@ -1,5 +1,5 @@
 module TNetstring # :nodoc:
   module Version # :nodoc:
-    STRING = '0.3.0'
+    STRING = '0.3.1'
   end
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Matt Yoho
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-16 00:00:00 -04:00
+date: 2011-04-17 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -56,6 +56,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/tnetstring/errors.rb
 - lib/tnetstring/version.rb
 - lib/tnetstring.rb
 has_rdoc: true