bindata 0.11.1 → 1.0.0

data/Rakefile

@@ -10,6 +10,7 @@ PKG_FILES = FileList[
   "{examples,spec,lib}/**/*.rb",
   "tasks/**/*.rake",
   "setup.rb",
+  "manual.haml",
 ]
 
 task :default => :spec

data/TODO

@@ -1,22 +1,6 @@
-== Documentation
-
-* Write a detailed tutorial (probably as a web page).
-
-* Need more examples.
-
 == Pending refactorings
 
 * Refactor registry into registry and numeric registry
     update specs accordingly
 
 * Perhaps refactor snapshot -> _snapshot et al
-
-== Bugs
-
-class A < BinData::Record
-  array :a, :type => :unknown
-end
-
-should give correct error message
-
-

data/examples/ip_address.rb

@@ -0,0 +1,23 @@
+require 'bindata'
+
+# A custom type representing an IP address.
+# The underlying binary representation is a sequence of four octets.
+# The human accessible representation is a dotted quad.
+class IPAddr < BinData::Primitive
+  array :octets, :type => :uint8, :initial_length => 4
+
+  def set(val)
+    ints = val.split(/\./).collect { |int| int.to_i }
+    self.octets = ints
+  end
+
+  def get
+    self.octets.collect { |octet| "%d" % octet }.join(".")
+  end
+end
+
+ip = IPAddr.new
+ip.value = "127.0.0.1"
+
+puts "human readable value:  #{ip}"                     #=> 127.0.0.1
+puts "binary representation: #{ip.to_binary_s.inspect}" #=> "\177\000\000\001"

data/lib/bindata.rb

@@ -20,6 +20,14 @@ require 'bindata/deprecated'
 # 
 # A declarative way to read and write structured binary data.
 # 
+# A full reference manual is available online at
+# http://bindata.rubyforge.org.
+#
+# == License
+#
+# BinData is released under the same license as Ruby.
+#
+# Copyright (c) 2007 - 2009 Dion Mendel.
 module BinData
-  VERSION = "0.11.1"
+  VERSION = "1.0.0"
 end

data/lib/bindata/array.rb

@@ -62,7 +62,7 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(params, sanitizer)
+      def sanitize_parameters!(params, sanitizer) #:nodoc:
         unless params.has_parameter?(:initial_length) or
                  params.has_parameter?(:read_until)
           # ensure one of :initial_length and :read_until exists
@@ -213,18 +213,16 @@ module BinData
       elements.each { |el| yield el }
     end
 
-    def debug_name_of(child)
+    def debug_name_of(child) #:nodoc:
       index = find_index_of(child)
       "#{debug_name}[#{index}]"
     end
 
-    def offset_of(child)
+    def offset_of(child) #:nodoc:
       index = find_index_of(child)
       sum = sum_num_bytes_below_index(index)
 
-      child_offset = child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
-
-      offset + child_offset
+      child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
     end
 
     #---------------
@@ -293,7 +291,7 @@ module BinData
       elements.each { |el| el.do_write(io) }
     end
 
-    def _do_num_bytes(deprecated)
+    def _do_num_bytes
       sum_num_bytes_for_all_elements.ceil
     end
 

data/lib/bindata/base.rb

@@ -3,7 +3,6 @@ require 'bindata/lazy'
 require 'bindata/params'
 require 'bindata/registry'
 require 'bindata/sanitize'
-require 'stringio'
 
 module BinData
   # Error raised when unexpected results occur when reading data from IO.
@@ -70,7 +69,7 @@ module BinData
         @accepted_parameters
       end
 
-      def sanitize_parameters!(params, sanitizer)
+      def sanitize_parameters!(params, sanitizer) #:nodoc:
       end
 
       #-------------
@@ -133,13 +132,13 @@ module BinData
       self
     end
 
-    def do_read(io)
+    def do_read(io) #:nodoc:
       check_or_adjust_offset(io)
       clear
       _do_read(io)
     end
 
-    def done_read
+    def done_read #:nodoc:
       _done_read
     end
     protected :do_read, :done_read
@@ -153,19 +152,18 @@ module BinData
       self
     end
 
-    def do_write(io)
+    def do_write(io) #:nodoc:
       _do_write(io)
     end
     protected :do_write
 
     # Returns the number of bytes it will take to write this data.
-    def num_bytes(deprecated = nil)
-      num = do_num_bytes(deprecated)
-      num.ceil
+    def num_bytes
+      do_num_bytes.ceil
     end
 
-    def do_num_bytes(deprecated = nil)
-      _do_num_bytes(deprecated)
+    def do_num_bytes #:nodoc:
+      _do_num_bytes
     end
     protected :do_num_bytes
 
