bindata 1.5.1 → 1.6.0

data/ChangeLog.rdoc

@@ -1,5 +1,12 @@
 = BinData Changelog
 
+== Version 1.6.0 (2013-09-02)
+
+* Added license to .gemspec
+* Moved test suite from RSpec to Minitest.
+* Added :assert and :asserted_value.
+* :check_value has been deprecated. Use :assert instead.
+
 == Version 1.5.1 (2013-08-16)
 
 * Rework build system and include .gemspec.  Requested by Simon Shortman.

data/NEWS.rdoc

@@ -1,3 +1,14 @@
+= 1.6.0
+
+Added :assert as a replacement for :check_value.  Note that :assert performs
+the checking on assignment as well as reading.
+
+The parameter :asserted_value is a new shortcut for combining :assert and :value
+    int8 :magic, :assert => 42, :value => 42
+
+Can be written more concisely as
+    int8 :magic, :asserted_value => 42
+
 = 1.5.0
 
 Finally moved the source code to github.

data/Rakefile

@@ -3,11 +3,16 @@ Bundler.setup
 Bundler::GemHelper.install_tasks
 
 require 'rake/clean'
+require 'rake/testtask'
 
 task :clobber do
   rm_rf 'pkg'
 end
 
-task :default => :spec
+Rake::TestTask.new do |t|
+    t.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test
 
 Dir['tasks/**/*.rake'].each { |t| load t }

data/bindata.gemspec

@@ -15,9 +15,10 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = ['NEWS.rdoc']
   s.rdoc_options << '--main' << 'NEWS.rdoc'
   s.files = `git ls-files`.split("\n")
+  s.license = 'Ruby'
 
   s.add_development_dependency('rake')
-  s.add_development_dependency('rspec', [">= 2.10.0"])
+  s.add_development_dependency('minitest', "> 5.0.0")
   s.add_development_dependency('haml', ["< 4.0.0"])
   s.add_development_dependency('maruku')
   s.add_development_dependency('syntax')

data/doc/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: 2013-05-21
+Last updated: 2013-09-02
 
 ## Source code
 
@@ -389,20 +389,28 @@ There are several parameters that are specific to all primitives.
         list.len #=> 3
     {:ruby}
 
-`:check_value`
+`:assert`
 
