bindata 1.4.0 → 1.4.1

data/ChangeLog

@@ -1,5 +1,11 @@
 = BinData Changelog
 
+== Version 1.4.1 (2011-06-20)
+
+* Added :default option for Choices.
+* Added count_bytes_remaining keyword.
+* Increased speed of lazy evaluation.
+
 == Version 1.4.0 (2011-06-14)
 
 * Record#snapshot now returns fields in order.

data/lib/bindata.rb

@@ -4,6 +4,7 @@
 require 'bindata/array'
 require 'bindata/bits'
 require 'bindata/choice'
+require 'bindata/count_bytes_remaining'
 require 'bindata/float'
 require 'bindata/int'
 require 'bindata/primitive'
@@ -31,5 +32,5 @@ require 'bindata/deprecated'
 #
 # Copyright (c) 2007 - 2011 Dion Mendel.
 module BinData
-  VERSION = "1.4.0"
+  VERSION = "1.4.1"
 end

data/lib/bindata/base.rb

@@ -129,7 +129,17 @@ module BinData
     #
     # Returns nil if +key+ does not refer to any parameter.
     def eval_parameter(key, overrides = nil)
-      LazyEvaluator.eval(self, get_parameter(key), overrides)
+      value = get_parameter(key)
+      if value.is_a?(Symbol) or value.respond_to?(:arity)
+        lazy_evaluator.lazy_eval(value, overrides)
+      else
+        value
+      end
+    end
+
+    # Returns a lazy evaluator for this object.
+    def lazy_evaluator #:nodoc:
+      @lazy ||= LazyEvaluator.new(self)
     end
 
     # Returns the parameter referenced by +key+.

data/lib/bindata/choice.rb

@@ -49,7 +49,9 @@ module BinData
   #                            is to have params passed to it, then it should
   #                            be provided as [type_symbol, hash_params].  An
   #                            implementation constraint is that the hash may
-  #                            not contain symbols as keys.
+  #                            not contain symbols as keys, with the exception
+  #                            of :default.  :default is to be used when then
+  #                            :selection does not exist in the :choices hash.
   # <tt>:selection</tt>::      An index/key into the :choices array/hash which
   #                            specifies the currently active choice.
   # <tt>:copy_on_change</tt>:: If set to true, copy the value of the previous
@@ -98,7 +100,7 @@ module BinData
         if choices.has_key?(nil)
           raise ArgumentError, ":choices hash may not have nil key"
         end
-        if choices.keys.detect { |key| key.is_a?(Symbol) }
+        if choices.keys.detect { |key| key.is_a?(Symbol) and key != :default }
           raise ArgumentError, ":choices hash may not have symbols for keys"
         end
       end

data/lib/bindata/count_bytes_remaining.rb

@@ -0,0 +1,35 @@
+require "bindata/base_primitive"
+
+module BinData
+  # Counts the number of bytes remaining in the input stream from the current
+  # position to the end of the stream.  This only makes sense for seekable
+  # streams.
+  #
+  #   require 'bindata'
+  #
+  #   class A < BinData::Record
+  #     count_bytes_remaining :bytes_remaining
+  #     string :all_data, :read_length => :bytes_remaining
+  #   end
+  #
+  #   obj = A.read("abcdefghij")
+  #   obj.all_data #=> "abcdefghij"
+  #
+  class CountBytesRemaining < BinData::BasePrimitive
+
+    #---------------
+    private
+
+    def value_to_binary_string(val)
+      ""
+    end
+
+    def read_and_return_value(io)
+      io.num_bytes_remaining
+    end
+
+    def sensible_default
+      0
+    end
+  end
+end

data/lib/bindata/io.rb

@@ -67,6 +67,20 @@ module BinData
       end
     end
 
+    # The number of bytes remaining in the input stream.
+    def num_bytes_remaining
+      if positioning_supported?
+        pos = @raw_io.pos
+        @raw_io.seek(0, ::IO::SEEK_END)
+        bytes_remaining = @raw_io.pos - pos
+        @raw_io.seek(pos, ::IO::SEEK_SET)
+
+        bytes_remaining
+      else
+        0
+      end
+    end
+
     # Seek +n+ bytes from the current position in the io stream.
     def seekbytes(n)
       reset_read_bits

data/lib/bindata/lazy.rb

@@ -19,26 +19,6 @@ module BinData
   # <tt>field</tt> instead of <tt>obj.field</tt>.
   class LazyEvaluator
 
