bindata 0.9.0 → 0.9.1

data/ChangeLog

@@ -1,5 +1,11 @@
 = BinData Changelog
 
+== Version 0.9.1 (2008-06-15)
+
+* Implemented bit fields.
+* Added :onlyif parameter to Base for specifying optional fields.
+* Fixed IO offset bug with SingleValues.
+
 == Version 0.9.0 (2008-06-02)
 
 * Added :adjust_offset option to automatically seek to a given offset.
@@ -7,14 +13,14 @@
 * Choice now accepts sparse arrays and hashes as :choice.
 * Added BinData::Rest to help with debugging.
 * Major internal restructuring - memory usage is much better.
-* Improved documentation
+* Improved documentation.
 
 == Version 0.8.1 (2008-01-14)
 
 * Reduced memory consumption.
 * Increased execution speed.
-* Deprecated BinData::Base.parameters
-* Fixed spec syntax (thanks to David Goodlad)
+* Deprecated BinData::Base.parameters.
+* Fixed spec syntax (thanks to David Goodlad).
 
 == Version 0.8.0 (2007-10-14)
 

data/README

@@ -175,6 +175,16 @@ BinData::Uint32be:: Unsigned 32 bit integer (big endian).
 BinData::Uint64le:: Unsigned 64 bit integer (little endian).
 BinData::Uint64be:: Unsigned 64 bit integer (big endian).
 
+BinData::Bit1::     1 bit unsigned integer (big endian).
+BinData::Bit2::     2 bit unsigned integer (big endian).
+...
+BinData::Bit63::    63 bit unsigned integer (big endian).
+
+BinData::Bit1le::   1 bit unsigned integer (little endian).
+BinData::Bit2le::   2 bit unsigned integer (little endian).
+...
+BinData::Bit63le::  63 bit unsigned integer (little endian).
+
 BinData::FloatLe::  Single precision floating point number (little endian).
 BinData::FloatBe::  Single precision floating point number (big endian).
 BinData::DoubleLe:: Double precision floating point number (little endian).

data/examples/gzip.rb

@@ -10,59 +10,46 @@ class Gzip
   DEFLATE = 8
 
   class Extra < BinData::MultiValue
-    uint16le :len,  :length => lambda { data.length }
-    string   :data, :read_length => :len
+    endian :little
+
+    uint16 :len,  :length => lambda { data.length }
+    string :data, :read_length => :len
   end
 
   class Header < BinData::MultiValue
-    uint16le :ident,      :value => 0x8b1f, :check_value => 0x8b1f
-    uint8    :compression_method, :initial_value => DEFLATE
-    uint8    :flags,      :value => :calculate_flags_val,
-                          # Upper 3 bits must be zero
-                          :check_value => lambda { (value & 0xe0) == 0 }
-    uint32le :mtime
-    uint8    :extra_flags
-    uint8    :os,         :initial_value => 255   # unknown OS
-
-    # These fields are optional depending on the bits in flags
-    extra    :extra,      :readwrite => :extra?
-    stringz  :file_name,  :readwrite => :file_name?
-    stringz  :comment,    :readwrite => :comment?
-    uint16le :crc16,      :readwrite => :crc16?
-
-
-    ## Convenience methods for accessing and manipulating flags
+    endian :little
 
-    attr_writer :text
+    uint16  :ident,      :value => 0x8b1f, :check_value => 0x8b1f
+    uint8   :compression_method, :initial_value => DEFLATE
 
-    # Access bits of flags
-    def text?;      flag_val(0) end
-    def crc16?;     flag_val(1) end
-    def extra?;     flag_val(2) end
-    def file_name?; flag_val(3) end
-    def comment?;   flag_val(4) end
+    bit3    :freserved,  :value => 0, :check_value => 0
+    bit1    :fcomment,   :value => lambda { comment.length > 0 ? 1 : 0 }
+    bit1    :ffile_name, :value => lambda { file_name.length > 0 ? 1 : 0 }
+    bit1    :fextra,     :value => lambda { extra.len > 0 ? 1 : 0 }
+    bit1    :fcrc16,     :value => 0  # see comment below
+    bit1    :ftext
 
-    def flag_val(bit) (flags & (1 << bit)) != 0 end
+    # Never include header crc.  This is because the current versions of the
+    # command-line version of gzip (up through version 1.3.x) do not
+    # support header crc's, and will report that it is a "multi-part gzip
+    # file" and give up.
 
