jbangert-bindata 1.5.0

data/lib/bindata/bits.rb

@@ -0,0 +1,87 @@
+require 'bindata/base_primitive'
+
+module BinData
+  # Defines a number of classes that contain a bit based integer.
+  # The integer is defined by endian and number of bits.
+
+  module BitField #:nodoc: all
+    class << self
+      def define_class(nbits, endian)
+        name = "Bit#{nbits}"
+        name << "le" if endian == :little
+        unless BinData.const_defined?(name)
+          BinData.module_eval <<-END
+            class #{name} < BinData::BasePrimitive
+              BitField.define_methods(self, #{nbits}, :#{endian})
+            end
+          END
+        end
+
+        BinData.const_get(name)
+      end
+
+      def define_methods(bit_class, nbits, endian)
+        bit_class.module_eval <<-END
+          def assign(val)
+            #{create_clamp_code(nbits)}
+            super(val)
+          end
+
+          def do_write(io)
+            io.writebits(_value, #{nbits}, :#{endian})
+          end
+
+          def do_num_bytes
+            #{nbits / 8.0}
+          end
+
+          #---------------
+          private
+
+          def read_and_return_value(io)
+            io.readbits(#{nbits}, :#{endian})
+          end
+
+          def sensible_default
+            0
+          end
+        END
+      end
+
+      def create_clamp_code(nbits)
+        min = 0
+        max = (1 << nbits) - 1
+        clamp = "(val < #{min}) ? #{min} : (val > #{max}) ? #{max} : val"
+
+        if nbits == 1
+          # allow single bits to be used as booleans
+          clamp = "(val == true) ? 1 : (not val) ? 0 : #{clamp}"
+        end
+
+        "val = #{clamp}"
+      end
+    end
+  end
+
+  # Create classes on demand
+  class << self
+    alias_method :const_missing_without_bits, :const_missing
+    def const_missing_with_bits(name)
+      name = name.to_s
+      mappings = {
+        /^Bit(\d+)$/ => :big,
+        /^Bit(\d+)le$/ => :little
+      }
+
+      mappings.each_pair do |regex, endian|
+        if regex =~ name
+          nbits = $1.to_i
+          return BitField.define_class(nbits, endian)
+        end
+      end
+
+      const_missing_without_bits(name)
+    end
+    alias_method :const_missing, :const_missing_with_bits
+  end
+end

data/lib/bindata/choice.rb

@@ -0,0 +1,216 @@
+require 'bindata/base'
+require 'bindata/dsl'
+
+module BinData
+  # A Choice is a collection of data objects of which only one is active
+  # at any particular time.  Method calls will be delegated to the active
+  # choice.
+  #
+  #   require 'bindata'
+  #
+  #   type1 = [:string, {:value => "Type1"}]
+  #   type2 = [:string, {:value => "Type2"}]
+  #
+  #   choices = {5 => type1, 17 => type2}
+  #   a = BinData::Choice.new(:choices => choices, :selection => 5)
+  #   a # => "Type1"
+  #
+  #   choices = [ type1, type2 ]
+  #   a = BinData::Choice.new(:choices => choices, :selection => 1)
+  #   a # => "Type2"
+  #
+  #   choices = [ nil, nil, nil, type1, nil, type2 ]
+  #   a = BinData::Choice.new(:choices => choices, :selection => 3)
+  #   a # => "Type1"
+  #
+  #
+  #   Chooser = Struct.new(:choice)
+  #   mychoice = Chooser.new
+  #   mychoice.choice = 'big'
+  #
+  #   choices = {'big' => :uint16be, 'little' => :uint16le}
+  #   a = BinData::Choice.new(:choices => choices, :copy_on_change => true,
+  #                           :selection => lambda { mychoice.choice })
+  #   a.assign(256)
+  #   a.to_binary_s #=> "\001\000"
+  #
+  #   mychoice.choice = 'little'
+  #   a.to_binary_s #=> "\000\001"
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params are:
+  #
+  # <tt>:choices</tt>::        Either an array or a hash specifying the possible
+  #                            data objects.  The format of the
+  #                            array/hash.values is a list of symbols
+  #                            representing the data object type.  If a choice
+  #                            is to have params passed to it, then it should
+  #                            be provided as [type_symbol, hash_params].  An
+  #                            implementation constraint is that the hash may
+  #                            not contain symbols as keys, with the exception
+  #                            of :default.  :default is to be used when then
+  #                            :selection does not exist in the :choices hash.
+  # <tt>:selection</tt>::      An index/key into the :choices array/hash which
+  #                            specifies the currently active choice.
+  # <tt>:copy_on_change</tt>:: If set to true, copy the value of the previous
+  #                            selection to the current selection whenever the
+  #                            selection changes.  Default is false.
+  class Choice < BinData::Base
+    include DSLMixin
+
+    dsl_parser :choice
+
+    mandatory_parameters :choices, :selection
+    optional_parameter   :copy_on_change
+
+    class << self
+
+      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] = params.create_sanitized_choices(choices)
+        end
+      end
+
+      #-------------
+      private
+
+      def choices_as_hash(choices)
+        if choices.respond_to?(:to_ary)
+          key_array_by_index(choices.to_ary)
+        else
+          choices
+        end
+      end
+
+      def key_array_by_index(array)
+        result = {}
+        array.each_with_index do |el, i|
+          result[i] = el unless el.nil?
+        end
+        result
+      end
+
+      def ensure_valid_keys(choices)
+        if choices.has_key?(nil)
+          raise ArgumentError, ":choices hash may not have nil key"
+        end
+        if choices.keys.detect { |key| key.is_a?(Symbol) and key != :default }
+          raise ArgumentError, ":choices hash may not have symbols for keys"
+        end
+      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
+    end
+
+    # A convenience method that returns the current selection.
+    def selection
+      eval_parameter(:selection)
+    end
+
+    def clear #:nodoc:
+      initialize_instance
+    end
+
+    def clear? #:nodoc:
+      current_choice.clear?
+    end
+
+    def assign(val)
+      current_choice.assign(val)
+    end
+
+    def snapshot
+      current_choice.snapshot
+    end
+
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      current_choice.respond_to?(symbol, include_private) || super
+    end
+
+    def safe_respond_to?(symbol, include_private = false) #:nodoc:
+      orig_respond_to?(symbol, include_private)
+    end
+
+    def method_missing(symbol, *args, &block) #:nodoc:
+      current_choice.__send__(symbol, *args, &block)
+    end
+
+    def do_read(io) #:nodoc:
+      hook_before_do_read
+      current_choice.do_read(io)
+    end
+
+    def do_write(io) #:nodoc:
+      current_choice.do_write(io)
+    end
+
+    def do_num_bytes #:nodoc:
+      current_choice.do_num_bytes
+    end
+
+    #---------------
+    private
+
+    def hook_before_do_read; end
+    def hook_after_current_choice(*args); end
+
+    def current_choice
+      selection = eval_parameter(:selection)
+      if selection.nil?
+        raise IndexError, ":selection returned nil for #{debug_name}"
+      end
+
+      obj = get_or_instantiate_choice(selection)
+      hook_after_current_choice(selection, obj)
+
+      obj
+    end
+
+    def get_or_instantiate_choice(selection)
+      @choices[selection] ||= instantiate_choice(selection)
+    end
+
+    def instantiate_choice(selection)
+      prototype = get_parameter(:choices)[selection]
+      if prototype.nil?
+        raise IndexError, "selection '#{selection}' does not exist in :choices for #{debug_name}"
+      end
+      prototype.instantiate(nil, self)
+    end
+
+    def copy_previous_value(selection, obj)
+      prev = get_previous_choice(selection)
+      obj.assign(prev) unless prev.nil?
+      remember_current_selection(selection)
+    end
+
+    def get_previous_choice(selection)
+      if selection != @last_selection and @last_selection != nil
+        @choices[@last_selection]
+      else
+        nil
+      end
+    end
+
+    def remember_current_selection(selection)
+      @last_selection = selection
+    end
+  end
+end

data/lib/bindata/count_bytes_remaining.rb

@@ -0,0 +1,35 @@
+require "bindata/base_primitive"
+
+module BinData
+  # Counts the number of bytes remaining in the input stream from the current
+  # position to the end of the stream.  This only makes sense for seekable
+  # streams.
+  #
+  #   require 'bindata'
+  #
+  #   class A < BinData::Record
+  #     count_bytes_remaining :bytes_remaining
+  #     string :all_data, :read_length => :bytes_remaining
+  #   end
+  #
+  #   obj = A.read("abcdefghij")
+  #   obj.all_data #=> "abcdefghij"
+  #
+  class CountBytesRemaining < BinData::BasePrimitive
+
+    #---------------
+    private
+
+    def value_to_binary_string(val)
+      ""
+    end
+
+    def read_and_return_value(io)
+      io.num_bytes_remaining
+    end
+
+    def sensible_default
+      0
+    end
+  end
+end

data/lib/bindata/deprecated.rb

@@ -0,0 +1,50 @@
+# Implement Kernel#instance_exec for Ruby 1.8.6 and below
+unless Object.respond_to? :instance_exec
+  module Kernel
+    # Taken from http://eigenclass.org/hiki/instance_exec
+    def instance_exec(*args, &block)
+      mname = "__instance_exec_#{Thread.current.object_id.abs}_#{object_id.abs}"
+      Object.class_eval{ define_method(mname, &block) }
+      begin
+        ret = send(mname, *args)
+      ensure
+        Object.class_eval{ undef_method(mname) } rescue nil
+      end
+      ret
+    end
+  end
+end
+
+module BinData
+  class Base
+
+    # Don't override initialize.  If you are defining a new kind of datatype
+    # (list, array, choice etc) then put your initialization code in
+    # #initialize_instance.  This is because BinData objects can be initialized
+    # as prototypes and your initialization code may not be called.
+    #
+    # If you're subclassing BinData::Record, you are definitely doing the wrong
+    # thing.  Read the documentation on how to use BinData.
+    # http://bindata.rubyforge.org/manual.html#records
+    alias_method :initialize_without_warning, :initialize
+    def initialize_with_warning(*args)
+      owner = method(:initialize).owner
+      if owner != BinData::Base
+        msg = "Don't override #initialize on #{owner}."
+        if %w(BinData::Base BinData::BasePrimitive).include? self.class.superclass.name
+          msg += "\nrename #initialize to #initialize_instance."
+        end
+        fail msg
+      end
+      initialize_without_warning(*args)
+    end
+    alias_method :initialize, :initialize_with_warning
+
+    def initialize_instance(*args)
+      unless args.empty?
+        fail "#{caller[0]} remove the call to super in #initialize_instance"
+      end
+    end
+
+  end
+end

data/lib/bindata/dsl.rb

@@ -0,0 +1,312 @@
+module BinData
+  module DSLMixin
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+      def dsl_parser(parser_type = nil)
+        unless defined? @dsl_parser
+          parser_type = superclass.dsl_parser.parser_type if parser_type.nil?
+          @dsl_parser = DSLParser.new(self, parser_type)
+        end
+        @dsl_parser
+      end
+
+      def method_missing(symbol, *args, &block) #:nodoc:
+        dsl_parser.__send__(symbol, *args, &block)
+      end
+
+      # Assert object is not an array or string.
+      def to_ary; nil; end
+      def to_str; nil; end
+    end
+
+    # A DSLParser parses and accumulates field definitions of the form
+    #
+    #   type name, params
+    #
+    # where:
+    #   * +type+ is the under_scored name of a registered type
+    #   * +name+ is the (possible optional) name of the field
+    #   * +params+ is a hash containing any parameters
+    #
+    class DSLParser
+      def initialize(the_class, parser_type)
+        @the_class   = the_class
+        @parser_type = parser_type
+        @endian      = parent_attribute(:endian, nil)
+      end
+
+      attr_reader :parser_type
+
+      def endian(endian = nil)
+        if endian.nil?
+          @endian
+        elsif endian == :big or endian == :little
+          @endian = endian
+        else
+          dsl_raise ArgumentError, "unknown value for endian '#{endian}'"
+        end
+      end
+
+      def hide(*args)
+        if option?(:hidden_fields)
+          hidden = args.collect do |name|
+                     unless Symbol === name
+                       warn "Hidden field '#{name}' should be provided as a symbol.  Using strings is deprecated"
+                     end
+                     name.to_sym
+                   end
+
+          unless defined? @hide
+            @hide = parent_attribute(:hide, []).dup
+          end
+
+          @hide.concat(hidden.compact)
+          @hide
+        end
+      end
+
+      def fields
+        unless defined? @fields
+          fields = parent_attribute(:fields, nil)
+          @fields = SanitizedFields.new(endian)
+          @fields.copy_fields(fields) if fields
+        end
+
+        @fields
+      end
+
+      def dsl_params
+        case @parser_type
+        when :struct
+          to_struct_params
+        when :array
+          to_array_params
+        when :choice
+          to_choice_params
+        when :primitive
+          to_struct_params
+        else
+          raise "unknown parser type #{@parser_type}"
+        end
+      end
+
+      def method_missing(symbol, *args, &block) #:nodoc:
+        type   = symbol
+        name   = name_from_field_declaration(args)
+        params = params_from_field_declaration(type, args, &block)
+
+        append_field(type, name, params)
+      end
+
+      #-------------
+      private
+
+      def option?(opt)
+        options.include?(opt)
+      end
+
+      def options
+        case @parser_type
+        when :struct
+          [:multiple_fields, :optional_fieldnames, :hidden_fields]
+        when :array
+          [:multiple_fields, :optional_fieldnames]
+        when :choice
+          [:multiple_fields, :all_or_none_fieldnames, :fieldnames_are_values]
+        when :primitive
+          [:multiple_fields, :optional_fieldnames]
+        else
+          raise "unknown parser type #{parser_type}"
+        end
+      end
+
+      def parent_attribute(attr, default = nil)
+        parent = @the_class.superclass.respond_to?(:dsl_parser) ? @the_class.superclass.dsl_parser : nil
+        if parent and parent.respond_to?(attr)
+          parent.send(attr)
+        else
+          default
+        end
+      end
+
+      def name_from_field_declaration(args)
+        name, params = args
+        if name == "" or name.is_a?(Hash)
+          nil
+        else
+          name
+        end
+      end
+
+      def params_from_field_declaration(type, args, &block)
+        params = params_from_args(args)
+
+        if block_given?
+          params.merge(params_from_block(type, &block))
+        else
+          params
+        end
+      end
+
+      def params_from_args(args)
+        name, params = args
+        params = name if name.is_a?(Hash)
+
+        params || {}
+      end
+
+      def params_from_block(type, &block)
+        bindata_classes = {
+          :array  => BinData::Array,
+          :choice => BinData::Choice,
+          :struct => BinData::Struct
+        }
+
+        if bindata_classes.include?(type)
+          parser = DSLParser.new(bindata_classes[type], type)
+          parser.endian(endian)
+          parser.instance_eval(&block)
+
+          parser.dsl_params
+        else
+          {}
+        end
+      end
+
+      def append_field(type, name, params)
+        ensure_valid_field(name)
+
+        fields.add_field(type, name, params)
+      rescue ArgumentError => err
+        dsl_raise ArgumentError, err.message
+      rescue UnRegisteredTypeError => err
+        dsl_raise TypeError, "unknown type '#{err.message}'"
+      end
+
+      def ensure_valid_field(field_name)
+        if too_many_fields?
+          dsl_raise SyntaxError, "attempting to wrap more than one type"
+        end
+
+        if must_not_have_a_name_failed?(field_name)
+          dsl_raise SyntaxError, "field must not have a name"
+        end
+
+        if all_or_none_names_failed?(field_name)
+          dsl_raise SyntaxError, "fields must either all have names, or none must have names"
+        end
+
+        if must_have_a_name_failed?(field_name)
+          dsl_raise SyntaxError, "field must have a name"
+        end
+
+        ensure_valid_name(field_name)
+      end
+
+      def ensure_valid_name(name)
+        if name and not option?(:fieldnames_are_values)
+          if malformed_name?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' is an illegal fieldname"
+          end
+
+          if duplicate_name?(name)
+            dsl_raise SyntaxError, "duplicate field '#{name}'"
+          end
+
+          if name_shadows_method?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' shadows an existing method"
+          end
+
+          if name_is_reserved?(name)
+            dsl_raise NameError.new("", name), "field '#{name}' is a reserved name"
+          end
+        end
+      end
+
+      def too_many_fields?
+        option?(:only_one_field) and not fields.empty?
+      end
+
+      def must_not_have_a_name_failed?(name)
+        option?(:no_fieldnames) and name != nil
+      end
+
+      def must_have_a_name_failed?(name)
+        option?(:mandatory_fieldnames) and name.nil?
+      end
+
+      def all_or_none_names_failed?(name)
+        if option?(:all_or_none_fieldnames) and not fields.empty?
+          all_names_blank = fields.all_field_names_blank?
+          no_names_blank = fields.no_field_names_blank?
+
+          (name != nil and all_names_blank) or (name == nil and no_names_blank)
+        else
+          false
+        end
+      end
+
+      def malformed_name?(name)
+        /^[a-z_]\w*$/ !~ name.to_s
+      end
+
+      def duplicate_name?(name)
+        fields.has_field_name?(name)
+      end
+
+      def name_shadows_method?(name)
+        @the_class.method_defined?(name)
+      end
+
+      def name_is_reserved?(name)
+        BinData::Struct::RESERVED.include?(name.to_sym)
+      end
+
+      def dsl_raise(exception, message)
+        backtrace = caller
+        backtrace.shift while %r{bindata/dsl.rb} =~ backtrace.first
+
+        raise exception, message + " in #{@the_class}", backtrace
+      end
+
+      def to_array_params
+        case fields.length
+        when 0
+          {}
+        when 1
+          {:type => fields[0].prototype}
+        else
+          {:type => [:struct, to_struct_params]}
+        end
+      end
+
+      def to_choice_params
+        if fields.length == 0
+          {}
+        elsif fields.all_field_names_blank?
+          {:choices => fields.collect { |f| f.prototype }}
+        else
+          choices = {}
+          fields.each { |f| choices[f.name] = f.prototype }
+          {:choices => choices}
+        end
+      end
+
+      def to_struct_params
+        result = {:fields => fields}
+        if not endian.nil?
+          result[:endian] = endian
+        end
+        if option?(:hidden_fields) and not hide.empty?
+          result[:hide] = hide
+        end
+
+        result
+      end
+    end
+  end
+end