bindata 1.3.1 → 1.4.0

data/BSDL

@@ -0,0 +1,22 @@
+Copyright (C) 2007-2011 Dion Mendel. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/COPYING

@@ -1,6 +1,6 @@
 BinData is copyrighted free software by Dion Mendel <dion@lostrealm.com>.
-You can redistribute it and/or modify it under either the terms of the GPL
-version 2 (see the file GPL), or the conditions below:
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
 
   1. You may make and give away verbatim copies of the source form of the
      software without restriction, provided that you duplicate all of the

data/ChangeLog

@@ -1,5 +1,17 @@
 = BinData Changelog
 
+== Version 1.4.0 (2011-06-14)
+
+* Record#snapshot now returns fields in order.
+* Removed the need to call #register_self in subclasses.
+* Wrapper is now deprecated.  Use subclassing instead.
+* Updated license to mimic changes to the Ruby License.
+* Refactoring to reduce memory usage.
+
+== Version 1.3.1 (2011-01-25)
+
+* Fixed file permissions problem.
+
 == Version 1.3.0 (2011-01-25)
 
 * BinData objects can now assign values when instantiating.

data/NEWS

@@ -1,3 +1,31 @@
+= 1.4.0
+
+== Deprecations
+
+There is no longer any need to call #register_self when inheriting from
+BinData::Base.
+
+BinData::Wrapper is deprecated.  You should use direct inheritance instead.
+
+If your code looks like:
+    class Uint8Array < BinData::Wrapper
+      default_parameter :initial_element_value => 0
+  
+      array :initial_length => 2 do
+        uint8 :initial_value => :initial_element_value
+      end
+    end
+
+It should be changed to:
+    class Uint8Array < BinData::Array
+      default_parameter :initial_element_value => 0
+      default_parameter :initial_length => 2
+  
+      uint8 :initial_value => :initial_element_value
+    end
+
+See http://bindata.rubyforge.org/#extending_existing_types for details.
+
 = 1.3.0
 
 == New features

data/examples/list.rb

@@ -2,7 +2,7 @@ require 'bindata'
 
 # An example of a recursively defined data format.
 #
-# This format is used to describe atoms and lists.
+# This example format describes atoms and lists.
 # It is recursive because lists can contain other lists.
 #
 # Atoms - contain a single integer
@@ -49,10 +49,9 @@ require 'bindata'
 #
 # The declaration then becomes:
 #
-#     class Term < BinData::Record; end # forward declaration
+#     class Term < BinData::Record; end  # forward declaration
 #     
-#     class Atom < BinData::Wrapper
-#       int32be
+#     class Atom < BinData::Int32be
 #     end
 #     
 #     class List < BinData::Record
@@ -71,9 +70,7 @@ require 'bindata'
 
 class Term < BinData::Record; end  # Forward declaration
 
-class Atom < BinData::Wrapper
-  int32be
-
+class Atom < BinData::Int32be
   def decode
     snapshot
   end
@@ -117,8 +114,11 @@ class Term < BinData::Record
 end
 
 
+puts "A single Atom"
 p Term.encode(4)
 p Term.encode(4).decode
 puts
+
+puts "A nested List"
 p Term.encode([1, [2, 3], 4])
 p Term.encode([1, [2, 3], 4]).decode

data/examples/nbt.rb

@@ -30,44 +30,32 @@ module Nbt
   end
 
   # NBT.txt line 31
-  class TagByte < BinData::Wrapper
-    int8
-
+  class TagByte < BinData::Int8
     def to_formatted_s(indent = 0); to_s; end
   end
 
   # NBT.txt line 34
-  class TagShort < BinData::Wrapper
-    int16be
-
+  class TagShort < BinData::Int16be
     def to_formatted_s(indent = 0); to_s; end
   end
 
   # NBT.txt line 37
-  class TagInt < BinData::Wrapper
-    int32be
-
+  class TagInt < BinData::Int32be
     def to_formatted_s(indent = 0); to_s; end
   end
 
   # NBT.txt line 40