-    # Calculate the value of flags based on current state.
-    def calculate_flags_val
-      ((@text               ? 1 : 0) << 0) |
+    uint32  :mtime
+    uint8   :extra_flags
+    uint8   :os,         :initial_value => 255   # unknown OS
 
-      # Never include header crc.  This is because the current versions of the
-      # command-line version of gzip (up through version 1.3.x) do not
-      # support header crc's, and will report that it is a "multi-part gzip
-      # file" and give up.
-      ((!clear?(:crc16)     ? 0 : 0) << 1) |
-
-      ((!clear?(:extra)     ? 1 : 0) << 2) |
-      ((!clear?(:file_name) ? 1 : 0) << 3) |
-      ((!clear?(:comment)   ? 1 : 0) << 4)
-    end
+    # These fields are optional depending on the bits in flags
+    extra   :extra,      :onlyif => lambda { fextra.nonzero? }
+    stringz :file_name,  :onlyif => lambda { ffile_name.nonzero? }
+    stringz :comment,    :onlyif => lambda { fcomment.nonzero? }
+    uint16  :crc16,      :onlyif => lambda { fcrc16.nonzero? }
   end
 
   class Footer < BinData::MultiValue
-    uint32le :crc32
-    uint32le :uncompressed_size
+    endian :little
+
+    uint32 :crc32
+    uint32 :uncompressed_size
   end
 
   def initialize
@@ -71,8 +58,8 @@ class Gzip
   end
 
   attr_accessor :compressed
-  def_delegators :@header, :file_name=, :file_name, :file_name?
-  def_delegators :@header, :comment=, :comment, :comment?
+  def_delegators :@header, :file_name=, :file_name
+  def_delegators :@header, :comment=, :comment
   def_delegators :@header, :compression_method
   def_delegators :@footer, :crc32, :uncompressed_size
 
@@ -166,7 +153,7 @@ if __FILE__ == $0
                                                    g.uncompressed_size,
                                                    ratio,
                                                    g.file_name]
-  puts "Comment: #{g.comment}" if g.comment?
+  puts "Comment: #{g.comment}" if g.comment != ""
   puts
 
   puts "Executing gzip -l -v"

data/lib/bindata.rb

@@ -2,6 +2,7 @@
 # Copyright (c) 2007,2008 Dion Mendel.
 
 require 'bindata/array'
+require 'bindata/bits'
 require 'bindata/choice'
 require 'bindata/float'
 require 'bindata/int'
@@ -17,5 +18,5 @@ require 'bindata/struct'
 # A declarative way to read and write structured binary data.
 # 
 module BinData
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 end

data/lib/bindata/array.rb

@@ -95,19 +95,6 @@ module BinData
       @element_params  = el_params
     end
 
-    # Clears the element at position +index+.  If +index+ is not given, then
-    # the internal state of the array is reset to that of a newly created
-    # object.
-    def clear(index = nil)
-      if @element_list.nil?
-        # do nothing as the array is already clear
-      elsif index.nil?
-        @element_list = nil
-      else
-        elements[index].clear
-      end
-    end
-
     # Returns if the element at position +index+ is clear?.  If +index+
     # is not given, then returns whether all fields are clear.
     def clear?(index = nil)
@@ -121,49 +108,19 @@ module BinData
       end
     end
 
-    # Reads the values for all fields in this object from +io+.
-    def _do_read(io)
-      if has_param?(:initial_length)
-        elements.each { |f| f.do_read(io) }
-      else # :read_until
+    # Clears the element at position +index+.  If +index+ is not given, then
+    # the internal state of the array is reset to that of a newly created
+    # object.
+    def clear(index = nil)
+      if @element_list.nil?
+        # do nothing as the array is already clear
+      elsif index.nil?
         @element_list = nil
-        loop do
-          element = append_new_element
-          element.do_read(io)
-          variables = { :index => self.length - 1, :element => self.last,
-                        :array => self }
-          finished = eval_param(:read_until, variables)
-          break if finished
-        end
-      end
-    end
-
-    # To be called after calling #do_read.
-    def done_read
-      elements.each { |f| f.done_read }
-    end
-
-    # Writes the values for all fields in this object to +io+.
-    def _write(io)
-      elements.each { |f| f.write(io) }
-    end
-
-    # Returns the number of bytes it will take to write the element at
-    # +index+.  If +index+, then returns the number of bytes required
-    # to write all fields.
-    def _num_bytes(index)
-      if index.nil?
-        elements.inject(0) { |sum, f| sum + f.num_bytes }
       else
