bindata 1.2.2 → 1.3.1

data/lib/bindata/choice.rb

@@ -1,5 +1,4 @@
 require 'bindata/base'
-require 'bindata/trace'
 
 module BinData
   # A Choice is a collection of data objects of which only one is active
@@ -13,26 +12,29 @@ module BinData
   #
   #   choices = {5 => type1, 17 => type2}
   #   a = BinData::Choice.new(:choices => choices, :selection => 5)
-  #   a.value # => "Type1"
+  #   a # => "Type1"
   #
   #   choices = [ type1, type2 ]
   #   a = BinData::Choice.new(:choices => choices, :selection => 1)
-  #   a.value # => "Type2"
+  #   a # => "Type2"
   #
   #   choices = [ nil, nil, nil, type1, nil, type2 ]
   #   a = BinData::Choice.new(:choices => choices, :selection => 3)
-  #   a.value # => "Type1"
+  #   a # => "Type1"
+  #
+  #
+  #   Chooser = Struct.new(:choice)
+  #   mychoice = Chooser.new
+  #   mychoice.choice = 'big'
   #
-  #   mychoice = 'big'
   #   choices = {'big' => :uint16be, 'little' => :uint16le}
-  #   a = BinData::Choice.new(:choices => choices,
-  #                           :selection => lambda { mychoice })
-  #   a.value  = 256
+  #   a = BinData::Choice.new(:choices => choices, :copy_on_change => true,
+  #                           :selection => lambda { mychoice.choice })
+  #   a.assign(256)
   #   a.to_binary_s #=> "\001\000"
-  #   mychoice.replace 'little'
-  #   a.selection #=> 'little'
-  #   a.to_binary_s #=> "\000\001"
   #
+  #   mychoice.choice = 'little'
+  #   a.to_binary_s #=> "\000\001"
   #
   # == Parameters
   #
@@ -98,9 +100,7 @@ module BinData
       end
     end
 
-    def initialize(parameters = {}, parent = nil)
-      super
-
+    def initialize_instance
       @choices = {}
       @last_selection = nil
     end
@@ -162,7 +162,7 @@ module BinData
     end
 
     def do_read(io) #:nodoc:
-      trace_selection
+      hook_before_do_read
       current_choice.do_read(io)
     end
 
@@ -177,12 +177,7 @@ module BinData
     #---------------
     private
 
-    def trace_selection
-      BinData::trace_message do |tracer|
-        selection_string = eval_parameter(:selection).inspect
-        tracer.trace_obj("#{debug_name}-selection-", selection_string)
-      end
-    end
+    def hook_before_do_read; end
 
     def current_choice
       selection = eval_parameter(:selection)
@@ -197,12 +192,7 @@ module BinData
     end
 
     def get_or_instantiate_choice(selection)
-      obj = @choices[selection]
-      if obj.nil?
-        obj = instantiate_choice(selection)
-        @choices[selection] = obj
-      end
-      obj
+      @choices[selection] ||= instantiate_choice(selection)
     end
 
     def instantiate_choice(selection)
@@ -210,7 +200,7 @@ module BinData
       if prototype.nil?
         raise IndexError, "selection '#{selection}' does not exist in :choices for #{debug_name}"
       end
-      prototype.instantiate(self)
+      prototype.instantiate(nil, self)
     end
 
     def copy_previous_value_if_required(selection, obj)

data/lib/bindata/deprecated.rb

@@ -17,6 +17,23 @@ end
 
 module BinData
   class Base
+
+    alias_method :initialize_without_deprecation, :initialize
+    def initialize_with_deprecation(*args)
+      owner = method(:initialize).owner
+      if owner != BinData::Base
+        fail "implementing #initialize on #{owner} is not allowed.\nEither downgrade to BinData 1.2.2, or rename #initialize to #initialize_instance."
+      end
+      initialize_without_deprecation(*args)
+    end
+    alias_method :initialize, :initialize_with_deprecation
+
+    def initialize_instance(*args)
+      unless args.empty?
+        warn "#{caller[0]} remove the call to super in #initialize_instance"
+      end
+    end
+
     class << self
       def register(name, class_to_register)
         if class_to_register == self

data/lib/bindata/dsl.rb

@@ -13,6 +13,7 @@ module BinData
       # [<tt>:sanitize_fields</tt>]        Fields are to be sanitized.
       # [<tt>:mandatory_fieldnames</tt>]   Fieldnames are mandatory.
       # [<tt>:optional_fieldnames</tt>]    Fieldnames are optional.
+      # [<tt>:fieldnames_for_choices</tt>] Fieldnames are choice keys.
       # [<tt>:no_fieldnames</tt>]          Fieldnames are prohibited.
       # [<tt>:all_or_none_fieldnames</tt>] All fields must have names, or
       #                                    none may have names.