-  class TagLong < BinData::Wrapper
-    int64be
-
+  class TagLong < BinData::Int64be
     def to_formatted_s(indent = 0); to_s; end
   end
 
   # NBT.txt line 43
-  class TagFloat < BinData::Wrapper
-    float_be
-
+  class TagFloat < BinData::FloatBe
     def to_formatted_s(indent = 0); to_s; end
   end
 
   # NBT.txt line 46
-  class TagDouble < BinData::Wrapper
-    double_be
-
+  class TagDouble < BinData::DoubleBe
     def to_formatted_s(indent = 0); to_s; end
   end
 
@@ -106,28 +94,25 @@ module Nbt
   class TagList < BinData::Record; end
 
   # NBT.txt line 10
-  class Payload < BinData::Wrapper
-    mandatory_parameter :tag_selector
-    choice :selection => :tag_selector do
-      tag_end        0
-      tag_byte       1
-      tag_short      2
-      tag_int        3
-      tag_long       4
-      tag_float      5
-      tag_double     6
-      tag_byte_array 7
-      tag_string     8
-      tag_list       9
-      tag_compound   10
-    end
+  class Payload < BinData::Choice
+    tag_end        0
+    tag_byte       1
+    tag_short      2
+    tag_int        3
+    tag_long       4
+    tag_float      5
+    tag_double     6
+    tag_byte_array 7
+    tag_string     8
+    tag_list       9
+    tag_compound   10
   end
 
   # NBT.txt line 6, 27
   class NamedTag < BinData::Record
     int8 :tag_id
     tag_string :name,    :onlyif => :not_end_tag?
-    payload    :payload, :onlyif => :not_end_tag?, :tag_selector => :tag_id
+    payload    :payload, :onlyif => :not_end_tag?, :selection => :tag_id
 
     def not_end_tag?
       tag_id != 0
@@ -145,7 +130,7 @@ module Nbt
     int8 :tag_id
     int32be :len, :value => lambda { data.length }
     array :data, :initial_length => :len do
-      payload :tag_selector => :tag_id
+      payload :selection => :tag_id
     end
 
     def to_formatted_s(indent = 0)
@@ -175,9 +160,7 @@ module Nbt
   end
 
   # NBT.txt line 3
-  class Nbt < BinData::Wrapper
-    named_tag
-
+  class Nbt < NamedTag
     def self.read(io)
       require 'zlib'
       super(Zlib::GzipReader.new(io))

data/lib/bindata.rb

@@ -31,5 +31,5 @@ require 'bindata/deprecated'
 #
 # Copyright (c) 2007 - 2011 Dion Mendel.
 module BinData
-  VERSION = "1.3.1"
+  VERSION = "1.4.0"
 end

data/lib/bindata/alignment.rb

@@ -13,8 +13,6 @@ module BinData
   #    MyRec.read("\x12\x34") #=> {"a" => 1, "b" => 3}
   #
   class ResumeByteAlignment < BinData::Base
-    register_self
-
     def clear; end
     def clear?; true; end
     def assign(val); end
@@ -50,7 +48,7 @@ module BinData
       end
       def readbytes(n)
         n.times.inject("") do |bytes, i|
-          bytes + @io.readbits(8, :big).chr
+          bytes << @io.readbits(8, :big).chr
         end
       end
       def method_missing(sym, *args, &block)
@@ -74,7 +72,6 @@ module BinData
   class BasePrimitive < BinData::Base
     def self.bit_aligned
       include BitAligned
-      register_self
     end
   end
 

data/lib/bindata/array.rb

@@ -1,4 +1,5 @@
 require 'bindata/base'
+require 'bindata/dsl'
 
 module BinData
   # An Array is a list of data objects of the same type.
@@ -47,9 +48,10 @@ 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
     include Enumerable
 