-        elements[index].num_bytes
+        elements[index].clear
       end
     end
 
-    # Returns a snapshot of the data in this array.
-    def snapshot
-      elements.collect { |e| e.snapshot }
-    end
-
     # Returns whether this data object contains a single value.  Single
     # value data objects respond to <tt>#value</tt> and <tt>#value=</tt>.
     def single_value?
@@ -175,6 +132,16 @@ module BinData
       []
     end
 
+    # Returns a snapshot of the data in this array.
+    def snapshot
+      elements.collect { |e| e.snapshot }
+    end
+
+    # To be called after calling #do_read.
+    def done_read
+      elements.each { |f| f.done_read }
+    end
+
     # Appends a new element to the end of the array.  If the array contains
     # single_values then the +value+ may be provided to the call.
     # Returns the appended object, or value in the case of single_values.
@@ -256,6 +223,39 @@ module BinData
     #---------------
     private
 
+    # Reads the values for all fields in this object from +io+.
+    def _do_read(io)
+      if has_param?(:initial_length)
+        elements.each { |f| f.do_read(io) }
+      else # :read_until
+        @element_list = nil
+        loop do
+          element = append_new_element
+          element.do_read(io)
+          variables = { :index => self.length - 1, :element => self.last,
+                        :array => self }
+          finished = eval_param(:read_until, variables)
+          break if finished
+        end
+      end
+    end
+
+    # Writes the values for all fields in this object to +io+.
+    def _do_write(io)
+      elements.each { |f| f.do_write(io) }
+    end
+
+    # Returns the number of bytes it will take to write the element at
+    # +index+.  If +index+, then returns the number of bytes required
+    # to write all fields.
+    def _do_num_bytes(index)
+      if index.nil?
+        (elements.inject(0) { |sum, f| sum + f.do_num_bytes }).ceil
+      else
+        elements[index].do_num_bytes
+      end
+    end
+
     # Returns the list of all elements in the array.  The elements
     # will be instantiated on the first call to this method.
     def elements

data/lib/bindata/base.rb

@@ -1,3 +1,4 @@
+require 'bindata/io'
 require 'bindata/lazy'
 require 'bindata/sanitize'
 require 'bindata/registry'
@@ -16,6 +17,9 @@ module BinData
   #
   # [<tt>:readwrite</tt>]     If false, calls to #read or #write will
   #                           not perform any I/O.  Default is true.
+  # [<tt>:onlyif</tt>]        This is an alias for :readwrite.  It is generally
+  #                           used to indicate a data object is optional.
+  #                           not perform any I/O.  Default is true.
   # [<tt>:check_offset</tt>]  Raise an error if the current IO offset doesn't
   #                           meet this criteria.  A boolean return indicates
   #                           success or failure.  Any other return is compared
@@ -116,6 +120,11 @@ module BinData
       def sanitize_parameters(params, *args)
         params = params.dup
 
+        # replace :onlyif with :readwrite
+        if params.has_key?(:onlyif)
+          params[:readwrite] = params.delete(:onlyif)
+        end
+
         # add default parameters
         default_parameters.each do |k,v|
           params[k] = v unless params.has_key?(k)
@@ -198,16 +207,7 @@ module BinData
 
     # Reads data into this data object by calling #do_read then #done_read.
     def read(io)
-      # wrap strings in a StringIO
-      io = StringIO.new(io) if io.respond_to?(:to_str)
-
-      # remove previous method to prevent warnings
-      class << io
-        remove_method(:bindata_mark) if method_defined?(:bindata_mark)
-      end
-
-      # remember the current position in the IO object
-      io.instance_eval "def bindata_mark; #{io.pos}; end"
+      io = BinData::IO.new(io) unless BinData::IO === io
 
       do_read(io)
       done_read
@@ -216,14 +216,49 @@ module BinData
 
     # Reads the value for this data from +io+.
     def do_read(io)
+      raise ArgumentError, "io must be a BinData::IO" unless BinData::IO === io
+
       clear
       check_offset(io)
