bindata 1.2.2 → 1.3.1

data/lib/bindata/sanitize.rb

@@ -13,37 +13,20 @@ module BinData
   # SanitizedParameters is a hash-like collection of parameters.  Its purpose
   # it to recursively sanitize the parameters of an entire BinData object chain
   # at a single time.
-  class SanitizedParameters
+  class SanitizedParameters < Hash
 
     def initialize(parameters, the_class)
+      parameters.each_pair { |key, value| self[key.to_sym] = value }
+
       @all_sanitized = false
       @the_class = the_class
-
-      @parameters = {}
-      parameters.each { |key, value| @parameters[key.to_sym] = value }
-
       ensure_no_nil_values
     end
 
-    def length
-      @parameters.size
-    end
-    alias_method :size, :length
-
-    def [](key)
-      @parameters[key]
-    end
-
-    def []=(key, value)
-      @parameters[key] = value unless @all_sanitized
-    end
-
-    def has_parameter?(key)
-      @parameters.has_key?(key)
-    end
+    alias_method :has_parameter?, :has_key?
 
     def needs_sanitizing?(key)
-      parameter = @parameters[key]
+      parameter = self[key]
 
       parameter and not parameter.is_a?(SanitizedParameter)
     end
@@ -67,9 +50,9 @@ module BinData
 
     def move_unknown_parameters_to(dest)
       unless @all_sanitized
-        unused_keys = @parameters.keys - @the_class.accepted_parameters.all
+        unused_keys = keys - @the_class.accepted_parameters.all
         unused_keys.each do |key|
-          dest[key] = @parameters.delete(key)
+          dest[key] = delete(key)
         end
       end
     end
@@ -85,7 +68,7 @@ module BinData
     private
 
     def ensure_no_nil_values
-      @parameters.each do |key, value|
+      each do |key, value|
         if value.nil?
           raise ArgumentError,
                 "parameter '#{key}' has nil value in #{@the_class}"
@@ -95,7 +78,7 @@ module BinData
 
     def merge_default_parameters!
       @the_class.default_parameters.each do |key, value|
-        @parameters[key] ||= value
+        self[key] ||= value
       end
     end
 
@@ -215,8 +198,10 @@ module BinData
       end
     end
 
-    def instantiate(parent = nil)
-      @obj_class.new(@obj_params, parent)
+    def instantiate(value = nil, parent = nil)
+      @factory ||= @obj_class.new(@obj_params)
+
+      @factory.new(value, parent)
     end
   end
   #----------------------------------------------------------------------------
@@ -228,8 +213,8 @@ module BinData
     end
     attr_reader :name
 
-    def instantiate(parent = nil)
-      @prototype.instantiate(parent)
+    def instantiate(value = nil, parent = nil)
+      @prototype.instantiate(value, parent)
     end
   end
   #----------------------------------------------------------------------------

data/lib/bindata/string.rb

@@ -10,24 +10,24 @@ module BinData
   #
   #   obj = BinData::String.new(:read_length => 5)
   #   obj.read(data)
-  #   obj.value #=> "abcde"
+  #   obj #=> "abcde"
   #
   #   obj = BinData::String.new(:length => 6)
   #   obj.read(data)
-  #   obj.value #=> "abcdef"
-  #   obj.value = "abcdefghij"
-  #   obj.value #=> "abcdef"
-  #   obj.value = "abcd"
-  #   obj.value #=> "abcd\000\000"
+  #   obj #=> "abcdef"
+  #   obj.assign("abcdefghij")
+  #   obj #=> "abcdef"
+  #   obj.assign("abcd")
+  #   obj #=> "abcd\000\000"
   #
   #   obj = BinData::String.new(:length => 6, :trim_padding => true)
-  #   obj.value = "abcd"
-  #   obj.value #=> "abcd"
+  #   obj.assign("abcd")
+  #   obj #=> "abcd"
   #   obj.to_binary_s #=> "abcd\000\000"
   #
   #   obj = BinData::String.new(:length => 6, :pad_char => 'A')
-  #   obj.value = "abcd"
-  #   obj.value #=> "abcdAA"
+  #   obj.assign("abcd")
+  #   obj #=> "abcdAA"
   #   obj.to_binary_s #=> "abcdAA"
   #
   # == Parameters
