bindata 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef9bdd3883fe70283af7a90ef1d7a7aabdbc1043
-  data.tar.gz: a0e441bd2a6fc0fcebe932b21737364baa53a373
+  metadata.gz: 53f36d1668fe4f1636ca00ab18b3764890d80b2b
+  data.tar.gz: bef4e40c419d1a411872e33cda5889d8d7f7d4f6
 SHA512:
-  metadata.gz: 45b2a84cd80c08590463773919d93cb8aececa94fc391d620e897a4b3b1d2a512dd2e8f91c9ec608008b6007a1828ff1dae80938de1d961eab7403a802d1a696
-  data.tar.gz: 179ea9774c018fa6d90f2e864d99ae829ee8f41d8289fc30da514481b2dddff94c6b1e6ca9c316f98657a9cfee6c307f001d6d1449db713569c17cb171e06645
+  metadata.gz: 4fecf533fc319ba22a437255557cc72ba48f2b3ac23d7fbc8870b50cbce77ceb8d443e1191646b5683f04f5d8633450b09e71131635399db8c34e7483a2bcadf
+  data.tar.gz: b0336f625a5a88ab2842e55b71b85920982ee66b89e021d7480a4238087f9532bed94c484ba1a44197987cbb67ca0a1ce81fc0a4043fbacaf9c7b405a9b6ce57

data/ChangeLog.rdoc

@@ -1,5 +1,12 @@
 = BinData Changelog
 
+== Version 2.3.0 (2016-03-25)
+
+* Add :to_abs_offset to Skip.
+* Added backwards seeking via multi pass I/O.  See DelayedIO.
+* Removed #offset, which was deprecated in 2.1.0.
+* Removed :adjust_offset.  See NEWS.rdoc for details.
+
 == Version 2.2.0 (2016-01-30)
 
 * Warn if String has :value but no :read_length.  Requested by Michael

data/NEWS.rdoc

@@ -1,3 +1,17 @@
+= 2.3.0
+
+This release adds I/O features.
+
+Seeking forward to an arbitrary offset is achieved with Skip's :to_abs_offset
+parameter.
+
+Multi pass I/O has been added.  BinData performs I/O in a single pass.  See
+DelayedIO to perform multi pass (backwards seeking) I/O.
+
+The experimental :adjust_offset feature has been removed.  If you have existing
+code that uses this feature, you need to explicitly require 'bindata/offset' to
+retain this functionality.
+
 = 2.1.0
 
 Several new features in this release.

data/lib/bindata.rb

@@ -15,6 +15,7 @@ require 'bindata/bits'
 require 'bindata/buffer'
 require 'bindata/choice'
 require 'bindata/count_bytes_remaining'
+require 'bindata/delayed_io'
 require 'bindata/float'
 require 'bindata/int'
 require 'bindata/primitive'

data/lib/bindata/alignment.rb

@@ -50,9 +50,10 @@ module BinData
           bytes << @io.readbits(8, :big).chr
         end
       end
-      def method_missing(sym, *args, &block)
-        @io.send(sym, *args, &block)
-      end
+    end
+
+    def bit_aligned?
+      true
     end
 
     def read_and_return_value(io)

data/lib/bindata/array.rb

@@ -217,7 +217,7 @@ module BinData
       index = find_index_of(child)
       sum = sum_num_bytes_below_index(index)
 
-      child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
+      child.bit_aligned? ? sum.floor : sum.ceil
     end
 
     def do_write(io) #:nodoc:
@@ -281,8 +281,9 @@ module BinData
         params[:initial_length] = 0
       end
 
+      params.warn_replacement_parameter(:length, :initial_length)
       params.warn_replacement_parameter(:read_length, :initial_length)
-      params.must_be_integer(:initial_length, :read_length)
+      params.must_be_integer(:initial_length)
 
       params.merge!(obj_class.dsl_params)
 

data/lib/bindata/base.rb

@@ -2,7 +2,6 @@ require 'bindata/framework'
 require 'bindata/io'
 require 'bindata/lazy'
 require 'bindata/name'
