bindata 1.3.1 → 1.4.0

data/lib/bindata/skip.rb

@@ -25,8 +25,6 @@ module BinData
   #
   class Skip < BinData::BasePrimitive
 
-    register_self
-
     mandatory_parameter :length
 
     #---------------

data/lib/bindata/string.rb

@@ -47,8 +47,6 @@ module BinData
   #                            not be trimmed when writing.
   class String < BinData::BasePrimitive
 
-    register_self
-
     optional_parameters :read_length, :length, :trim_padding
     default_parameters  :pad_char => "\0"
     mutually_exclusive_parameters :read_length, :length
@@ -56,7 +54,7 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
+      def sanitize_parameters!(params) #:nodoc:
         params.warn_replacement_parameter(:initial_length, :read_length)
 
         if params.has_parameter?(:pad_char)
@@ -97,6 +95,8 @@ module BinData
     private
 
     def clamp_to_length(str)
+      str.force_encoding(Encoding::BINARY) if RUBY_VERSION >= "1.9"
+
       len = eval_parameter(:length) || str.length
       if str.length == len
         str

data/lib/bindata/stringz.rb

@@ -26,8 +26,6 @@ module BinData
   #                        byte.
   class Stringz < BinData::BasePrimitive
 
-    register_self
-
     optional_parameters :max_length
 
     def assign(val)
@@ -69,6 +67,8 @@ module BinData
     end
 
     def trim_and_zero_terminate(str)
+      str.force_encoding(Encoding::BINARY) if RUBY_VERSION >= "1.9"
+
       str = truncate_after_first_zero_byte(str)
       str = trim_to(str, eval_parameter(:max_length))
       append_zero_byte_if_needed(str)

data/lib/bindata/struct.rb

@@ -52,57 +52,46 @@ module BinData
   #                      calls to #read, #write, #num_bytes or #snapshot.
   class Struct < BinData::Base
 
-    register_self
-
     mandatory_parameter :fields
     optional_parameters :endian, :hide
 
     # These reserved words may not be used as field names
     RESERVED = Hash[*
-                 (::Hash.instance_methods.collect { |meth| meth.to_s } + 
+                 (Hash.instance_methods +
                   %w{alias and begin break case class def defined do else elsif
                      end ensure false for if in module next nil not or redo
                      rescue retry return self super then true undef unless until
                      when while yield} +
-                  %w{array element index value} ).
+                  %w{array element index value} ).collect { |name| name.to_sym }.
                   uniq.collect { |key| [key, true] }.flatten
                ]
 
-    # A hash that can be accessed via attributes.
-    class Snapshot < Hash #:nodoc:
-      def respond_to?(symbol, include_private = false)
-        has_key?(symbol.to_s) || super
-      end
-
-      def method_missing(symbol, *args)
-        self[symbol.to_s] || super
-      end
-    end
-
     class << self
 
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
-        sanitize_endian(params, sanitizer)
-        sanitize_fields(params, sanitizer)
-        sanitize_hide(params, sanitizer)
+      def sanitize_parameters!(params) #:nodoc:
+        sanitize_endian(params)
+        sanitize_fields(params)
+        sanitize_hide(params)
       end
 
       #-------------
       private
 
-      def sanitize_endian(params, sanitizer)
+      def sanitize_endian(params)
         if params.needs_sanitizing?(:endian)
-          params[:endian] = sanitizer.create_sanitized_endian(params[:endian])
+          endian = params.create_sanitized_endian(params[:endian])
+          params[:endian] = endian
+          params.endian   = endian # sync params[:endian] and params.endian
         end
       end
 
-      def sanitize_fields(params, sanitizer)
+      def sanitize_fields(params)
         if params.needs_sanitizing?(:fields)
           fields = params[:fields]
 
-          params[:fields] = sanitizer.create_sanitized_fields
+          params[:fields] = params.create_sanitized_fields
           fields.each do |ftype, fname, fparams|
-            params[:fields].add_field(ftype, fname, fparams, params[:endian])
+            params[:fields].add_field(ftype, fname, fparams)
           end
 
           field_names = sanitized_field_names(params[:fields])
@@ -110,7 +99,7 @@ module BinData
         end
       end
 
-      def sanitize_hide(params, sanitizer)
+      def sanitize_hide(params)
         if params.needs_sanitizing?(:hide) and params.has_parameter?(:fields)
           field_names  = sanitized_field_names(params[:fields])
           hfield_names = hidden_field_names(params[:hide])
@@ -128,7 +117,7 @@ module BinData
           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
+          h.to_sym
         end
       end
 
@@ -170,11 +159,11 @@ module BinData
 
     def assign(val)
       clear
-      assign_fields(as_snapshot(val))
+      assign_fields(val)
     end
 
     def snapshot
-      snapshot = Snapshot.new
+      snapshot = Snapshot.new(field_names)
       field_names.each do |name|
         obj = find_obj_for_name(name)
         snapshot[name] = obj.snapshot if include_obj(obj)
