bindata 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1591b7284eb5311a1577007b50506a3169849cc
-  data.tar.gz: a60a5656dcb5586f12bc7fe88e98af7d12652d7a
+  metadata.gz: fba829df2a0f618021920683747584daef8f572a
+  data.tar.gz: efe2ac6d0ab61895a09f271fb9d7712e289f1897
 SHA512:
-  metadata.gz: 57b52b55ca1ab97820293d9c73b3e085542a955052b64e3873a87e7b8f0fdd84635a33843ad4aeb92dd7b089a7b988e2b9fe236c265189dbe310766811d7c5cc
-  data.tar.gz: 01a0327084e334cd02459daf396253b11f266a3c443dcf3f57e144dea6f653e98e5aa4d03249a8f5794bd867e727df609137b5e7519b400aa00cdec9c2cfc64b
+  metadata.gz: eef3a6fd17fcb5fe9afcffa35c566cd4e0752063f20bc4d9d135aa3300184454b8974d3161d90e37390dfa3b6606b5f1bfe1217705075e28bd2e5641b11f878d
+  data.tar.gz: 55bc265de56013c33f1e9abf7d38a796deff58cedf7faa1c20e77ee6dbad5e42a080c3ab46c8f06503e7268888cedd38b51667e1d091fa23cb89afc39b5b124e

data/.travis.yml

@@ -2,4 +2,6 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.1
   - jruby
+  - ruby-head

data/ChangeLog.rdoc

@@ -1,5 +1,18 @@
 = BinData Changelog
 
+== Version 2.1.0 (2014-04-16)
+
+* Performance improvements.
+* Removed deprecated parameters.
+* Code refactored to use Ruby 1.9 features.
+* #eval_parameters can now call private methods.  Requested by Ole Rasmussen.
+* Can now determine state of :onlyif fields.  Requested by Ole Rasmussen.
+* Renamed #offset to #abs_offset for clarity.  #offset is now deprecated.
+* Support :byte_align for fields in structs.  Requested by Igor Yamolov.
+* Added bit fields with dynamic length.  Requested by Jacob Dam.
+* Added "endian :big_and_little" option which creates :big and :little
+  versions of the class.  Thanks to Jacob Lukas for the prototype.
+
 == Version 2.0.0 (2014-02-02)
 
 * Ruby 1.8 now has its own separate branch.

data/NEWS.rdoc

@@ -1,3 +1,19 @@
+= 2.1.0
+
+Several new features in this release.
+
+* Fields can be aligned on n-bytes boundaries.  This make it easier to write
+  parsers for aligned structures.
+* The endian value :big_and_little can be used to automatically create :big and
+  :little endian versions of the class.
+* Bit fields can be defined to have their length determined at runtime.
+* The state of :onlyif fields can be determined by #field?
+
+== Deprecations
+
+The #offset method has been renamed to #abs_offset.  This make an obvious
+distinction to #rel_offset.
+
 = 2.0.0
 
 BinData 2.0.0 requires ruby 1.9 or greater.  Support for ruby 1.8 is found in

data/README.md

@@ -1,5 +1,10 @@
 # What is BinData?
 