-      _do_read(io) if eval_param(:readwrite) != false
+
+      if eval_param(:readwrite)
+        _do_read(io)
+      end
     end
 
-    # Writes the value for this data to +io+.
+    # Writes the value for this data to +io+ by calling #do_write.
     def write(io)
-      _write(io) if eval_param(:readwrite) != false
+      io = BinData::IO.new(io) unless BinData::IO === io
+
+      do_write(io)
+      io.flush
+      self
+    end
+
+
+    # Writes the value for this data to +io+.
+    def do_write(io)
+      raise ArgumentError, "io must be a BinData::IO" unless BinData::IO === io
+
+      if eval_param(:readwrite)
+        _do_write(io)
+      end
+    end
+
+    # Returns the number of bytes it will take to write this data by calling
+    # #do_num_bytes.
+    def num_bytes(what = nil)
+      num = do_num_bytes(what)
+      num.ceil
+    end
+
+    # Returns the number of bytes it will take to write this data.
+    def do_num_bytes(what = nil)
+      if eval_param(:readwrite)
+        _do_num_bytes(what)
+      else
+        0
+      end
     end
 
     # Returns the string representation of this data object.
@@ -234,11 +269,6 @@ module BinData
       io.read
     end
 
-    # Returns the number of bytes it will take to write this data.
-    def num_bytes(what = nil)
-      (eval_param(:readwrite) != false) ? _num_bytes(what) : 0
-    end
-
     # Return a human readable representation of this object.
     def inspect
       snapshot.inspect
@@ -277,7 +307,7 @@ module BinData
     # be called from #do_read before performing the reading.
     def check_offset(io)
       if has_param?(:check_offset)
-        actual_offset = io.pos - io.bindata_mark
+        actual_offset = io.offset
         expected = eval_param(:check_offset, :offset => actual_offset)
 
         if not expected
@@ -287,12 +317,12 @@ module BinData
                                "expected '#{expected}'"
         end
       elsif has_param?(:adjust_offset)
-        actual_offset = io.pos - io.bindata_mark
+        actual_offset = io.offset
         expected = eval_param(:adjust_offset)
         if actual_offset != expected
           begin
             seek = expected - actual_offset
-            io.seek(seek, IO::SEEK_CUR)
+            io.seekbytes(seek)
             warn "adjusting stream position by #{seek} bytes" if $VERBOSE
           rescue
             # could not seek so raise an error
@@ -317,46 +347,46 @@ module BinData
       raise NotImplementedError
     end
 
-    # Reads the data for this data object from +io+.
-    def _do_read(io)
+    # Returns whether this data object contains a single value.  Single
+    # value data objects respond to <tt>#value</tt> and <tt>#value=</tt>.
+    def single_value?
       raise NotImplementedError
     end
 
-    # To be called after calling #do_read.
-    def done_read
+    # Returns a list of the names of all fields accessible through this
+    # object.
+    def field_names
       raise NotImplementedError
     end
 
-    # Writes the value for this data to +io+.
-    def _write(io)
+    # Returns a snapshot of this data object.
+    def snapshot
       raise NotImplementedError
     end
 
-    # Returns the number of bytes it will take to write this data.
-    def _num_bytes
+    # To be called after calling #do_read.
+    def done_read
       raise NotImplementedError
     end
 
-    # Returns a snapshot of this data object.
-    def snapshot
+    # Reads the data for this data object from +io+.
+    def _do_read(io)
       raise NotImplementedError
     end
 
-    # Returns whether this data object contains a single value.  Single
-    # value data objects respond to <tt>#value</tt> and <tt>#value=</tt>.
-    def single_value?
+    # Writes the value for this data to +io+.
+    def _do_write(io)
       raise NotImplementedError
     end
 
-    # Returns a list of the names of all fields accessible through this
-    # object.
-    def field_names
+    # Returns the number of bytes it will take to write this data.
+    def _do_num_bytes
       raise NotImplementedError
     end
 
     # Set visibility requirements of methods to implement
-    public :clear, :done_read, :snapshot, :single_value?, :field_names
-    private :_do_read, :_write, :_num_bytes
+    public :clear, :single_value?, :field_names, :snapshot, :done_read
+    private :_do_read, :_do_write, :_do_num_bytes
 
     # End To be implemented by subclasses
     ###########################################################################