-:   When reading, will raise a `ValidityError` if the value read does
-    not match the value of this parameter.  This is useful when
-    [debugging](#debugging), rather than as a general error detection
-    system.
+:   When reading or assigning, will raise a `ValidityError` if the value
+    read or assigned does not match the value of this parameter.
 
-        obj = BinData::String.new(:check_value => lambda { /aaa/ =~ value })
+        obj = BinData::String.new(:assert => lambda { /aaa/ =~ value })
         obj.read("baaa!") #=> "baaa!"
         obj.read("bbb") #=> raises ValidityError
 
-        obj = BinData::String.new(:check_value => "foo")
+        obj = BinData::String.new(:assert => "foo")
         obj.read("foo") #=> "foo"
-        obj.read("bar") #=> raises ValidityError
+        obj.assign("bar") #=> raises ValidityError
+    {:ruby}
+
+`:asserted_value`
+
+:   A combination of `:assert` and `:value`.  Used as a shortcut when
+    both `:assert` and `:value` have the same values.  The following
+    are equivalent.
+
+        obj = BinData::Uint32Be.new(:assert => 42, :value => 42)
+        obj = BinData::Uint32Be.new(:asserted_value => 42)
     {:ruby}
 
 ## Numerics

data/examples/gzip.rb

@@ -19,10 +19,10 @@ class Gzip
   class Header < BinData::Record
     endian :little
 
-    uint16  :ident,      :value => 0x8b1f, :check_value => 0x8b1f
+    uint16  :ident,      :asserted_value => 0x8b1f
     uint8   :compression_method, :initial_value => DEFLATE
 
-    bit3    :freserved,  :value => 0, :check_value => 0
+    bit3    :freserved,  :asserted_value => 0
     bit1    :fcomment,   :value => lambda { comment.length > 0 ? 1 : 0 }
     bit1    :ffile_name, :value => lambda { file_name.length > 0 ? 1 : 0 }
     bit1    :fextra,     :value => lambda { extra.len > 0 ? 1 : 0 }

data/examples/list.rb

@@ -20,12 +20,12 @@ require 'bindata'
 # A first attempt at a declaration would be:
 #
 #     class Atom < BinData::Record
-#       string  :tag, :length => 1, :check_value => 'a'
+#       string  :tag, :length => 1, :assert => 'a'
 #       int32be :val
 #     end
 #
 #     class List < BinData::Record
-#       string  :tag,  :length => 1, :check_value => 'l'
+#       string  :tag,  :length => 1, :assert => 'l'
 #       int32be :num,  :value => lambda { vals.length }
 #       array   :vals, :initial_length => :num do
 #         choice :selection => ??? do

data/lib/bindata/alignment.rb

@@ -13,7 +13,6 @@ module BinData
   #    MyRec.read("\x12\x34") #=> {"a" => 1, "b" => 3}
   #
   class ResumeByteAlignment < BinData::Base
-    def clear; end
     def clear?; true; end
     def assign(val); end
     def snapshot; nil; end
@@ -69,15 +68,11 @@ module BinData
     end
   end
 
-  class BasePrimitive < BinData::Base
-    def self.bit_aligned
-      include BitAligned
-    end
+  def BasePrimitive.bit_aligned
+    include BitAligned
   end
 
-  class Primitive < BinData::BasePrimitive
-    def self.bit_aligned
-      fail "'bit_aligned' is not needed for BinData::Primitives"
-    end
+  def Primitive.bit_aligned
+    fail "'bit_aligned' is not needed for BinData::Primitives"
   end
 end

data/lib/bindata/array.rb

@@ -79,6 +79,15 @@ module BinData
 
     def initialize_shared_instance
       @element_prototype = get_parameter(:type)
+      if get_parameter(:read_until) == :eof
+        extend ReadUntilEOFPlugin
+      elsif has_parameter?(:read_until)
+        extend ReadUntilPlugin
+      elsif has_parameter?(:initial_length)
+        extend InitialLengthPlugin
+      end
+
+      super
     end
 
     def initialize_instance
@@ -89,10 +98,6 @@ module BinData
       @element_list.nil? or elements.all? { |el| el.clear? }
     end
 
-    def clear
-      initialize_instance
-    end
-
     def assign(array)
       raise ArgumentError, "can't set a nil value for #{debug_name}" if array.nil?
 
@@ -234,14 +239,6 @@ module BinData
       child.do_num_bytes.is_a?(Integer) ? sum.ceil : sum.floor
     end
 
-    def do_read(io) #:nodoc:
-      if has_parameter?(:initial_length)
-        elements.each { |el| el.do_read(io) }
-      elsif has_parameter?(:read_until)
-        read_until(io)
-      end
-    end
-
     def do_write(io) #:nodoc:
       elements.each { |el| el.do_write(io) }
     end
@@ -264,46 +261,8 @@ module BinData
       els.collect { |el| new_element(el) }
     end
 
-    def read_until(io)
-      if get_parameter(:read_until) == :eof
-        read_until_eof(io)
-      else
-        read_until_condition(io)
-      end
-    end
-
-    def read_until_eof(io)
-      loop do
-        element = append_new_element
-        begin
-          element.do_read(io)
-        rescue EOFError, IOError
-          elements.pop
-          break
-        end
-      end
-    end
-
-    def read_until_condition(io)
-      loop do
-        element = append_new_element
-        element.do_read(io)
-        variables = { :index => self.length - 1, :element => self.last,
-                      :array => self }
-        break if eval_parameter(:read_until, variables)
-      end
-    end
-
     def elements
-      if @element_list.nil?
-        @element_list = []
-        if has_parameter?(:initial_length)
-          eval_parameter(:initial_length).times do
-            @element_list << new_element
-          end
-        end
-      end
-      @element_list
+      @element_list ||= []
     end
 
     def append_new_element
@@ -332,4 +291,51 @@ module BinData
       end
     end
   end
+
+  # Logic for the :read_until parameter
+  module ReadUntilPlugin
+    def do_read(io)
+      loop do
+        element = append_new_element
+        element.do_read(io)
+        variables = { :index => self.length - 1, :element => self.last,
+                      :array => self }
+        break if eval_parameter(:read_until, variables)
+      end
+    end
+
+  end
+
+  # Logic for the :read_until => :eof parameter
+  module ReadUntilEOFPlugin
+    def do_read(io)
+      loop do
+        element = append_new_element
+        begin
+          element.do_read(io)
+        rescue EOFError, IOError
+          elements.pop
+          break
+        end
+      end
+    end
+  end
+
+  # Logic for the :initial_length parameter
+  module InitialLengthPlugin
+    def do_read(io)
+      elements.each { |el| el.do_read(io) }
+    end
+
+    def elements
+      if @element_list.nil?
+        @element_list = []
+        eval_parameter(:initial_length).times do
+          @element_list << new_element
+        end
+      end
+
+      @element_list
+    end
+  end
 end

data/lib/bindata/base.rb

@@ -1,16 +1,15 @@
+require 'bindata/framework'
 require 'bindata/io'
 require 'bindata/lazy'
+require 'bindata/name'
 require 'bindata/offset'
 require 'bindata/params'
 require 'bindata/registry'
 require 'bindata/sanitize'
 
 module BinData
-  # Error raised when unexpected results occur when reading data from IO.
-  class ValidityError < StandardError ; end
-
   # ArgExtractors take the arguments passed to BinData::Base.new and
-  # separates them into [value, parameters, parent].
+  # separate them into [value, parameters, parent].
   class BaseArgExtractor
     @@empty_hash = Hash.new.freeze
 
@@ -38,8 +37,10 @@ module BinData
 
   # This is the abstract base class for all data objects.
   class Base
-    include AcceptedParametersMixin
-    include CheckOrAdjustOffsetMixin
+    extend AcceptedParametersPlugin
+    include Framework
+    include CheckOrAdjustOffsetPlugin
+    include RegisterNamePlugin
 
     class << self
 
@@ -82,9 +83,6 @@ module BinData
     # Register all subclasses of this class.
     register_subclasses
 
-    # The registered name may be provided explicitly.
-    optional_parameter :name
-
     # Creates a new data object.
     #
     # Args are optional, but if present, must be in the following order.
@@ -97,28 +95,12 @@ module BinData
     # +parent+ is the parent data object (e.g. struct, array, choice) this
     # object resides under.
     #
-    # == Parameters
-    #
-    # Parameters may be provided at initialisation to control the behaviour of
-    # an object.  These params are:
-    #
-    # <tt>:name</tt>:: The name that this object can be referred to may be
-    #                  set explicitly.  This is only useful when dynamically
-    #                  generating types.
-    #                  <code><pre>
-    #                    BinData::Struct.new(:name => :my_struct, :fields => ...)
-    #                    array = BinData::Array.new(:type => :my_struct)
-    #                  </pre></code>
-    #
     def initialize(*args)
       value, parameters, parent = extract_args(args)
 
       @params = SanitizedParameters.sanitize(parameters, self.class)
       @parent = parent
 
-      register_prototype
-      add_methods_for_check_or_adjust_offset
-
       initialize_shared_instance
       initialize_instance
       assign(value) if value
@@ -172,6 +154,11 @@ module BinData
       @params.has_parameter?(key)
     end
 
+    # Resets the internal state to that of a newly created object.
+    def clear
+      initialize_instance
+    end
+
     # Reads data into this data object.
     def read(io)
       io = BinData::IO.new(io) unless BinData::IO === io
@@ -274,7 +261,7 @@ module BinData
     def safe_respond_to?(symbol, include_private = false) #:nodoc:
       respond_to?(symbol, include_private)
     end
-    alias_method :orig_respond_to?, :respond_to? #:nodoc:
+    alias_method :base_respond_to?, :respond_to? #:nodoc:
 
     #---------------
     private
@@ -283,12 +270,6 @@ module BinData
       self.class.arg_extractor.extract(self.class, the_args)
     end
 
-    def register_prototype
-      if has_parameter?(:name)
-        RegisteredClasses.register(get_parameter(:name), self)
-      end
-    end
-
     def furthest_ancestor
       if parent.nil?
         self
@@ -306,83 +287,5 @@ module BinData
         str.dup
       end
     end
-
-    ###########################################################################
-    # To be implemented by subclasses
-
-    # Performs sanity checks on the given parameters.  This method converts
-    # the parameters to the form expected by this data object.
-    def self.sanitize_parameters!(parameters) #:nodoc:
-    end
-
-    # Initializes the state of the object.  All instance variables that
-    # are used by the object must be initialized here.
-    def initialize_instance
-    end
-
-    # Initialises state that is shared by objects with the same parameters.
-    #
-    # This should only be used when optimising for performance.  Instance
-    # variables set here, and changes to the singleton class will be shared
-    # between all objects that are initialized with the same parameters.
-    # This method is called only once for a particular set of parameters.
-    def initialize_shared_instance
-    end
-
-    # Resets the internal state to that of a newly created object.
-    def clear
-      raise NotImplementedError
-    end
-
-    # Returns true if the object has not been changed since creation.
-    def clear?
-      raise NotImplementedError
-    end
-
-    # Assigns the value of +val+ to this data object.  Note that +val+ must
-    # always be deep copied to ensure no aliasing problems can occur.
-    def assign(val)
-      raise NotImplementedError
-    end
-
-    # Returns a snapshot of this data object.
-    def snapshot
-      raise NotImplementedError
-    end
-
-    # Returns the debug name of +child+.  This only needs to be implemented
-    # by objects that contain child objects.
-    def debug_name_of(child) #:nodoc:
-      debug_name
-    end
-
-    # Returns the offset of +child+.  This only needs to be implemented
-    # by objects that contain child objects.
-    def offset_of(child) #:nodoc:
-      0
-    end
-
-    # Reads the data for this data object from +io+.
-    def do_read(io) #:nodoc:
-      raise NotImplementedError
-    end
-
-    # Writes the value for this data to +io+.
-    def do_write(io) #:nodoc:
-      raise NotImplementedError
-    end
-
-    # Returns the number of bytes it will take to write this data.
-    def do_num_bytes #:nodoc:
-      raise NotImplementedError
-    end
-
-    # Set visibility requirements of methods to implement
-    public :clear, :clear?, :assign, :snapshot, :debug_name_of, :offset_of
-    protected :initialize_instance, :initialize_shared_instance
-    protected :do_read, :do_write, :do_num_bytes
-
-    # End To be implemented by subclasses
-    ###########################################################################
   end
 end