bindata 1.2.2 → 1.3.1

data/lib/bindata.rb

@@ -1,5 +1,5 @@
 # BinData -- Binary data manipulator.
-# Copyright (c) 2007 - 2010 Dion Mendel.
+# Copyright (c) 2007 - 2011 Dion Mendel.
 
 require 'bindata/array'
 require 'bindata/bits'
@@ -15,6 +15,7 @@ require 'bindata/stringz'
 require 'bindata/struct'
 require 'bindata/trace'
 require 'bindata/wrapper'
+require 'bindata/alignment'
 require 'bindata/deprecated'
 
 # = BinData
@@ -28,7 +29,7 @@ require 'bindata/deprecated'
 #
 # BinData is released under the same license as Ruby.
 #
-# Copyright (c) 2007 - 2010 Dion Mendel.
+# Copyright (c) 2007 - 2011 Dion Mendel.
 module BinData
-  VERSION = "1.2.2"
+  VERSION = "1.3.1"
 end

data/lib/bindata/alignment.rb

@@ -0,0 +1,86 @@
+require 'bindata/base_primitive'
+
+module BinData
+  # Resets the stream alignment to the next byte.  This is
+  # only useful when using bit-based primitives.
+  #
+  #    class MyRec < BinData::Record
+  #      bit4 :a
+  #      resume_byte_alignment
+  #      bit4 :b
+  #    end
+  #
+  #    MyRec.read("\x12\x34") #=> {"a" => 1, "b" => 3}
+  #
+  class ResumeByteAlignment < BinData::Base
+    register_self
+
+    def clear; end
+    def clear?; true; end
+    def assign(val); end
+    def snapshot; nil; end
+    def do_num_bytes; 0; end
+
+    def do_read(io)
+      io.reset_read_bits
+    end
+
+    def do_write(io)
+      io.flushbits
+    end
+  end
+
+  # A monkey patch to force byte-aligned primitives to
+  # become bit-aligned.  This allows them to be used at
+  # non byte based boundaries.
+  #
+  #     class BitString < BinData::String
+  #       bit_aligned
+  #     end
+  #
+  #     class MyRecord < BinData::Record
+  #       bit4       :preamble
+  #       bit_string :str, :length => 2
+  #     end
+  #
+  module BitAligned
+    class BitAlignedIO
+      def initialize(io)
+        @io = io
+      end
+      def readbytes(n)
+        n.times.inject("") do |bytes, i|
+          bytes + @io.readbits(8, :big).chr
+        end
+      end
+      def method_missing(sym, *args, &block)
+        @io.send(sym, *args, &block)
+      end
+    end
+
+    def read_and_return_value(io)
+      super(BitAlignedIO.new(io))
+    end
+
+    def do_num_bytes
+      super.to_f
+    end
+
+    def do_write(io)
+      value_to_binary_string(_value).each_byte { |v| io.writebits(v, 8, :big) }
+    end
+  end
+
+  class BasePrimitive < BinData::Base
+    def self.bit_aligned
+      include BitAligned
+      register_self
+    end
+  end
+
+  class Primitive < BinData::BasePrimitive
+    def self.bit_aligned
+      fail "'bit_aligned' is not needed for BinData::Primitives"
+    end
+  end
+end

data/lib/bindata/array.rb

@@ -8,27 +8,22 @@ module BinData
   #   data = "\x03\x04\x05\x06\x07\x08\x09"
   #
   #   obj = BinData::Array.new(:type => :int8, :initial_length => 6)
-  #   obj.read(data)
-  #   obj.snapshot #=> [3, 4, 5, 6, 7, 8]
+  #   obj.read(data) #=> [3, 4, 5, 6, 7, 8]
   #
   #   obj = BinData::Array.new(:type => :int8,
   #                            :read_until => lambda { index == 1 })
-  #   obj.read(data)
-  #   obj.snapshot #=> [3, 4]
+  #   obj.read(data) #=> [3, 4]
   #
   #   obj = BinData::Array.new(:type => :int8,
   #                            :read_until => lambda { element >= 6 })
-  #   obj.read(data)
-  #   obj.snapshot #=> [3, 4, 5, 6]
+  #   obj.read(data) #=> [3, 4, 5, 6]
   #
   #   obj = BinData::Array.new(:type => :int8,
   #           :read_until => lambda { array[index] + array[index - 1] == 13 })
-  #   obj.read(data)
-  #   obj.snapshot #=> [3, 4, 5, 6, 7]
+  #   obj.read(data) #=> [3, 4, 5, 6, 7]
   #
   #   obj = BinData::Array.new(:type => :int8, :read_until => :eof)
-  #   obj.read(data)
-  #   obj.snapshot #=> [3, 4, 5, 6, 7, 8, 9]
+  #   obj.read(data) #=> [3, 4, 5, 6, 7, 8, 9]
   #
   # == Parameters
   #
