jbangert-bindata 1.5.0

data/lib/bindata/base.rb

@@ -0,0 +1,388 @@
+require 'bindata/io'
+require 'bindata/lazy'
+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].
+  class BaseArgExtractor
+    @@empty_hash = Hash.new.freeze
+
+    def self.extract(the_class, the_args)
+      args = the_args.dup
+      value = parameters = parent = nil
+
+      if args.length > 1 and args.last.is_a? BinData::Base
+        parent = args.pop
+      end
+
+      if args.length > 0 and args.last.is_a? Hash
+        parameters = args.pop
+      end
+
+      if args.length > 0
+        value = args.pop
+      end
+
+      parameters ||= @@empty_hash
+
+      return [value, parameters, parent]
+    end
+  end
+
+  # This is the abstract base class for all data objects.
+  class Base
+    include AcceptedParametersMixin
+    include CheckOrAdjustOffsetMixin
+
+    class << self
+
+      # Instantiates this class and reads from +io+, returning the newly
+      # created data object.
+      def read(io)
+        obj = self.new
+        obj.read(io)
+        obj
+      end
+
+      # The arg extractor for this class.
+      def arg_extractor
+        BaseArgExtractor
+      end
+
+      # The name of this class as used by Records, Arrays etc.
+      def bindata_name
+        RegisteredClasses.underscore_name(self.name)
+      end
+
+      # 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 #:nodoc:
+        class << self
+          define_method(:inherited) do |subclass|
+            RegisteredClasses.register(subclass.name, subclass)
+            register_subclasses
+          end
+        end
+      end
+
+      private :unregister_self, :register_subclasses
+    end
+
+    # 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.
+    #
+    # +value+ is a value that is +assign+ed immediately after initialization.
+    #
+    # +parameters+ is a hash containing symbol keys.  Some parameters may
+    # reference callable objects (methods or procs).
+    #
+    # +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
+    end
+
+    attr_accessor :parent
+    protected :parent=
+
+    # Creates a new data object based on this instance.
+    #
+    # All parameters will be be duplicated.  Use this method
+    # when creating multiple objects with the same parameters.
+    def new(value = nil, parent = nil)
+      obj = clone
+      obj.parent = parent if parent
+      obj.initialize_instance
+      obj.assign(value) if value
+
+      obj
+    end
+
+    # Returns the result of evaluating the parameter identified by +key+.
+    #
+    # +overrides+ is an optional +parameters+ like hash that allow the
+    # parameters given at object construction to be overridden.
+    #
+    # Returns nil if +key+ does not refer to any parameter.
+    def eval_parameter(key, overrides = nil)
+      value = get_parameter(key)
+      if value.is_a?(Symbol) or value.respond_to?(:arity)
+        lazy_evaluator.lazy_eval(value, overrides)
+      else
+        value
+      end
+    end
+
+    # Returns a lazy evaluator for this object.
+    def lazy_evaluator #:nodoc:
+      @lazy ||= LazyEvaluator.new(self)
+    end
+
+    # Returns the parameter referenced by +key+.
+    # Use this method if you are sure the parameter is not to be evaluated.
+    # You most likely want #eval_parameter.
+    def get_parameter(key)
+      @params[key]
+    end
+
+    # Returns whether +key+ exists in the +parameters+ hash.
+    def has_parameter?(key)
+      @params.has_parameter?(key)
+    end
+
+    # Reads data into this data object.
+    def read(io)
+      io = BinData::IO.new(io) unless BinData::IO === io
+
+      @in_read = true
+      clear
+      do_read(io)
+      @in_read = false
+
+      self
+    end
+
+    #:nodoc:
+    attr_reader :in_read
+    protected   :in_read
+
+    # Returns if this object is currently being read.  This is used
+    # internally by BasePrimitive.
+    def reading? #:nodoc:
+      furthest_ancestor.in_read
+    end
+    protected :reading?
+
+    # Writes the value for this data object to +io+.
+    def write(io)
+      io = BinData::IO.new(io) unless BinData::IO === io
+
+      do_write(io)
+      io.flush
+      self
+    end
+
+    # Returns the number of bytes it will take to write this data object.
+    def num_bytes
+      do_num_bytes.ceil
+    end
+
+    # Returns the string representation of this data object.
+    def to_binary_s
+      io = BinData::IO.create_string_io
+      write(io)
+      io.rewind
+      io.read
+    end
+
+    # Return a human readable representation of this data object.
+    def inspect
+      snapshot.inspect
+    end
+
+    # Return a string representing this data object.
+    def to_s
+      snapshot.to_s
+    end
+
+    # Work with Ruby's pretty-printer library.
+    def pretty_print(pp) #:nodoc:
+      pp.pp(snapshot)
+    end
+
+    # Override and delegate =~ as it is defined in Object.
+    def =~(other)
+      snapshot =~ other
+    end
+
+    # Returns a user friendly name of this object for debugging purposes.
+    def debug_name
+      if @parent
+        @parent.debug_name_of(self)
+      else
+        "obj"
+      end
+    end
+
+    # Returns the offset of this object wrt to its most distant ancestor.
+    def offset
+      if @parent
+        @parent.offset + @parent.offset_of(self)
+      else
+        0
+      end
+    end
+
+    # Returns the offset of this object wrt to its parent.
+    def rel_offset
+      if @parent
+        @parent.offset_of(self)
+      else
+        0
+      end
+    end
+
+    def ==(other) #:nodoc:
+      # double dispatch
+      other == snapshot
+    end
+
+    # A version of +respond_to?+ used by the lazy evaluator.  It doesn't
+    # reinvoke the evaluator so as to avoid infinite evaluation loops.
+    def safe_respond_to?(symbol, include_private = false) #:nodoc:
+      respond_to?(symbol, include_private)
+    end
+    alias_method :orig_respond_to?, :respond_to? #:nodoc:
+
+    #---------------
+    private
+
+    def extract_args(the_args)
+      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
+      else
+        an = parent
+        an = an.parent while an.parent
+        an
+      end
+    end
+
+    def binary_string(str)
+      if str.respond_to?(:force_encoding)
+        str.dup.force_encoding(Encoding::BINARY)
+      else
+        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

