jbangert-bindata 1.5.0

data/lib/bindata/lazy.rb

@@ -0,0 +1,105 @@
+module BinData
+  # A LazyEvaluator is bound to a data object.  The evaluator will evaluate
+  # lambdas in the context of this data object.  These lambdas
+  # are those that are passed to data objects as parameters, e.g.:
+  #
+  #    BinData::String.new(:value => lambda { %w{a test message}.join(" ") })
+  #
+  # As a shortcut, :foo is the equivalent of lambda { foo }.
+  #
+  # When evaluating lambdas, unknown methods are resolved in the context of the
+  # parent of the bound data object.  Resolution is attempted firstly as keys
+  # in #parameters, and secondly as methods in this parent.  This
+  # resolution propagates up the chain of parent data objects.
+  #
+  # An evaluation will recurse until it returns a result that is not
+  # a lambda or a symbol.
+  #
+  # This resolution process makes the lambda easier to read as we just write
+  # <tt>field</tt> instead of <tt>obj.field</tt>.
+  class LazyEvaluator
+
+    # Creates a new evaluator.  All lazy evaluation is performed in the
+    # context of +obj+.
+    def initialize(obj)
+      @obj = obj
+    end
+
+    def lazy_eval(val, overrides = nil)
+      @overrides = overrides if overrides
+      if val.is_a? Symbol
+        __send__(val)
+      elsif val.respond_to? :arity
+        instance_exec(&val)
+      else
+        val
+      end
+    end
+
+    # Returns a LazyEvaluator for the parent of this data object.
+    def parent
+      if @obj.parent
+        @obj.parent.lazy_evaluator
+      else
+        nil
+      end
+    end
+
+    # Returns the index of this data object inside it's nearest container
+    # array.
+    def index
+      return @overrides[:index] if @overrides and @overrides.has_key?(:index)
+
+      child = @obj
+      parent = @obj.parent
+      while parent
+        if parent.respond_to?(:find_index_of)
+          return parent.find_index_of(child)
+        end
+        child = parent
+        parent = parent.parent
+      end
+      raise NoMethodError, "no index found"
+    end
+
+    def method_missing(symbol, *args)
+      return @overrides[symbol] if defined? @overrides and @overrides.has_key?(symbol)
+
+      if @obj.parent
+        eval_symbol_in_parent_context(symbol, args)
+      else
+        super
+      end
+    end
+
+    #---------------
+    private
+
+    def eval_symbol_in_parent_context(symbol, args)
+      result = resolve_symbol_in_parent_context(symbol, args)
+      recursively_eval(result, args)
+    end
+
+    def resolve_symbol_in_parent_context(symbol, args)
+      obj_parent = @obj.parent
+
+      if obj_parent.has_parameter?(symbol)
+        obj_parent.get_parameter(symbol)
+      elsif obj_parent.safe_respond_to?(symbol)
+        obj_parent.__send__(symbol, *args)
+      else
+        symbol
+      end
+    end
+
+    def recursively_eval(val, args)
+      if val.is_a?(Symbol)
+        parent.__send__(val, *args)
+      elsif val.respond_to?(:arity)
+        parent.instance_exec(&val)
+      else
+        val
+      end
+    end
+  end
+end

data/lib/bindata/offset.rb