@@ -108,7 +109,13 @@ module BinData
 
       def hide(*args)
         if option?(:hidden_fields)
-          @hide.concat(args.collect { |name| name.to_s })
+          hidden = args.collect do |name|
+                     unless Symbol === name
+                       warn "Hidden field '#{name}' should be provided as a symbol.  Using strings is deprecated"
+                     end
+                     name.to_sym
+                   end
+          @hide.concat(hidden.compact)
           @hide
         end
       end
@@ -187,9 +194,10 @@ module BinData
 
       def name_from_field_declaration(args)
         name, params = args
-        name = nil if name.is_a?(Hash)
+        name = "" if name.nil? or name.is_a?(Hash)
+        name = name.to_s if name.is_a?(Symbol)
 
-        name.to_s
+        name
       end
 
       def params_from_field_declaration(type, args, &block)
@@ -234,20 +242,22 @@ module BinData
           dsl_raise SyntaxError, "field must have a name"
         end
 
-        if malformed_name?(name)
-          dsl_raise NameError.new("", name), "field '#{name}' is an illegal fieldname"
-        end
+        unless option?(:fieldnames_for_choices)
+          if malformed_name?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' is an illegal fieldname"
+          end
 
-        if duplicate_name?(name)
-          dsl_raise SyntaxError, "duplicate field '#{name}'"
-        end
+          if duplicate_name?(name)
+            dsl_raise SyntaxError, "duplicate field '#{name}'"
+          end
 
-        if name_shadows_method?(name)
-          dsl_raise NameError.new("", name), "field '#{name}' shadows an existing method"
-        end
+          if name_shadows_method?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' shadows an existing method"
+          end
 
-        if name_is_reserved?(name)
-          dsl_raise NameError.new("", name), "field '#{name}' is a reserved name"
+          if name_is_reserved?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' is a reserved name"
+          end
         end
       end
 
@@ -317,7 +327,7 @@ module BinData
 
     class ChoiceBlockParser
       def self.extract_params(endian, &block)
-        parser = DSLParser.new(BinData::Choice, :multiple_fields, :all_or_none_fieldnames)
+        parser = DSLParser.new(BinData::Choice, :multiple_fields, :all_or_none_fieldnames, :fieldnames_for_choices)
         parser.endian endian
         parser.instance_eval(&block)
 

data/lib/bindata/int.rb

@@ -56,6 +56,7 @@ module BinData
           def read_and_return_value(io)
             val = #{create_read_code(nbits, endian)}
             #{create_uint2int_code(nbits) if signed == :signed}
+            val
           end
         END
       end
@@ -82,8 +83,7 @@ module BinData
       def create_uint2int_code(nbits)
         mask = (1 << (nbits - 1)) - 1
 
-        "val = ((val & #{1 << (nbits - 1)}).zero?) ? " +
-                 "val & #{mask} : -(((~val) & #{mask}) + 1)"
+        "val = -(((~val) & #{mask}) + 1) if (val >= #{1 << (nbits - 1)})"
       end
 
       def create_read_code(nbits, endian)

data/lib/bindata/io.rb

@@ -111,6 +111,14 @@ module BinData
       end
     end
 
+    # Discards any read bits so the stream becomes aligned at the
+    # next byte boundary.
+    def reset_read_bits
+      raise "Internal state error nbits = #{@rnbits}" if @rnbits >= 8
+      @rnbits = 0
+      @rval   = 0
+    end
+
     # Writes the given string of bytes to the io stream.
     def writebytes(str)
       flushbits
@@ -160,12 +168,6 @@ module BinData
       @positioning_supported
     end
 
-    def reset_read_bits
-      raise "Internal state error nbits = #{@rnbits}" if @rnbits >= 8
-      @rnbits = 0
-      @rval   = 0
-    end
-
     def skipbytes(n)
       # skip over data in 8k blocks
       while n > 0

data/lib/bindata/offset.rb

@@ -0,0 +1,91 @@
+module BinData
+  # == 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.
+  module CheckOrAdjustOffsetMixin
+
+    def self.included(base) #:nodoc:
+      base.optional_parameters :check_offset, :adjust_offset
+      base.mutually_exclusive_parameters :check_offset, :adjust_offset
+    end
+
+    # Ideally these two methods should be protected,
+    # but Ruby 1.9.2 requires them to be public.
+    # see http://redmine.ruby-lang.org/issues/show/2375
+
+    def do_read_with_check_offset(io) #:nodoc:
+      check_offset(io)
+      do_read_without_check_offset(io)
+    end
+
+    def do_read_with_adjust_offset(io) #:nodoc:
+      adjust_offset(io)
+      do_read_without_adjust_offset(io)
+    end
+
+    #---------------
+    private
+
+    # To be called from BinData::Base#initialize.
+    #
+    # Monkey patches #do_read to check or adjust the stream offset
+    # as appropriate.
+    def add_methods_for_check_or_adjust_offset
+      if has_parameter?(:check_offset)
+        class << self
+          alias_method :do_read_without_check_offset, :do_read
+          alias_method :do_read, :do_read_with_check_offset
+        end
+      end
+      if has_parameter?(:adjust_offset)
+        class << self
+          alias_method :do_read_without_adjust_offset, :do_read
+          alias_method :do_read, :do_read_with_adjust_offset
+        end
+      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
+  end
+end
+