data/lib/bindata/base_primitive.rb

@@ -0,0 +1,214 @@
+require 'bindata/base'
+
+module BinData
+  # A BinData::BasePrimitive object is a container for a value that has a
+  # particular binary representation.  A value corresponds to a primitive type
+  # such as as integer, float or string.  Only one value can be contained by
+  # this object.  This value can be read from or written to an IO stream.
+  #
+  #   require 'bindata'
+  #
+  #   obj = BinData::Uint8.new(:initial_value => 42)
+  #   obj #=> 42
+  #   obj.assign(5)
+  #   obj #=> 5
+  #   obj.clear
+  #   obj #=> 42
+  #
+  #   obj = BinData::Uint8.new(:value => 42)
+  #   obj #=> 42
+  #   obj.assign(5)
+  #   obj #=> 42
+  #
+  #   obj = BinData::Uint8.new(:check_value => 3)
+  #   obj.read("\005") #=> BinData::ValidityError: value is '5' but expected '3'
+  #
+  #   obj = BinData::Uint8.new(:check_value => lambda { value < 5 })
+  #   obj.read("\007") #=> BinData::ValidityError: value not as expected
+  #
+  # == Parameters
+  #
+  # Parameters may be provided at initialisation to control the behaviour of
+  # an object.  These params include those for BinData::Base as well as:
+  #
+  # [<tt>:initial_value</tt>] This is the initial value to use before one is
+  #                           either #read or explicitly set with #value=.
+  # [<tt>:value</tt>]         The object will always have this value.
+  #                           Calls to #value= are ignored when
+  #                           using this param.  While reading, #value
+  #                           will return the value of the data read from the
+  #                           IO, not the result of the <tt>:value</tt> param.
+  # [<tt>:check_value</tt>]   Raise an error unless the value read in meets
+  #                           this criteria.  The variable +value+ is made
+  #                           available to any lambda assigned to this
+  #                           parameter.  A boolean return indicates success
+  #                           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
+
+    def initialize_shared_instance
+      if has_parameter?(:check_value)
+        class << self
+          alias_method :do_read_without_check_value, :do_read
+          alias_method :do_read, :do_read_with_check_value
+        end
+      end
+      if has_parameter?(:value)
+        class << self
+          alias_method :_value, :_value_with_value
+        end
+      end
+      if has_parameter?(:initial_value)
+        class << self
+          alias_method :_value, :_value_with_initial_value
+        end
+      end
+    end
+
+    def initialize_instance
+      @value = nil
+    end
+
+    def clear #:nodoc:
+      @value = nil
+    end
+
+    def clear? #:nodoc:
+      @value.nil?
+    end
+
+    def assign(val)
+      raise ArgumentError, "can't set a nil value for #{debug_name}" if val.nil?
+
+      unless has_parameter?(:value)
+        raw_val = val.respond_to?(:snapshot) ? val.snapshot : val
+        @value = begin
+                   raw_val.dup
+                 rescue TypeError
+                   # can't dup Fixnums
+                   raw_val
+                 end
+      end
+    end
+
+    def snapshot
+      _value
+    end
+
+    def value
+      snapshot
+    end
+    alias_method :value=, :assign
+
+    def respond_to?(symbol, include_private = false) #:nodoc:
+      child = snapshot
+      child.respond_to?(symbol, include_private) || super
+    end
+
+    def method_missing(symbol, *args, &block) #:nodoc:
+      child = snapshot
+      if child.respond_to?(symbol)
+        child.__send__(symbol, *args, &block)
+      else
+        super
+      end
+    end
+
+    def <=>(other)
+      snapshot <=> other
+    end
+
+    def eql?(other)
+      # double dispatch
+      other.eql?(snapshot)
+    end
+
+    def hash
+      snapshot.hash
+    end
+
+    def do_read(io) #:nodoc:
+      @value = read_and_return_value(io)
+      hook_after_do_read
+    end
+
+    def do_read_with_check_value(io) #:nodoc:
+      do_read_without_check_value(io)
+      check_value(snapshot)
+    end
+
+    def do_write(io) #:nodoc:
+      io.writebytes(value_to_binary_string(_value))
+    end
+
+    def do_num_bytes #:nodoc:
+      value_to_binary_string(_value).length
+    end
+
+    #---------------
+    private
+
+    def hook_after_do_read; end
+
+    def check_value(current_value)
+      expected = eval_parameter(:check_value, :value => current_value)
+      if not expected
+        raise ValidityError,
+              "value '#{current_value}' not as expected for #{debug_name}"
+      elsif current_value != expected and expected != true
+        raise ValidityError,
+              "value is '#{current_value}' but " +
+              "expected '#{expected}' for #{debug_name}"
+      end
+    end
+
+    # The unmodified value of this data object.  Note that #snapshot calls this
+    # method.  This indirection is so that #snapshot can be overridden in
+    # subclasses to modify the presentation value.
+    #
+    # Table of possible preconditions and expected outcome
+    #   1. :value and !reading?         ->   :value
+    #   2. :value and reading?          ->   @value
+    #   3. :initial_value and clear?    ->   :initial_value
+    #   4. :initial_value and !clear?   ->   @value
+    #   5. clear?                       ->   sensible_default
+    #   6. !clear?                      ->   @value
+
+    def _value
+      @value != nil ? @value : sensible_default()
+    end
+
+    def _value_with_value #:nodoc:
+      reading?      ? @value : eval_parameter(:value)
+    end
+
+    def _value_with_initial_value #:nodoc:
+      @value != nil ? @value : eval_parameter(:initial_value)
+    end
+
+    ###########################################################################
+    # To be implemented by subclasses
+
+    # Return the string representation that +val+ will take when written.
+    def value_to_binary_string(val)
+      raise NotImplementedError
+    end
+
+    # Read a number of bytes from +io+ and return the value they represent.
+    def read_and_return_value(io)
+      raise NotImplementedError
+    end
+
+    # Return a sensible default for this data.
+    def sensible_default
+      raise NotImplementedError
+    end
+
+    # To be implemented by subclasses
+    ###########################################################################
+  end
+end