-require 'bindata/offset'
 require 'bindata/params'
 require 'bindata/registry'
 require 'bindata/sanitize'
@@ -12,20 +11,21 @@ module BinData
   class Base
     extend AcceptedParametersPlugin
     include Framework
-    include CheckOrAdjustOffsetPlugin
     include RegisterNamePlugin
 
     class << self
       # Instantiates this class and reads from +io+, returning the newly
       # created data object.  +args+ will be used when instantiating.
-      def read(io, *args)
+      def read(io, *args, &block)
         obj = self.new(*args)
-        obj.read(io)
+        obj.read(io, &block)
         obj
       end
 
       # The arg processor for this class.
       def arg_processor(name = nil)
+        @arg_processor ||= nil
+
         if name
           @arg_processor = "#{name}_arg_processor".gsub(/(?:^|_)(.)/) { $1.upcase }.to_sym
         elsif @arg_processor.is_a? Symbol
@@ -49,6 +49,7 @@ module BinData
 
       # Registers all subclasses of this class for use
       def register_subclasses #:nodoc:
+        singleton_class.send(:undef_method, :inherited)
         define_singleton_method(:inherited) do |subclass|
           RegisteredClasses.register(subclass.name, subclass)
           register_subclasses
@@ -138,34 +139,27 @@ module BinData
     end
 
     # Reads data into this data object.
-    def read(io)
+    def read(io, &block)
       io = BinData::IO::Read.new(io) unless BinData::IO::Read === io
 
-      @in_read = true
-      clear
-      do_read(io)
-      @in_read = false
+      start_read do
+        clear
+        do_read(io)
+      end
+      block.call(self) if block_given?
 
       self
     end
 
-    #:nodoc:
-    attr_reader :in_read
-    protected   :in_read
-
-    # Returns if this object is currently being read.  This is used
-    # internally by BasePrimitive.
-    def reading? #:nodoc:
-      furthest_ancestor.in_read
-    end
-    protected :reading?
-
     # Writes the value for this data object to +io+.
-    def write(io)
+    def write(io, &block)
       io = BinData::IO::Write.new(io) unless BinData::IO::Write === io
 
       do_write(io)
       io.flush
+
+      block.call(self) if block_given?
+
       self
     end
 
@@ -175,16 +169,16 @@ module BinData
     end
 
     # Returns the string representation of this data object.
-    def to_binary_s
+    def to_binary_s(&block)
       io = BinData::IO.create_string_io
-      write(io)
+      write(io, &block)
       io.rewind
       io.read
     end
 
     # Returns the hexadecimal string representation of this data object.
-    def to_hex
-      to_binary_s.unpack('H*')[0]
+    def to_hex(&block)
+      to_binary_s(&block).unpack('H*')[0]
     end
 
     # Return a human readable representation of this data object.
@@ -243,7 +237,7 @@ module BinData
     # A version of +respond_to?+ used by the lazy evaluator.  It doesn't
     # reinvoke the evaluator so as to avoid infinite evaluation loops.
     def safe_respond_to?(symbol, include_private = false) #:nodoc:
-      respond_to?(symbol, include_private)
+      base_respond_to?(symbol, include_private)
     end
     alias_method :base_respond_to?, :respond_to? #:nodoc:
 
@@ -254,14 +248,36 @@ module BinData
       self.class.arg_processor.extract_args(self.class, args)
     end
 
-    def furthest_ancestor
+    def start_read(&block)
+      top_level_set(:in_read, true)
+      block.call
+    ensure
+      top_level_set(:in_read, false)
+    end
+
+    # Is this object tree currently being read?  Used by BasePrimitive.
+    def reading?
+      top_level_get(:in_read)
+    end
+
+    def top_level_set(sym, value)
+      top_level.instance_variable_set("@tl_#{sym}", value)
+    end
+
+    def top_level_get(sym)
+      top_level.instance_variable_defined?("@tl_#{sym}") and
+        top_level.instance_variable_get("@tl_#{sym}")
+    end
+
+    def top_level
       if parent.nil?
-        self
+        tl = self
       else