@@ -78,13 +73,14 @@ module BinData
       end
     end
 
-    def initialize(parameters = {}, parent = nil)
-      super
-
-      @element_list      = nil
+    def initialize_shared_instance
       @element_prototype = get_parameter(:type)
     end
 
+    def initialize_instance
+      @element_list = nil
+    end
+
     def clear?
       @element_list.nil? or elements.all? { |el| el.clear? }
     end
@@ -247,7 +243,7 @@ module BinData
     end
 
     def do_num_bytes #:nodoc:
-      sum_num_bytes_for_all_elements.ceil
+      sum_num_bytes_for_all_elements
     end
 
     #---------------
@@ -261,13 +257,7 @@ module BinData
     end
 
     def to_storage_formats(els)
-      els.collect { |el| to_storage_format(el) }
-    end
-
-    def to_storage_format(obj)
-      element = new_element
-      element.assign(obj)
-      element
+      els.collect { |el| new_element(el) }
     end
 
     def read_until(io)
@@ -318,8 +308,8 @@ module BinData
       element
     end
 
-    def new_element
-      @element_prototype.instantiate(self)
+    def new_element(value = nil)
+      @element_prototype.instantiate(value, self)
     end
 
     def sum_num_bytes_for_all_elements
@@ -327,13 +317,15 @@ module BinData
     end
 
     def sum_num_bytes_below_index(index)
-      sum = 0
-      (0...index).each do |i|
+      (0...index).inject(0) do |sum, i|
         nbytes = elements[i].do_num_bytes
-        sum = (nbytes.is_a?(Integer) ? sum.ceil : sum) + nbytes
-      end
 
-      sum
+        if nbytes.is_a?(Integer)
+          (sum + nbytes).ceil
+        else
+          sum + nbytes
+        end
+      end
     end
   end
 end

data/lib/bindata/base.rb

@@ -1,5 +1,6 @@
 require 'bindata/io'
 require 'bindata/lazy'
+require 'bindata/offset'
 require 'bindata/params'
 require 'bindata/registry'
 require 'bindata/sanitize'
@@ -8,39 +9,49 @@ module BinData
   # Error raised when unexpected results occur when reading data from IO.
   class ValidityError < StandardError ; end
 
+  # ArgExtractors take the arguments to BinData::Base.new and
+  # separate them into [value, parameters, parent].
+  class BaseArgExtractor
+    def self.extract(the_class, the_args)
+      args = the_args.dup
+      value = parameters = parent = nil
+
+      if args.length > 1 and args.last.is_a? BinData::Base
+        parent = args.pop
+      end
+
+      if args.length > 0 and args.last.is_a? Hash
+        parameters = args.pop
+      end
+
+      if args.length > 0
+        value = args.pop
+      end
+
+      parameters ||= {}
+
+      return [value, parameters, parent]
+    end
+  end
+
   # This is the abstract base class for all data objects.
-  #
-  # == Parameters
-  #
-  # Parameters may be provided at initialisation to control the behaviour of
-  # an object.  These parameters are:
-  #
-  # [<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
-  #                           to the current offset.  The variable +offset+
-  #                           is made available to any lambda assigned to
-  #                           this parameter.  This parameter is only checked
-  #                           before reading.
-  # [<tt>:adjust_offset</tt>] Ensures that the current IO offset is at this
-  #                           position before reading.  This is like
-  #                           <tt>:check_offset</tt>, except that it will
-  #                           adjust the IO offset instead of raising an error.
   class Base
     include AcceptedParametersMixin
-
-    optional_parameters :check_offset, :adjust_offset
-    optional_parameter  :onlyif                            # Used by Struct
-    mutually_exclusive_parameters :check_offset, :adjust_offset
+    include CheckOrAdjustOffsetMixin
 
     class << self
 
       # Instantiates this class and reads from +io+, returning the newly
       # created data object.
       def read(io)
-        data = self.new
-        data.read(io)
-        data
+        obj = self.new
+        obj.read(io)
+        obj
+      end
+
+      # The arg extractor for this class.
+      def arg_extractor
+        BaseArgExtractor
       end
 
       # The name of this class as used by Records, Arrays etc.
@@ -71,19 +82,42 @@ module BinData
 
     # Creates a new data object.
     #
+    # Args are optional, but if present, must be in the following order.
+    #
+    # +value+ is a value that is +assign+ed immediately after initialization.
+    #
     # +parameters+ is a hash containing symbol keys.  Some parameters may
     # reference callable objects (methods or procs).
     #
     # +parent+ is the parent data object (e.g. struct, array, choice) this
     # object resides under.
-    def initialize(parameters = {}, parent = nil)
+    def initialize(*args)
+      value, parameters, parent = extract_args(args)
       @params = Sanitizer.sanitize(parameters, self.class)