+[![Version     ](http://img.shields.io/gem/v/bindata.svg)                       ](https://rubygems.org/gems/bindata)
+[![Travis CI   ](http://img.shields.io/travis/dmendel/bindata/master.svg)     ](https://travis-ci.org/dmendel/bindata)
+[![Quality     ](http://img.shields.io/codeclimate/github/dmendel/bindata.svg)](https://codeclimate.com/github/dmendel/bindata)
+[![Coverage    ](http://img.shields.io/coveralls/dmendel/bindata.svg)         ](https://coveralls.io/r/dmendel/bindata)
+
 Do you ever find yourself writing code like this?
 
 ```ruby

data/bindata.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency('rake')
   s.add_development_dependency('minitest', "> 5.0.0")
+  s.add_development_dependency('coveralls')
   s.description = <<-END.gsub(/^ +/, "")
     BinData is a declarative way to read and write binary file formats.
 

data/examples/gzip.rb

@@ -105,7 +105,7 @@ if __FILE__ == $0
                                                    g.footer.uncompressed_size,
                                                    ratio,
                                                    g.file_name]
-  puts "Comment: #{g.comment}" if g.comment != ""
+  puts "Comment: #{g.comment}" if g.comment?
   puts
 
   puts "Executing gzip -l -v"

data/lib/bindata.rb

@@ -23,7 +23,7 @@ require 'bindata/struct'
 require 'bindata/trace'
 require 'bindata/virtual'
 require 'bindata/alignment'
-require 'bindata/deprecated'
+require 'bindata/warnings'
 
 # = BinData
 # 

data/lib/bindata/array.rb

@@ -48,35 +48,16 @@ module BinData
   # Each data object in an array has the variable +index+ made available
   # to any lambda evaluated as a parameter of that data object.
   class Array < BinData::Base
-    include DSLMixin
+    extend DSLMixin
     include Enumerable
 
-    dsl_parser :array
+    dsl_parser    :array
+    arg_processor :array
 
     mandatory_parameter :type
     optional_parameters :initial_length, :read_until
     mutually_exclusive_parameters :initial_length, :read_until
 
-    class << self
-
-      def sanitize_parameters!(params) #:nodoc:
-        unless params.has_parameter?(:initial_length) or
-                 params.has_parameter?(:read_until)
-          # ensure one of :initial_length and :read_until exists
-          params[:initial_length] = 0
-        end
-
-        params.warn_replacement_parameter(:read_length, :initial_length)
-
-        params.merge!(dsl_params)
-
-        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
-
     def initialize_shared_instance
       @element_prototype = get_parameter(:type)
       if get_parameter(:read_until) == :eof
@@ -292,6 +273,26 @@ module BinData
     end
   end
 
+  class ArrayArgProcessor < BaseArgProcessor
+    def sanitize_parameters!(obj_class, params) #:nodoc:
+      unless params.has_parameter?(:initial_length) or
+               params.has_parameter?(:read_until)
+        # ensure one of :initial_length and :read_until exists
+        params[:initial_length] = 0
+      end
+
+      params.warn_replacement_parameter(:read_length, :initial_length)
+      params.must_be_integer(:initial_length, :read_length)
+
+      params.merge!(obj_class.dsl_params)
+
+      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
+
   # Logic for the :read_until parameter
   module ReadUntilPlugin
     def do_read(io)

data/lib/bindata/base.rb

@@ -8,33 +8,6 @@ require 'bindata/registry'
 require 'bindata/sanitize'
 
 module BinData
-  # ArgExtractors take the arguments passed to BinData::Base.new and
-  # separate them into [value, parameters, parent].
-  class BaseArgExtractor
-    @@empty_hash = Hash.new.freeze
-
-    def self.extract(the_class, the_args)
-      args = the_args.dup
-      value = parameters = parent = nil
-
-      if args.length > 1 and args.last.is_a? BinData::Base
-        parent = args.pop
-      end
-
-      if args.length > 0 and args.last.is_a? Hash
-        parameters = args.pop
-      end
-
-      if args.length > 0
-        value = args.pop
-      end
-
-      parameters ||= @@empty_hash
-
-      return [value, parameters, parent]
-    end
-  end
-
   # This is the abstract base class for all data objects.
   class Base
     extend AcceptedParametersPlugin
@@ -43,18 +16,25 @@ module BinData
     include RegisterNamePlugin
 
     class << self
-
       # Instantiates this class and reads from +io+, returning the newly
-      # created data object.
-      def read(io)
-        obj = self.new
+      # created data object.  +args+ will be used when instantiating.
+      def read(io, *args)
+        obj = self.new(*args)
         obj.read(io)
         obj
       end
 
-      # The arg extractor for this class.
-      def arg_extractor
-        BaseArgExtractor
+      # The arg processor for this class.
+      def arg_processor(name = nil)
+        if name
+          @arg_processor = "#{name}_arg_processor".gsub(/(?:^|_)(.)/) { $1.upcase }.to_sym
+        elsif @arg_processor.is_a? Symbol
+          @arg_processor = BinData::const_get(@arg_processor).new
+        elsif @arg_processor.nil?
+          @arg_processor = superclass.arg_processor
+        else
+          @arg_processor
+        end
       end
 
       # The name of this class as used by Records, Arrays etc.
@@ -69,11 +49,9 @@ module BinData
 
       # Registers all subclasses of this class for use
       def register_subclasses #:nodoc:
-        class << self
-          define_method(:inherited) do |subclass|
-            RegisteredClasses.register(subclass.name, subclass)
-            register_subclasses
-          end
+        define_singleton_method(:inherited) do |subclass|
+          RegisteredClasses.register(subclass.name, subclass)
+          register_subclasses
         end
       end
 
@@ -83,6 +61,9 @@ module BinData
     # Register all subclasses of this class.
     register_subclasses
 
+    # Set the initial arg processor.
+    arg_processor :base
+
     # Creates a new data object.
     #
     # Args are optional, but if present, must be in the following order.
@@ -96,10 +77,7 @@ module BinData
     # object resides under.
     #
     def initialize(*args)
-      value, parameters, parent = extract_args(args)
-
-      @params = SanitizedParameters.sanitize(parameters, self.class)
-      @parent = parent
+      value, @params, @parent = extract_args(args)
 
       initialize_shared_instance
       initialize_instance
@@ -233,16 +211,17 @@ module BinData
       end
     end
 
-    # Returns the offset of this object wrt to its most distant ancestor.
-    def offset
+    # Returns the offset (in bytes) of this object with respect to its most
+    # distant ancestor.
+    def abs_offset
       if @parent
-        @parent.offset + @parent.offset_of(self)
+        @parent.abs_offset + @parent.offset_of(self)
       else
         0
       end
     end
 
-    # Returns the offset of this object wrt to its parent.
+    # Returns the offset (in bytes) of this object with respect to its parent.
     def rel_offset
       if @parent
         @parent.offset_of(self)
@@ -266,8 +245,8 @@ module BinData
     #---------------
     private
 
-    def extract_args(the_args)
-      self.class.arg_extractor.extract(self.class, the_args)
+    def extract_args(args)
+      self.class.arg_processor.extract_args(self.class, args)
     end
 
     def furthest_ancestor
@@ -284,4 +263,51 @@ module BinData
       str.to_s.dup.force_encoding(Encoding::BINARY)
     end
   end
+
+  # ArgProcessors process the arguments passed to BinData::Base.new into
+  # the form required to initialise the BinData object.
+  #
+  # Any passed parameters are sanitized so the BinData object doesn't
+  # need to perform error checking on the parameters.
+  class BaseArgProcessor
+    @@empty_hash = Hash.new.freeze
+
+    # Takes the arguments passed to BinData::Base.new and
+    # extracts [value, sanitized_parameters, parent].
+    def extract_args(obj_class, obj_args)
+      value, params, parent = separate_args(obj_class, obj_args)
+      sanitized_params = SanitizedParameters.sanitize(params, obj_class)
+
+      [value, sanitized_params, parent]
+    end
+
+    # Separates the arguments passed to BinData::Base.new into
+    # [value, parameters, parent].  Called by #extract_args.
+    def separate_args(obj_class, obj_args)
+      args = obj_args.dup
+      value = parameters = parent = nil
+
+      if args.length > 1 and args.last.is_a? BinData::Base
+        parent = args.pop
+      end
+
+      if args.length > 0 and args.last.is_a? Hash
+        parameters = args.pop
+      end
+
+      if args.length > 0
+        value = args.pop
+      end
+
+      parameters ||= @@empty_hash
+
+      return [value, parameters, parent]
+    end
+
+    # Performs sanity checks on the given parameters.
+    # This method converts the parameters to the form expected
+    # by the data object.
+    def sanitize_parameters!(obj_class, obj_params) 
+    end
+  end
 end

data/lib/bindata/base_primitive.rb

@@ -20,10 +20,10 @@ module BinData
   #   obj.assign(5)
   #   obj #=> 42
   #
-  #   obj = BinData::Uint8.new(:check_value => 3)
+  #   obj = BinData::Uint8.new(:assert_value => 3)
   #   obj.read("\005") #=> BinData::ValidityError: value is '5' but expected '3'
   #
-  #   obj = BinData::Uint8.new(:check_value => lambda { value < 5 })
+  #   obj = BinData::Uint8.new(:assert_value => lambda { value < 5 })
   #   obj.read("\007") #=> BinData::ValidityError: value not as expected
   #
   # == Parameters
@@ -49,22 +49,13 @@ module BinData
   class BasePrimitive < BinData::Base
     unregister_self
 
-    optional_parameters :initial_value, :value, :check_value, :assert, :asserted_value
+    optional_parameters :initial_value, :value, :assert, :asserted_value
     mutually_exclusive_parameters :initial_value, :value
     mutually_exclusive_parameters :asserted_value, :value, :assert
-    mutually_exclusive_parameters :check_value, :assert
-    mutually_exclusive_parameters :check_value, :asserted_value
 
     def initialize_shared_instance
-      if has_parameter?(:check_value) and has_parameter?(:value)
-        warn ":check_value has been deprecated.  Consider using :asserted_value instead of :check_value and :value in #{self.class}."
-      elsif has_parameter?(:check_value)
-        warn ":check_value has been deprecated.  Use :assert instead in #{self.class}."
-      end
-
       extend InitialValuePlugin  if has_parameter?(:initial_value)
       extend ValuePlugin         if has_parameter?(:value)
-      extend CheckValuePlugin    if has_parameter?(:check_value)
       extend AssertPlugin        if has_parameter?(:assert)
       extend AssertedValuePlugin if has_parameter?(:asserted_value)
       super
@@ -169,26 +160,6 @@ module BinData
       end
     end
 
-    # Logic for the :check_value parameter
-    module CheckValuePlugin
-      def do_read(io) #:nodoc:
-        super(io)
-        check_value(snapshot)
-      end
-
-      def check_value(current_value)
-        expected = eval_parameter(:check_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
-          raise ValidityError,
-                "value is '#{current_value}' but " +
-                "expected '#{expected}' for #{debug_name}"
-        end
-      end
-    end
-
     # Logic for the :assert parameter
     module AssertPlugin
       def assign(val)

data/lib/bindata/bits.rb

@@ -6,13 +6,11 @@ module BinData
 
   module BitField #:nodoc: all
     class << self
-      def define_class(nbits, endian, signed = :unsigned)
-        name = ((signed == :signed ) ? "Sbit" : "Bit") + nbits.to_s
-        name << "le" if endian == :little
+      def define_class(name, nbits, endian, signed = :unsigned)
         unless BinData.const_defined?(name)
           BinData.module_eval <<-END
             class #{name} < BinData::BasePrimitive
-              BitField.define_methods(self, #{nbits}, :#{endian}, :#{signed})
+              BitField.define_methods(self, #{nbits.inspect}, #{endian.inspect}, #{signed.inspect})
             end
           END
         end
@@ -22,27 +20,34 @@ module BinData
 
       def define_methods(bit_class, nbits, endian, signed)
         bit_class.module_eval <<-END
+          #{create_params_code(nbits)}
+
           def assign(val)
+            #{create_nbits_code(nbits)}
             #{create_clamp_code(nbits, signed)}
             super(val)
           end
 
           def do_write(io)
+            #{create_nbits_code(nbits)}
             val = _value
-            #{create_int2uint_code(nbits) if signed == :signed}
+            #{create_int2uint_code(nbits, signed)}
             io.writebits(val, #{nbits}, :#{endian})
           end
 
           def do_num_bytes
-            #{nbits / 8.0}
+            #{create_nbits_code(nbits)}
+            #{create_do_num_bytes_code(nbits)}
           end
 
           #---------------
           private
 
+
           def read_and_return_value(io)
+            #{create_nbits_code(nbits)}
             val = io.readbits(#{nbits}, :#{endian})
-            #{create_uint2int_code(nbits) if signed == :signed}
+            #{create_uint2int_code(nbits, signed)}
             val
           end
 
@@ -52,7 +57,51 @@ module BinData
         END
       end
 
+      def create_params_code(nbits)
+        if nbits == :nbits
+          "mandatory_parameter :nbits"
+        else
+          ""
+        end
+      end
+
+      def create_nbits_code(nbits)
+        if nbits == :nbits
+          "nbits = eval_parameter(:nbits)"
+        else
+          ""
+        end
+      end
+
+      def create_do_num_bytes_code(nbits)
+        if nbits == :nbits
+          "nbits / 8.0"
+        else
+          nbits / 8.0
+        end
+      end
+
       def create_clamp_code(nbits, signed)
+        if nbits == :nbits
+          create_dynamic_clamp_code(nbits, signed)
+        else
+          create_fixed_clamp_code(nbits, signed)
+        end
+      end
+
+      def create_dynamic_clamp_code(nbits, signed)
+        if signed == :signed
+          max = "max = (1 << (nbits - 1)) - 1"
+          min = "min = -(max + 1)"
+        else
+          max = "max = (1 << nbits) - 1"
+          min = "min = 0"
+        end
+
+        "#{max}; #{min}; val = (val < min) ? min : (val > max) ? max : val"
+      end
+
+      def create_fixed_clamp_code(nbits, signed)
         if nbits == 1 and signed == :signed
           raise "signed bitfield must have more than one bit" 
         end
@@ -75,30 +124,50 @@ module BinData
         "val = #{clamp}"
       end
 
-      def create_int2uint_code(nbits)
-        "val = val & #{(1 << nbits) - 1}"
+      def create_int2uint_code(nbits, signed)
+        if signed != :signed
+          ""
+        elsif nbits == :nbits
+          "val &= (1 << nbits) - 1"
+        else
+          "val &= #{(1 << nbits) - 1}"
+        end
       end
 
-      def create_uint2int_code(nbits)
-        "val = val - #{1 << nbits} if (val >= #{1 << (nbits - 1)})"
+      def create_uint2int_code(nbits, signed)
+        if signed != :signed
+          ""
+        elsif nbits == :nbits
+          "val -= (1 << nbits) if (val >= (1 << (nbits - 1)))"
+        else
+          "val -= #{1 << nbits} if (val >= #{1 << (nbits - 1)})"
+        end
       end
     end
   end
 
+  # Create classes for dynamic bitfields
+  {
+    "Bit"    => :big,
+    "BitLe"  => :little,
+    "Sbit"   => [:big, :signed],
+    "SbitLe" => [:little, :signed],
+  }.each_pair { |name, args| BitField.define_class(name, :nbits, *args) }
+
   # Create classes on demand
   module BitFieldFactory
     def const_missing(name)
       mappings = {
-        /^Bit(\d+)$/ => :big,
-        /^Bit(\d+)le$/ => :little,
-        /^Sbit(\d+)$/ => [:big, :signed],
+        /^Bit(\d+)$/    => :big,
+        /^Bit(\d+)le$/  => :little,
+        /^Sbit(\d+)$/   => [:big, :signed],
         /^Sbit(\d+)le$/ => [:little, :signed]
       }
 
       mappings.each_pair do |regex, args|
         if regex =~ name.to_s
           nbits = $1.to_i
-          return BitField.define_class(nbits, *args)
+          return BitField.define_class(name, nbits, *args)
         end
       end