-        an = parent
-        an = an.parent while an.parent
-        an
+        tl = parent
+        tl = tl.parent while tl.parent
       end
+
+      tl
     end
 
     def binary_string(str)

data/lib/bindata/base_primitive.rb

@@ -176,9 +176,7 @@ module BinData
         current_value = snapshot
         expected = eval_parameter(:assert, :value => current_value)
 
-        msg = if not expected and current_value.nil?
-          "assertion failed"
-        elsif not expected
+        msg = if not expected
           "value '#{current_value}' not as expected"
         elsif expected != true and current_value != expected
           "value is '#{current_value}' but expected '#{expected}'"
@@ -212,10 +210,7 @@ module BinData
 
       def assert_value(current_value)
         expected = eval_parameter(:asserted_value, :value => current_value)
-        if not expected
-          raise ValidityError,
-                "value '#{current_value}' not as expected for #{debug_name}"
-        elsif current_value != expected and expected != true
+        if current_value != expected
           raise ValidityError,
                 "value is '#{current_value}' but " +
                 "expected '#{expected}' for #{debug_name}"

data/lib/bindata/bits.rb

@@ -40,10 +40,13 @@ module BinData
             #{create_do_num_bytes_code(nbits)}
           end
 
+          def bit_aligned?
+            true
+          end
+
           #---------------
           private
 