-      @parent = parent
 
-      prepare_for_read_with_offset
+      add_methods_for_check_or_adjust_offset
+
+      @parent = parent if parent
+      initialize_shared_instance
+      initialize_instance
+      assign(value) if value
     end
 
-    attr_reader :parent
+    attr_accessor :parent
+    protected :parent=
+
+    # Creates a new data object based on this instance.
+    #
+    # All parameters will be be duplicated.  Use this method 
+    # when creating multiple objects with the same parameters.
+    def new(value = nil, parent = nil)
+      obj = clone
+      obj.parent = parent if parent
+      obj.initialize_instance
+      obj.assign(value) if value
+
+      obj
+    end
 
     # Returns the result of evaluating the parameter identified by +key+.
     #
@@ -202,6 +236,10 @@ module BinData
     #---------------
     private
 
+    def extract_args(the_args)
+      self.class.arg_extractor.extract(self.class, the_args)
+    end
+
     def furthest_ancestor
       if parent.nil?
         self
@@ -212,58 +250,6 @@ module BinData
       end
     end
 
-    def prepare_for_read_with_offset
-      if has_parameter?(:check_offset) or has_parameter?(:adjust_offset)
-        class << self
-          alias_method :do_read_without_offset, :do_read
-          alias_method :do_read, :do_read_with_offset
-          public :do_read # Ruby 1.9.2 bug.  Should be protected
-        end
-      end
-    end
-
-    def do_read_with_offset(io) #:nodoc:
-      check_or_adjust_offset(io)
-      do_read_without_offset(io)
-    end
-
-    def check_or_adjust_offset(io)
-      if has_parameter?(:check_offset)
-        check_offset(io)
-      elsif has_parameter?(:adjust_offset)
-        adjust_offset(io)
-      end
-    end
-
-    def check_offset(io)
-      actual_offset = io.offset
-      expected = eval_parameter(:check_offset, :offset => actual_offset)
-
-      if not expected
-        raise ValidityError, "offset not as expected for #{debug_name}"
-      elsif actual_offset != expected and expected != true
-        raise ValidityError,
-              "offset is '#{actual_offset}' but " +
-              "expected '#{expected}' for #{debug_name}"
-      end
-    end
-
-    def adjust_offset(io)
-      actual_offset = io.offset
-      expected = eval_parameter(:adjust_offset)
-      if actual_offset != expected
-        begin
-          seek = expected - actual_offset
-          io.seekbytes(seek)
-          warn "adjusting stream position by #{seek} bytes" if $VERBOSE
-        rescue
-          raise ValidityError,
-                "offset is '#{actual_offset}' but couldn't seek to " +
-                "expected '#{expected}' for #{debug_name}"
-        end
-      end
-    end
-
     ###########################################################################
     # To be implemented by subclasses
 
@@ -272,6 +258,20 @@ module BinData
     def self.sanitize_parameters!(parameters, sanitizer) #:nodoc:
     end
 
+    # Initializes the state of the object.  All instance variables that
+    # are used by the object must be initialized here.
+    def initialize_instance
+    end
+
+    # Initialises state that is shared by objects with the same parameters.
+    #
+    # This should only be used when optimising for performance.  Instance
+    # variables set here, and changes to the singleton class will be shared
+    # between all objects that are initialized with the same parameters.
+    # This method is called only once for a particular set of parameters.
+    def initialize_shared_instance
+    end
+
     # Resets the internal state to that of a newly created object.
     def clear
       raise NotImplementedError
@@ -282,7 +282,7 @@ module BinData
       raise NotImplementedError
     end
 
-    # Assigns the value of +val+ to this data object.  Note that +val+ will
+    # Assigns the value of +val+ to this data object.  Note that +val+ must
     # always be deep copied to ensure no aliasing problems can occur.
     def assign(val)
       raise NotImplementedError
@@ -322,6 +322,7 @@ module BinData
 
     # Set visibility requirements of methods to implement
     public :clear, :clear?, :assign, :snapshot, :debug_name_of, :offset_of
+    protected :initialize_instance, :initialize_shared_instance
     protected :do_read, :do_write, :do_num_bytes
 
     # End To be implemented by subclasses

data/lib/bindata/base_primitive.rb

@@ -1,5 +1,4 @@
 require 'bindata/base'
-require 'bindata/trace'
 
 module BinData
   # A BinData::BasePrimitive object is a container for a value that has a
@@ -10,16 +9,16 @@ module BinData
   #   require 'bindata'
   #
   #   obj = BinData::Uint8.new(:initial_value => 42)
-  #   obj.value #=> 42
-  #   obj.value = 5
-  #   obj.value #=> 5
+  #   obj #=> 42
+  #   obj.assign(5)
+  #   obj #=> 5
   #   obj.clear