data/lib/bindata/primitive.rb

@@ -29,7 +29,7 @@ module BinData
   #    ps = PascalString.new(:initial_value => "hello")
   #    ps.to_binary_s #=> "\005hello"
   #    ps.read("\003abcde")
-  #    ps.value #=> "abc"
+  #    ps #=> "abc"
   #
   #    # Unsigned 24 bit big endian integer
   #    class Uint24be < BinData::Primitive
@@ -53,7 +53,7 @@ module BinData
   #
   #    u24 = Uint24be.new
   #    u24.read("\x12\x34\x56")
-  #    "0x%x" % u24.value #=> 0x123456
+  #    "0x%x" % u24 #=> 0x123456
   #
   # == Parameters
   #
@@ -73,20 +73,36 @@ module BinData
 
     mandatory_parameter :struct_params
 
-    def initialize(parameters = {}, parent = nil)
-      super
-
+    def initialize_instance
       @struct = BinData::Struct.new(get_parameter(:struct_params), self)
     end
 
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      @struct.respond_to?(symbol, include_private) || super
+    end
+
     def method_missing(symbol, *args, &block) #:nodoc:
-      @struct.__send__(symbol, *args, &block)
+      if @struct.respond_to?(symbol)
+        @struct.__send__(symbol, *args, &block)
+      else
+        super
+      end
     end
 
     def debug_name_of(child) #:nodoc:
       debug_name + "-internal-"
     end
 
+    def do_write(io)
+      set(_value)
+      @struct.do_write(io)
+    end
+
+    def do_num_bytes
+      set(_value)
+      @struct.do_num_bytes
+    end
+
     #---------------
     private
 
@@ -99,11 +115,6 @@ module BinData
       get
     end
 
-    def value_to_binary_string(val)
-      set(val)
-      @struct.to_binary_s
-    end
-
     ###########################################################################
     # To be implemented by subclasses
 

data/lib/bindata/record.rb

@@ -3,6 +3,28 @@ require 'bindata/sanitize'
 require 'bindata/struct'
 
 module BinData
+  class RecordArgExtractor
+    def self.extract(the_class, the_args)
+      value, parameters, parent = BaseArgExtractor.extract(the_class, the_args)
+
+      if value.nil? and parameters.length > 0
+        if field_names_in_parameters(the_class, parameters).length > 0
+          value = parameters
+          parameters = nil
+        end
+      end
+
+      [value, parameters, parent]
+    end
+
+    def self.field_names_in_parameters(the_class, parameters)
+      field_names = the_class.fields.field_names.collect { |k| k.to_s }
+      param_keys = parameters.keys.collect { |k| k.to_s }
+
+      (field_names & param_keys)
+    end
+  end
+
   # A Record is a declarative wrapper around Struct.
   #
   #    require 'bindata'
@@ -49,6 +71,11 @@ module BinData
     dsl_parser :multiple_fields, :optional_fieldnames, :sanitize_fields, :hidden_fields
 
     class << self
+
+      def arg_extractor
+        RecordArgExtractor
+      end
+
       def sanitize_parameters!(params, sanitizer) #:nodoc:
         params[:fields] = fields
         params[:endian] = endian unless endian.nil?
@@ -65,22 +92,25 @@ module BinData
       def define_field_accessors(fields) #:nodoc:
         unless method_defined?(:bindata_defined_accessors_for_fields?)
           fields.each_with_index do |field, i|
-            name = field.name
-            if name
-              define_method(name.to_sym) do
-                instantiate_obj_at(i) unless @field_objs[i]
-                @field_objs[i]
-              end
-              define_method((name + "=").to_sym) do |*vals|
-                instantiate_obj_at(i) unless @field_objs[i]
-                @field_objs[i].assign(*vals)
-              end
+            if field.name
+              define_field_accessors_for(field.name, i)
             end
           end
 
           define_method(:bindata_defined_accessors_for_fields?) { true }
         end
       end
+
+      def define_field_accessors_for(name, index)
+        define_method(name.to_sym) do
+          instantiate_obj_at(index) unless @field_objs[index]
+          @field_objs[index]
+        end
+        define_method((name + "=").to_sym) do |*vals|
+          instantiate_obj_at(index) unless @field_objs[index]
+          @field_objs[index].assign(*vals)
+        end
+      end
     end
   end
 end