jbangert-bindata 1.5.0

data/lib/bindata/record.rb

@@ -0,0 +1,110 @@
+require 'bindata/dsl'
+require 'bindata/sanitize'
+require 'bindata/struct'
+
+module BinData
+  # Extracts args for Records.
+  #
+  # Foo.new(:bar => "baz) is ambiguous as to whether :bar is a value or parameter.
+  #
+  # BaseArgExtractor always assumes :bar is parameter.  This extractor correctly
+  # identifies it as value or parameter.
+  class RecordArgExtractor
+    class << self
+      def extract(the_class, the_args)
+        value, parameters, parent = BaseArgExtractor.extract(the_class, the_args)
+
+        if parameters_is_value?(the_class, value, parameters)
+          value = parameters
+          parameters = {}
+        end
+
+        [value, parameters, parent]
+      end
+
+      def parameters_is_value?(the_class, value, parameters)
+        if value.nil? and parameters.length > 0
+          field_names_in_parameters?(the_class, parameters)
+        else
+          false
+        end
+      end
+
+      def field_names_in_parameters?(the_class, parameters)
+        field_names = the_class.fields.field_names
+        param_keys = parameters.keys
+
+        (field_names & param_keys).length > 0
+      end
+    end
+  end
+
+  # A Record is a declarative wrapper around Struct.
+  #
+  #    require 'bindata'
+  #
+  #    class SomeDataType < BinData::Record
+  #      hide :a
+  #
+  #      int32le :a
+  #      int16le :b
+  #      struct  :s do
+  #        int8  :x
+  #        int8  :y
+  #        int8  :z
+  #      end
+  #    end
+  #
+  #    obj = SomeDataType.new
+  #    obj.field_names   =># ["b", "s"]
+  #    obj.s.field_names =># ["x", "y", "z"]
+  #
+  class Record < BinData::Struct
+    include DSLMixin
+
+    unregister_self
+    dsl_parser :struct
+
+    class << self
+
+      def arg_extractor
+        RecordArgExtractor
+      end
+
+      def sanitize_parameters!(params) #:nodoc:
+        params.merge!(dsl_params)
+
+        super(params)
+
+        define_field_accessors(params[:fields].fields)
+      end
+
+      # Defines accessor methods to avoid the overhead of going through
+      # Struct#method_missing.  This is purely a speed optimisation.
+      # Removing this method will not have any effect on correctness.
+      def define_field_accessors(fields) #:nodoc:
+        unless method_defined?(:bindata_defined_accessors_for_fields?)
+          fields.each_with_index do |field, i|
+            name = field.name_as_sym
+            if name
+              define_field_accessors_for(name, i)
+            end
+          end
+
+          define_method(:bindata_defined_accessors_for_fields?) { true }
+        end
+      end
+
+      def define_field_accessors_for(name, index)
+        define_method(name) do
+          instantiate_obj_at(index) unless @field_objs[index]
+          @field_objs[index]
+        end
+        define_method(name.to_s + "=") do |*vals|
+          instantiate_obj_at(index) unless @field_objs[index]
+          @field_objs[index].assign(*vals)
+        end
+      end
+    end
+  end
+end

data/lib/bindata/registry.rb

@@ -0,0 +1,92 @@
+module BinData
+
+  class UnRegisteredTypeError < StandardError ; end
+
+  # This registry contains a register of name -> class mappings.
+  #
+  # Numerics (integers and floating point numbers) have an endian property as
+  # part of their name (e.g. int32be, float_le).  The lookup can either be
+  # on the full name, or on the shortened name plus endian (e.g. "int32", :big)
+  #
+  # Names are stored in under_score_style, not camelCase.
+  class Registry
+
+    def initialize
+      @registry = {}
+    end
+
+    def register(name, class_to_register)
+      return if class_to_register.nil?
+
+      formatted_name = lookup_key(name)
+      warn_if_name_is_already_registered(formatted_name, class_to_register)
+
+      @registry[formatted_name] = class_to_register
+    end
+
+    def unregister(name)
+      formatted_name = lookup_key(name)
+      @registry.delete(formatted_name)
+    end
+
+    def lookup(name, endian = nil)
+      key = lookup_key(name, endian)
+      try_registering_key(key) unless @registry.has_key?(key)
+
+      @registry[key] || raise(UnRegisteredTypeError, name.to_s)
+    end
+
+    def normalize_name(name, endian = nil)
+      if lookup(name, endian)
+        lookup_key(name, endian)
+      end
+    end
+
+    # Convert CamelCase +name+ to underscore style.
+    def underscore_name(name)
+      name.to_s.sub(/.*::/, "").
+                gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+                gsub(/([a-z\d])([A-Z])/,'\1_\2').
+                tr("-", "_").
+                downcase
+    end
+
+    #---------------
+    private
+
+    def lookup_key(name, endian = nil)
+      name = underscore_name(name)
+
+      result = name
+      if endian != nil
+        if /^u?int\d+$/ =~ name
+          result = name + ((endian == :little) ? "le" : "be")
+        elsif /^(float|double)$/ =~ name
+          result = name + ((endian == :little) ? "_le" : "_be")
+        end
+      end
+      result
+    end
+
+    def try_registering_key(key)
+      if /^u?int\d+(le|be)$/ =~ key or /^bit\d+(le)?$/ =~ key
+        class_name = key.gsub(/(?:^|_)(.)/) { $1.upcase }
+        begin
+          register(key, BinData::const_get(class_name))
+        rescue NameError
+        end
+      end
+    end
+
+    def warn_if_name_is_already_registered(name, class_to_register)
+      prev_class = @registry[name]
+      if $VERBOSE and prev_class and prev_class != class_to_register
+        warn "warning: replacing registered class #{prev_class} " +
+             "with #{class_to_register}"
+      end
+    end
+  end
+
+  # A singleton registry of all registered classes.
+  RegisteredClasses = Registry.new
+end