@@ -83,12 +83,11 @@ module BinData
     end
 
     def snapshot
-      # override to ensure length and optionally trim padding
+      # override to trim padding
       result = super
-      if has_parameter?(:length)
-        result = truncate_or_pad_to_length(result)
-      end
-      if get_parameter(:trim_padding) == true
+      result = clamp_to_length(result)
+
+      if get_parameter(:trim_padding)
         result = trim_padding(result)
       end
       result
@@ -97,7 +96,7 @@ module BinData
     #---------------
     private
 
-    def truncate_or_pad_to_length(str)
+    def clamp_to_length(str)
       len = eval_parameter(:length) || str.length
       if str.length == len
         str
@@ -113,7 +112,7 @@ module BinData
     end
 
     def value_to_binary_string(val)
-      truncate_or_pad_to_length(val)
+      clamp_to_length(val)
     end
 
     def read_and_return_value(io)

data/lib/bindata/stringz.rb

@@ -14,7 +14,6 @@ module BinData
   #   obj = BinData::Stringz.new
   #   obj.read(data)
   #   obj.snapshot #=> "abcd"
-  #   obj.value #=> "abcd"
   #   obj.num_bytes #=> 5
   #   obj.to_binary_s #=> "abcd\000"
   #

data/lib/bindata/struct.rb

@@ -1,6 +1,11 @@
 require 'bindata/base'
 
 module BinData
+
+  class Base
+    optional_parameter :onlyif  # Used by Struct
+  end
+
   # A Struct is an ordered collection of named data objects.
   #
   #    require 'bindata'
@@ -119,7 +124,12 @@ module BinData
       end
 
       def hidden_field_names(hidden)
-        (hidden || []).collect { |h| h.to_s }
+        (hidden || []).collect do |h|
+          unless Symbol === h
+            warn "Hidden field '#{h}' should be provided as a symbol.  Using strings is deprecated"
+          end
+          h.to_s # TODO: change this to sym
+        end
       end
 
       def ensure_field_names_are_valid(field_names)
@@ -142,10 +152,11 @@ module BinData
       end
     end
 
-    def initialize(parameters = {}, parent = nil)
-      super
+    def initialize_shared_instance
+      @field_names = get_parameter(:fields).field_names.freeze
+    end
 
-      @field_names = get_parameter(:fields).field_names
+    def initialize_instance
       @field_objs  = []
     end
 
@@ -219,7 +230,7 @@ module BinData
 
     def do_num_bytes #:nodoc:
       instantiate_all_objs
-      sum_num_bytes_for_all_fields.ceil
+      sum_num_bytes_for_all_fields
     end
 
     #---------------
@@ -258,7 +269,7 @@ module BinData
     def instantiate_obj_at(index)
       if @field_objs[index].nil?
         field = get_parameter(:fields)[index]
-        @field_objs[index] = field.instantiate(self)
+        @field_objs[index] = field.instantiate(nil, self)
       end
     end
 

data/lib/bindata/trace.rb

@@ -25,10 +25,14 @@ module BinData
   # This is useful for debugging a BinData declaration.
   def trace_reading(io = STDERR, &block)
     @tracer = Tracer.new(io)
+    BasePrimitive.turn_on_tracing
+    Choice.turn_on_tracing
     if block_given?
       begin
         block.call
       ensure
+        BasePrimitive.turn_off_tracing
+        Choice.turn_off_tracing
         @tracer = nil
       end
     end
@@ -39,4 +43,52 @@ module BinData
   end
 
   module_function :trace_reading, :trace_message