@@ -0,0 +1,91 @@
+module BinData
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These parameters are:
+  #
+  # [<tt>:check_offset</tt>]  Raise an error if the current IO offset doesn't
+  #                           meet this criteria.  A boolean return indicates
+  #                           success or failure.  Any other return is compared
+  #                           to the current offset.  The variable +offset+
+  #                           is made available to any lambda assigned to
+  #                           this parameter.  This parameter is only checked
+  #                           before reading.
+  # [<tt>:adjust_offset</tt>] Ensures that the current IO offset is at this
+  #                           position before reading.  This is like
+  #                           <tt>:check_offset</tt>, except that it will
+  #                           adjust the IO offset instead of raising an error.
+  module CheckOrAdjustOffsetMixin
+
+    def self.included(base) #:nodoc:
+      base.optional_parameters :check_offset, :adjust_offset
+      base.mutually_exclusive_parameters :check_offset, :adjust_offset
+    end
+
+    # Ideally these two methods should be protected,
+    # but Ruby 1.9.2 requires them to be public.
+    # see http://redmine.ruby-lang.org/issues/show/2375
+
+    def do_read_with_check_offset(io) #:nodoc:
+      check_offset(io)
+      do_read_without_check_offset(io)
+    end
+
+    def do_read_with_adjust_offset(io) #:nodoc:
+      adjust_offset(io)
+      do_read_without_adjust_offset(io)
+    end
+
+    #---------------
+    private
+
+    # To be called from BinData::Base#initialize.
+    #
+    # Monkey patches #do_read to check or adjust the stream offset
+    # as appropriate.
+    def add_methods_for_check_or_adjust_offset
+      if has_parameter?(:check_offset)
+        class << self
+          alias_method :do_read_without_check_offset, :do_read
+          alias_method :do_read, :do_read_with_check_offset
+        end
+      end
+      if has_parameter?(:adjust_offset)
+        class << self
+          alias_method :do_read_without_adjust_offset, :do_read
+          alias_method :do_read, :do_read_with_adjust_offset
+        end
+      end
+    end
+
+    def check_offset(io)
+      actual_offset = io.offset
+      expected = eval_parameter(:check_offset, :offset => actual_offset)
+
+      if not expected
+        raise ValidityError, "offset not as expected for #{debug_name}"
+      elsif actual_offset != expected and expected != true
+        raise ValidityError,
+              "offset is '#{actual_offset}' but " +
+              "expected '#{expected}' for #{debug_name}"
+      end
+    end
+
+    def adjust_offset(io)
+      actual_offset = io.offset
+      expected = eval_parameter(:adjust_offset)
+      if actual_offset != expected
+        begin
+          seek = expected - actual_offset
+          io.seekbytes(seek)
+          warn "adjusting stream position by #{seek} bytes" if $VERBOSE
+        rescue
+          raise ValidityError,
+                "offset is '#{actual_offset}' but couldn't seek to " +
+                "expected '#{expected}' for #{debug_name}"
+        end
+      end
+    end
+  end
+end
+

data/lib/bindata/params.rb

@@ -0,0 +1,135 @@
+require 'bindata/lazy'
+
+module BinData
+  module AcceptedParametersMixin
+    def self.included(base) #:nodoc:
+      base.extend ClassMethods
+    end
+
+    # Class methods to mix in to BinData::Base
+    module ClassMethods
+      # Mandatory parameters must be present when instantiating a data object.
+      def mandatory_parameters(*args)
+        accepted_parameters.mandatory(*args)
+      end
+
+      # Optional parameters may be present when instantiating a data object.
+      def optional_parameters(*args)
+        accepted_parameters.optional(*args)
+      end
+
+      # Default parameters can be overridden when instantiating a data object.
+      def default_parameters(*args)
+        accepted_parameters.default(*args)
+      end
+
+      # Mutually exclusive parameters may not all be present when
+      # instantiating a data object.
+      def mutually_exclusive_parameters(*args)
+        accepted_parameters.mutually_exclusive(*args)
+      end
+
+      alias_method :mandatory_parameter, :mandatory_parameters
+      alias_method :optional_parameter, :optional_parameters
+      alias_method :default_parameter, :default_parameters
+
+      def accepted_parameters #:nodoc:
+        unless defined? @accepted_parameters
+          ancestor_params = superclass.respond_to?(:accepted_parameters) ?
+                              superclass.accepted_parameters : nil
+          @accepted_parameters = AcceptedParameters.new(ancestor_params)
+        end
+        @accepted_parameters
+      end
+    end
+
+    # BinData objects accept parameters when initializing.  AcceptedParameters
+    # allow a BinData class to declaratively identify accepted parameters as
+    # mandatory, optional, default or mutually exclusive.
+    class AcceptedParameters
+
+      def initialize(ancestor_parameters = nil)
+        if ancestor_parameters
+          @mandatory = ancestor_parameters.mandatory.dup
+          @optional  = ancestor_parameters.optional.dup
+          @default   = ancestor_parameters.default.dup
+          @mutually_exclusive = ancestor_parameters.mutually_exclusive.dup
+        else
+          @mandatory = []
+          @optional  = []
+          @default   = Hash.new
+          @mutually_exclusive = []
+        end
+      end
+
+      def mandatory(*args)
+        if not args.empty?
+          @mandatory.concat(to_syms(args))
+          @mandatory.uniq!
+        end
+        @mandatory
+      end
+
+      def optional(*args)
+        if not args.empty?
+          @optional.concat(to_syms(args))
+          @optional.uniq!
+        end
+        @optional
+      end
+
+      def default(args = nil)
+        if args
+          to_syms(args.keys)  # call for side effect of validating names
+          args.each_pair do |param, value|
+            @default[param.to_sym] = value
+          end
+        end
+        @default
+      end
+
+      def mutually_exclusive(*args)
+        arg1, arg2 = args
+        if arg1 != nil && arg2 != nil
+          @mutually_exclusive.push([arg1.to_sym, arg2.to_sym])
+          @mutually_exclusive.uniq!
+        end
+        @mutually_exclusive
+      end
+
+      def all
+        (@mandatory + @optional + @default.keys).uniq
+      end
+
+      #---------------
+      private
+
+      def to_syms(args)
+        syms = args.collect { |el| el.to_sym }
+        ensure_valid_names(syms)
+        syms
+      end
+
+      def ensure_valid_names(names)
+        invalid_names = self.class.invalid_parameter_names
+        names.each do |name|
+          if invalid_names.include?(name)
+            raise NameError.new("Rename parameter '#{name}' " +
+                                "as it shadows an existing method.", name)
+          end
+        end
+      end
+
+      def self.invalid_parameter_names
+        unless defined? @invalid_names
+          all_names = LazyEvaluator.instance_methods(true) + Kernel.methods
+          allowed_names = ["name", "type", :name, :type] # ruby 1.8 vs 1.9
+          invalid_names = (all_names - allowed_names).uniq
+          @invalid_names = Hash[*invalid_names.collect { |key| [key.to_sym, true] }.flatten]
+        end
+        @invalid_names
+      end
+    end
+  end
+end
+