@@ -191,11 +180,11 @@ module BinData
       else
         hidden = get_parameter(:hide) || []
         @field_names.compact - hidden
-      end
+      end.collect { |x| x.to_s }
     end
 
     def respond_to?(symbol, include_private = false) #:nodoc:
-      field_names(true).include?(symbol.to_s.chomp("=")) || super
+      @field_names.include?(base_field_name(symbol)) || super
     end
 
     def method_missing(symbol, *args, &block) #:nodoc:
@@ -233,9 +222,28 @@ module BinData
       sum_num_bytes_for_all_fields
     end
 
+    def [](key)
+      find_obj_for_name(key)
+    end
+
+    def []=(key, value)
+      obj = find_obj_for_name(key)
+      if obj
+        obj.assign(value)
+      end
+    end
+
+    def has_key?(key)
+      @field_names.index(base_field_name(key))
+    end
+
     #---------------
     private
 
+    def base_field_name(name)
+      name.to_s.chomp("=").to_sym
+    end
+
     def invoke_field(obj, symbol, args)
       name = symbol.to_s
       is_writer = (name[-1, 1] == "=")
@@ -252,8 +260,7 @@ module BinData
     end
 
     def find_obj_for_name(name)
-      field_name = name.to_s.chomp("=")
-      index = @field_names.index(field_name)
+      index = @field_names.index(base_field_name(name))
       if index
         instantiate_obj_at(index)
         @field_objs[index]
@@ -273,27 +280,29 @@ module BinData
       end
     end
 
-    def as_snapshot(val)
-      if val.class == Hash
-        snapshot = Snapshot.new
-        val.each_pair { |k,v| snapshot[k.to_s] = v unless v.nil? }
-        snapshot
-      elsif val.nil?
-        Snapshot.new
-      else
-        val
-      end
-    end
+    def assign_fields(val)
+      src = as_stringified_hash(val)
 
-    def assign_fields(snapshot)
-      field_names(true).each do |name|
+      @field_names.compact.each do |name|
         obj = find_obj_for_name(name)
-        if obj and snapshot.respond_to?(name)
-          obj.assign(snapshot.__send__(name))
+        if obj and src.has_key?(name)
+          obj.assign(src[name])
         end
       end
     end
 
+    def as_stringified_hash(val)
+      if BinData::Struct === val
+        val
+      elsif val.nil?
+        {}
+      else
+        hash = Snapshot.new(field_names)
+        val.each_pair { |k,v| hash[k] = v }
+        hash
+      end
+    end
+
     def sum_num_bytes_for_all_fields
       sum_num_bytes_below_index(@field_objs.length)
     end
@@ -314,5 +323,53 @@ module BinData
     def include_obj(obj)
       not obj.has_parameter?(:onlyif) or obj.eval_parameter(:onlyif)
     end
+
+    # A hash that can be accessed via attributes.
+    class Snapshot < ::Hash #:nodoc:
+      def initialize(order = [])
+        @order = order.compact
+      end
+
+      if RUBY_VERSION <= "1.9"
+        def keys
+          k = super
+          @order & k
+        end
+
+        def each
+          keys.each do |k|
+            yield [k, self[k]]
+          end
+        end
+
+        def each_pair
+          each do |el|
+            yield *el
+          end
+        end
+      end
+
+      def has_key?(key)
+        super(key.to_s)
+      end
+
+      def [](key)
+        super(key.to_s)
+      end
+
+      def []=(key, value)
+        if value != nil
+          super(key.to_s, value)
+        end
+      end
+
+      def respond_to?(symbol, include_private = false)
+        has_key?(symbol) || super
+      end
+
+      def method_missing(symbol, *args)
+        self[symbol] || super
+      end
+    end
   end
 end

data/lib/bindata/wrapper.rb

@@ -2,6 +2,15 @@ require 'bindata/base'
 require 'bindata/dsl'
 
 module BinData
+  class SanitizedParameters < Hash
+    def move_unknown_parameters_to(dest)
+      unused_keys = keys - @the_class.accepted_parameters.all
+      unused_keys.each do |key|
+        dest[key] = delete(key)
+      end
+    end
+  end
+
   # A Wrapper allows the creation of new BinData types that
   # provide default parameters.
   #
@@ -24,19 +33,23 @@ module BinData
   class Wrapper < BinData::Base
     include DSLMixin
 
-    register_subclasses
-    dsl_parser :only_one_field, :no_fieldnames
+    unregister_self
+    dsl_parser :wrapper
 
     class << self
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
-        raise "no wrapped type was specified in #{self}" if field.nil?
+      def sanitize_parameters!(params) #:nodoc:
+        raise "no wrapped type was specified in #{self}" if fields[0].nil?
 
-        wrapped_type = field.type
-        wrapped_params = field.params.dup
+        wrapped_type = fields[0].type
+        wrapped_params = fields[0].params.dup
 
         params.move_unknown_parameters_to(wrapped_params)
 