-    class << self
-      # Lazily evaluates +val+ in the context of +obj+, with possibility of
-      # +overrides+.
-      def eval(obj, val, overrides = nil)
-        if can_eval?(val)
-          env = self.new(obj)
-          env.lazy_eval(val, overrides)
-        else
-          val
-        end
-      end
-
-      #-------------
-      private
-
-      def can_eval?(val)
-        val.is_a?(Symbol) or val.respond_to?(:arity)
-      end
-    end
-
     # Creates a new evaluator.  All lazy evaluation is performed in the
     # context of +obj+.
     def initialize(obj)
@@ -59,7 +39,7 @@ module BinData
     # Returns a LazyEvaluator for the parent of this data object.
     def parent
       if @obj.parent
-        LazyEvaluator.new(@obj.parent)
+        @obj.parent.lazy_evaluator
       else
         nil
       end

data/lib/bindata/params.rb

@@ -78,8 +78,8 @@ module BinData
         @optional
       end
 
-      def default(args = {})
-        if not args.empty?
+      def default(args = nil)
+        if args
           to_syms(args.keys)  # call for side effect of validating names
           args.each_pair do |param, value|
             @default[param.to_sym] = value

data/lib/bindata/sanitize.rb

@@ -110,7 +110,11 @@ module BinData
           prototype = SanitizedPrototype.new(type, param, endian)
         end
 
-        @choices[key] = prototype
+        if key == :default
+          @choices.default = prototype
+        else
+          @choices[key] = prototype
+        end
       end
     end
 

data/manual.haml

@@ -2,7 +2,7 @@
 %html{ :xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en" }
   %head
     %meta{ :content => "text/html; charset=utf-8", "http-equiv" => "Content-Type" }
-    %meta{ :description =>"How to easily read and write binary data in Ruby" }
+    %meta{ :name => "description", :content =>"How to easily read and write binary data in Ruby" }
     %meta{ :keywords =>"ruby, binary, binary data, parse binary data, read binary data, write binary data, binary file, read binary file, write binary file" }
     %title
       Reading, writing and parsing binary data in Ruby
@@ -299,6 +299,11 @@
                       Choice parameters
                     .acc-section
                       .acc-content
+                  %li
+                    %a{ :href => "#default_selection" }
+                      Default Selection
+                    .acc-section
+                      .acc-content
           %li
             %a{ :href => "#advanced_topics" }
               Advanced Topics
@@ -352,6 +357,11 @@
                       Skipping over unused data
                     .acc-section
                       .acc-content
+                  %li
+                    %a{ :href => "#determining_stream_length" }
+                      Determining stream length
+                    .acc-section
+                      .acc-content
                   %li
                     %a{ :href => "#bitaligned_records" }
                       Bit-aligned Records

data/manual.md

@@ -40,7 +40,7 @@ manipulating.
 It supports all the common datatypes that are found in structured binary
 data. Support for dependent and variable length fields is built in. 
 
-Last updated: 2011-06-14
+Last updated: 2011-06-20
 
 ## License
 
@@ -1085,16 +1085,12 @@ Examples
     obj = BinData::Choice.new(:choices => choices, :selection => 1)
     obj # => "Type2"
 
-    choices = [ nil, nil, nil, type1, nil, type2 ]
-    obj = BinData::Choice.new(:choices => choices, :selection => 3)
-    obj # => "Type1"
-
     class MyNumber < BinData::Record
       int8 :is_big_endian
       choice :data, :selection => lambda { is_big_endian != 0 },
                     :copy_on_change => true do
-        int32be true
         int32le false
+        int32be true
       end
     end
 
@@ -1107,6 +1103,23 @@ Examples
     obj.to_binary_s #=> "\000\005\000\000\000"
 {:ruby}
 
+## Default selection
+
+A key of `:default` can be specified as a default selection.  If the value of the
+selection isn't specified then the :default will be used.  The previous `MyNumber`
+example used a flag for endian.  Zero is little endian while any other value
+is big endian.  This can be concisely written as:
+
+    class MyNumber < BinData::Record
+      int8 :is_big_endian
+      choice :data, :selection => :is_big_endian,
+                    :copy_on_change => true do
+        int32le 0          # zero is little endian
+        int32be :default   # anything else is big endian
+      end
+    end
+{:ruby}
+
 ---------------------------------------------------------------------------
 
 # Advanced Topics
@@ -1302,6 +1315,28 @@ data and won't consume space in memory.  When writing it will write
     end
 {:ruby}
 
+## Determining stream length
+
+Some file formats don't use length fields but rather read until the end
+of the file.  The stream length is needed when reading these formats.  The
+`count_bytes_remaining` keyword will give the number of bytes remaining in the
+stream.
+
+Consider a string followed by a 2 byte checksum.  The length of the string is
+not specified but is implied by the file length.
+
+    class StringWithChecksum < BinData::Record
+      count_bytes_remaining :bytes_remaining
+      string :the_string, :read_length => lambda { bytes_remaining - 2 }
+      int16le :checksum
+    end
+{:ruby}
+
+These file formats only work with seekable streams (e.g. files).  These formats
+do not stream well as they must be buffered by the client before being
+processed.  Consider using an explicit length when creating a new file format
+as it is easier to work with.
+
 ## Bit-aligned Records
 
 Most structured binary data is byte-aligned.  Any bitfields that occur,

data/spec/choice_spec.rb

@@ -207,6 +207,20 @@ describe BinData::Choice, "with copy_on_change => true" do
   end
 end
 
+describe BinData::Choice, "with :default" do
+  let(:choices) { { "a" => :int8, :default => :int16be } }
+
+  it "should select for existing case" do
+    subject = BinData::Choice.new(:selection => "a", :choices => choices)
+    subject.num_bytes.should == 1
+  end
+
+  it "should select for default case" do
+    subject = BinData::Choice.new(:selection => "other", :choices => choices)
+    subject.num_bytes.should == 2
+  end
+end
+
 describe BinData::Choice, "subclassed with default parameters" do
   class DerivedChoice < BinData::Choice
     endian :big
@@ -214,6 +228,7 @@ describe BinData::Choice, "subclassed with default parameters" do
 
     uint16 'a'
     uint32 'b'
+    uint64 :default
   end
 
   it "should set initial selection" do
@@ -225,4 +240,9 @@ describe BinData::Choice, "subclassed with default parameters" do
     subject = DerivedChoice.new(:selection => 'b')
     subject.num_bytes.should == 4
   end
+
+  it "should select default selection" do
+    subject = DerivedChoice.new(:selection => 'z')
+    subject.num_bytes.should == 8
+  end
 end

data/spec/count_bytes_remaining_spec.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), "spec_common"))
+require 'bindata/count_bytes_remaining'
+
+describe BinData::CountBytesRemaining do
+  it { should == 0 }
+
+  it "should count till end of stream" do
+    data = "abcdefghij"
+    subject.read(data).should == 10
+  end
+
+  it "should have no size" do
+    subject.num_bytes.should == 0
+  end
+
+  it "should not read any data" do
+    io = StringIO.new "abcdefghij"
+    subject.read(io)
+
+    io.pos.should == 0
+  end
+
+  it "should not write any data" do
+    subject.to_binary_s.should == ""
+  end
+
+  it "should allow setting value for completeness" do
+    subject.assign("123")
+    subject.should == "123"
+    subject.to_binary_s.should == ""
+  end
+
+  it "should accept BinData::BasePrimitive parameters" do
+    count = BinData::CountBytesRemaining.new(:check_value => 2)
+    lambda {
+      count.read("xyz")
+    }.should raise_error(BinData::ValidityError)
+  end
+end