-  #   obj.value #=> 42
+  #   obj #=> 42
   #
   #   obj = BinData::Uint8.new(:value => 42)
-  #   obj.value #=> 42
-  #   obj.value = 5
-  #   obj.value #=> 42
+  #   obj #=> 42
+  #   obj.assign(5)
+  #   obj #=> 42
   #
   #   obj = BinData::Uint8.new(:check_value => 3)
   #   obj.read("\005") #=> BinData::ValidityError: value is '5' but expected '3'
@@ -50,9 +49,26 @@ module BinData
     optional_parameters :initial_value, :value, :check_value
     mutually_exclusive_parameters :initial_value, :value
 
-    def initialize(parameters = {}, parent = nil)
-      super
+    def initialize_shared_instance
+      if has_parameter?(:check_value)
+        class << self
+          alias_method :do_read_without_check_value, :do_read
+          alias_method :do_read, :do_read_with_check_value
+        end
+      end
+      if has_parameter?(:value)
+        class << self
+          alias_method :_value, :_value_with_value
+        end
+      end
+      if has_parameter?(:initial_value)
+        class << self
+          alias_method :_value, :_value_with_initial_value
+        end
+      end
+    end
 
+    def initialize_instance
       @value = nil
     end
 
@@ -83,27 +99,28 @@ module BinData
     end
 
     def value
-      # TODO: warn "#value is deprecated, use #snapshot instead"
       snapshot
     end
-
-    def value=(val)
-      # TODO: warn "#value= is deprecated, use #assign instead"
-      assign(val)
-    end
+    alias_method :value=, :assign
 
     def respond_to?(symbol, include_private = false) #:nodoc:
-      value.respond_to?(symbol, include_private) || super
+      child = snapshot
+      child.respond_to?(symbol, include_private) || super
     end
 
     def method_missing(symbol, *args, &block) #:nodoc:
-      if value.respond_to?(symbol)
-        value.__send__(symbol, *args, &block)
+      child = snapshot
+      if child.respond_to?(symbol)
+        child.__send__(symbol, *args, &block)
       else
         super
       end
     end
 
+    def <=>(other)
+      snapshot <=> other
+    end
+
     def eql?(other)
       # double dispatch
       other.eql?(snapshot)
@@ -114,13 +131,13 @@ module BinData
     end
 
     def do_read(io) #:nodoc:
-      @value   = read_and_return_value(io)
-
-      trace_value
+      @value = read_and_return_value(io)
+      hook_after_do_read
+    end
 
-      if has_parameter?(:check_value)
-        check_value(value)
-      end
+    def do_read_with_check_value(io) #:nodoc:
+      do_read_without_check_value(io)
+      check_value(snapshot)
     end
 
     def do_write(io) #:nodoc:
@@ -134,12 +151,7 @@ module BinData
     #---------------
     private
 
-    def trace_value
-      BinData::trace_message do |tracer|
-        value_string = _value.inspect
-        tracer.trace_obj(debug_name, value_string)
-      end
-    end
+    def hook_after_do_read; end
 
     def check_value(current_value)
       expected = eval_parameter(:check_value, :value => current_value)
@@ -153,28 +165,34 @@ module BinData
       end
     end
 
-    # The unmodified value of this data object.  Note that #value calls this
-    # method.  This indirection is so that #value can be overridden in
-    # subclasses to modify the value.
+    # The unmodified value of this data object.  Note that #snapshot calls this
+    # method.  This indirection is so that #snapshot can be overridden in
+    # subclasses to modify the presentation value.
+    #
+    # Table of possible preconditions and expected outcome
+    #   1. :value and !reading?         ->   :value
+    #   2. :value and reading?          ->   @value
+    #   3. :initial_value and clear?    ->   :initial_value
+    #   4. :initial_value and !clear?   ->   @value
+    #   5. clear?                       ->   sensible_default
+    #   6. !clear?                      ->   @value
+
     def _value
-      # Table of possible preconditions and expected outcome
-      #   1. :value and !reading?         ->   :value
-      #   2. :value and reading?          ->   @value
-      #   3. :initial_value and clear?    ->   :initial_value
-      #   4. :initial_value and !clear?   ->   @value
-      #   5. clear?                       ->   sensible_default
-      #   6. !clear?                      ->   @value
-
-      if has_parameter?(:value) and not reading?
-        # rule 1 above
-        eval_parameter(:value)
+      @value || sensible_default()
+    end
+
+    def _value_with_value #:nodoc:
+      if reading?
+        @value
       else
-        # combining all other rules gives this simplified expression
-        @value || eval_parameter(:value) ||
-          eval_parameter(:initial_value) || sensible_default()
+        eval_parameter(:value)
       end
     end
 
+    def _value_with_initial_value #:nodoc:
+      @value || eval_parameter(:initial_value)
+    end
+
     ###########################################################################
     # To be implemented by subclasses