data/lib/bindata/rest.rb

@@ -0,0 +1,35 @@
+require "bindata/base_primitive"
+
+module BinData
+  # Rest will consume the input stream from the current position to the end of
+  # the stream.  This will mainly be useful for debugging and developing.
+  #
+  #   require 'bindata'
+  #
+  #   class A < BinData::Record
+  #     string :a, :read_length => 5
+  #     rest   :rest
+  #   end
+  #
+  #   obj = A.read("abcdefghij")
+  #   obj.a #=> "abcde"
+  #   obj.rest #=" "fghij"
+  #
+  class Rest < BinData::BasePrimitive
+
+    #---------------
+    private
+
+    def value_to_binary_string(val)
+      val
+    end
+
+    def read_and_return_value(io)
+      io.read_all_bytes
+    end
+
+    def sensible_default
+      ""
+    end
+  end
+end

data/lib/bindata/sanitize.rb

@@ -0,0 +1,290 @@
+require 'bindata/registry'
+
+module BinData
+
+  # Subclasses of this are sanitized
+  class SanitizedParameter; end
+
+  class SanitizedPrototype < SanitizedParameter
+    def initialize(obj_type, obj_params, endian)
+      endian = endian.endian if endian.respond_to? :endian
+      obj_params ||= {}
+      if BinData::Base === obj_type or obj_type.is_a?(Class)
+        obj_class = obj_type
+      else
+        obj_class = RegisteredClasses.lookup(obj_type, endian)
+      end
+
+      if BinData::Base === obj_class
+        @factory = obj_class
+      else
+        @obj_class  = obj_class
+        @obj_params = SanitizedParameters.new(obj_params, @obj_class, endian)
+      end
+    end
+
+    def instantiate(value = nil, parent = nil)
+      @factory ||= @obj_class.new(@obj_params)
+
+      @factory.new(value, parent)
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedField < SanitizedParameter
+    def initialize(name, field_type, field_params, endian)
+      @name      = name
+      @prototype = SanitizedPrototype.new(field_type, field_params, endian)
+    end
+
+    attr_reader :prototype
+
+    def name_as_sym
+      @name.nil? ? nil : @name.to_sym
+    end
+
+    def name
+      @name
+    end
+
+    def instantiate(value = nil, parent = nil)
+      @prototype.instantiate(value, parent)
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedFields < SanitizedParameter
+    def initialize(endian)
+      @fields = []
+      @endian = endian
+    end
+    attr_reader :fields
+
+    def add_field(type, name, params)
+      name = nil if name == ""
+
+      @fields << SanitizedField.new(name, type, params, @endian)
+    end
+
+    def [](idx)
+      @fields[idx]
+    end
+
+    def empty?
+      @fields.empty?
+    end
+
+    def length
+      @fields.length
+    end
+
+    def each(&block)
+      @fields.each(&block)
+    end
+
+    def collect(&block)
+      @fields.collect(&block)
+    end
+
+    def field_names
+      @fields.collect { |field| field.name_as_sym }
+    end
+
+    def has_field_name?(name)
+      @fields.detect { |f| f.name_as_sym == name.to_sym }
+    end
+
+    def all_field_names_blank?
+      @fields.all? { |f| f.name == nil }
+    end
+
+    def no_field_names_blank?
+      @fields.all? { |f| f.name != nil }
+    end
+
+    def copy_fields(other)
+      @fields.concat(other.fields)
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedChoices < SanitizedParameter
+    def initialize(choices, endian)
+      @choices = {}
+      choices.each_pair do |key, val|
+        if SanitizedParameter === val
+          prototype = val
+        else
+          type, param = val
+          prototype = SanitizedPrototype.new(type, param, endian)
+        end
+
+        if key == :default
+          @choices.default = prototype
+        else
+          @choices[key] = prototype
+        end
+      end
+    end
+
+    def [](key)
+      @choices[key]
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  class SanitizedBigEndian < SanitizedParameter
+    def endian
+      :big
+    end
+  end
+
+  class SanitizedLittleEndian < SanitizedParameter
+    def endian
+      :little
+    end
+  end
+  #----------------------------------------------------------------------------
+
+  # BinData objects are instantiated with parameters to determine their
+  # behaviour.  These parameters must be sanitized to ensure their values
+  # are valid.  When instantiating many objects with identical parameters,
+  # such as an array of records, there is much duplicated sanitizing.
+  #
+  # The purpose of the sanitizing code is to eliminate the duplicated
+  # validation.
+  #
+  # SanitizedParameters is a hash-like collection of parameters.  Its purpose
+  # is to recursively sanitize the parameters of an entire BinData object chain
+  # at a single time.
+  class SanitizedParameters < Hash
+
+    # Memoized constants
+    BIG_ENDIAN    = SanitizedBigEndian.new
+    LITTLE_ENDIAN = SanitizedLittleEndian.new
+
+    class << self
+      def sanitize(parameters, the_class)
+        if SanitizedParameters === parameters
+          parameters
+        else
+          SanitizedParameters.new(parameters, the_class, nil)
+        end
+      end
+    end
+
+    def initialize(parameters, the_class, endian)
+      parameters.each_pair { |key, value| self[key.to_sym] = value }
+
+      @the_class = the_class
+      @endian    = endian
+
+      sanitize!
+    end
+
+    alias_method :has_parameter?, :has_key?
+
+    def needs_sanitizing?(key)
+      parameter = self[key]
+
+      parameter and not parameter.is_a?(SanitizedParameter)
+    end
+
+    def warn_replacement_parameter(bad_key, suggested_key)
+      if has_parameter?(bad_key)
+        warn ":#{bad_key} is not used with #{@the_class}.  " +
+        "You probably want to change this to :#{suggested_key}"
+      end
+    end
+
+    def warn_renamed_parameter(old_key, new_key)
+      val = delete(old_key)
+      if val
+        self[new_key] = val
+        warn ":#{old_key} has been renamed to :#{new_key} in #{@the_class}.  " +
+        "Using :#{old_key} is now deprecated and will be removed in the future"
+      end
+    end
+
+    def endian
+      @endian || self[:endian]
+    end
+    attr_writer :endian
+
+    def create_sanitized_endian(endian)
+      if endian == :big
+        BIG_ENDIAN
+      elsif endian == :little
+        LITTLE_ENDIAN
+      else
+        raise ArgumentError, "unknown value for endian '#{endian}'"
+      end
+    end
+
+    def create_sanitized_params(params, the_class)
+      SanitizedParameters.new(params, the_class, self.endian)
+    end
+
+    def create_sanitized_choices(choices)
+      SanitizedChoices.new(choices, self.endian)
+    end
+
+    def create_sanitized_fields
+      SanitizedFields.new(self.endian)
+    end
+
+    def create_sanitized_object_prototype(obj_type, obj_params)
+      SanitizedPrototype.new(obj_type, obj_params, self.endian)
+    end
+
+    #---------------
+    private
+
+    def sanitize!
+      ensure_no_nil_values
+      merge_default_parameters!
+
+      @the_class.sanitize_parameters!(self)
+
+      ensure_mandatory_parameters_exist
+      ensure_mutual_exclusion_of_parameters
+    end
+
+    def ensure_no_nil_values
+      each do |key, value|
+        if value.nil?
+          raise ArgumentError,
+                "parameter '#{key}' has nil value in #{@the_class}"
+        end
+      end
+    end
+
+    def merge_default_parameters!
+      @the_class.default_parameters.each do |key, value|
+        self[key] ||= value
+      end
+    end
+
+    def ensure_mandatory_parameters_exist
+      @the_class.mandatory_parameters.each do |key|
+        unless has_parameter?(key)
+          raise ArgumentError,
+                  "parameter '#{key}' must be specified in #{@the_class}"
+        end
+      end
+    end
+
+    def ensure_mutual_exclusion_of_parameters
+      return if length < 2
+
+      @the_class.mutually_exclusive_parameters.each do |key1, key2|
+        if has_parameter?(key1) and has_parameter?(key2)
+          raise ArgumentError, "params '#{key1}' and '#{key2}' " +
+                               "are mutually exclusive in #{@the_class}"
+        end
+      end
+    end
+  end
+  #----------------------------------------------------------------------------
+
+end