data/spec/io_spec.rb

@@ -39,6 +39,10 @@ describe BinData::IO, "reading from non seekable stream" do
     @io.seekbytes(4999)
     @io.readbytes(5).should == "abbbb"
   end
+
+  it "should return zero for num bytes remaining" do
+    @io.num_bytes_remaining.should == 0
+  end
 end
 
 describe BinData::IO, "when reading" do
@@ -76,6 +80,13 @@ describe BinData::IO, "when reading" do
     io.read_all_bytes.should == "abcdefghij"
   end
 
+  it "should return number of bytes remaining" do
+    stream_length = io.num_bytes_remaining
+
+    io.readbytes(4)
+    io.num_bytes_remaining.should == stream_length - 4
+  end
+
   it "should raise error when reading at eof" do
     io.seekbytes(10)
     lambda {

data/spec/lazy_spec.rb

@@ -22,52 +22,56 @@ class MockBinDataObject
   def get_parameter(key)
     @parameters[key]
   end
+
+  def lazy_evaluator
+    BinData::LazyEvaluator.new(self)
+  end
 end
 
-# Shortcut to save typing
-LE = BinData::LazyEvaluator
+def lazy_eval(*rest)
+  subject.lazy_evaluator.lazy_eval(*rest)
+end
 
 describe BinData::LazyEvaluator, "with no parents" do
-  let(:obj) {
+  subject {
     methods = {:m1 => 'm1', :com => 'mC'}
     params  = {:p1 => 'p1', :com => 'pC'}
     MockBinDataObject.new(methods, params)
   }
 
   it "should evaluate raw value when instantiated" do
-    le = LE.new(obj)
-    le.lazy_eval(5).should == 5
+    lazy_eval(5).should == 5
   end
 
   it "should evaluate raw value" do
-    LE.eval(obj, 5).should == 5
+    lazy_eval(5).should == 5
   end
 
   it "should evaluate value" do
-    LE.eval(obj, lambda { 5 }).should == 5
+    lazy_eval(lambda { 5 }).should == 5
   end
 
   it "should evaluate overrides" do
-    LE.eval(obj, lambda { o1 }, :o1 => 'o1').should == 'o1'
+    lazy_eval(lambda { o1 }, :o1 => 'o1').should == 'o1'
   end
 
   it "should not resolve any unknown methods" do
-    lambda { LE.eval(obj, lambda { unknown }) }.should raise_error(NameError)
-    lambda { LE.eval(obj, lambda { m1 }) }.should raise_error(NameError)
-    lambda { LE.eval(obj, lambda { p1 }) }.should raise_error(NameError)
+    lambda { lazy_eval(lambda { unknown }) }.should raise_error(NameError)
+    lambda { lazy_eval(lambda { m1 }) }.should raise_error(NameError)
+    lambda { lazy_eval(lambda { p1 }) }.should raise_error(NameError)
   end
 
   it "should not have a parent" do
-    LE.eval(obj, lambda { parent }).should be_nil
+    lazy_eval(lambda { parent }).should be_nil
   end
 
   it "should not resolve #index" do
-    lambda { LE.eval(obj, lambda { index }) }.should raise_error(NoMethodError)
+    lambda { lazy_eval(lambda { index }) }.should raise_error(NoMethodError)
   end
 end
 
 describe BinData::LazyEvaluator, "with one parent" do
-  let(:obj) {
+  subject {
     parent_methods = {:m1 => 'Pm1', :com => 'PmC', :mm => 3}
     parent_params  = {:p1 => 'Pp1', :com => 'PpC'}
     parent_obj = MockBinDataObject.new(parent_methods, parent_params)
@@ -82,52 +86,52 @@ describe BinData::LazyEvaluator, "with one parent" do
   }
 
   it "should evaluate raw value" do
-    LE.eval(obj, 5).should == 5
+    lazy_eval(5).should == 5
   end
 
   it "should evaluate value" do
-    LE.eval(obj, lambda { 5 }).should == 5
+    lazy_eval(lambda { 5 }).should == 5
   end
 
   it "should evaluate overrides before params" do
-    LE.eval(obj, lambda { p1 }, :p1 => 'o1').should == 'o1'
+    lazy_eval(lambda { p1 }, :p1 => 'o1').should == 'o1'
   end
 
   it "should evaluate overrides before methods" do
-    LE.eval(obj, lambda { m1 }, :m1 => 'o1').should == 'o1'
+    lazy_eval(lambda { m1 }, :m1 => 'o1').should == 'o1'
   end
 
   it "should not resolve any unknown methods" do
-    lambda { LE.eval(obj, lambda { unknown }) }.should raise_error(NameError)
+    lambda { lazy_eval(lambda { unknown }) }.should raise_error(NameError)
   end
 
   it "should resolve parameters in the parent" do
-    LE.eval(obj, lambda { p1 }).should == 'Pp1'
+    lazy_eval(lambda { p1 }).should == 'Pp1'
   end
 
   it "should resolve methods in the parent" do
-    LE.eval(obj, lambda { m1 }).should == 'Pm1'
+    lazy_eval(lambda { m1 }).should == 'Pm1'
   end
 
   it "should invoke methods in the parent" do
-    LE.eval(obj, lambda { echo(p1, m1) }).should == ['Pp1', 'Pm1']
+    lazy_eval(lambda { echo(p1, m1) }).should == ['Pp1', 'Pm1']
   end
 
   it "should resolve parameters in preference to methods in the parent" do
-    LE.eval(obj, lambda { com }).should == 'PpC'
+    lazy_eval(lambda { com }).should == 'PpC'
   end
 
   it "should have a parent" do
-    LE.eval(obj, lambda { parent }).should_not be_nil
+    lazy_eval(lambda { parent }).should_not be_nil
   end
 
   it "should not resolve #index" do
-    lambda { LE.eval(obj, lambda { index }) }.should raise_error(NoMethodError)
+    lambda { lazy_eval(lambda { index }) }.should raise_error(NoMethodError)
   end
 end
 
 describe BinData::LazyEvaluator, "with nested parents" do
-  let(:obj) {
+  subject {
     pparent_methods = {:m1 => 'PPm1', :m2 => 'PPm2', :com => 'PPmC'}
     pparent_params  = {:p1 => 'PPp1', :p2 => 'PPp2', :com => 'PPpC'}
     pparent_obj = MockBinDataObject.new(pparent_methods, pparent_params)
@@ -154,58 +158,58 @@ describe BinData::LazyEvaluator, "with nested parents" do
   }
 
   it "should accept symbols as a shortcut to lambdas" do
-    LE.eval(obj, :p1).should == 'Pp1'
-    LE.eval(obj, :p2).should == 'PPp2'
-    LE.eval(obj, :m1).should == 'Pm1'
-    LE.eval(obj, :m2).should == 'PPm2'
+    lazy_eval(:p1).should == 'Pp1'
+    lazy_eval(:p2).should == 'PPp2'
+    lazy_eval(:m1).should == 'Pm1'
+    lazy_eval(:m2).should == 'PPm2'
   end
 
   it "should not resolve any unknown methods" do
-    lambda { LE.eval(obj, lambda { unknown }) }.should raise_error(NameError)
+    lambda { lazy_eval(lambda { unknown }) }.should raise_error(NameError)
   end
 
   it "should resolve parameters in the parent" do
-    LE.eval(obj, lambda { p1 }).should == 'Pp1'
+    lazy_eval(lambda { p1 }).should == 'Pp1'
   end
 
   it "should resolve methods in the parent" do
-    LE.eval(obj, lambda { m1 }).should == 'Pm1'
+    lazy_eval(lambda { m1 }).should == 'Pm1'
   end
 
   it "should resolve parameters in the parent's parent" do
-    LE.eval(obj, lambda { p2 }).should == 'PPp2'
+    lazy_eval(lambda { p2 }).should == 'PPp2'
   end
 
   it "should resolve methods in the parent's parent" do
-    LE.eval(obj, lambda { m2 }).should == 'PPm2'
+    lazy_eval(lambda { m2 }).should == 'PPm2'
   end
 
   it "should invoke methods in the parent" do
-    LE.eval(obj, lambda { echo(m1) }).should == ['P', 'Pm1']
+    lazy_eval(lambda { echo(m1) }).should == ['P', 'Pm1']
   end
 
   it "should invoke methods in the parent's parent" do
-    LE.eval(obj, lambda { parent.echo(m1) }, { :m1 => 'o1'}).should == ['PP', 'o1']
+    lazy_eval(lambda { parent.echo(m1) }, { :m1 => 'o1'}).should == ['PP', 'o1']
   end
 
   it "should invoke methods in the parent's parent" do
-    LE.eval(obj, lambda { echo2(m1) }).should == ['PP2', 'Pm1']
+    lazy_eval(lambda { echo2(m1) }).should == ['PP2', 'Pm1']
   end
 
   it "should resolve parameters in preference to methods in the parent" do
-    LE.eval(obj, lambda { com }).should == 'PpC'
+    lazy_eval(lambda { com }).should == 'PpC'
   end
 
   it "should resolve methods in the parent explicitly" do
-    LE.eval(obj, lambda { parent.m1 }).should == 'PPm1'
+    lazy_eval(lambda { parent.m1 }).should == 'PPm1'
   end
 
   it "should cascade lambdas " do
-    LE.eval(obj, lambda { sym1 }).should == 'PPm2'
-    LE.eval(obj, lambda { sym2 }).should == 'PPm2'
+    lazy_eval(lambda { sym1 }).should == 'PPm2'
+    lazy_eval(lambda { sym2 }).should == 'PPm2'
   end
 
   it "should not resolve #index" do
-    lambda { LE.eval(obj, lambda { index }) }.should raise_error(NoMethodError)
+    lambda { lazy_eval(lambda { index }) }.should raise_error(NoMethodError)
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bindata
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: false
   segments: 
   - 1
   - 4
-  - 0
-  version: 1.4.0
+  - 1
+  version: 1.4.1
 platform: ruby
 authors: 
 - Dion Mendel
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-14 00:00:00 +08:00
+date: 2011-06-20 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -104,6 +104,7 @@ files:
 - examples/nbt.rb
 - examples/NBT.txt
 - examples/list.rb
+- spec/count_bytes_remaining_spec.rb
 - spec/base_spec.rb
 - spec/string_spec.rb
 - spec/record_spec.rb
@@ -136,6 +137,7 @@ files:
 - lib/bindata/trace.rb
 - lib/bindata/struct.rb
 - lib/bindata/lazy.rb
+- lib/bindata/count_bytes_remaining.rb
 - lib/bindata/base.rb
 - lib/bindata/stringz.rb
 - lib/bindata/string.rb