-
           def read_and_return_value(io)
             #{create_nbits_code(nbits)}
             val = io.readbits(#{nbits}, :#{endian})

data/lib/bindata/buffer.rb

@@ -78,10 +78,6 @@ module BinData
       @type.respond_to?(symbol, include_private) || super
     end
 
-    def safe_respond_to?(symbol, include_private = false) #:nodoc:
-      base_respond_to?(symbol, include_private)
-    end
-
     def method_missing(symbol, *args, &block) #:nodoc:
       @type.__send__(symbol, *args, &block)
     end

data/lib/bindata/choice.rb

@@ -85,10 +85,6 @@ module BinData
       selection
     end
 
-    def safe_respond_to?(symbol, include_private = false) #:nodoc:
-      base_respond_to?(symbol, include_private)
-    end
-
     def respond_to?(symbol, include_private = false) #:nodoc:
       current_choice.respond_to?(symbol, include_private) || super
     end

data/lib/bindata/delayed_io.rb

@@ -0,0 +1,194 @@
+require 'bindata/base'
+require 'bindata/dsl'
+
+module BinData
+  # BinData declarations are evaluated in a single pass.
+  # However, some binary formats require multi pass processing.  A common
+  # reason is seeking backwards in the input stream.
+  #
+  # DelayedIO supports multi pass processing.  It works by ignoring the normal
+  # #read or #write calls.  The user must explicitly call the #read_now! or
+  # #write_now! methods to process an additional pass.  This additional pass
+  # must specify the abs_offset of the I/O operation.
+  #
+  #   require 'bindata'
+  #
+  #   obj = BinData::DelayedIO.new(:read_abs_offset => 3, :type => :uint16be)
+  #   obj.read("\x00\x00\x00\x11\x12")
+  #   obj #=> 0
+  #
+  #   obj.read_now!
+  #   obj #=> 0x1112
+  #
+  #   - OR -
+  #
+  #   obj.read("\x00\x00\x00\x11\x12") { obj.read_now! } #=> 0x1122
+  #
+  #   obj.to_binary_s { obj.write_now! } #=> "\x00\x00\x00\x11\x12"
+  #
+  # You can use the +auto_call_delayed_io+ keyword to cause #read and #write to
+  # automatically perform the extra passes.
+  #
+  #   class ReversePascalString < BinData::Record
+  #     auto_call_delayed_io
+  #
+  #     delayed_io :str, :read_abs_offset => 0 do
+  #       string :read_length => :len
+  #     end
+  #     count_bytes_remaining :total_size
+  #     skip :to_abs_offset => lambda { total_size - 1 }
+  #     uint8  :len, :value => lambda { str.length }
+  #   end
+  #
+  #   s = ReversePascalString.read("hello\x05")
+  #   s.to_binary_s #=> "hello\x05"
+  #
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params are:
+  #
+  # <tt>:read_abs_offset</tt>::   The abs_offset to start reading at.
+  # <tt>:type</tt>::              The single type inside the delayed io.  Use
+  #                               a struct if multiple fields are required.
+  class DelayedIO < BinData::Base
+    extend DSLMixin
+
+    dsl_parser    :delayed_io
+    arg_processor :delayed_io
+
+    mandatory_parameters :read_abs_offset, :type
+
+    def initialize_instance
+      @type       = get_parameter(:type).instantiate(nil, self)
+      @abs_offset = nil
+      @read_io    = nil
+      @write_io   = nil
+    end
+
+    def clear?
+      @type.clear?
+    end
+
+    def assign(val)
+      @type.assign(val)
+    end
+
+    def snapshot
+      @type.snapshot
+    end
+
+    def num_bytes
+      @type.num_bytes
+    end
+
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      @type.respond_to?(symbol, include_private) || super
+    end
+
+    def method_missing(symbol, *args, &block) #:nodoc:
+      @type.__send__(symbol, *args, &block)
+    end
+
+    def abs_offset
+      @abs_offset || eval_parameter(:read_abs_offset)
+    end
+
+    # Sets the +abs_offset+ to use when writing this object.
+    def abs_offset=(offset)
+      @abs_offset = offset
+    end
+
+    def rel_offset
+      abs_offset
+    end
+
+    def do_read(io) #:nodoc:
+      @read_io = io
+    end
+
+    def do_write(io) #:nodoc:
+      @write_io = io
+    end
+
+    def do_num_bytes #:nodoc:
+      0
+    end
+
+    # DelayedIO objects aren't read when #read is called.
+    # The reading is delayed until this method is called.
+    def read_now!
+      raise IOError.new "read from where?" unless @read_io
+
+      @read_io.seekbytes(abs_offset - @read_io.offset)
+      start_read do
+        @type.do_read(@read_io)
+      end
+    end
+
+    # DelayedIO objects aren't written when #write is called.
+    # The writing is delayed until this method is called.
+    def write_now!
+      raise IOError.new "write to where?" unless @write_io
+      @write_io.seekbytes(abs_offset - @write_io.offset)
+      @type.do_write(@write_io)
+    end
+  end
+
+  class DelayedIoArgProcessor < BaseArgProcessor
+    include MultiFieldArgSeparator
+
+    def sanitize_parameters!(obj_class, params)
+      params.merge!(obj_class.dsl_params)
+
+      params.must_be_integer(:read_abs_offset)
+
+      if params.needs_sanitizing?(:type)
+        el_type, el_params = params[:type]
+        params[:type] = params.create_sanitized_object_prototype(el_type, el_params)
+      end
+    end
+  end
+
+  # Add +auto_call_delayed_io+ keyword to BinData::Base.
+  class Base
+    class << self
+      # The +auto_call_delayed_io+ keyword sets a data object tree to perform
+      # multi pass I/O automatically.
+      def auto_call_delayed_io
+        include AutoCallDelayedIO
+
+        DelayedIO.send(:alias_method, :initialize_instance_without_record_io, :initialize_instance)
+        DelayedIO.send(:define_method, :initialize_instance) do
+          if @parent and ! defined? @delayed_io_recorded
+            @delayed_io_recorded = true
+            list = top_level_get(:delayed_ios)
+            list << self if list
+          end
+
+          initialize_instance_without_record_io
+        end
+      end
+    end
+
+    module AutoCallDelayedIO
+      def initialize_shared_instance
+        top_level_set(:delayed_ios, [])
+        super
+      end
+
+      def read(io)
+        super(io) { top_level_get(:delayed_ios).each { |obj| obj.read_now! } }
+      end
+
+      def write(io, *args)
+        super(io) { top_level_get(:delayed_ios).each { |obj| obj.write_now! } }
+      end
+
+      def num_bytes
+        to_binary_s.size
+      end
+    end
+  end
+end