@@ -182,7 +180,7 @@ module BinData
 
     # Returns the string representation of this data object.
     def to_binary_s
-      io = StringIO.new
+      io = BinData::IO.create_string_io
       write(io)
       io.rewind
       io.read
@@ -198,6 +196,11 @@ module BinData
       snapshot.to_s
     end
 
+    # Work with Ruby's pretty-printer library.
+    def pretty_print(pp) #:nodoc:
+      pp.pp(snapshot)
+    end
+
     # Returns a user friendly name of this object for debugging purposes.
     def debug_name
       if parent
@@ -209,6 +212,15 @@ module BinData
 
     # Returns the offset of this object wrt to its most distant ancestor.
     def offset
+      if parent
+        parent.offset + parent.offset_of(self)
+      else
+        0
+      end
+    end
+
+    # Returns the offset of this object wrt to its parent.
+    def rel_offset
       if parent
         parent.offset_of(self)
       else
@@ -216,7 +228,7 @@ module BinData
       end
     end
 
-    def ==(other)
+    def ==(other) #:nodoc:
       # double dispatch
       other == snapshot
     end
@@ -276,14 +288,14 @@ module BinData
 
     # Returns the debug name of +child+.  This only needs to be implemented
     # by objects that contain child objects.
-    def debug_name_of(child)
-      raise NotImplementedError
+    def debug_name_of(child) #:nodoc:
+      debug_name
     end
 
     # Returns the offset of +child+.  This only needs to be implemented
     # by objects that contain child objects.
-    def offset_of(child)
-      raise NotImplementedError
+    def offset_of(child) #:nodoc:
+      0
     end
 
     # Reads the data for this data object from +io+.
@@ -302,7 +314,7 @@ module BinData
     end
 
     # Returns the number of bytes it will take to write this data.
-    def _do_num_bytes(deprecated)
+    def _do_num_bytes
       raise NotImplementedError
     end
 

data/lib/bindata/base_primitive.rb

@@ -58,12 +58,12 @@ module BinData
       @in_read = false
     end
 
-    def clear
+    def clear #:nodoc:
       @value = nil
       @in_read = false
     end
 
-    def clear?
+    def clear? #:nodoc:
       @value.nil?
     end
 
@@ -77,11 +77,11 @@ module BinData
       assign(val)
     end
 
-    def respond_to?(symbol, include_private=false)
+    def respond_to?(symbol, include_private=false) #:nodoc:
       super || value.respond_to?(symbol, include_private)
     end
 
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, *args, &block) #:nodoc:
       if value.respond_to?(symbol)
         value.__send__(symbol, *args, &block)
       else
@@ -144,7 +144,7 @@ module BinData
       io.writebytes(value_to_binary_string(_value))
     end
 
-    def _do_num_bytes(ignored)
+    def _do_num_bytes
       value_to_binary_string(_value).length
     end
 

data/lib/bindata/bits.rb

@@ -45,7 +45,7 @@ module BinData
           io.writebits(_value, #{nbits}, :#{endian})
         end
 
-        def _do_num_bytes(ignored)
+        def _do_num_bytes
           #{nbits} / 8.0
         end
 

data/lib/bindata/choice.rb

@@ -61,7 +61,7 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(params, sanitizer)
+      def sanitize_parameters!(params, sanitizer) #:nodoc:
         if params.needs_sanitizing?(:choices)
           choices = choices_as_hash(params[:choices])
           ensure_valid_keys(choices)
@@ -137,27 +137,19 @@ module BinData
       raise NoMethodError
     end
 
-    def clear
+    def clear #:nodoc:
       current_choice.clear
     end
 
-    def clear?
+    def clear? #:nodoc:
       current_choice.clear?
     end
 
-    def debug_name_of(child)
-      debug_name
-    end
-
-    def offset_of(child)
-      offset
-    end
-
-    def respond_to?(symbol, include_private = false)
+    def respond_to?(symbol, include_private = false) #:nodoc:
       super || current_choice.respond_to?(symbol, include_private)
     end
 
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, *args, &block) #:nodoc:
       current_choice.__send__(symbol, *args, &block)
     end
 
@@ -188,8 +180,8 @@ module BinData
       current_choice.do_write(io)
     end
 
-    def _do_num_bytes(deprecated)
-      current_choice.do_num_bytes(deprecated)
+    def _do_num_bytes
+      current_choice.do_num_bytes
     end
 
     def _assign(val)

data/lib/bindata/deprecated.rb

@@ -1,148 +1,17 @@
 module BinData