-    register_self
+    dsl_parser :array
 
     mandatory_parameter :type
     optional_parameters :initial_length, :read_until
@@ -57,7 +59,7 @@ module BinData
 
     class << self
 
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
+      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
@@ -66,9 +68,11 @@ module BinData
 
         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] = sanitizer.create_sanitized_object_prototype(el_type, el_params)
+          params[:type] = params.create_sanitized_object_prototype(el_type, el_params)
         end
       end
     end
@@ -321,7 +325,7 @@ module BinData
         nbytes = elements[i].do_num_bytes
 
         if nbytes.is_a?(Integer)
-          (sum + nbytes).ceil
+          sum.ceil + nbytes
         else
           sum + nbytes
         end

data/lib/bindata/base.rb

@@ -9,9 +9,11 @@ module BinData
   # Error raised when unexpected results occur when reading data from IO.
   class ValidityError < StandardError ; end
 
-  # ArgExtractors take the arguments to BinData::Base.new and
-  # separate them into [value, parameters, parent].
+  # ArgExtractors take the arguments passed to BinData::Base.new and
+  # separates 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
@@ -28,7 +30,7 @@ module BinData
         value = args.pop
       end
 
-      parameters ||= {}
+      parameters ||= @@empty_hash
 
       return [value, parameters, parent]
     end
@@ -59,27 +61,27 @@ module BinData
         RegisteredClasses.underscore_name(self.name)
       end
 
-      # Registers this class for use.
-      def register_self
-        register_class(self)
+      # Call this method if this class is abstract and not to be used.
+      def unregister_self
+        RegisteredClasses.unregister(name)
       end
 
       # Registers all subclasses of this class for use
-      def register_subclasses
+      def register_subclasses #:nodoc:
         class << self
           define_method(:inherited) do |subclass|
-            register_class(subclass)
+            RegisteredClasses.register(subclass.name, subclass)
+            register_subclasses
           end
         end
       end
 
-      def register_class(class_to_register) #:nodoc:
-        RegisteredClasses.register(class_to_register.name, class_to_register)
-      end
-
-      private :register_self, :register_subclasses, :register_class
+      private :unregister_self, :register_subclasses
     end
 
+    # Register all subclasses of this class.
+    register_subclasses
+
     # Creates a new data object.
     #
     # Args are optional, but if present, must be in the following order.
@@ -93,11 +95,12 @@ module BinData
     # object resides under.
     def initialize(*args)
       value, parameters, parent = extract_args(args)
-      @params = Sanitizer.sanitize(parameters, self.class)
+
+      @params = SanitizedParameters.sanitize(parameters, self.class)
+      @parent = parent
 
       add_methods_for_check_or_adjust_offset
 
-      @parent = parent if parent
       initialize_shared_instance
       initialize_instance
       assign(value) if value
@@ -125,7 +128,7 @@ module BinData
     # parameters given at object construction to be overridden.
     #
     # Returns nil if +key+ does not refer to any parameter.
-    def eval_parameter(key, overrides = {})
+    def eval_parameter(key, overrides = nil)
       LazyEvaluator.eval(self, get_parameter(key), overrides)
     end
 
@@ -255,7 +258,7 @@ module BinData
 
     # 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, sanitizer) #:nodoc:
+    def self.sanitize_parameters!(parameters) #:nodoc:
     end
 
     # Initializes the state of the object.  All instance variables that

data/lib/bindata/base_primitive.rb

@@ -45,6 +45,7 @@ module BinData
   #                           or failure.  Any other return is compared to
   #                           the value just read in.
   class BasePrimitive < BinData::Base
+    unregister_self
 
     optional_parameters :initial_value, :value, :check_value
     mutually_exclusive_parameters :initial_value, :value

data/lib/bindata/bits.rb

@@ -12,7 +12,6 @@ module BinData
         unless BinData.const_defined?(name)
           BinData.module_eval <<-END
             class #{name} < BinData::BasePrimitive