-        params[:wrapped] = sanitizer.create_sanitized_object_prototype(wrapped_type, wrapped_params, endian)
+        params.endian = endian unless endian.nil?
+        params[:wrapped] = params.create_sanitized_object_prototype(wrapped_type, wrapped_params)
+
+        wrapped_class = params[:wrapped].instance_variable_get(:@obj_class)
+        warn "BinData::Wrapper is deprecated as of BinData 1.3.2.  #{self} should derive from #{wrapped_class}\n   See http://bindata.rubyforge.org/#extending_existing_types"
       end
     end
 
@@ -96,10 +109,10 @@ module BinData
     end
 
     def wrapped_class
-      return nil if self.class.field.nil?
+      return nil if self.class.fields[0].nil?
 
       begin
-        RegisteredClasses.lookup(self.class.field.type, self.class.endian)
+        RegisteredClasses.lookup(self.class.fields[0].type, self.class.endian)
       rescue BinData::UnRegisteredTypeError
         nil
       end

data/manual.haml

@@ -1,16 +1,16 @@
 !!!
 %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" }
+    %meta{ :content => "text/html; charset=utf-8", "http-equiv" => "Content-Type" }
+    %meta{ :description =>"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
-      Parsing Binary Data in Ruby - BinData Reference Manual
+      Reading, writing and parsing binary data in Ruby
     :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, menu12, menu13;
+      var menu1, menu2, menu3, menu4, menu5, menu6, menu7;
+      var menu8, menu9, menu10, menu11, menu12, menu13, menu14;
 
       function init_accordion() {
         menu1 = new TINY.accordion.slider("menu1"); menu1.init("menu1","a",1,-1);
@@ -24,8 +24,9 @@
         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);
+        menu12 = new TINY.accordion.slider("menu12"); menu12.init("menu12","a",1,-1);
+        menu13 = new TINY.accordion.slider("menu13"); menu13.init("menu13","a",1,-1);
+        menu14 = new TINY.accordion.slider("menu14"); menu14.init("menu14","a",1,-1);
       };
       window.onload = init_accordion;
 
@@ -108,6 +109,17 @@
         #main_content .ruby .global { color: #7FB; }
         #main_content .ruby .expr { color: #227; }
         #main_content .ruby .escape { color: #277; }
+    %script{:type => "text/javascript"}
+      :plain
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', 'UA-20958115-1']);
+        _gaq.push(['_trackPageview']);
+
+        (function() {
+          var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+          ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+          var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+        })();
 
   %body
     #left_frame
@@ -246,13 +258,13 @@
                               .acc-content
                   %li
                     %a{ :href => "#user_defined_primitive_types" }
-                      User Defined Primitive Types
+                      User-defined Primitive Types
                     .acc-section
                       .acc-content
                         %ul.level3#menu8
                           %li
                             %a{ :href => "#advanced_user_defined_primitive_types" }
-                              Advanced User Defined Primitive Types
+                              Advanced Example
                             .acc-section
                               .acc-content
           %li
@@ -293,37 +305,6 @@
             .acc-section
               .acc-content
                 %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
-                    .acc-section
-                      .acc-content
-                  %li
-                    %a{ :href => "#parameterizing_user_defined_types" }
-                      Parameterizing User Defined Types
-                    .acc-section
-                      .acc-content
-                        %ul.level3#menu12
-                          %li
-                            %a{ :href => "#mandatory_parameters" }
-                              Mandatory Parameters
-                            .acc-section
-                              .acc-content
-                          %li
-                            %a{ :href => "#default_parameters" }
-                              Default Parameters
-                            .acc-section
-                              .acc-content
                   %li
                     %a{ :href => "#debugging" }
                       Debugging
@@ -345,6 +326,58 @@
                               Hidden fields
                             .acc-section
                               .acc-content
+                  %li
+                    %a{ :href => "#parameterizing_user_defined_types" }
+                      Parameterizing Types
+                    .acc-section
+                      .acc-content
+                        %ul.level3#menu12
+                          %li
+                            %a{ :href => "#mandatory_parameters" }
+                              Mandatory Parameters
+                            .acc-section
+                              .acc-content
+                          %li
+                            %a{ :href => "#default_parameters" }
+                              Default Parameters
+                            .acc-section
+                              .acc-content
+                  %li
+                    %a{ :href => "#extending_existing_types" }
+                      Extending existing Types
+                    .acc-section
+                      .acc-content
+                  %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 => "#faq" }
+              FAQ
+            .acc-section
+              .acc-content
+                %ul.level2#menu14
+                  %li
+                    %a{ :href => "#im_using_ruby_19_how_do_i_use_string_encodings_with_bindata" }
+                      String encoding - Ruby 1.9
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#how_do_i_speed_up_initialization" }
+                      Performance
+                    .acc-section
+                      .acc-content
+                  %li
+                    %a{ :href => "#how_do_i_model_this_complex_nested_format" }
+                      Recursive declarations
+                    .acc-section
+                      .acc-content
           %li
             %a{ :href => "#alternatives" }
               Alternatives