data/lib/bindata/primitive.rb

@@ -0,0 +1,135 @@
+require 'bindata/base_primitive'
+require 'bindata/dsl'
+require 'bindata/struct'
+
+module BinData
+  # A Primitive is a declarative way to define a new BinData data type.
+  # The data type must contain a primitive value only, i.e numbers or strings.
+  # For new data types that contain multiple values see BinData::Record.
+  #
+  # To define a new data type, set fields as if for Record and add a
+  # #get and #set method to extract / convert the data between the fields
+  # and the #value of the object.
+  #
+  #    require 'bindata'
+  #
+  #    class PascalString < BinData::Primitive
+  #      uint8  :len,  :value => lambda { data.length }
+  #      string :data, :read_length => :len
+  #
+  #      def get
+  #        self.data
+  #      end
+  #
+  #      def set(v)
+  #        self.data = v
+  #      end
+  #    end
+  #
+  #    ps = PascalString.new(:initial_value => "hello")
+  #    ps.to_binary_s #=> "\005hello"
+  #    ps.read("\003abcde")
+  #    ps #=> "abc"
+  #
+  #    # Unsigned 24 bit big endian integer
+  #    class Uint24be < BinData::Primitive
+  #      uint8 :byte1
+  #      uint8 :byte2
+  #      uint8 :byte3
+  #
+  #      def get
+  #        (self.byte1 << 16) | (self.byte2 << 8) | self.byte3
+  #      end
+  #
+  #      def set(v)
+  #        v = 0 if v < 0
+  #        v = 0xffffff if v > 0xffffff
+  #
+  #        self.byte1 = (v >> 16) & 0xff
+  #        self.byte2 = (v >>  8) & 0xff
+  #        self.byte3 =  v        & 0xff
+  #      end
+  #    end
+  #
+  #    u24 = Uint24be.new
+  #    u24.read("\x12\x34\x56")
+  #    "0x%x" % u24 #=> 0x123456
+  #
+  # == Parameters
+  #
+  # Primitive objects accept all the parameters that BinData::BasePrimitive do.
+  #
+  class Primitive < BasePrimitive
+    include DSLMixin
+
+    unregister_self
+    dsl_parser :primitive
+
+    class << self
+      def sanitize_parameters!(params) #:nodoc:
+        params[:struct_params] = params.create_sanitized_params(dsl_params, BinData::Struct)
+      end
+    end
+
+    mandatory_parameter :struct_params
+
+    def initialize_instance
+      @struct = BinData::Struct.new(get_parameter(:struct_params), self)
+    end
+
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      @struct.respond_to?(symbol, include_private) || super
+    end
+
+    def method_missing(symbol, *args, &block) #:nodoc:
+      if @struct.respond_to?(symbol)
+        @struct.__send__(symbol, *args, &block)
+      else
+        super
+      end
+    end
+
+    def debug_name_of(child) #:nodoc:
+      debug_name + "-internal-"
+    end
+
+    def do_write(io)
+      set(_value)
+      @struct.do_write(io)
+    end
+
+    def do_num_bytes
+      set(_value)
+      @struct.do_num_bytes
+    end
+
+    #---------------
+    private
+
+    def sensible_default
+      get
+    end
+
+    def read_and_return_value(io)
+      @struct.do_read(io)
+      get
+    end
+
+    ###########################################################################
+    # To be implemented by subclasses
+
+    # Extracts the value for this data object from the fields of the
+    # internal struct.
+    def get
+      raise NotImplementedError
+    end
+
+    # Sets the fields of the internal struct to represent +v+.
+    def set(v)
+      raise NotImplementedError
+    end
+
+    # To be implemented by subclasses
+    ###########################################################################
+  end
+end