-              register_self
               BitField.define_methods(self, #{nbits}, :#{endian})
             end
           END

data/lib/bindata/choice.rb

@@ -1,4 +1,5 @@
 require 'bindata/base'
+require 'bindata/dsl'
 
 module BinData
   # A Choice is a collection of data objects of which only one is active
@@ -55,19 +56,22 @@ module BinData
   #                            selection to the current selection whenever the
   #                            selection changes.  Default is false.
   class Choice < BinData::Base
+    include DSLMixin
 
-    register_self
+    dsl_parser :choice
 
     mandatory_parameters :choices, :selection
     optional_parameter   :copy_on_change
 
     class << self
 
-      def sanitize_parameters!(params, sanitizer) #:nodoc:
+      def sanitize_parameters!(params) #:nodoc:
+        params.merge!(dsl_params)
+
         if params.needs_sanitizing?(:choices)
           choices = choices_as_hash(params[:choices])
           ensure_valid_keys(choices)
-          params[:choices] = sanitizer.create_sanitized_choices(choices)
+          params[:choices] = params.create_sanitized_choices(choices)
         end
       end
 
@@ -100,6 +104,14 @@ module BinData
       end
     end
 
+    def initialize_shared_instance
+      if eval_parameter(:copy_on_change) == true
+        class << self
+          alias_method :hook_after_current_choice, :copy_previous_value
+        end
+      end
+    end
+
     def initialize_instance
       @choices = {}
       @last_selection = nil
@@ -110,33 +122,6 @@ module BinData
       eval_parameter(:selection)
     end
 
-    # This method does not exist. This stub only exists to document why.
-    # There is no #selection= method to complement the #selection method.
-    # This is deliberate to promote the declarative nature of BinData.
-    #
-    # If you really *must* be able to programmatically adjust the selection
-    # then try something like the following.
-    #
-    #   class ProgrammaticChoice < BinData::Wrapper
-    #     choice :selection => :selection
-    #     attr_accessor :selection
-    #   end
-    #
-    #   type1 = [:string, {:value => "Type1"}]
-    #   type2 = [:string, {:value => "Type2"}]
-    #
-    #   choices = {5 => type1, 17 => type2}
-    #   pc = ProgrammaticChoice.new(:choices => choices)
-    #
-    #   pc.selection = 5
-    #   pc #=> "Type1"
-    #
-    #   pc.selection = 17
-    #   pc #=> "Type2"
-    def selection=(sel)
-      raise NoMethodError, "See rdoc BinData::Choice.selection= for details"
-    end
-
     def clear #:nodoc:
       current_choice.clear
     end
@@ -178,6 +163,7 @@ module BinData
     private
 
     def hook_before_do_read; end
+    def hook_after_current_choice(*args); end
 
     def current_choice
       selection = eval_parameter(:selection)
@@ -186,7 +172,7 @@ module BinData
       end
 
       obj = get_or_instantiate_choice(selection)
-      copy_previous_value_if_required(selection, obj)
+      hook_after_current_choice(selection, obj)
 
       obj
     end
@@ -203,18 +189,12 @@ module BinData
       prototype.instantiate(nil, self)
     end
 
-    def copy_previous_value_if_required(selection, obj)
+    def copy_previous_value(selection, obj)
       prev = get_previous_choice(selection)
-      if should_copy_value?(prev, obj)
-        obj.assign(prev)
-      end
+      obj.assign(prev) unless prev.nil?
       remember_current_selection(selection)
     end
 
-    def should_copy_value?(prev, cur)
-      prev != nil and eval_parameter(:copy_on_change) == true
-    end
-
     def get_previous_choice(selection)
       if selection != @last_selection and @last_selection != nil
         @choices[@last_selection]
@@ -224,9 +204,7 @@ module BinData
     end
 
     def remember_current_selection(selection)
-      if selection != @last_selection
-        @last_selection = selection
-      end
+      @last_selection = selection
     end
   end
 end