+
+  class BasePrimitive < BinData::Base
+    class << self
+      def turn_on_tracing
+        alias_method :hook_after_do_read, :trace_value
+      end
+
+      def turn_off_tracing
+        alias_method :hook_after_do_read, :null_method
+      end
+    end
+
+    #---------------
+    private
+
+    def null_method; end
+
+    def trace_value
+      BinData::trace_message do |tracer|
+        value_string = _value.inspect
+        tracer.trace_obj(debug_name, value_string)
+      end
+    end
+  end
+
+  class Choice < BinData::Base
+    class << self
+      def turn_on_tracing
+        alias_method :hook_before_do_read, :trace_selection
+      end
+
+      def turn_off_tracing
+        alias_method :hook_before_do_read, :null_method
+      end
+    end
+
+    #---------------
+    private
+
+    def null_method; end
+
+    def trace_selection
+      BinData::trace_message do |tracer|
+        selection_string = eval_parameter(:selection).inspect
+        tracer.trace_obj("#{debug_name}-selection-", selection_string)
+      end
+    end
+  end
 end

data/lib/bindata/wrapper.rb

@@ -9,8 +9,10 @@ module BinData
   #
   #   class Uint8Array < BinData::Wrapper
   #     default_parameter :initial_element_value => 0
-  #     array :type => [:uint8, {:initial_value => :initial_element_value}],
-  #           :initial_length => 2
+  #
+  #     array :initial_length => 2 do
+  #       uint8 :initial_value => :initial_element_value
+  #     end
   #   end
   #
   #   arr = Uint8Array.new
@@ -40,11 +42,9 @@ module BinData
 
     mandatory_parameter :wrapped
 
-    def initialize(parameters = {}, parent = nil)
-      super
-
+    def initialize_instance
       prototype = get_parameter(:wrapped)
-      @wrapped = prototype.instantiate(self)
+      @wrapped = prototype.instantiate(nil, self)
     end
 
     def clear #:nodoc:
@@ -82,5 +82,27 @@ module BinData
     def do_num_bytes #:nodoc:
       @wrapped.do_num_bytes
     end
+
+    #---------------
+    private
+
+    def extract_args(args)
+      klass = wrapped_class
+      if klass
+        klass.arg_extractor.extract(klass, args)
+      else
+        super
+      end
+    end
+
+    def wrapped_class
+      return nil if self.class.field.nil?
+
+      begin
+        RegisteredClasses.lookup(self.class.field.type, self.class.endian)
+      rescue BinData::UnRegisteredTypeError
+        nil
+      end
+    end
   end
 end

data/manual.haml