-  class Base
-    def single_value?
-      warn "#single_value? is deprecated.  It should no longer be needed"
-      false
-    end
-  end
-
-  class SingleValue < Primitive
+  class SingleValue
     class << self
       def inherited(subclass) #:nodoc:
-        warn "BinData::SingleValue is deprecated.  Replacing with BinData::Primitive"
-        super
+        fail "BinData::SingleValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData 1.0.0"
       end
     end
   end
 
-  class MultiValue < Record
+  class MultiValue
     class << self
       def inherited(subclass) #:nodoc:
-        warn "BinData::MultiValue is deprecated.  Replacing with BinData::Record"
-        super
-      end
-    end
-  end
-
-  class Registry
-    def Registry.instance #:nodoc:
-      warn "'Registry.instance' is deprecated.  Replacing with 'RegisteredClasses'"
-      RegisteredClasses
-    end
-  end
-
-  class Array
-    alias_method :orig_clear?, :clear?
-    def clear?(index = nil) #:nodoc:
-      if index.nil?
-        orig_clear?
-      elsif index < elements.length
-        warn "'obj.clear?(n)' is deprecated.  Replacing with 'obj[n].clear?'"
-        elements[index].clear?
-      else
-        true
-      end
-    end
-
-    alias_method :orig_clear, :clear
-    def clear(index = nil) #:nodoc:
-      if index.nil?
-        orig_clear
-      elsif index < elements.length
-        warn "'obj.clear(n)' is deprecated.  Replacing with 'obj[n].clear'"
-        elements[index].clear
-      end
-    end
-
-    alias_method :orig__do_num_bytes, :_do_num_bytes
-    def _do_num_bytes(index) #:nodoc:
-      if index.nil?
-        orig__do_num_bytes(nil)
-      elsif index < elements.length
-        warn "'obj.num_bytes(n)' is deprecated.  Replacing with 'obj[n].num_bytes'"
-        elements[index].do_num_bytes
-      else
-        0
-      end
-    end
-
-    def append(value = nil) #:nodoc:
-      warn "#append is deprecated, use push or slice instead"
-      if value.nil?
-        slice(length)
-      else
-        push(value)
-      end
-      self.last
-    end
-  end
-
-  class String < BinData::BasePrimitive
-    class << self
-      def deprecate!(params, old_key, new_key) #:nodoc:
-        if params.has_parameter?(old_key)
-          warn ":#{old_key} is deprecated. Replacing with :#{new_key}"
-          params[new_key] = params.delete(old_key)
-        end
-      end
-
-      alias_method :orig_sanitize_parameters!, :sanitize_parameters!
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
-        deprecate!(params, :trim_value, :trim_padding)
-        orig_sanitize_parameters!(params, sanitizer)
-      end
-    end
-  end
-
-
-  class Struct < BinData::Base
-    class << self
-      def inherited(subclass) #:nodoc:
-        if subclass != Record
-          fail "error: inheriting from BinData::Struct has been deprecated. Inherit from BinData::Record instead."
-        end
-      end
-    end
-
-    alias_method :orig_clear, :clear
-    def clear(name = nil) #:nodoc:
-      if name.nil?
-        orig_clear
-      else
-        warn "'obj.clear(name)' is deprecated.  Replacing with 'obj.name.clear'"
-        obj = find_obj_for_name(name)
-        obj.clear unless obj.nil?
-      end
-    end
-
-    alias_method :orig_clear?, :clear?
-    def clear?(name = nil) #:nodoc:
-      if name.nil?
-        orig_clear?
-      else
-        warn "'obj.clear?(name)' is deprecated.  Replacing with 'obj.name.clear?'"
-        obj = find_obj_for_name(name)
-        obj.nil? ? true : obj.clear?
-      end
-    end
-
-    alias_method :orig__do_num_bytes, :_do_num_bytes
-    def _do_num_bytes(name) #:nodoc:
-      if name.nil?
-        orig__do_num_bytes(nil)
-      else
-        warn "'obj.num_bytes(name)' is deprecated.  Replacing with 'obj.name.num_bytes'"
-        obj = find_obj_for_name(name)
-        obj.nil? ? 0 : obj.do_num_bytes
-      end
-    end
-
-    alias_method :orig_offset_of, :offset_of
-    def offset_of(child)
-      if child.is_a?(::String) or child.is_a?(Symbol)
-        fail "error: 'offset_of(#{child.inspect})' is deprecated.  Use '#{child.to_s}.offset' instead"
+        fail "BinData::MultiValue is deprecated.  Downgrade to BinData 0.11.1.\nYou will need to make changes to your code before you can use BinData 1.0.0"
       end
-      orig_offset_of(child)
     end
   end
 end