@@ -2,16 +2,18 @@
 %html{ :xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en" }
   %head
     %meta{ :content => "text/html; charset=iso-8859-1", "http-equiv" => "Content-Type" }
+    %meta{ :description =>"How to easily parse binary data in Ruby" }
+    %meta{ :keywords =>"ruby, parse binary data, read binary data" }
     %title
-      BinData Reference Manual
+      Parsing Binary Data in Ruby - BinData Reference Manual
     :javascript
       var TINY={};function T$(i){return document.getElementById(i)}function T$$(e,p){return p.getElementsByTagName(e)}TINY.accordion=function(){function slider(n){this.n=n;this.a=[]}slider.prototype.init=function(t,e,m,o,k){var a=T$(t),i=s=0,n=a.childNodes,l=n.length;this.s=k||0;this.m=m||0;for(i;i<l;i++){var v=n[i];if(v.nodeType!=3){this.a[s]={};this.a[s].h=h=T$$(e,v)[0];this.a[s].c=c=T$$('div',v)[0];h.onclick=new Function(this.n+'.pr(0,'+s+')');if(o==s){h.className=this.s;c.style.height='auto';c.d=1}else{c.style.height=0;c.d=-1}s++}}this.l=s};slider.prototype.pr=function(f,d){for(var i=0;i<this.l;i++){var h=this.a[i].h,c=this.a[i].c,k=c.style.height;k=k=='auto'?1:parseInt(k);clearInterval(c.t);if((k!=1&&c.d==-1)&&(f==1||i==d)){c.style.height='';c.m=c.offsetHeight;c.style.height=k+'px';c.d=1;h.className=this.s;su(c,1)}else if(k>0&&(f==-1||this.m||i==d)){c.d=-1;h.className='';su(c,-1)}}};function su(c){c.t=setInterval(function(){sl(c)},20)};function sl(c){var h=c.offsetHeight,d=c.d==1?c.m-h:h;c.style.height=h+(Math.ceil(d/5)*c.d)+'px';c.style.opacity=h/c.m;c.style.filter='alpha(opacity='+h*100/c.m+')';if((c.d==1&&h>=c.m)||(c.d!=1&&h==1)){if(c.d==1){c.style.height='auto'}clearInterval(c.t)}};return{slider:slider}}();
 
       var menu1, menu2, menu3, menu4, menu5, menu6;
-      var menu7, menu8, menu9, menu10, menu11;
+      var menu7, menu8, menu9, menu10, menu11, menu12, menu13;
 
       function init_accordion() {
-        menu1 = new TINY.accordion.slider("menu1"); menu1.init("menu1","a",1,0);
+        menu1 = new TINY.accordion.slider("menu1"); menu1.init("menu1","a",1,-1);
         menu2 = new TINY.accordion.slider("menu2"); menu2.init("menu2","a",1,-1);
         menu3 = new TINY.accordion.slider("menu3"); menu3.init("menu3","a",1,-1);
         menu4 = new TINY.accordion.slider("menu4"); menu4.init("menu4","a",1,-1);
@@ -22,6 +24,8 @@
         menu9 = new TINY.accordion.slider("menu9"); menu9.init("menu9","a",1,-1);
         menu10 = new TINY.accordion.slider("menu10"); menu10.init("menu10","a",1,-1);
         menu11 = new TINY.accordion.slider("menu11"); menu11.init("menu11","a",1,-1);
+        menu12 = new TINY.accordion.slider("menu12"); menu11.init("menu12","a",1,-1);
+        menu13 = new TINY.accordion.slider("menu13"); menu11.init("menu13","a",1,-1);
       };
       window.onload = init_accordion;
 
@@ -125,6 +129,11 @@
                       License
                     .acc-section
                       .acc-content
+                  %li
+                    %a{ :href => "#donate" }
+                      Donate
+                    .acc-section
+                      .acc-content
           %li
             %a{ :href => "#installation" }
               Installation
@@ -168,13 +177,23 @@
                     .acc-section
                       .acc-content
                   %li
-                    %a{ :href => "#optional_fields" }
-                      Optional fields
+                    %a{ :href => "#dependencies_between_fields" }
+                      Dependencies between fields
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#nested_records" }
+                      Nested Records
                     .acc-section
                       .acc-content
                   %li
-                    %a{ :href => "#handling_dependencies_between_fields" }
-                      Handling dependencies between fields
+                    %a{ :href => "#bitfields" }
+                      Bitfields
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#optional_fields" }
+                      Optional fields
                     .acc-section
                       .acc-content
           %li
@@ -241,22 +260,49 @@
               Arrays
             .acc-section
               .acc-content
+                %ul.level2#menu9
+                  %li
+                    %a{ :href => "#array_syntax" }
+                      Array syntax
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#array_parameters" }
+                      Array parameters
+                    .acc-section
+                      .acc-content
           %li
             %a{ :href => "#choices" }
               Choices
             .acc-section
               .acc-content
+                %ul.level2#menu10
+                  %li
+                    %a{ :href => "#choice_syntax" }
+                      Choice syntax
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#choice_parameters" }
+                      Choice parameters
+                    .acc-section
+                      .acc-content
           %li
             %a{ :href => "#advanced_topics" }
               Advanced Topics
             .acc-section
               .acc-content
-                %ul.level2#menu9
+                %ul.level2#menu11
                   %li
                     %a{ :href => "#skipping_over_unused_data" }
                       Skipping over unused data
                     .acc-section
                       .acc-content
+                  %li
+                    %a{ :href => "#bitaligned_records" }
+                      Bit-aligned Records
+                    .acc-section
+                      .acc-content
                   %li
                     %a{ :href => "#wrappers" }
                       Wrappers
@@ -267,7 +313,7 @@
                       Parameterizing User Defined Types
                     .acc-section
                       .acc-content
-                        %ul.level3#menu10
+                        %ul.level3#menu12
                           %li
                             %a{ :href => "#mandatory_parameters" }
                               Mandatory Parameters
@@ -283,7 +329,7 @@
                       Debugging
                     .acc-section
                       .acc-content
-                        %ul.level3#menu11
+                        %ul.level3#menu13
                           %li
                             %a{ :href => "#tracing" }
                               Tracing